@erclx/aitk 0.104.1 → 0.106.0

package/claude/skills/write-human/references/source-material.md

@@ -0,0 +1,37 @@
+---
+title: Source material
+description: Which external writing patterns this skill adopted, which it declined, and the measurement behind each decision
+---
+
+# Source material
+
+Two external writing skills were read on 2026-08-19 as source material for this one. The first catalogs 31 patterns of machine-sounding prose. The second layers document mode, sentence construction, information density, and ambiguity prevention.
+
+Neither was imported wholesale, and one measurement settles why. Read this before adding a rule from outside this corpus, and extend the position below rather than deriving a second one.
+
+## What was adopted
+
+Roughly half the pattern catalog had no counterpart in this corpus, and six of those patterns are now in `machine-tells.md`: rule-of-three, synonym cycling, false ranges, inline-header lists, adverb propping, and passive voice with an unnamed actor. Each is a shape rather than a token, which is what kept it out of a ban list that matches words.
+
+The density layer had no counterpart at all and is now `density.md`. Its useful half is the split between what a compression pass may cut and what it may not, since a terse register already instructs a session to cut and names nothing that has to survive.
+
+The ambiguity rules travel with that layer for the same reason. Compression is what creates the ambiguity, so a rule about pronouns and modifiers belongs beside the rule that shortened the sentence.
+
+## What was declined
+
+- **The ban on abstract metaphor nouns.** The nouns it names are load-bearing terms in this corpus rather than decoration, and the count below is what decides it.
+- **Document mode as a selector.** The source has the writer pick a mode before drafting. In this corpus a document's shape is already fixed by the standard governing its type, so a mode selector adds a second authority over one question and the two will disagree.
+- **Any restatement of a banned word set.** The bans ship as package data that `aitk markdown audit` reads, and a copy here would be a second source for one list with a machine reading the other.
+- **A voice register per surface.** One baseline covers every surface. A surface needing a warmer register states its own voice and claims the yield, which lifts voice alone and leaves the bans, the rhythm rules, and the tells in force.
+
+The first of those four rests on a count. The source names `surface` among the nouns it bans, and tracked markdown in the authoring repository used `surface` 593 times, `harness` 95, `scaffolding` 17, and `primitive` 4, measured at `57ee7467` on 2026-08-19. Adopting the item either rewrites established vocabulary across the corpus or is ignored in silence, and a reader arriving later cannot tell which happened.
+
+## Where this diverges
+
+The source material treats repetition of a noun as a defect. This skill treats it as precision and bans the synonym cycling that avoids it, which reverses the item for reference prose where a reader has to know that two names are one thing.
+
+The source material also prefers shorter sentences without bound. This skill measures the spread instead, since a passage of uniformly short sentences is the reported failure rather than the fix for it.
+
+## The industry-guide record
+
+The cadence rules and the bans they pair with trace to three industry style guides, being Google's developer documentation style guide, Microsoft's writing style guide, and Apple's style guide. The authoring toolkit keeps the per-rule attributions and the dates each guide was read, and no install carries that record, so this file is the position a target reads.

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/markdown-audit.md

@@ -5,7 +5,7 @@ description: Running the audit over any markdown path, where its bans and checkp
 
 # Markdown audit
 
