@erclx/aitk 0.104.0 → 0.105.0

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

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

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

@@ -227,6 +227,10 @@ A board carrying one task written `../plans/x.md` and another written `.claude/p
 
 Exclude the closing task explicitly. It sits on the board and cites the plan itself, so a scan that counts it never reaches zero and no plan is ever archived.
 
+`aitk tasks plan-citations <stem> --json` answers this same question, and the archive gate already reads it. This body states the rule anyway rather than calling the verb, because a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes, so a target whose installed `aitk` predates the verb gets no record back and routes on nothing. Measured against the `claude:docs` `board-sweep` arm, where calling the verb archived neither plan and created no `.claude/plans-archive/`.
+
+Nothing in the exit code reports that. Branch on the record's `ok` and `reason` fields and never on the exit, which is the rule every task verb already carries: an operator's shell profile may wrap `aitk` in a function that runs the binary and then another command, taking its status from the second, and one measured here masks every non-zero exit rather than only an absent verb. The binary itself exits 1 for an unknown subcommand and 1 for an ordinary refusal alike. Switching this body to the verb needs a release that carries it and a read of the record rather than the exit, which together retire the duplication.
+
 A plan can serve more than one task, and archiving on the first task to close strands every other task's pointer at a path that has moved. `.claude/plans/` is gitignored, so that retarget would be the only record and there is nothing to recover it from.
 
 - Target resolves inside `.claude/plans/`, the file exists, and no other task file cites it: create `.claude/plans-archive/`, move the file there under its original name, overwriting any file already sitting at that name. Then rewrite the task file's `Plan:` line to the archive path, so a completed task still leads to the reasoning behind it.

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

@@ -21,7 +21,8 @@ Read `.claude/standards/groundwork.md` from the project root before writing any
 
 - Write only inside `.claude/groundwork/<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
 - One exception, at close only: write one task file recording what the track concluded.
-- A second exception, for experiments: write a fixture a spike needs under `.claude/.tmp/groundwork-fixtures/<slug>/`. Keep it out of `.claude/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
+- A second exception, for what a spike reads: write an input under `.claude/.tmp/groundwork-fixtures/<slug>/`. Keep it out of `.claude/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
+- What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.claude/groundwork/<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
 - Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
 - Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
 - Treat the folder as gitignored and unbacked. It dies with the machine, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
@@ -36,7 +37,7 @@ A track may run an experiment to settle an open question without stopping to ask
 
 A fixture a headless run is pointed at goes outside the repository, under `mktemp -d`, and never under `.claude/.tmp/`. A session started anywhere beneath the project root loads that project's `CLAUDE.md`, `.claude/rules/`, and `.claude/standards/` through the ancestor chain, so an in-repo fixture measures the repository instead of the arm. Record the fixture as contaminated and re-run it outside if this is discovered after the fact, because the result reads as evidence either way.
 
-Record method, result, measured cost, and caveats in `08-spikes.md`. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
+Record method, result, measured cost, and caveats in `08-spikes.md`. Put whatever the run produced that the record cites in `evidence/` beside it, so a reader checking a claim opens the artifact rather than taking the prose for it. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
 
 ## Step 1: detect the mode
 

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

@@ -113,9 +113,14 @@ The last line is what keeps the step honest on a stack this skill cannot read. E
 
 Then report the port this worktree derives, on a second line:
 
-- `scripts/worktree-port.sh` present: run `bash scripts/worktree-port.sh` and emit `Port offset <n>. Every served port adds it to the stack default.`
+- `scripts/worktree-port.sh` present and exiting zero: run `bash scripts/worktree-port.sh` and emit `Port offset <n>. Every served port adds it to the stack default.`
+- Present and exiting non-zero: emit `The port helper refuses this directory, so no server here has a port. <its stderr>`
 - Absent: `No port derivation installed, so every served port is the stack default.`
 
+Branch on the exit rather than on the output, since the helper prints nothing to stdout when it refuses and reading that as a number reports an offset of zero, which is the main checkout's.
+
+The helper refuses a folder left behind after its worktree was removed, which Step 4 cannot land on, since it registers whatever it creates. The branch is here so a refusal is never read back as an offset of zero, which is the main checkout's port and the collision the helper exists to prevent.
+
 The offset is what `claude-orchestrate` sends a reader here to read rather than assign, and what an operator overrides through `WORKTREE_PORT_OFFSET` when two worktrees derive the same value. Deriving it correctly and printing it nowhere leaves both instructions naming a number no surface emits.
 
 Do not invoke `ExitWorktree` from this skill. Exit is the user's call.

