New:Socket for Asana Is Now Available.Learn more →
Get Started

@erclx/aitk

Package Overview
Dependencies
Maintainers
1
Versions
217
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@erclx/aitk - npm Package Compare versions

Comparing version
3.29.1
 to
3.30.0
+38
docs/agents/standards-audit.md
---
title: Standard success criteria
description: Reading the corpus against the Success criterion gate, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
---
# Standard success criteria
`aitk standards audit` reads the corpus at `standards/` and reports which files carry a `## Success criterion` section against which do not, per `standards/standard.md`. It fails only on a standard new to the current branch, never on one already short the section.
```bash
aitk standards audit
aitk standards audit --json
aitk standards audit --arrivals-only
```
| Option | Behavior |
| ----------------- | ------------------------------------------------------------ |
| `[path]` | Project root, defaulting to the current directory |
| `--json` | Add a machine-readable record on stdout, keeping the frame |
| `--arrivals-only` | Run the gating check alone, printing nothing on a clean pass |
## Why arrival rather than the corpus
`standards/standard.md` states that a criterion is added to an existing standard when that standard is next exercised, not in a sweep: a criterion written with no failure to point at is the taste-based edit the rule exists to prevent. Gating the whole corpus would fail every push until every standard already short the section was closed at once, which is the sweep that rule forbids. The check reads the whole corpus and fails only on a file present in the working tree and absent at the branch's merge base, treating a rename into the corpus the same as a standard authored fresh.
## Exit codes and refusals
| Code | Meaning |
| ---- | --------------------------------------------------------------- |
| `0` | every arriving standard carries the section |
| `1` | refused, with `reason` naming the cause |
| `2` | a standard new to this branch carries no `## Success criterion` |
A project authoring no standards refuses with `no-corpus`, the ordinary state of most targets, the same absence `aitk claude skills audit` reads as its own `no-corpus`.
## What it does not measure
Presence of the heading is the whole check. The section's content, the questions it must answer or the task it must let a reader complete, is a judgment `aitk standards audit` cannot read, so a standard carrying an empty or token section still passes.
+132
src/standards/audit.ts
import { existsSync, readFileSync, readdirSync } from 'node:fs'
import { basename, join } from 'node:path'
import { $ } from 'bun'
import { gitEnv } from '@/git-env'
import { resolveBaseRef } from '@/git-files'
import { INDEX_FILE, standardsSourceDir } from '@/standards/read'
/** Returned when a standard new to this branch carries no `## Success criterion` section, the gating check. */
export const EXIT_MISSING_CRITERION = 2
/** Matched at any casing, level-2 only, per the heading `standards/standard.md` itself uses. */
const CRITERION_HEADING = /^##\s+success criterion\s*$/im
/**
* The reasons an audit produces no reading. `no-corpus` is the ordinary state
* of a target that authors no standards of its own, the same absence the
* skills audit reads as its own `no-corpus`. The other two are a broken git
* invocation rather than a project stating nothing.
*/
export type StandardsAuditRefusal =
| 'no-corpus'
| 'no-base'
| 'unreadable-arrivals'
export type StandardsAudit =
| {
readonly kind: 'measured'
readonly base: string
readonly standards: readonly string[]
readonly withCriterion: readonly string[]
readonly withoutCriterion: readonly string[]
readonly arrivals: readonly string[]
readonly arrivalsWithoutCriterion: readonly string[]
}
| { readonly kind: 'refused'; readonly reason: StandardsAuditRefusal }
/**
* Measures the corpus authored at `standards/` under `root` against the
* `## Success criterion` gate `standards/standard.md` states, and names which
* of those files are new since the branch's merge base.
*
* Reads the working-root corpus alone, never the packaged fallback
* `src/standards/read.ts` falls through to for a name lookup, since a target
* with no authored standards of its own has nothing here to gate.
*/
export async function auditStandards(root: string): Promise<StandardsAudit> {
const dir = standardsSourceDir(root)
if (!existsSync(dir)) return { kind: 'refused', reason: 'no-corpus' }
const standards = readdirSync(dir, { withFileTypes: true })
.filter(
(entry) =>
entry.isFile() &&
entry.name.endsWith('.md') &&
entry.name !== INDEX_FILE,
)
.map((entry) => entry.name)
.sort()
const withCriterion: string[] = []
const withoutCriterion: string[] = []
for (const name of standards) {
const body = readFileSync(join(dir, name), 'utf8')
;(CRITERION_HEADING.test(body) ? withCriterion : withoutCriterion).push(
name,
)
}
const base = await resolveBaseRef(root)
if (base === undefined) return { kind: 'refused', reason: 'no-base' }
const arrived = await arrivedStandards(root, base)
if (arrived === undefined) {
return { kind: 'refused', reason: 'unreadable-arrivals' }
}
const arrivals = standards.filter((name) => arrived.has(name))
const arrivalsWithoutCriterion = arrivals.filter((name) =>
withoutCriterion.includes(name),
)
return {
kind: 'measured',
base,
standards,
withCriterion,
withoutCriterion,
arrivals,
arrivalsWithoutCriterion,
}
}
/**
* Only an arrival missing the section sets a failing code. Every other
* standard without one is a known gap `standards/standard.md` names rather
* than a violation, so failing the push on the 26 already there teaches
* contributors to route around the stage.
*/
export function auditExitCode(audit: StandardsAudit): number {
if (audit.kind === 'refused') return 1
return audit.arrivalsWithoutCriterion.length > 0 ? EXIT_MISSING_CRITERION : 0
}
/**
* Filenames under `standards/` present in the working tree and absent at
* `base`: a plain add, with rename detection forced off so a standard moved
* into the corpus from elsewhere counts the same as one authored fresh.
*/
async function arrivedStandards(
root: string,
base: string,
): Promise<Set<string> | undefined> {
const [added, untracked] = await Promise.all([
$`git -C ${root} diff --no-renames --name-only --diff-filter=A ${base} -- standards`
.env(gitEnv())
.quiet()
.nothrow(),
$`git -C ${root} ls-files --others --exclude-standard -- standards`
.env(gitEnv())
.quiet()
.nothrow(),
])
if (added.exitCode !== 0 || untracked.exitCode !== 0) return undefined
const paths = [
...added.text().split('\n'),
...untracked.text().split('\n'),
].filter(Boolean)
return new Set(paths.map((path) => basename(path)))
}
+1
-1
claude/.claude-plugin/plugin.json
{
"name": "aitk",
"description": "Automated governance, versioning, and discovery tools for Claude Code.",
"version": "3.29.1",
"version": "3.30.0",
"author": {

@@ -6,0 +6,0 @@ "name": "Eric Le",

+2
-1
docs/agents/commands.md

@@ -49,2 +49,3 @@ ---

| `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md` |
| `aitk standards audit` | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`) |
| `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`) |

@@ -87,3 +88,3 @@ | `aitk claude skills reach` | Report the shipped bodies citing a toolkit path no target project receives, exiting 2 on an unqualified one |

| `snippets` | `list`, `create` |
| `standards` | `list`, `<name>` |
| `standards` | `list`, `audit`, `<name>` |
| `gov` | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded` |

@@ -90,0 +91,0 @@ | `claude` | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`, `setup [dest]` |

+1
-0
docs/agents/index.md

@@ -36,2 +36,3 @@ ---

- [Citation reach](skills-reach.md): Reporting the shipped skill bodies that cite a path no target project receives, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
- [Standard success criteria](standards-audit.md): Reading the corpus against the Success criterion gate, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
- [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports

@@ -38,0 +39,0 @@ - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the exemption marker, the blind spot it cannot reach, and why it reports rather than gates

+1
-1
package.json
{
"name": "@erclx/aitk",
"type": "module",
"version": "3.29.1",
"version": "3.30.0",
"description": "Infrastructure and quality tooling for developer workflows",

@@ -6,0 +6,0 @@ "license": "MIT",

+17
-0
scripts/core/verify.sh

@@ -463,2 +463,19 @@ #!/usr/bin/env bash

# Scoped to arrival rather than the corpus, since standards/standard.md
# forbids writing a criterion into an existing standard outside the change
# that exercises it. Gating the 26 known gaps would fail every push until
# someone closed them all, which is the sweep that rule exists to prevent.
log_step "Standard success criteria"
local standards_output standards_status=0
standards_output=$(cd "$PROJECT_ROOT" && bun src/cli.ts standards audit --arrivals-only 2>&1) || standards_status=$?
if [ "$standards_status" -eq 0 ]; then
log_info "Arriving standards carry a success criterion"
elif [ "$standards_status" -eq 2 ]; then
echo "$standards_output" | pipe_output
log_error "A standard new to this branch carries no ## Success criterion section. Run bun src/cli.ts standards audit."
else
echo "$standards_output" | pipe_output
log_error "aitk standards audit could not read which standards arrived on this branch. Run bun src/cli.ts standards audit --json to see why."
fi
# `aitk sandbox coverage` moves only when a person runs it, so a scenario added

@@ -465,0 +482,0 @@ # with no expectation ships unnoticed. The gate is an absolute count of

+180
-2
src/commands/standards.ts

@@ -0,10 +1,31 @@

import { resolve } from 'node:path'
import type { Command } from 'commander'
import { registerPassThroughVerbs } from '@/commands/pass-through'
import {
auditExitCode,
auditStandards,
type StandardsAudit,
} from '@/standards/audit'
import { listStandards, readStandard, resolveStandard } from '@/standards/read'
import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
import {
frameError,
intro,
logError,
logInfo,
logStep,
logWarn,
outro,
pipeOutput,
plural,
} from '@/ui'
interface StandardsAuditOptions {
readonly json?: boolean
readonly arrivalsOnly?: boolean
}
export function register(program: Command): void {
const standards = program
.command('standards')
.description('Standards commands (list, <name>)')
.description('Standards commands (list, audit, <name>)')
.argument('[name]', 'Standard to print, by name with or without .md')

@@ -40,2 +61,37 @@ .helpOption('-h, --help', 'Show this help message')

registerPassThroughVerbs(standards, 'standards', ['list'])
standards
.command('audit')
.description(
'Report the corpus against the `## Success criterion` gate in standards/standard.md',
)
.argument('[path]', 'Project root, defaulting to the current directory')
.helpOption('-h, --help', 'Show this help message')
.option('--json', 'Add a machine-readable record on stdout')
.option(
'--arrivals-only',
'Run the gating check for standards new on this branch alone',
)
.addHelpText(
'after',
[
'',
'Exit codes:',
' 0 the audit completed with every arriving standard carrying the section',
' 1 refused, with the reason on stderr',
' 2 a standard new to this branch carries no ## Success criterion section',
'',
'A standard already in the corpus without the section is a known gap',
'standards/standard.md names, not a violation, so only an arrival fails.',
'',
'Examples:',
' aitk standards audit',
' aitk standards audit --json',
' aitk standards audit --arrivals-only',
'',
].join('\n'),
)
.action(async (path: string | undefined, opts: StandardsAuditOptions) => {
process.exitCode = await runStandardsAudit(path, opts)
})
}

