@erclx/aitk 3.29.1 → 3.31.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.31.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -10,6 +10,8 @@ Sweep the board as orchestrator after merging. Run this once per batch of merges
 3. Re-verify every plan already written, not only the ones this sweep writes. A queued plan goes stale from whatever merged while it waited, and the loop's verify step fires at handoff rather than after a merge, so nothing else catches it. Grep each construct the plan names and count the sites against its claim, then open each file rather than trusting its account.
 4. Re-check any precondition a plan states about live state outside the repository. A remote branch, an open issue, or an installed version was true when the plan was written and is not a fact about the tree.
 
+Run `aitk worktrees list` after the pull, which is the first point at which the merges this sweep followed are readable. It owns the reclaim rule and it removes nothing, so read its rows and act on the ones you mean to. Never substitute a git ancestry check for it.
+
 Run `aitk tasks validate` once the board is rewritten and before reporting it. It resolves every plan pointer, accounts every task file against the board and the backlog both, tests the `## Run now` file sets for overlap, and re-takes the two blocker kinds a command can settle. It reports and never writes, so fix each row it names and run it again. A finding it reports is a board defect rather than a task finding, so it goes nowhere but the board.
 
 Then run `orchestrator-parked.md` over the rows the validator listed as untested. Those carry the three blocker kinds no command settles, and the merge this sweep followed changed the tree under every one of them at once while the refill above re-read none. Take the untested rows alone rather than the whole board, since the validator already answered the rest.

package/docs/agents/commands.md