package/docs/agents/commands.md

@@ -45,6 +45,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `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 claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD` (`--json`)                                                         |
+| `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                   |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                     |
 
 ## Domain commands
@@ -56,7 +57,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                      |
 | `snippets`  | `list`, `install`, `sync`, `create`                                                         |
 | `standards` | `list`, `install`, `sync`, `<name>`                                                         |
-| `gov`       | `list`, `install`, `sync`, `build`                                                          |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`                                   |
 | `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `setup [dest]` |
 | `wiki`      | `init`                                                                                      |
 | `design`    | `render`                                                                                    |

package/docs/agents/index.md

@@ -27,3 +27,4 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [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
 - [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

package/docs/agents/tasks.md

@@ -24,6 +24,8 @@ aitk tasks archive --pull-request 673 --json
 
 Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, `plan-unswept`, or `bad-input`.
 
+`plan-unswept` fires on the last task pointing at a live plan, never on every task pointing at one. The gate counts the other live tasks whose `Plan:` line resolves onto the same file, so a plan several tasks share archives its tasks freely and only the final one is held until `claude-docs` sweeps the plan. Reading the folder alone refused all of them, which deadlocked the board against a sweep correctly declining to move a plan another live task cites.
+
 `bad-input` covers a malformed command line, which all three task verbs answer the same way. It is separate from `ambiguous` and `no-match` because those describe the board, and a caller that passed two selectors would otherwise be sent to repair a task citation that is fine.
 
 The board is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree archives against the same board every other session reads.
@@ -34,6 +36,27 @@ Skills branch on the reason rather than on the exit code:
 aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
 ```
 
+## Plan citations
+
+`aitk tasks plan-citations <stem>` answers where a task's plan sits and which other live tasks hold it. It reports and never writes.
+
+| Option          | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The record carries `location`, one of `unstated`, `live`, `archived`, or `outside`, and `citedBy`, the other live tasks whose `Plan:` line lands on the same file. Exit codes: `0` read, `1` refused with `no-board` or `no-match`.
+
+`aitk tasks archive` gates on this same answer, so a caller wanting the count reads it here rather than scanning the board. The `claude-docs` plans sweep is the exception and still states the rule in its own body, because a plugin skill reaches a target on merge while the CLI reaches one on release, so a sweep calling a verb the installed `aitk` predates gets no record back and archives nothing.
+
+Branch on `reason` rather than on the exit code, which is the rule the archive section above already states and which this verb needs for a second reason. An operator's shell profile may wrap `aitk` in a function that runs the binary and then another command and takes the second status, which masks every non-zero exit rather than only an absent verb. The binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike, so the record is the only signal that survives the wrapper.
+
+A `live` location with an empty `citedBy` is the sweep to run. One whose `citedBy` names a sibling is a plan several tasks share, which the sweep leaves alone and the archive gate lets through.
+
+```bash
+aitk tasks plan-citations v28.1-trigger-escalation --json | jq -r '.location'
+```
+
 ## Pull request
 
 `aitk tasks pull-request` records the number a branch's pull request carries onto the task that branch closes. It adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already holds, and corrects the number in place when the line exists.
@@ -106,7 +129,11 @@ A backlog line is a bullet carrying a link to a sibling task, since the backlog
 
 The collision check is the one a person cannot run by eye. Paths come from the backticked spans in the Touches column, a span naming no file is dropped, and a directory collides with any file beneath it. A `## Run now` row whose column parses to nothing is reported rather than skipped, since a row stating no file set makes a claim nothing can check.
 
-The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or closing every outcome, and a collision is settled by nothing under `## Run now` still holding the file the cell cites.
+The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or by its work reaching the trunk, and a collision is settled by nothing under `## Run now` still holding the file the cell cites.
+
+A closed outcome is not the fact the dependency half needs. The ship chain marks outcomes as its first step and opens the pull request several steps later, so a check reading the checkbox reports the row settled while the branch is still in review. A live task therefore settles the row only once it closed every outcome and carries a `Pull request:` line the trunk holds. One that names no pull request, and one whose number no trunk ref could answer for, land in the untested array below rather than being settled or left silent.
+
+The trunk is read as the clone already holds it, `origin/main` first and local `main` behind it, and no run fetches. A validate runs several times a sweep and a fetch per run is a cost this command does not carry, so a clone behind its remote under-reports rather than claiming work landed.
 
 Both halves gate on a citation inside the `Waiting on` cell, never on the columns beside it. The board format gives a collision cell the file held by the running task, so a row whose cell names no file was parked by something else, and testing its Touches column instead reports a cleared collision on a row no collision ever parked while counting that row as re-tested. A cited task is a bare sibling link, the way the Task column spells one, so a pointer into another folder names a plan rather than a task and settles nothing. A cited task carrying no outcome box settles nothing either, since a file the check could not parse is not evidence of a finished one.
 