-`aitk markdown audit [path...]` reports any markdown file against the two attribute standards, `markdown.md` and `prose.md`. An attribute standard governs a file rather than a folder, so this resolves no folder and requires no `index.md`, which is what puts `.claude/rules/`, `governance/`, and `snippets/` in reach. Folder-shaped findings stay in `aitk context audit`, described in `context-audit.md`.
+`aitk markdown audit [path...]` reports any markdown file against the attribute standard `markdown.md`. An attribute standard governs a file rather than a folder, so this resolves no folder and requires no `index.md`, which is what puts `.claude/rules/`, `governance/`, and `snippets/` in reach. Folder-shaped findings stay in `aitk context audit`, described in `context-audit.md`.
 
 ```bash
 aitk markdown audit
@@ -29,9 +29,9 @@ A bare run measures every markdown file git lists, tracked plus untracked-and-no
 
 The three ban sets and all six checkpoints ship with the `aitk` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same sets whether or not it installed any standards, and no file has to resolve for a run to mean something.
 
-Reading them out of the standards per run was the original design. It put a parser contract on two documents authored for people, and `prose.md` had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
+Reading them out of the standards per run was the original design. It put a parser contract on a document authored for people, and the standard had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
 
-`markdown.md` and `prose.md` still state every ban and every checkpoint, and a reader follows those rather than the code. Nothing compares the two, so a number moved in one place and left in the other drifts silently. Move both in the same change.
+`markdown.md` still states every ban and every checkpoint, and a reader follows it rather than the code. Nothing compares the two, so a number moved in one place and left in the other drifts silently. Move both in the same change.
 
 The sets are closed rather than extensible, so a project cannot add a term by editing a file. What decides that is the measurement behind them: 21 terms across 483 markdown files report a clean exit, and every occurrence of a banned word in the corpus sits inside the ban list itself or inside an example demonstrating the ban. The set is a prior an author already knows rather than a filter that has caught anything, and enumeration cannot close the gap it aims at, since `just`, `allows`, and `very` carry honest uses no literal match separates.
 
@@ -45,7 +45,7 @@ A set shipped empty is reported rather than passed. It finds nothing and would e
 
 ### Bans
 
-Three closed sets report a hit: the characters `markdown.md` bans under `## Punctuation`, the single lowercase words `prose.md` bans under `## Language`, and the British spellings of the American examples that section lists.
+Three closed sets report a hit: the characters `markdown.md` bans under `## Punctuation`, the single lowercase words it bans under `## Language`, and the British spellings of the American examples that section lists.
 
 Deriving the spellings rather than pattern-matching a suffix is what keeps `exercises`, `promises`, and `revised` out of the report. A suffix pattern over the same corpus produced 46 false positives from words of that shape, and a closed set of whole words reaches none of them.
 
@@ -120,7 +120,7 @@ Rewrite the sentence rather than swapping the banned token for a near-synonym. T
 
 A code span clears the report too, since the ban scan walks around one, and it is the answer only where the token is genuinely an identifier under discussion. `## Code and identifiers` in `markdown.md` reserves the span for commands, API names, file paths, and identifiers, so backticking a quoted utterance spends one rule to satisfy another and leaves the corpus no cleaner.
 
-A hit the closed set cannot separate from correct prose is the case with no third option. `prose.md` bans vague qualifiers and lists the tokens those qualifiers happen to spell, so the temporal `just` reports as the vague one. The rule as written reaches neither, and rewriting the sentence is what the toolkit settled on over building an exemption path, for the reasons below.
+A hit the closed set cannot separate from correct prose is the case with no third option. `markdown.md` bans vague qualifiers and lists the tokens those qualifiers happen to spell, so the temporal `just` reports as the vague one. The rule as written reaches neither, and rewriting the sentence is what the toolkit settled on over building an exemption path, for the reasons below.
 
 ### Where the rules are enforced
 
@@ -150,9 +150,9 @@ Masking took 7 of the weight-only paragraphs the checkpoint reported at 400 and
 
 ### How the ban count reached zero
 
-Eight word hits stood between the baseline and a gate, and only three carried the sense `prose.md` bans. `leverage` sat in the requirements worldview, `allows` in the claude stack reference, and one `just` was the vague qualifier in a skill body. Those three lost the qualifier rather than the word.
+Eight word hits stood between the baseline and a gate, and only three carried the sense the standard bans. `leverage` sat in the requirements worldview, `allows` in the claude stack reference, and one `just` was the vague qualifier in a skill body. Those three lost the qualifier rather than the word.
 
