## Context issue-87a27629f6a6 closed a narrow version of this: the packaged agent guide told agents to run a `reindex` flag that has never existed, at the single most important recovery step, and nothing checked the guide against the CLI it documents. The fix was a test that introspects the Typer tree from `cli.app` and resolves every `docir ...` code span in `modules/agents/infra/templates/skill.md`, later extended to `README.md`. That covered what an **adopter** reads. It did not cover what an agent working *in this repository* reads, which is `CLAUDE.md` and the project store — and CLAUDE.md's first instruction is to read the store. A review of the corpus on 2026-08-15 found that half had rotted exactly the way the guide had: - `arch-1cfb1b212237`, the document CLAUDE.md sends readers to first, carried **96** invocations of the binary's previous name, plus `--set-field` (never shipped), `reindex --all` (the very flag issue-87a27629f6a6 is about) and a command table listing 11 of the 22 commands that exist. - Two active documents asserted `docir check --fix` did not exist, years of `--fix` after it shipped, and one asserted there was no similarity floor after `--min-score` landed. None of it was found by reading the suite. All of it was found by running the commands. ## Decision **One oracle, six sources.** `tests/entry_points/test_agent_guide_matches_cli.py` resolves every `docir ...` code literal in the packaged guide, `README.md`, `CLAUDE.md`, every file under `.docir/docs/**`, every docstring under `src/`, and every markdown file shipped inside the package — the six `CONTRACT.md` files — against the same introspected command tree. A document in the store, a docstring on the method that implements the command, and the guide shipped to other repositories are judged by identical rules, because they fail identically. Each source was added believing the previous pass had finished the job, and each one moved the count: the store held 96 stale invocations, `src/` docstrings held 37 more after the markdown side was clean, and the contracts held none — which is the result the rule is *for*. A source is not covered because someone looked at it; it is covered because the oracle is pointed at it and keeps being pointed at it. The `CONTRACT.md` files earn their place for a structural reason rather than a historical one. §8.6 already makes each change in the same commit as the `api.py` it documents, so they are the one document class *guaranteed* to be edited exactly when a module's public operations move — which is precisely when a command name in one goes stale. They were clean today and are the most likely to rot tomorrow. Three parts are load-bearing and are the reason this is a decision rather than a patch. ### A retired binary name needs its own check, in every source The extractor is anchored on `docir `. A code span opening with the binary's *previous* name therefore never reaches it — the line reads as "nothing to validate", which is indistinguishable from "valid". That is precisely how one document accumulated 96 of them while the guard beside it was green, and how `src/` kept 37 after the markdown side was clean. `_RETIRED_BINARIES` matches an old name followed by a word that is a live subcommand; requiring the second word to resolve is what keeps the docs *directory* and `docs-schema.yaml` out, since neither is followed by a space and a command. Generalising: a guard anchored on the correct spelling cannot see the incorrect one. Whenever a name changes, the retired name needs an explicit check or the rename is unenforced in exactly the places nobody re-reads. ### Prose that names an unreal command is exempted by list, and the list may only shrink A corpus of decisions necessarily writes commands that do not exist: `docir import` was proposed and rejected, `docir repair` is the name of the gap `check --fix` closed, and the probe logs quote `reindex --all` as the defect they record. Rewriting those would destroy the argument. `_DELIBERATELY_UNREAL` maps the leading words to *why*, and `test_every_exemption_is_still_needed` fails when an entry stops matching anything. That inverse test is the point. An exemption that outlives its prose becomes a blind spot pointed at the exact command most likely to be typed wrong later — if `docir import` ever ships, a stale entry would swallow every future typo in it silently. Dropping the entry is part of shipping the command, and this is what says so. An exemption is never the fix for a document that tells a reader to *run* something. issue-8f6576cd7bc9 instructed the reader to supply a missing steward with an update call naming a bare `--owner`; the flag is `--set-owner`, and that took the correction, not an entry. Writing the wrong invocation here as a code span would have failed this document too — as an earlier draft of it did. ### Type and status values are checked; other values are not Resolving a command proves the *shape* of a line and nothing about its meaning. A filter reading `--type decision --status open` parses, runs, exits zero and matches nothing — forever — because `decision` goes proposed -> accepted and never holds an `open`. That is worse than a broken command, which at least announces itself. So `--type` and `--status` values are checked against the **core merged with every bundled profile**, not against the schema this store resolved. Which profiles a store enables is a local choice; whether `decision` declares an `open` status is not. An example may therefore reach for a `test_plan` from the qa profile that this repository does not turn on, and still fail if it pairs that type with a status the type never declares. Without a `--type` to scope it, a status only has to be one some shipped type declares, because `update --status resolved` names no type and cannot. Other values stay unchecked, and the line is deliberate: a tag, an id, a heading or a path is a fact about one corpus, while a type and its statuses are facts about docir. Checking the first class would bind this test to the contents of a store, and the guard would then fail for anyone who wrote a different document. The corpus-level instrument remains and is not replaced by this: Tier 1's `unknown-status` and `unknown-type` findings judge *documents*, which is where a wrong status actually costs something. This guard judges prose, which is where the wrong status is learned. ## Consequences - Extraction had to get stricter before it could get broader. Global flags precede the command (`docir --pretty get `), slash alternatives occur below the top level (`docir agent install/update`), and a `$(...)` substitution carries another program's flags. All three produced false failures on correct prose and are now handled in the shared helpers, so the guide and README benefit too. - The suite grew from 1154 to 1779 tests. They are parametrized per invocation, so a failure names the line rather than a count. - Writing about docir in docir is now constrained: a command named in backticks must be real or exempted. Prose stays prose. This document's own first draft tripped the retired-binary check by quoting an example, which is the rule working. - All fourteen failure modes were verified by injection — a wrong flag, an unknown subcommand, an unknown command, a misplaced global, a retired binary, an unreal subcommand, a stale exemption, a moved store path, and six shapes of bad `--type`/`--status` value — because a guard that has never failed has not been shown to work, and because two earlier versions of this same test silently checked nothing. The value check was run against five legitimate lines as well, since a guard that rejects correct prose gets deleted rather than obeyed. - Extending the checker turned up its own bug: the placeholder rule knew `...` and not the typographic `…` that prose actually uses, so an ellipsis read as a type name. A checker that understands only one spelling of a convention is the same failure as one anchored on only the current binary name.