package/docs/agents/test-order.md

@@ -0,0 +1,56 @@
+---
+title: Test order
+description: 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
+---
+
+# Test order
+
+`aitk gov test-order` reports where an implementation reached a commit ahead of the test covering the same behavior. It answers the rule in `.claude/rules/core/070-planning.md` that asks for the test first, which until this verb existed was prose loaded on a glob match with nothing measuring it.
+
+```bash
+aitk gov test-order
+aitk gov test-order --base origin/main --json
+aitk gov test-order --root ../my-app
+```
+
+| Option          | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `--base <ref>`  | Far side of the range, defaulting to the merge base against trunk |
+| `--root <path>` | Repository to read, defaulting to the current directory           |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame        |
+
+Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode. A consumer reading stdout sees pure data, and an operator reading the terminal sees why a run refused rather than a command that appeared to do nothing.
+
+## The range it reads
+
+The default range is the branch against the trunk, resolved as the merge base against `origin/main` and then local `main`. A repository carrying neither falls back to the root commit, so a fresh checkout still answers rather than refusing.
+
+Reading all history on every run measures work nobody is reviewing and buries the finding that matters under the ones already merged. `--base` widens or narrows it when a reader wants a different window.
+
+Only history is read. A file sitting in the working tree and in no commit is invisible here, which is the point: the verification run sees a tree at one moment, and the ordering exists nowhere but history.
+
+## How a pair is decided
+
+A test is paired to an implementation by the module path with the test suffix removed, so `src/parser.test.ts` covers `src/parser.ts`. Every record is keyed on the implementation path, which is what a reader goes looking for.
+
+Pairing is the whole difficulty. A test and its implementation are related by behavior rather than by filename, so a behavior split across two modules pairs wrongly or not at all. That is what the unclassified verdict exists to catch rather than hide.
+
+## The three verdicts
+
+- **Satisfied.** The implementation was added in the range and its test reached history no later. A test that predates the range counts, and so does one commit carrying both sides, since the rule asks that the test not come after and a single commit is the shape a small change takes.
+- **Implementation-first.** The implementation was added in the range and its test was added in a later commit of the same range. This is the only verdict that moves the exit code.
+- **Unclassified.** Everything the pairing cannot read, each carrying its own reason. A module the range modified rather than added lands here, because a refactor and a new behavior cannot be told apart from history. So does an implementation no test names, and a test whose implementation the range never introduced.
+
+## What it reads past
+
+Only `.ts` and `.tsx` are paired, since a test sits beside its subject under one name across that corpus and a bash script has no such partner. Declaration files carry no behavior to test. Every other changed path is counted under `Read past` rather than dropped silently.
+
+Coverage is narrower than the rule the check answers to. The rule speaks to every behavior, and the verb speaks to the behaviors it can identify, so the report states its own scope on every run rather than implying it looked at everything.
+
+## Exit codes
+
+Exit codes are `0` when nothing reached history ahead of its test, `1` for a refusal, and `2` for at least one implementation-first finding. Unclassified rows move no exit code.
+
+Nothing wires this into `bun run check` or into a hook. The unclassified class is large and known, and gating a measure carrying a known false-positive class is what teaches contributors to route around the stage. `aitk tasks validate` is the precedent: it exits `2` on findings and is called where the claim is made rather than on every push.
+
+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 JSON record's `findings` array rather than the exit when a skill consumes this.

package/docs/ai-workflow.md

@@ -55,6 +55,8 @@ The routing test is whether the repository can answer an item today. A session g
 
 A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.claude/.tmp/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
 
+What a spike produces goes somewhere else again. An input the run reads is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it, while a recording or a render the track cites as evidence for a finding is what a later reader opens to check the claim. Evidence therefore lives in `evidence/` inside the track beside the file citing it, since the scratch tree holds only what can be deleted without loss.
+
 #### Session 2
 
 Start a fresh Claude Code session. The diff is sufficient context for both review and ship.
@@ -105,11 +107,11 @@ The sweep reads the whole board rather than the tasks the session touched. It is
 
 `.claude/memory/` carries the same arrangement, its own hook regenerating `index.md` from each entry's `title`, `description`, and `category`. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
 