@@ -42,10 +42,12 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                           |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                              |
 | `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                       |
+| `aitk worktrees list`      | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                           |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                                               |
 | `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 +85,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,8 +33,10 @@ 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
 - [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
+- [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes

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/agents/worktrees.md

@@ -0,0 +1,62 @@
+---
+title: Worktrees
+description: Reporting which worktrees are reclaimable, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
+---
+
+# Worktrees
+
+## List
+
+`aitk worktrees list` reports every worktree of the current repository with a reclaim verdict and the reason behind it.
+
+```bash
+aitk worktrees list
+aitk worktrees list --json
+```
+
+| Option   | Behavior                                |
+| -------- | --------------------------------------- |
+| `--json` | Add a machine-readable record on stdout |
+
+It reads and removes nothing. The question it answers is which worktrees the work has finished with, which nothing in the loop asks: a worktree is created per feature and removed by nobody, so directories left by shipped work accumulate for the life of the checkout.
+
+Exit codes: `0` every worktree was read, `1` refused. The refusal carries a `reason` of `gh-missing`, `gh-failed`, or `sessions-unreadable`.
+
+An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `reason` rather than the exit when a skill consumes this.
+
+## What makes a worktree reclaimable
+
+All three hold: its branch has a merged pull request, its working tree is clean, and no live session holds the directory. Each alone has a case where removal loses something, so `refusals` names every failing condition rather than the first.
+
+| Refusal                  | What it means                                           |
+| ------------------------ | ------------------------------------------------------- |
+| `main-worktree`          | The main worktree, which is never reclaimable           |
+| `detached-head`          | No branch, so nothing names a pull request              |
+| `no-merged-pull-request` | Its branch has no merged pull request                   |
+| `uncommitted-changes`    | Work no history stands behind, untracked files included |
+| `unreadable-worktree`    | The working tree status could not be read               |
+| `held-by-session`        | A live session still holds the directory                |
+
+Uncommitted work is the condition that gates rather than warns. A worktree is gitignored scratch with no history behind it, so a directory removed with unstaged changes takes them somewhere nothing recovers.
+
+## Why the pull request rather than git ancestry
+
+Ancestry is the reading anyone reaches for and it fails in both directions on a repository that squash merges. A merged branch is never an ancestor of the trunk there, so `git merge-base --is-ancestor` calls shipped work unmerged. Measured against nine worktrees, it named five of six lingering branches unmerged, each of which had a merged pull request, reporting them 2 to 6 commits ahead.
+
+The one branch it did call merged was the one that had to stay. That branch had no pull request at all, sat at a release commit, and its worktree held finished work outside any commit. So the cheap test kept every directory safe to remove and offered the only one that was not.
+
+The read is one `gh pr list --state merged` for the whole repository rather than one call per worktree, which would be a network round trip inside a loop. It covers the most recent 200 merges, so a worktree older than that reads as having none and is refused, which fails in the direction that keeps a directory.
+
+## Two removal shapes
+
+`route` names which one applies rather than choosing it, since picking wrong strands state.
+
+- `session`: a live session holds the directory, and `claude rm <name>` removes the session and its worktree together. The `sessions` field carries the names, and a name is whatever string the session was launched under, spaces included, so quote it.
+- `worktree`: the session has ended, and `git worktree remove` with a branch delete is the pair.
+- `null`: the main worktree, which no removal shape reaches.
+
+A held worktree is refused rather than reported reclaimable, and its route is reported for whoever decides to act on it. Deleting a directory underneath a live session is the case that has to refuse.
+
+## What an unreadable input does
+
+It refuses the whole report rather than producing verdicts around the gap. An absent merge state and a branch with no merged pull request return the same empty answer, and so do an absent session roster and a worktree nobody holds. Reporting the second when it was the first is a false clean, and here that ends in a removal rather than in a warning.

package/package.json

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

@@ -27,6 +27,7 @@ import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
+import { register as worktrees } from '@/commands/worktrees'
 import { register as audits } from '@/commands/audits'
 import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
@@ -71,6 +72,7 @@ function showHelp(): void {
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
+    `${GREY}│${NC}    worktrees [cmd]    ${GREY}# Report which worktrees are reclaimable (list)${NC}`,
     `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
@@ -117,6 +119,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk records size --json`,
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
+    `${GREY}│${NC}    aitk worktrees list --json`,
     `${GREY}│${NC}    aitk secrets scan --json`,
     `${GREY}│${NC}    aitk deps audit --json`,
     `${GREY}│${NC}    aitk labels audit --json`,
@@ -167,6 +170,7 @@ context(program)
 markdown(program)
 records(program)
 sessions(program)
+worktrees(program)
 secrets(program)
 deps(program)
 labels(program)

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/commands/worktrees.ts

@@ -0,0 +1,191 @@
+import type { Command } from 'commander'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+import {
+  type Refusal,
+  reclaimReport,
+  type Unreadable,
+  type WorktreeVerdict,
+} from '@/worktrees/reclaim'
+
+interface ListCommandOptions {
+  readonly json?: boolean
+}
+
+const REFUSALS: Record<Refusal, string> = {
+  'main-worktree': 'the main worktree, which is never reclaimable',
+  'detached-head': 'detached HEAD, so no branch names a pull request',
+  'no-merged-pull-request': 'no merged pull request for its branch',
+  'uncommitted-changes': 'uncommitted work no history stands behind',
+  'unreadable-worktree': 'the working tree could not be read',
+  'held-by-session': 'a live session still holds it',
+}
+
+const UNREADABLE: Record<Unreadable, string> = {
+  'gh-missing':
+    'gh is not on the path, so the merge state could not be read. Install it and run this again.',
+  'gh-failed':
+    'The pull request read failed, so every worktree would report as unmerged whatever its real state. Authenticate gh and run this again.',
+  'sessions-unreadable':
+    'The session roster could not be read, so nothing was read about which worktrees are still held.',
+}
+
+export function register(program: Command): void {
+  const worktrees = program
+    .command('worktrees')
+    .description('Report which worktrees are reclaimable and which are not')
+    .helpOption('-h, --help', 'Show this help message')
+
+  worktrees
+    .command('list')
+    .description(
+      'Report every worktree with a reclaim verdict and the reason behind it',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every worktree was read',
+        '  1  refused, with the reason on stderr',
+        '',
+        'A worktree is reclaimable when all three hold: its branch has a merged',
+        'pull request, its working tree is clean, and no live session holds it.',
+        'Each alone has a case where removal loses something, so "refusals"',
+        'carries every failing condition rather than the first.',
+        '',
+        'The merged state comes from gh rather than from git ancestry. A',
+        'repository that squash merges never makes a merged branch an ancestor',
+        'of its trunk, so ancestry calls shipped work unmerged and calls an',
+        'abandoned branch sitting at a release commit merged.',
+        '',
+        'This reports and removes nothing. "route" names which removal shape',
+        'applies: "session" when a live session holds the directory, where',
+        '`claude rm <name>` takes the session and its worktree together, and',
+        '"worktree" when the session has ended, where `git worktree remove`',
+        'and a branch delete are the pair.',
+        '',
+        'An unreadable input refuses the whole reading rather than reporting',
+        'every worktree as not reclaimable, since an absent merge state and a',
+        'branch with no merged pull request produce the same empty answer.',
+        '',
+        'The merge read covers the most recent 200 merged pull requests. A',
+        'worktree older than that reads as having none and is refused, which',
+        'keeps a directory rather than removing one.',
+        '',
+        'Examples:',
+        '  aitk worktrees list',
+        '  aitk worktrees list --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ListCommandOptions) => {
+      process.exitCode = await runList(opts)
+    })
+}
+
+async function runList(opts: ListCommandOptions): Promise<number> {
+  const report = await reclaimReport({ cwd: process.cwd() })
+
+  intro('aitk worktrees list')
+
+  if (report.kind === 'unreadable') {
+    logStep('Refused')
+    logWarn(UNREADABLE[report.reason])
+    logInfo(report.detail)
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          reason: report.reason,
+          detail: report.detail,
+          worktrees: [],
+        })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportWorktrees(report.worktrees)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        reason: null,
+        detail: null,
+        worktrees: report.worktrees,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+function reportWorktrees(worktrees: readonly WorktreeVerdict[]): void {
+  logStep('Worktrees')
+
+  if (worktrees.length === 0) {
+    logInfo('No worktree resolved here. Run this inside a repository.')
+    return
+  }
+
+  logInfo(plural(worktrees.length, 'worktree'))
+  pipeOutput(worktrees.map(describe).join('\n'))
+
+  const reclaimable = worktrees.filter((entry) => entry.reclaimable)
+
+  logStep('Reclaimable')
+  if (reclaimable.length === 0) {
+    logInfo('None. Every worktree fails at least one condition.')
+    return
+  }
+
+  logWarn(
+    `${plural(reclaimable.length, 'worktree')} can be reclaimed. This reports and removes nothing, so run the named command yourself.`,
+  )
+}
+
+/**
+ * Names the evidence beside the conclusion on every row.
+ *
+ * The reading has two consumers and they act on different halves. The sweep
+ * reads the verdict to decide what to offer, and a person reads it to decide
+ * what to remove, so a row phrased for the first alone leaves the second
+ * removing a directory on a conclusion it cannot check.
+ */
+function describe(verdict: WorktreeVerdict): string {
+  const held = verdict.branch ?? 'detached'
+  const head = `${verdict.path}  ${held}`
+
+  if (!verdict.reclaimable) {
+    const reasons = verdict.refusals.map((refusal) => REFUSALS[refusal])
+    // A name is quoted because a session carries whatever string it was
+    // launched under, spaces included, and one command per name because a
+    // joined list reads as a single argument.
+    const routes =
+      verdict.route === 'session'
+        ? verdict.sessions.map(
+            (name) => `\n  Removal there goes through: claude rm '${name}'`,
+          )
+        : []
+    return `${head}\n  Refused: ${reasons.join('; ')}.${routes.join('')}`
+  }
+
+  return [
+    head,
+    `  Reclaimable. Pull request #${verdict.pullRequest} merged it, the tree is clean, and no session holds it.`,
+    `  Remove with: git worktree remove ${verdict.path} && git branch -D ${held}`,
+  ].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/src/worktrees/reclaim.ts

@@ -0,0 +1,306 @@
+import { $ } from 'bun'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+import {
+  repositoryOf,
+  type ResolvedSession,
+  resolveSessions,
+  type SessionReport,
+} from '@/sessions/resolve'
+import { listWorktrees, type WorktreeEntry } from '@/worktree'
+
+const GH_TIMEOUT_MS = 30_000
+
+/**
+ * How many merged pull requests one read covers. A worktree older than this
+ * many merges reads as having none and is refused, which is the safe direction:
+ * the failure keeps a directory rather than removing one.
+ */
+const MERGED_LIMIT = 200
+
+/** Why one worktree cannot be reclaimed, one entry per failing condition. */
+export type Refusal =
+  | 'main-worktree'
+  | 'detached-head'
+  | 'no-merged-pull-request'
+  | 'uncommitted-changes'
+  | 'unreadable-worktree'
+  | 'held-by-session'
+
+/** Why the whole reading was refused, so no verdict was produced at all. */
+export type Unreadable = 'gh-missing' | 'gh-failed' | 'sessions-unreadable'
+
+/**
+ * Which removal shape applies. `session` removes the background session and its
+ * worktree together, and `worktree` removes a directory whose session has
+ * ended. Picking the wrong one strands state, so this is reported rather than
+ * assumed.
+ */
+export type Route = 'session' | 'worktree'
+
+/** No removal shape reaches the main worktree, which is what `null` says. */
+export type RemovalRoute = Route | null
+
+export interface WorktreeVerdict {
+  readonly path: string
+  readonly branch: string | null
+  readonly reclaimable: boolean
+  /** Every failing condition, so a reader sees what to fix rather than a bare refusal. */
+  readonly refusals: readonly Refusal[]
+  /** The pull request that retired the branch, so a report can name what it read. */
+  readonly pullRequest: number | null
+  /** The names of the live sessions holding this worktree, which is what `claude rm` takes. */
+  readonly sessions: readonly string[]
+  readonly route: RemovalRoute
+}
+
+export interface MergedPullRequest {
+  readonly branch: string
+  readonly number: number
+}
+
+export type MergedReport =
+  | { readonly kind: 'read'; readonly merged: readonly MergedPullRequest[] }
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: Extract<Unreadable, 'gh-missing' | 'gh-failed'>
+      readonly detail: string
+    }
+
+export interface StatusReport {
+  /** False when the status read itself failed, so a clean `dirty` says nothing. */
+  readonly readable: boolean
+  readonly dirty: boolean
+}
+
+export type ReclaimReport =
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: Unreadable
+      readonly detail: string
+    }
+  | { readonly kind: 'read'; readonly worktrees: readonly WorktreeVerdict[] }
+
+export interface ReclaimOptions {
+  readonly cwd?: string
+  readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>
+  readonly mergedPullRequests?: (cwd: string) => Promise<MergedReport>
+  readonly worktreeStatus?: (path: string) => Promise<StatusReport>
+  readonly resolve?: () => Promise<SessionReport>
+}
+
+/**
+ * Reads the pull request state for the whole repository in one call.
+ *
+ * One call rather than one per worktree, since the per-worktree shape is a
+ * network round trip inside a loop and the branches being matched are already
+ * known before any of them runs.
+ */
+async function mergedPullRequests(cwd: string): Promise<MergedReport> {
+  if (Bun.which('gh') === null) {
+    return {
+      kind: 'unreadable',
+      reason: 'gh-missing',
+      detail: 'gh is not on the path, so no merge state could be read.',
+    }
+  }
+
+  const args = [
+    'pr',
+    'list',
+    '--state',
+    'merged',
+    '--limit',
+    String(MERGED_LIMIT),
+    '--json',
+    'headRefName,number',
+  ]
+
+  try {
+    // `gh` resolves its repository through git, so it reads the same
+    // resolution variables a hook exports and they take precedence over `cwd`.
+    // A run from inside one would answer with another repository's merged
+    // branches, and a branch name that recurs across repositories would then
+    // match a merge that happened somewhere else and read a live worktree as
+    // reclaimable, which is the unsafe direction on an unrecoverable removal.
+    const result = await execa('gh', args, {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    const rows = JSON.parse(result.stdout) as readonly {
+      headRefName: string
+      number: number
+    }[]
+
+    return {
+      kind: 'read',
+      merged: rows.map((row) => ({
+        branch: row.headRefName,
+        number: row.number,
+      })),
+    }
+  } catch (error) {
+    return {
+      kind: 'unreadable',
+      reason: 'gh-failed',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+/**
+ * Reports whether a worktree holds work no history is behind.
+ *
+ * Untracked files count, since a worktree is gitignored scratch and a directory
+ * removed with them takes them nowhere recoverable. A failed read is separated
+ * from a clean tree, because the two produce the same empty output and only one
+ * of them is safe to act on.
+ */
+async function worktreeStatus(path: string): Promise<StatusReport> {
+  const result = await $`git -C ${path} status --porcelain`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return { readable: false, dirty: false }
+
+  return { readable: true, dirty: result.stdout.toString().trim().length > 0 }
+}
+
+/**
+ * Names the live sessions holding one worktree.
+ *
+ * The path match is the direct reading and the branch match is what survives a
+ * path spelled differently on either side, such as a symlinked temporary
+ * directory. The branch half is scoped to the repository, since a branch name
+ * identifies a branch inside one and nothing across a machine.
+ */
+function holders(
+  entry: WorktreeEntry,
+  sessions: readonly ResolvedSession[],
+  repository: string | null,
+): readonly string[] {
+  return sessions
+    .filter(
+      (candidate) =>
+        candidate.worktree === entry.path ||
+        (entry.branch !== null &&
+          candidate.branch === entry.branch &&
+          candidate.repository === repository),
+    )
+    .map((candidate) => candidate.name)
+}
+
+function verdict(
+  entry: WorktreeEntry,
+  isMain: boolean,
+  status: StatusReport,
+  merged: ReadonlyMap<string, number>,
+  sessions: readonly ResolvedSession[],
+  repository: string | null,
+): WorktreeVerdict {
+  const held = holders(entry, sessions, repository)
+  const pullRequest =
+    entry.branch === null ? null : (merged.get(entry.branch) ?? null)
+  const refusals: Refusal[] = []
+
+  if (isMain) refusals.push('main-worktree')
+  if (entry.branch === null) refusals.push('detached-head')
+  else if (pullRequest === null) refusals.push('no-merged-pull-request')
+
+  if (!status.readable) refusals.push('unreadable-worktree')
+  else if (status.dirty) refusals.push('uncommitted-changes')
+
+  if (held.length > 0) refusals.push('held-by-session')
+
+  return {
+    path: entry.path,
+    branch: entry.branch,
+    reclaimable: refusals.length === 0,
+    refusals,
+    pullRequest,
+    sessions: held,
+    // No removal shape reaches the main worktree, and reporting one there
+    // offers a command whose only effect is to break the checkout. Deciding it
+    // here rather than in the reporter keeps the record and the framed output
+    // answering the same way, since the two consumers act on different halves.
+    route: isMain ? null : held.length > 0 ? 'session' : 'worktree',
+  }
+}
+
+/**
+ * Reports which worktrees are reclaimable and which are not, with the reason on
+ * each.
+ *
+ * Reclaimable means all three of a merged pull request, a clean working tree,
+ * and no live session holding the directory. Each alone has a case where
+ * removal loses something, and removal is unrecoverable here since a worktree
+ * is gitignored and no history stands behind it.
+ *
+ * The pull request is what decides the first condition rather than git
+ * ancestry. A repository that squash merges never makes a merged branch an
+ * ancestor of its trunk, so the ancestry reading calls shipped work unmerged
+ * and calls an abandoned branch sitting at a release commit merged, which is
+ * wrong in the one direction that removes a directory.
+ *
+ * An unreadable input refuses the whole reading rather than producing verdicts
+ * around it. An absent merge state and a branch with no merged pull request
+ * produce the same empty answer, as do an absent session roster and a worktree
+ * nobody holds, and reporting the second when it was the first is a false clean
+ * that ends in a removal.
+ */
+export async function reclaimReport(
+  opts: ReclaimOptions = {},
+): Promise<ReclaimReport> {
+  const cwd = opts.cwd ?? process.cwd()
+  const listAll = opts.listWorktrees ?? listWorktrees
+  const readMerged = opts.mergedPullRequests ?? mergedPullRequests
+  const readStatus = opts.worktreeStatus ?? worktreeStatus
+  const resolve = opts.resolve ?? resolveSessions
+
+  const [entries, merged, sessions, repository] = await Promise.all([
+    listAll(cwd),
+    readMerged(cwd),
+    resolve(),
+    repositoryOf(cwd),
+  ])
+
+  if (merged.kind === 'unreadable') {
+    return {
+      kind: 'unreadable',
+      reason: merged.reason,
+      detail: merged.detail,
+    }
+  }
+
+  if (sessions.kind !== 'resolved') {
+    return {
+      kind: 'unreadable',
+      reason: 'sessions-unreadable',
+      detail: `No session registry at ${sessions.dir}, so nothing was read about which worktrees are still held.`,
+    }
+  }
+
+  const byBranch = new Map(
+    merged.merged.map((request) => [request.branch, request.number]),
+  )
+  const statuses = await Promise.all(
+    entries.map((entry) => readStatus(entry.path)),
+  )
+
+  // `git worktree list` puts the main worktree first, which is the only signal
+  // separating it from a linked one in the porcelain output.
+  const worktrees = entries.map((entry, index) =>
+    verdict(
+      entry,
+      index === 0,
+      statuses[index] ?? { readable: false, dirty: false },
+      byBranch,
+      sessions.sessions,
+      repository,
+    ),
+  )
+
+  return { kind: 'read', worktrees }
+}

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