@erclx/aitk 3.29.0 → 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.0",
+  "version": "3.30.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator dispatch runbook
-description: The collision check before a self-dispatch, the worker cap, the launch command, and the loop's stopping condition
+description: The collision check before a self-dispatch, the worker cap, the branch and model the launch names, and the loop's stopping condition
 ---
 
 Run this at loop step 4, for a `## Run now` row whose plan is verified and whose file set has already cleared the Parallelism test against every track in flight, in place of handing the worktree to a human.
@@ -9,15 +9,27 @@ Run this at loop step 4, for a `## Run now` row whose plan is verified and whose
 
 Resolve `<slug>` from the row's plan the way `claude-worktree` Step 2 resolves a plan-matched name, per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Resolve `<type>` off that plan's `## Summary` and `**Files to touch:**` lines, per `${CLAUDE_SKILL_DIR}/../../standards/branch.md`, defaulting to `feat` when the lines settle nothing. The candidate branch is `<type>/<slug>`.
 
+This is the branch the worker takes, not a guess at one it will derive for itself. Carry the exact string into the launch below. Both halves of that derivation have already disagreed in production: one run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, and a later one checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`. A check against a branch nobody uses verifies nothing, and the run dies anyway, since `claude-autoship` resolves its plan from the slug the worker actually took.
+
 ## Check the branch is unclaimed
 
 Run `aitk sessions list --branch <type>/<slug> --json` and read `claimed` off the record.
 
-- `claimed: true`: the row is not free. Report what holds it, `worktree` when it names a path and `sessions` when it carries a row, and move to the next candidate rather than colliding.
-- `claimed: false` and `sessionsReadable: true`: proceed to the cap check.
-- `claimed: false` and `sessionsReadable: false`, or the command refuses, or the record carries no `claimed` key (`reason` reads `no-registry` or `no-repository`): treat the candidate as unverified rather than clear. Report the refusal and fall back to the human-launch line below. Dispatching on a check that could not be read reproduces the exact collision this exists to prevent.
+- `claimed: true`: the row is not free. Report what holds it, `worktree` when it names a path, `sessions` when it carries a row, and `refs` when the branch already exists. Move to the next candidate rather than colliding.
+- `claimed: false`, `sessionsReadable: true`, and `refsReadable: true`: proceed to the cap check.
+- `claimed: false` with either flag false, or the command refuses, or the record carries no `claimed` key (`reason` reads `no-registry` or `no-repository`): treat the candidate as unverified rather than clear. Report which reading could not be taken and fall back to the human-launch line below. Dispatching on a check that could not be read reproduces the exact collision this exists to prevent.
+
+Reading `claimed` off the record is what keeps this a check rather than a rule a session can talk itself out of. The field is already the composed answer across the worktree listing, the live session roster, and the refs that name the branch, so nothing here re-derives the OR.
+
+`refs` is the reading that catches a shipped row. A branch behind a merged pull request has no worktree and no session, so the check answered clear on one until a worker refused the instruction and named the consequences: a second pull request against a head GitHub already shows merged, a row whose pull-request line points at two numbers, and the `ambiguous` refusal `aitk tasks archive` documents.
+
+What the ref read cannot see is a branch pushed from another machine since the last fetch, because it reads the remote-tracking ref rather than the remote. Nobody has hit that, and a `git ls-remote` per dispatch costs 0.438s against 0.001s, so the gap is recorded rather than closed.
+
+## Hold what this pass already launched
+
+A worker registers with `branch: main` and the main worktree as its `cwd` until `claude-autoship` Step 0 moves it, which took several seconds on both measured runs. Neither the roster nor the refs name the candidate during that window, so a second check inside it reads clear.
 
-Reading `claimed` off the record is what keeps this a check rather than a rule a session can talk itself out of. The field is already the composed answer across the worktree listing and the live session listing, so nothing here re-derives the OR.
+Keep the branch of every row this pass has launched and treat a candidate matching one as claimed, without re-running the check. That closes the window for this dispatcher and only for it. A second dispatcher in another session reads git and the roster alone, sees none of this record, and can still take the same row. Say so when reporting, rather than implying the window is shut.
 
 ## Check the worker cap
 
@@ -25,15 +37,25 @@ Run `aitk sessions list --json` with no `--branch`, then count entries whose `na
 
 Three already out: report the cap and stop dispatching for this pass, leaving the row ready for the next one. The cap binds the self-dispatch path alone, since the evidence behind it is one task shipped once and the operator's own launches stay uncapped by count.
 