-The other five were correct prose the closed set cannot separate from a violation. Four were the temporal `just`, meaning a moment ago, in phrases like the implementation `just` completed and the field the user `just` edited. The fifth quoted an anti-pattern a skill exists to forbid. `prose.md` bans vague qualifiers and lists the tokens those qualifiers happen to spell, so the rule as written reaches none of the five while the scan reaches all of them.
+The other five were correct prose the closed set cannot separate from a violation. Four were the temporal `just`, meaning a moment ago, in phrases like the implementation `just` completed and the field the user `just` edited. The fifth quoted an anti-pattern a skill exists to forbid. `markdown.md` bans vague qualifiers and lists the tokens those qualifiers happen to spell, so the rule as written reaches none of the five while the scan reaches all of them.
 
 ### Why they were rewritten rather than exempted
 

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.
@@ -279,6 +281,7 @@ This section is the corpus the coverage claim is measured against: every name `a
 | `aitk:toolkit-cli`         | Before a sync or install, to learn what it overwrites, merges, or leaves alone |
 | `aitk:youtube-transcripts` | When a video transcript is wanted in the repo as context                       |
 | `aitk:claude-teach`        | To learn a subject across sessions, in a workspace that holds the progress     |
+| `aitk:write-human`         | Before drafting or revising prose, for voice, rhythm, and density              |
 
 Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
 

package/docs/target-projects.md

@@ -88,7 +88,7 @@ Run `aitk tooling list --json` and `aitk gov list --json` to see the current cat
 
 `governance`, `standards`, and `wiki` are skippable:
 
-- `--skip governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/prose.md` lands with nothing pointing at it and no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
+- `--skip governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/markdown.md` lands with nothing pointing at it and no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
 - `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing for a reader following the path. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root. `aitk standards <name>` searches the corpus inside the CLI's own package behind both project roots, so it prints a standard in a project that skipped the install, and `aitk markdown audit` needs no standard at all, its ban sets and checkpoints shipping with the package as data. What the skip costs is the editable copy rather than the enforcement.
 - `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
 

package/governance/rules/claude/500-prose.md

@@ -1,13 +1,15 @@
 ---
-description: Route markdown edits to the prose standard for voice, language, and frontmatter wording
+description: Route markdown edits to the write-human skill for voice, rhythm, sentence construction, and information density
 paths:
   - '**/*.md'
 ---
 
-# Markdown prose standards
+# Markdown voice standards
 
 ## Authority
 
-- Follow `.claude/standards/prose.md` for voice, language, and the wording of a `title` or `description`. It is the single source.
-- Read it before a substantial prose edit. Do not work the banned words from memory.
-- Punctuation, formatting, and file references are a separate topic. `501-markdown` routes them.
+- Load the `aitk:write-human` skill for voice, rhythm, sentence construction, and information density. It is the single source for all four.
+- Load it before drafting a passage, not after revising one.
+- Report it rather than proceeding silently when the skill does not resolve.
+- Do not work these rules from memory.
+- Banned words, spellings, punctuation, formatting, and file references are a separate topic. `501-markdown` routes them.

package/governance/rules/claude/501-markdown.md

@@ -1,5 +1,5 @@
 ---
-description: Route markdown edits to the markdown standard for headings, lists, punctuation, and file references
+description: Route markdown edits to the markdown standard for headings, lists, punctuation, banned words, and frontmatter wording
 paths:
   - '**/*.md'
 ---
@@ -8,6 +8,7 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/markdown.md` for headings, paragraph and list structure, code spans, punctuation, emphasis, and file references. It is the single source.
-- Read it before a substantial markdown edit. Do not work the banned characters from memory.
-- Voice, language, and frontmatter wording are a separate topic. `500-prose` routes them.
+- Follow `.claude/standards/markdown.md` for headings, paragraph and list structure, code spans, punctuation, emphasis, file references, the banned words and spellings, and the wording of a `title` or `description`. It is the single source.
+- Read it before a substantial markdown edit. Do not work the banned words or characters from memory.
+- Run `aitk markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+- Voice, rhythm, and sentence construction are a separate topic. `500-prose` routes them.

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.1",
+  "version": "0.106.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/install-check.sh

@@ -79,7 +79,7 @@ log_step "Assert scaffold"
 # The snippets path has to name a slug the default preset still carries, since
 # init resolves snippets through `essentials`. Editing that preset without
 # editing this line fails the gate on a correct install.
-for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/standards/prose.md" ".claude/standards/markdown.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
+for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/standards/skill.md" ".claude/standards/markdown.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/core/000-constitution.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

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/markdown.ts

@@ -87,8 +87,8 @@ export function register(program: Command): void {
         '',
         'Bans and checkpoints ship with the aitk package rather than being read',
         'out of a standards file, so a project that installed no standards is',
-        'measured the same as one that did. markdown.md and prose.md still state',
-        'every rule for a reader. No folder has to resolve and no index.md has',
+        'measured the same as one that did. markdown.md still states every rule',
+        'for a reader. No folder has to resolve and no index.md has',
         'to exist, so .claude/rules/, governance/, and snippets/ are in reach.',
         '',
         'Examples:',

package/src/comments/vocabulary.ts

@@ -57,7 +57,7 @@ export function parseVocabulary(markdown: string): string[] | undefined {
  *
  * Reading the list out of the rule rather than hardcoding it is what keeps one
  * definition when the rule installs into a target, the same way
- * `.claude/hooks/standards-audit.sh` reads its word bans out of `prose.md`.
+ * `aitk markdown audit` owns one copy of the ban sets for every caller.
  */
 export async function loadVocabulary(root: string): Promise<Vocabulary> {
   for (const ruleRoot of RULE_ROOTS) {