-`aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every row and task file map one to one, no task sits in two groups, and no two rows marked ready touch the same file. That fourth check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. A fifth re-takes what a parked row waits on, reporting one whose cited task has closed and one whose cited file nothing running still holds. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, which is where the three kinds resting on a person's judgment land. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
+`aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and no two rows marked ready touch the same file. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. That fourth check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. A fifth re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
 
 `aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
 
-Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses to run while the `Plan:` line still points into `.claude/plans/`. The sweep only reaches tasks still in the live folder, and archiving the task first would strand the plan there with nothing citing it.
+Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses the last task pointing at a live plan. The sweep only reaches tasks still in the live folder, and archiving that task first would strand the plan there with nothing citing it. A task whose plan a sibling still cites archives freely, because the sweep is correct to leave that plan where it is and a gate reading the folder instead would park every task sharing one plan behind a sweep that will never move it.
 
 Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `aitk:claude-autoship` or `aitk:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook names the board's archive candidates and stays silent otherwise, including on a project with no board.
 

package/governance/rules/core/070-planning.md

@@ -13,4 +13,5 @@ description: Enforce planning standards before implementation
 - Propose the simplest solution that satisfies the requirement before implementing complex patterns.
 - Write or update tests as part of every implementation plan.
 - Write the test for a behavior before the code that implements it. Confirm visual output after implementing it, not before.
+- Run `aitk gov test-order` before shipping a branch. Fix what it names as reaching history ahead of its test.
 - Do not modify code without a confirmed plan.

package/package.json

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

package/src/commands/gov.ts

@@ -14,6 +14,11 @@ import {
   mergeExtraRules,
   resolveRules,
 } from '@/gov/stacks'