+## Pick the model
+
+A `claude --bg` session inherits the model of whatever launched it rather than reading the machine's configured default. That was measured on 2026-08-27, with `~/.claude/settings.json` set to `sonnet` while both dispatched workers ran `claude-opus-5`. An orchestrator on the larger model therefore spends it on every worker it launches, and the operator who set the default never sees the override.
+
+Name `<model>` on the launch, and pick it against the task rather than copying whatever this session happens to run. Sizing the model to the row is the dispatcher's call, the same call it already makes on the branch. A mechanical row moving files under a written plan is not the row that needs the largest model, and one whose plan carries an open judgment is.
+
 ## Dispatch
 
 ```bash
-claude --bg -n "orchestrator-<slug>" "/aitk:claude-autoship .claude/tasks/<task-file>.md"
+claude --bg --model <model> -n "orchestrator-<slug>" "Run /aitk:claude-worktree <type>/<slug>, then /aitk:claude-autoship .claude/tasks/<task-file>.md"
 ```
 
-`claude-autoship`'s own Step 0 enters the worktree, so this session never does. `--bg, --background` starts the session as a background agent and returns immediately, and `-n, --name` sets the display name `aitk sessions list` reads back for the worker cap.
+`--bg, --background` starts the session as a background agent and returns immediately, `-n, --name` sets the display name `aitk sessions list` reads back for the worker cap, and `--model` overrides the inheritance the section above measured.
+
+The worktree call comes first and carries the branch as its argument, which is tier 0 of `claude-worktree` Step 2 and the only tier a caller can reach. `claude-autoship` Step 0 then finds the session already in a linked worktree and continues, which is a path it already documents. Autoship still resolves its plan, since the slug inside a dispatcher-named `<type>/<slug>` is the slug the dispatcher read off that plan.
+
+Naming the branch in prose instead was tried and closes nothing, because no tier of that ladder reads the prompt. A worker launched onto `main` cannot match tier 1, a board carrying more than one plan puts tier 2 out of reach, and tier 3 tells it to ask a person who is not there. Four workers took the right branch that way, by inference rather than by contract, which is the same judgment both live disagreements came from.
 
-Report the dispatch as loudly as the human-launch line it replaces: name the branch, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
+Report the dispatch as loudly as the human-launch line it replaces: name the branch, the model, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
 
 ## Fall back to the human
 

package/claude/skills/claude-worktree/SKILL.md

@@ -34,6 +34,7 @@ The directory test separates the defect from a genuinely bare repository, which
 
 Try each source in order. Stop at the first match.
 
+0. **Caller-supplied.** The invocation carried an argument. Take it as the name and infer nothing further. Accept `<name>` or `<type>/<name>`, where a leading segment matching a type in `${CLAUDE_SKILL_DIR}/../../standards/branch.md` sets `<type>` and the rest is `<name>`. A bare `<name>` falls to the default type below.
 1. **Plan matched to current branch.** Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. An empty result falls through to the next source here rather than becoming `latest`, since the slug is one candidate among several. If `<main-root>/.claude/plans/feature-<slug>.md` exists, use `<slug>`.
 2. **Single plan file.** List `<main-root>/.claude/plans/feature-*.md`. If exactly one match, derive `<slug>` from the filename.
 3. **Multiple plan files, no branch match.** Ask the user which plan. Show the candidate slugs as a numbered list. Do not pick.
@@ -41,22 +42,28 @@ Try each source in order. Stop at the first match.
    4b. **Session context.** When on `main` or `master` with no matching plan, read the current conversation to infer a kebab slug from the topic being discussed. Propose it: `Infer: <slug>. Confirm or rename?` Do not enter the worktree until the user confirms or provides a corrected name.
 5. **Ask.** None of the above applies. Ask the user for a name. Do not invent one.
 
+Tier 0 sits ahead of the inference because every tier below it answers from state the caller cannot set, and a caller that already knows the name has no way to say so. That gap is what a dispatched worker meets. It starts on `main`, so tier 1 cannot match, and a board carrying more than one plan puts tier 2 out of reach too, which lands the run on tier 3 and its instruction to ask somebody who is not there. A prompt naming the branch does not reach any of them, since no tier reads the prompt.
+
 Validate the result: letters, digits, dots, underscores, dashes only, max 64 chars (`/` separators are also allowed). If the derived name violates the rule, sanitize by replacing invalid chars with `-` and truncating. Show the sanitized name in the preview before invoking.
 
