@erclx/aitk 3.29.1 → 3.30.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.29.1",
+  "version": "3.30.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -46,6 +46,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                            |
 | `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                               |
 | `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`)                            |
 | `aitk claude skills reach` | Report the shipped bodies citing a toolkit path no target project receives, exiting 2 on an unqualified one                                                          |
 | `aitk claude skills rank`  | Score the shipped catalog's descriptions against a hand-authored case corpus by TF-IDF cosine similarity, reporting rank-one and top-three                           |
@@ -83,7 +84,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                                                |
 | `snippets`  | `list`, `create`                                                                                                                      |
-| `standards` | `list`, `<name>`                                                                                                                      |
+| `standards` | `list`, `audit`, `<name>`                                                                                                             |
 | `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                               |
 | `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`, `setup [dest]` |
 | `demo`      | `compile`, `run`                                                                                                                      |

package/docs/agents/index.md

@@ -33,6 +33,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [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
 - [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
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree

package/docs/agents/standards-audit.md

@@ -0,0 +1,38 @@
+---
+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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.29.1",
+  "version": "3.30.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/verify.sh

@@ -460,6 +460,23 @@ main() {
   run_check "cd $PROJECT_ROOT && bun src/cli.ts claude skills audit --requirements-only" "A skill folder carries no REQUIREMENT.md. Run bun src/cli.ts claude skills audit."
   log_info "Skill requirements present"
 
+  # 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
   # with no expectation ships unnoticed. The gate is an absolute count of
   # undeclared scenarios rather than a ratio or a floor under the declared count.

package/src/commands/standards.ts

@@ -1,12 +1,33 @@
+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')
     .helpOption('-h, --help', 'Show this help message')
     .addHelpText(
@@ -37,6 +58,41 @@ export function register(program: Command): void {
     })
 
   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)
+    })
 }
 
 /**
@@ -67,3 +123,125 @@ function print(name: string): number {
   outro()
   return 0
 }
+
+/**
+ * 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'))
+}

package/src/standards/audit.ts

@@ -0,0 +1,132 @@
+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)))
+}

package/standards/design.md

@@ -18,14 +18,14 @@ Does not govern:
 
 ## What goes in
 
-- 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
 - Visual rules a developer could get wrong without guidance
 - Non-obvious omissions ("no motion", "no custom icons") that prevent scope creep
 
 ## What does not go in
 
-- 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
 
 ## Format