@@ -71,1 +127,123 @@

}
/**
* Measures the corpus at the cwd rather than the toolkit root the catalog
* reads, so a linked worktree audits its own branch instead of `main`.
*/
async function runStandardsAudit(
path: string | undefined,
opts: StandardsAuditOptions,
): Promise<number> {
const root = resolve(path ?? process.cwd())
const gateOnly = opts.arrivalsOnly ?? false
const audit = await auditStandards(root)
if (audit.kind === 'refused') {
const message =
audit.reason === 'no-corpus'
? `No standards/ under ${root}.`
: audit.reason === 'no-base'
? 'No merge base against main resolved.'
: 'Could not read which standards arrived on this branch.'
if (gateOnly) {
frameError(message)
} else {
intro('aitk standards audit')
logStep('Refused')
logWarn(message)
outro()
}
if (opts.json) {
process.stdout.write(
`${JSON.stringify({ root, reason: audit.reason, message })}\n`,
)
}
return auditExitCode(audit)
}
if (gateOnly) {
reportArrivalGate(audit)
} else {
intro('aitk standards audit')
reportCorpus(audit)
outro()
}
if (opts.json) {
process.stdout.write(
`${JSON.stringify({
root,
base: audit.base,
standards: audit.standards,
withCriterion: audit.withCriterion,
withoutCriterion: audit.withoutCriterion,
arrivals: audit.arrivals,
arrivalsWithoutCriterion: audit.arrivalsWithoutCriterion,
})}\n`,
)
}
return auditExitCode(audit)
}
/**
* Prints nothing when every arriving standard carries the section.
*
* `--arrivals-only` is what `verify.sh` runs on every push, and that script
* pipes a stage's whole output into its own frame. A passing gate that
* printed its frame would nest one inside the other on every contributor's
* push.
*/
function reportArrivalGate(
audit: Extract<StandardsAudit, { kind: 'measured' }>,
): void {
const missing = audit.arrivalsWithoutCriterion
if (missing.length === 0) return
intro('aitk standards audit')
logError(
missing.length === 1
? '1 standard new to this branch carries no ## Success criterion section'
: `${missing.length} standards new to this branch carry no ## Success criterion section`,
)
pipeOutput(missing.join('\n'))
outro()
}
function reportCorpus(
audit: Extract<StandardsAudit, { kind: 'measured' }>,
): void {
logStep('Corpus')
logInfo(`${plural(audit.standards.length, 'standard')} at standards/`)
logInfo(
`${plural(audit.withCriterion.length, 'standard')} carrying ## Success criterion`,
)
logStep('Known gaps')
if (audit.withoutCriterion.length === 0) {
logInfo('None. Every standard carries the section.')
} else {
pipeOutput(audit.withoutCriterion.join('\n'))
}
logStep('Arrivals since main')
if (audit.arrivals.length === 0) {
logInfo('No standard new to this branch.')
return
}
if (audit.arrivalsWithoutCriterion.length === 0) {
logInfo(
`${plural(audit.arrivals.length, 'standard')} arrived, every one carrying the section.`,
)
return
}
logError(
`${plural(audit.arrivalsWithoutCriterion.length, 'standard')} arrived carrying no ## Success criterion section`,
)
pipeOutput(audit.arrivalsWithoutCriterion.join('\n'))
}
+2
-2
standards/design.md

@@ -21,3 +21,3 @@ ---

- Tokens described as intent ("mid gray, muted text"), not computed values. Exact values live in code.
- A token's exact value, anchored to the surface it was read from and tagged per `## The uncertainty tag` when unconfirmed. Fall back to intent language ("mid gray, muted text") only where no source exists yet to anchor from.
- Layout constraints and sizing rules not obvious from wireframes

@@ -29,3 +29,3 @@ - Visual rules a developer could get wrong without guidance

- CSS classes, computed values, component filenames, and prop names. Those live in code.
- CSS classes and prop names. Those live in code.
- Anything that needs updating every time the code is refactored

@@ -32,0 +32,0 @@