-Resolve `<type>` here as well, since Step 3 previews it and Step 5 renames onto it. A name from a plan takes the type that plan's own work carries, read off its `## Summary` and `**Files to touch:**` lines. Every other case takes `feat`, which covers a name from a branch, a name from the user, and a plan whose lines settle nothing. Draw the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`.
+Resolve `<type>` here as well, since Step 3 previews it and Step 5 renames onto it, drawing the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. A type the caller spelled in tier 0 wins outright and no reading overrides it. A name from a plan takes the type that plan's own work carries, read off its `## Summary` and `**Files to touch:**` lines. Every other case takes `feat`, which covers a name from a branch, a bare name from the user, and a plan whose lines settle nothing.
+
+The caller's type wins because reading it off a plan is the half that has already disagreed in production. One dispatch checked `fix/path-form-hook` and the worker took `feat/path-form-hook`, both sides reading the same plan and grading it differently.
 
 A wrong type is cheap. `git-branch` renames to conventional format later in the same chain and runs ahead of `git-pr`, so a `feat/` written over a fix is corrected before any pull request opens.
 
 Then test both names the entry is about to claim. Neither read needs a worktree, and a stop after Step 4 leaves one built with the session sitting inside it, so both belong here rather than beside the rename:
 
-- Branch. `git show-ref --verify --quiet refs/heads/<type>/<name>` succeeding means the ref exists. Stop: `❌ Branch <type>/<name> already exists. Resolve manually before continuing.`
+- Branch. `git for-each-ref --format='%(refname)' refs/heads/<type>/<name> refs/remotes/origin/<type>/<name>` printing any ref means the name is taken. Stop: `❌ Branch <type>/<name> already exists. Resolve manually before continuing.` A non-zero exit is a read that failed rather than a free name, so stop on that too and say the read failed.
 - Directory. `<main-root>/.claude/worktrees/<name>/` existing means an earlier entry claimed the name. Stop: `❌ Worktree .claude/worktrees/<name>/ already exists. Resolve manually before continuing.`
 
 Leave both in place. Resolving either automatically risks the wrong one.
 
 The two tests catch different collisions. The branch test misses the one `${CLAUDE_SKILL_DIR}/../../standards/slug.md` records, where two branches differing only in type collapse onto one name: `feat/foo` and `fix/foo` are distinct refs and reach one directory. The directory test is the only read that sees it.
 
-The branch test fires on the tier 1 and tier 4 sources whenever the branch the session started on is already conventional, since a name derived from that branch resolves back onto it. Stopping is the answer there. The concern already has a branch, git refuses a second under the same name, and the bare-name rename this replaces only carried the collision forward to the `git-branch` step.
+The branch test fires on the tier 1 and tier 4 sources whenever the branch the session started on is already conventional, since a name derived from that branch resolves back onto it. Stopping is the answer there. The concern already has a branch, git refuses a second under the same name, and the bare-name rename this replaces only carried the collision forward to the `git-branch` step. It fires on tier 0 as well, where a caller handed a name something already holds.
+
+It reads both ref spaces rather than the local head alone, and it reads them the way `checkClaim` does, so a name this skill clears and a branch a dispatcher cleared are one answer. `git show-ref --verify` is what that replaces. It sees no remote-tracking ref, so a branch pushed from elsewhere passed the test and collided at the first push, and its exit code cannot separate an absent ref from a tree it could not read, which reports a failed read as a free name.
 
 ## Step 3: preview
 

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/sessions.md

@@ -36,13 +36,15 @@ The match can return more than one session. Read the count rather than the first
 
 ## Whether a branch is already claimed
 
-With `--branch`, the JSON record also carries `worktree` (the path of any worktree already checked out to it, or `null`) and `claimed` (`true` when either a worktree or a live session already holds the branch).
+With `--branch`, the JSON record also carries `worktree` (the path of any worktree already checked out to it, or `null`), `refs` (the refs that already name the branch, the local head and the `origin` remote-tracking ref alike), and `claimed` (`true` when any of the three holds it).
 