+import {
+  type PairRecord,
+  readTestOrder,
+  type TestOrderReport,
+} from '@/gov/test-order'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
 import {
@@ -48,6 +53,12 @@ interface ListOptions {
   readonly json?: boolean
 }
 
+interface TestOrderOptions {
+  readonly base?: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -133,6 +144,130 @@ export function register(program: Command): void {
     .action((opts: ListOptions) => {
       process.exitCode = runList(opts)
     })
+
+  gov
+    .command('test-order')
+    .description(
+      'Report where an implementation reached history before its test',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Measures the rule in .claude/rules/core/070-planning.md that asks for',
+        'the test before the code. It reports and never gates, because pairing',
+        'a test to an implementation is a judgment.',
+        '',
+        'Coverage:',
+        '  a test sits beside its subject under the same name, minus .test',
+        '  only .ts and .tsx are paired, and every other path is named as read past',
+        '  a module the range modified rather than added is unclassified, since',
+        '  a refactor and a new behavior cannot be told apart from history',
+        '',
+        'Exit codes:',
+        '  0  no implementation reached history ahead of its test',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one implementation reached history ahead of its test',
+        '',
+        'Examples:',
+        '  aitk gov test-order',
+        '  aitk gov test-order --base origin/main --json',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: TestOrderOptions) => {
+      process.exitCode = runTestOrder(opts)
+    })
+}
+
+/**
+ * Reports and never gates, so the finding count moves the exit code without
+ * anything wiring it into a push. `aitk tasks validate` set that shape: a
+ * measure carrying a known false-positive class is what forces contributors to
+ * route around a stage, and the unclassified bucket here is that class.
+ */
+function runTestOrder(opts: TestOrderOptions): number {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = readTestOrder(root, { base: opts.base })
+  const emitJson = opts.json ?? false
+
+  // The frame renders on stderr in both modes and the record goes to stdout
+  // alone, which is the split `docs/agents/output-shape.md` fixes. A consumer
+  // reading stdout sees pure data either way, and an operator reading the
+  // terminal sees the refusal rather than a command that appeared to do nothing.
+  if (report.kind === 'unreadable') {
+    intro('aitk gov test-order')
+    logStep('Refused')
+    logError(report.reason)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: report.reason })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportTestOrder(report, root)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ok: true, root, ...report })}\n`)
+  }
+
+  return report.findings.length > 0 ? 2 : 0
+}
+
+function describePair(record: PairRecord): string {
+  const test = record.test === null ? 'no test' : record.test
+  return `${record.subject} → ${test}: ${record.reason}`
+}
+
+function reportTestOrder(
+  report: Extract<TestOrderReport, { kind: 'measured' }>,
+  root: string,
+): void {
+  intro('aitk gov test-order')
+
+  logStep('Range')
+  logInfo(`${report.base.slice(0, 8)}..${report.head.slice(0, 8)} in ${root}`)
+
+  logStep(report.findings.length === 0 ? 'Clean' : 'Findings')
+  if (report.findings.length === 0) {
+    logInfo('no implementation reached history ahead of the test covering it')
+  } else {
+    for (const finding of report.findings) logWarn(describePair(finding))
+  }
+
+  logStep('Satisfied')
+  logInfo(`${report.satisfied.length} pair(s) whose test came first`)
+
+  // The unclassified rows carry the warn glyph and move no exit code. A pass
+  // over a change the pairing could not read is the claim this check exists to
+  // avoid making, so the rows are named rather than counted into the clean line.
+  logStep('Unclassified')
+  if (report.unclassified.length === 0) {
+    logInfo('every changed module paired')
+  } else {
+    logWarn(
+      `${report.unclassified.length} change(s) the pairing could not read`,
+    )
+    for (const record of report.unclassified) logWarn(describePair(record))
+  }
+
+  // Coverage is narrower than the rule, and a report that did not say so would
+  // read as a verdict over every behavior in the range.
+  logStep('Read past')
+  logInfo(
+    `${report.ignored.length} path(s) outside ${report.scope.extensions.join(', ')}`,
+  )
+
+  outro()
 }
 
 /**

package/src/commands/tasks.ts

@@ -1,6 +1,12 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
-import { type ArchiveOutcome, archiveTask } from '@/tasks/archive'
+import {
+  type ArchiveOutcome,
+  archiveTask,
+  type CitationOutcome,
+  type PlanCitations,
+  planCitations,
+} from '@/tasks/archive'
 import {
   type CloseOutcome,
   closeOutcomes,
@@ -42,6 +48,11 @@ interface ValidateCommandOptions {
   readonly root?: string
 }
 
+interface CitationsCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface PullRequestCommandOptions {
   readonly json?: boolean
   readonly plan?: string
@@ -126,6 +137,41 @@ export function register(program: Command): void {
       process.exitCode = await runValidate(opts)
     })
 
+  tasks
+    .command('plan-citations')
+    .description('Report where a task plan sits and which live tasks hold it')
+    .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Locations:',
+        '  unstated  the task carries no Plan: line',
+        '  live      the target resolves inside .claude/plans/',
+        '  archived  the target resolves inside .claude/plans-archive/',
+        '  outside   the target resolves somewhere else',
+        '',
+        'Exit codes:',
+        '  0  the citations were read',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It reports and never writes. A live plan whose citedBy list is empty',
+        'is the sweep to run, and one a sibling still holds is left alone.',
+        'The archive gate reads the same answer, so neither can drift.',
+        '',
+        'Examples:',
+        '  aitk tasks plan-citations v28.1-trigger-escalation',
+        '  aitk tasks plan-citations v28.1-trigger-escalation --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string, opts: CitationsCommandOptions) => {
+      process.exitCode = await runCitations(task, opts)
+    })
+
   tasks
     .command('pull-request')
     .description('Record a pull request number on the task a branch closes')
@@ -426,6 +472,67 @@ async function runValidate(opts: ValidateCommandOptions): Promise<number> {
   return reportValidation(outcome, opts.json ?? false, root)
 }
 
+async function runCitations(
+  task: string,
+  opts: CitationsCommandOptions,
+): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await planCitations(root, task)
+
+  return reportCitations(outcome, opts.json ?? false, root)
+}
+
+function reportCitations(
+  outcome: CitationOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('aitk tasks plan-citations')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return 0
+  }
+
+  intro('aitk tasks plan-citations')
+  logStep(outcome.stem)
+  logInfo(describeCitations(outcome))
+  outro()
+
+  return 0
+}
+
+function describeCitations(outcome: PlanCitations): string {
+  if (outcome.location === 'unstated') return 'carries no Plan: line.'
+
+  if (outcome.location === 'archived') {
+    return `points at ${outcome.target}, which an earlier sweep already archived.`
+  }
+
+  if (outcome.location === 'outside') {
+    return `points at ${outcome.target}, which resolves outside both plans folders.`
+  }
+
+  if (outcome.citedBy.length === 0) {
+    return `is the last live task citing ${outcome.target}, so the sweep may archive it.`
+  }
+
+  return `shares ${outcome.target} with ${outcome.citedBy.join(', ')}, so the sweep leaves it.`
+}
+
 function reportValidation(
   outcome: ValidateOutcome,
   emitJson: boolean,