-Read `claimed` rather than composing the two fields by hand. A worktree can outlive the session that made it, and a session can hold a branch before a worktree exists for it, so either field alone can miss a real claim. A dispatcher deciding whether it is safe to start a build against a branch reads this one field instead of re-deriving the OR itself.
+Read `claimed` rather than composing the three fields by hand. A worktree can outlive the session that made it, and a session can hold a branch before any worktree exists for it. A branch sitting behind a merged pull request has neither and is taken all the same, which is the reading that was missing when a dispatcher cleared a merged branch and told a worker to build on it.
 
-`worktree` and `claimed` are `null` on a bare run with no `--branch`, since neither question has a branch to answer about. A refusal (`no-registry` or `no-repository`) carries neither key at all, which a caller should read as unverified rather than as clear.
+The ref read covers the local head and the remote-tracking ref, which means it sees the remote at whatever the last fetch left behind. A branch pushed from another machine since then reads absent. Closing that gap needs `git ls-remote`, and it is left open deliberately: the remote read costs 0.438s against 0.001s for the local one, on a check that runs before every dispatch.
 
-`sessionsReadable` is `false` when the session roster could not be read, which leaves `claimed` covering the worktree half alone. A `false` here is a report that ran short of evidence, not a report that the branch is clear, so a caller reads it as unverified alongside `claimed` rather than trusting `claimed` on its own.
+`worktree`, `refs`, and `claimed` are `null` on a bare run with no `--branch`, since none of the three questions has a branch to answer about. A refusal (`no-registry` or `no-repository`) carries none of the keys at all, which a caller should read as unverified rather than as clear.
+
+Two flags say which reading came up short. `sessionsReadable` is `false` when the session roster could not be read, and `refsReadable` is `false` when the ref read failed. Either one leaves `claimed` covering the readings around it alone, so a `false` there is a report that ran short of evidence rather than a report that the branch is clear. They stay separate fields because a caller told the roster failed goes and looks at the roster, and folding both into one flag would send it to the wrong place.
 
 ## Why the verb exists
 

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/docs/operating-model.md

@@ -37,7 +37,7 @@ and no later session recovers that vantage.
 One feature travels this path end to end.
 
 1. Orchestrator plans the next feature with `claude-feature`, writing a plan to `.claude/plans/`. Planning stays in the warm session because good planning is cross-feature. It needs the contract other features consume and the shared wiring seam. A cold session would re-derive or guess.
-2. Orchestrator checks the branch is unclaimed and the worker cap has room, then dispatches a background worker with `claude --bg` against the plan. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the check refuses, the cap is reached, or the plan collides with a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
+2. Orchestrator checks the branch is unclaimed and the worker cap has room, then dispatches a background worker with `claude --bg` against the plan, naming the branch and the model on the launch rather than leaving the worker to derive either. The branch travels as the argument to the worker's own worktree call, which is the one place the name is read rather than inferred. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the check refuses, the cap is reached, or the plan collides with a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
 3. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
 4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `aitk sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.
 5. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds anything and under `## Review closed` when it finds nothing, so a reader learns from the heading whether work is still owed and takes the merge decision from the counts on the line under it. Repeat from step 4 until a pass closes the review.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.29.0",
+  "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/indexes.ts

@@ -3,6 +3,7 @@ import { dirname, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
 import { exitCodeFor, type RegenResult, regenOne } from '@/indexes/regen'
+import { gitEnv } from '@/git-env'
 import { findIndexedAncestor, isIgnored, listIndexes } from '@/indexes/walk'
 import { intro, logAdd, logInfo, logStep, logWarn, outro } from '@/ui'
 
@@ -164,6 +165,7 @@ async function stage(path: string, rel: string, root: string): Promise<void> {
   if (await isIgnored(root, path)) return
 
   const staged = await $`git -C ${root} add -- ${path}`
+    .env(gitEnv())
     .quiet()
     .nothrow()
     .then((result) => result.exitCode === 0)

package/src/commands/sessions.ts

@@ -60,17 +60,23 @@ export function register(program: Command): void {
         'so a caller filtering by hand has something that identifies one.',
         '',
         'With --branch, the JSON also carries "worktree" (the path of any',
-        'worktree already checked out to it, or null) and "claimed" (true when',
-        'either a worktree or a live session already holds it). A dispatcher',
-        'reads "claimed" rather than composing the two fields itself, since',
-        'either one alone can miss a real claim: a worktree can outlive the',
-        'session that made it, and a session can hold a branch before a',
-        'worktree exists for it.',
+        'worktree already checked out to it, or null), "refs" (the refs that',
+        'already name it, local head and origin remote-tracking alike), and',
+        '"claimed" (true when a worktree, a live session, or an existing ref',
+        'holds it). A dispatcher reads "claimed" rather than composing the',
+        'three fields itself, since each alone misses a real claim: a worktree',
+        'can outlive the session that made it, a session can hold a branch',
+        'before a worktree exists for it, and a branch behind a merged pull',
+        'request has neither while still being taken.',
         '',
-        '"sessionsReadable" is false when the session roster could not be read,',
-        'which leaves "claimed" covering the worktree half alone. Treat that',
+        '"sessionsReadable" is false when the session roster could not be read',
+        'and "refsReadable" is false when the ref read failed. Either one',
+        'leaves "claimed" covering the readings around it alone. Treat that',
         'case as unverified rather than as a clean "false".',
         '',
+        'The ref read sees the remote at whatever the last fetch left, so a',
+        'branch pushed from another machine since then reads absent here.',
+        '',
         'The match can return more than one session. Read the count rather than',
         'the first row, since two sessions can hold one branch.',
         '',
@@ -166,8 +172,10 @@ async function runList(opts: ListCommandOptions): Promise<number> {
         branch: opts.branch ?? null,
         repository,
         worktree: claim?.worktree ?? null,
+        refs: claim?.refs ?? null,
         claimed: claim?.claimed ?? null,
         sessionsReadable: claim?.sessionsReadable ?? null,
+        refsReadable: claim?.refsReadable ?? null,
         sessions: shown,
       })}\n`,
     )
@@ -261,11 +269,21 @@ function reportClaim(claim: ClaimReport): void {
     logInfo(`Worktree: ${claim.worktree}`)
   }
 
+  if (claim.refs.length > 0) {
+    logInfo(`Refs: ${claim.refs.join(', ')}`)
+  }
+
   logInfo(claim.claimed ? 'Claimed.' : 'Unclaimed.')
 
   if (!claim.sessionsReadable) {
     logWarn(
-      'The session roster could not be read, so this reads the worktree listing alone. Treat the session half as unverified rather than clear.',
+      'The session roster could not be read, so this leaves the session half out. Treat it as unverified rather than clear.',
+    )
+  }
+
+  if (!claim.refsReadable) {
+    logWarn(
+      'The ref read failed, so this cannot say whether the branch already exists. Treat it as unverified rather than clear.',
     )
   }
 }

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/sessions/claim.ts

@@ -4,26 +4,41 @@ import {
   type ResolvedSession,
   type SessionReport,
 } from '@/sessions/resolve'
-import { listWorktrees, type WorktreeEntry } from '@/worktree'
+import {
+  branchRefs,
+  listWorktrees,
+  type RefReport,
+  type WorktreeEntry,
+} from '@/worktree'
 
 export interface ClaimReport {
   readonly claimed: boolean
   readonly worktree: string | null
   readonly sessions: readonly ResolvedSession[]
-  /** False when the session roster could not be read, so `claimed` covers the worktree half alone and cannot be trusted as a clean "unclaimed". */
+  /** The refs already naming the branch, local head and `origin` remote-tracking alike. */
+  readonly refs: readonly string[]
+  /** False when the session roster could not be read, so `claimed` covers the readings around it alone and cannot be trusted as a clean "unclaimed". */
   readonly sessionsReadable: boolean
+  /** False when the ref read failed, which is the same false clean under a different reading. */
+  readonly refsReadable: boolean
 }
 
 export interface ClaimOptions {
   readonly cwd?: string
   readonly resolve?: () => Promise<SessionReport>
   readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>
+  readonly branchRefs?: (branch: string, cwd: string) => Promise<RefReport>
 }
 
 /**
- * Answers whether a branch is already claimed, composing the two readings
- * neither surface can answer alone: a worktree can outlive the session that
- * made it, and a session can hold a branch before a worktree exists for it.
+ * Answers whether a branch is already claimed, composing the three readings no
+ * one surface can answer alone: a worktree can outlive the session that made
+ * it, a session can hold a branch before a worktree exists for it, and a branch
+ * behind a merged pull request has neither while still being taken.
+ *
+ * The two readable flags stay separate because a caller told the roster failed
+ * looks at the roster. Folding either into `claimed` would report the failure
+ * as a clean "unclaimed", which is the answer this exists to stop giving.
  */
 export async function checkClaim(
   branch: string,
@@ -32,11 +47,13 @@ export async function checkClaim(
   const cwd = opts.cwd ?? process.cwd()
   const resolve = opts.resolve ?? resolveSessions
   const listAll = opts.listWorktrees ?? listWorktrees
+  const readRefs = opts.branchRefs ?? branchRefs
 
-  const [repository, worktrees, report] = await Promise.all([
+  const [repository, worktrees, report, refs] = await Promise.all([
     repositoryOf(cwd),
     listAll(cwd),
     resolve(),
+    readRefs(branch, cwd),
   ])
 
   const worktree =
@@ -51,9 +68,11 @@ export async function checkClaim(
       : []
 
   return {
-    claimed: worktree !== null || sessions.length > 0,
+    claimed: worktree !== null || sessions.length > 0 || refs.refs.length > 0,
     worktree,
     sessions,
+    refs: refs.refs,
     sessionsReadable: report.kind === 'resolved',
+    refsReadable: refs.readable,
   }
 }

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/src/sync/git.ts

@@ -1,5 +1,6 @@
 import { basename } from 'node:path'
 import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
 import type { SyncDomain } from '@/sync/target'
 import { pipeOutput } from '@/ui'
 
@@ -186,13 +187,27 @@ export async function hasGh(): Promise<boolean> {
   return result.exitCode === 0
 }
 
+/**
+ * Both seams strip git's repository-resolution variables, since a hook exports
+ * `GIT_DIR` into every process it runs and it beats `-C`. A sync driven from
+ * inside one would otherwise read the hook's repository and, through `mutate`,
+ * commit and push into it.
+ */
 async function read(target: string, args: readonly string[]): Promise<string> {
-  const result = await execa('git', ['-C', target, ...args], { reject: false })
+  const result = await execa('git', ['-C', target, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
   return result.exitCode === 0 ? result.stdout : ''
 }
 
 async function mutate(target: string, args: readonly string[]): Promise<void> {
-  const result = await execa('git', ['-C', target, ...args], { reject: false })
+  const result = await execa('git', ['-C', target, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
 
   if (result.exitCode !== 0) {
     throw new GitCommandError(

package/src/worktree.ts

@@ -50,6 +50,59 @@ export interface WorktreeEntry {
   readonly branch: string | null
 }
 
+export interface RefReport {
+  /** False when the ref read itself failed, so an empty `refs` says nothing about whether the branch exists. */
+  readonly readable: boolean
+  readonly refs: readonly string[]
+}
+
+/**
+ * Reports which of the local head and the `origin` remote-tracking ref already
+ * name a branch, separating an absent branch from a read that failed.
+ *
+ * `git for-each-ref` is what carries that separation. `git show-ref --verify`
+ * handed the same two ref paths exits 128 when one of them is missing, which is
+ * the code it also exits when the directory is no repository, so a caller
+ * cannot tell a half match from an unreadable tree. `for-each-ref` exits zero
+ * with empty output for absent and non-zero only for a failed read.
+ *
+ * A ref path is a pattern here rather than an exact name, so `refs/heads/x`
+ * also matches `refs/heads/x/y`. Git forbids both existing at once, so the
+ * over-match names the branch that blocks the candidate rather than a wrong
+ * one.
+ *
+ * The remote-tracking ref is read at whatever the last fetch left, so a branch
+ * pushed from another machine since then is invisible here. Closing that needs
+ * `git ls-remote`, measured at 0.438s against 0.001s for a local read.
+ */
+export async function branchRefs(
+  branch: string,
+  cwd: string = process.cwd(),
+): Promise<RefReport> {
+  // Every argument is interpolated rather than written inline, since Bun's
+  // shell parses the bare parentheses in `%(refname)` as syntax of its own.
+  const args = [
+    '--format=%(refname)',
+    `refs/heads/${branch}`,
+    `refs/remotes/origin/${branch}`,
+  ]
+
+  const result = await $`git -C ${cwd} for-each-ref ${args}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return { readable: false, refs: [] }
+
+  return {
+    readable: true,
+    refs: result.stdout
+      .toString()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0),
+  }
+}
+
 /**
  * Parses `git worktree list --porcelain`, which emits one block per worktree
  * separated by a blank line. A detached worktree carries no `branch` line,

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