@erclx/canon 4.0.0

package/docs/agents/tasks.md

@@ -0,0 +1,200 @@
+---
+title: Tasks
+description: 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
+---
+
+# Tasks
+
+## Archive
+
+`canon tasks archive` moves a shipped task from `.claude/tasks/` into `.claude/tasks/archive/`, drops its row from `priority.md`, and regenerates the board index. The three run as one unit, so the attended and unattended callers cannot archive differently.
+
+Name the task by its filename stem, or by the pull request it carries:
+
+```bash
+canon tasks archive v28.1-trigger-escalation
+canon tasks archive --pull-request 673 --json
+```
+
+| Option               | Behavior                                                     |
+| -------------------- | ------------------------------------------------------------ |
+| `--pull-request <n>` | Select the task whose `Pull request:` line names this number |
+| `--json`             | Emit a machine-readable record on stdout                     |
+| `--root <path>`      | Board root, defaulting to the main worktree                  |
+
+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 row is matched by the link in its first cell rather than by a pattern against the whole line. A row names the task it is about in the first cell, so a link anywhere after it is a reference, such as a blocker naming what it waits on, and matching the line would drop the referring task's row too.
+
+The row removal reaches `priority.md` alone. A task gets to a merge by being planned and handed out, and both steps move it onto the board first, so one archived straight off `backlog.md` leaves its bullet standing and `canon tasks validate` reports that bullet as naming a file that is gone.
+
+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.
+
+Skills branch on the reason rather than on the exit code:
+
+```bash
+canon tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
+```
+
+## Plan citations
+
+`canon 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`.
+
+The target resolves against `.claude/tasks/` and against the project root both, so `../plans/x.md` and `.claude/plans/x.md` land on the same file and one plan two tasks spelled differently counts once.
+
+`canon 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 `canon` 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 `canon` 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
+canon tasks plan-citations v28.1-trigger-escalation --json | jq -r '.location'
+```
+
+## Pull request
+
+`canon 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.
+
+Name the task by its filename stem, or by the plan its `Plan:` line points at:
+
+```bash
+canon tasks pull-request 673 v28.1-trigger-escalation
+canon tasks pull-request 673 --plan worktree-scratch-routing --json
+```
+
+| Option          | Behavior                                           |
+| --------------- | -------------------------------------------------- |
+| `--plan <slug>` | Select the task whose `Plan:` line names this plan |
+| `--json`        | Emit a machine-readable record on stdout           |
+| `--root <path>` | Board root, defaulting to the main worktree        |
+
+A plan is matched on the token both spellings share, so `worktree-scratch-routing`, `feature-worktree-scratch-routing`, and `.claude/plans/feature-worktree-scratch-routing.md` all select the same task. The `action` field reports `added`, `corrected`, or `unchanged`, which makes a rerun against the same number safe.
+
+Exit codes: `0` recorded, `1` refused. The `reason` field carries `no-board`, `no-match`, or `ambiguous`. `git-pr` skips silently on those three, because each is a case where a guessed write would archive the wrong task once the branch merges.
+
+A malformed argument refuses as `bad-input` instead, which sits outside that set on purpose. `git-pr` derives the number by slicing whatever `gh pr create` printed, so a non-numeric value is reachable, and folding it into the swallowed set would lose the number with nothing reporting it.
+
+## Outcome
+
+`canon tasks outcome` marks outcomes `[x]` on a task by their position in its outcome list, counting every checkbox in file order from 1.
+
+```bash
+canon tasks outcome v28.1-trigger-escalation --close 1 --close 3
+canon tasks outcome --plan worktree-scratch-routing --close 2 --json
+```
+
+| Option               | Behavior                                           |
+| -------------------- | -------------------------------------------------- |
+| `--close <position>` | Outcome to mark `[x]`, 1-based, repeatable         |
+| `--plan <slug>`      | Select the task whose `Plan:` line names this plan |
+| `--json`             | Emit a machine-readable record on stdout           |
+| `--root <path>`      | Board root, defaulting to the main worktree        |
+
+An outcome already closed comes back under `alreadyClosed` rather than refusing, so a rerun against the same positions changes nothing. A position past the end of the list refuses as `out-of-range`, since a caller counting wrong should hear about it rather than mark a neighbor.
+
+Positions skip fenced blocks. A checkbox inside a sample a task displays is not an outcome the task claims, and counting one would shift every position after it. `canon tasks archive` reads the list through the same walker, so the two verbs cannot disagree about which checkboxes are outcomes.
+
+Exit codes: `0` closed, `1` refused. The `reason` field adds `no-outcomes`, `out-of-range`, and `bad-input` to the three above.
+
+Both verbs exist because the write is an edit inside a file that already exists. `Edit` and `Write` refuse a main-root path from a linked worktree, and a shell stream editor is banned for in-place edits, so a verb resolving the board root in-process is the only route a skill body has. Creating a whole file needs no verb, because a heredoc through `Bash` writes it safely.
+
+## Validate
+
+`canon tasks validate` reports what each row of `priority.md` claims against what the tree holds. It reads and never writes, because a row is a session's claim about readiness and a validator that repaired one would be asserting the claim it exists to test.
+
+```bash
+canon tasks validate
+canon tasks validate --json
+```
+
+Seven checks run. Plan and Collisions reach one half each of the `## Run now` test the board standard states. Mapping and Grouping test the folder contract and hold for every group, and Shape holds for every group too, ahead of the four. Ordering reaches only the `## Needs a plan` rows, and Blockers reaches every row outside `## Run now`:
+
+| Check      | What it reports                                                                                                      |
+| ---------- | -------------------------------------------------------------------------------------------------------------------- |
+| Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed |
+| Plan       | A `## Run now` row whose Plan column carries no link, or one resolving to no file                                    |
+| Mapping    | A row or backlog line naming no task file, and a task file neither surface names                                     |
+| Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                          |
+| Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits                                  |
+| Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                    |
+| Blockers   | A parked row whose blocker has stopped holding, or whose cited task resolves nowhere                                 |
+
+Shape runs before any other check reads a row, since a row failing it carries no dependable fields for the rest to check. A blank or prose line closes the table above it, so the walk treats the next pipe line as a fresh header candidate rather than as a continuation. That candidate counts as a header only when the line behind it is a separator carrying the same cell count, and one that fails is `row-untabled`, stranded behind a table that already closed. Cell count still has to match the header on every row that clears that test, and a row whose count disagrees is `row-misshapen`, the shape a dropped pipe or a merged column produces.
+
+Mapping spans two surfaces, because a task sits on `priority.md` when it would plausibly be planned soon and on `backlog.md` otherwise. A task file either surface names is accounted for, a file neither names is `row-missing`, and a file both name is `row-duplicated` for the reason a task in two groups is: it claims two things about itself and only one can hold. One check across both is what lets a task move between them without the move reading as a dropped file.
+
+A backlog line is a bullet carrying a link to a sibling task, since the backlog is a flat unordered list rather than a table. A bullet holding prose is skipped rather than reported, which keeps the file's own intro out of the findings, and the task that bullet meant to name is still reported as reaching neither surface. A project carrying no `backlog.md` reads as an empty backlog rather than a refusal, which leaves the one-to-one mapping this check ran before the second surface existed.
+
+Ordering reads only a `## Needs a plan` row whose `Waiting on` cell states a position at all. That phrase is prose rather than data, searched for anywhere in the cell rather than at its start, since every live row states its position at the end of a sentence rather than at the front. The vocabulary stops at `first` through `twentieth` plus `last`, since a parser strict enough to catch a gap would otherwise flag a row phrased correctly and differently, and bounding it to those words is what keeps a cell reading `Untestable from here` from matching on `from`. A row that does state a position is checked against where it actually sits, and that one comparison catches a gap, a duplicate, and a sequence starting somewhere other than first alike.
+
+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.
+
+Where a directory holds the other row's file, the finding names the row that claimed it, reading `both touch src/tasks, which v2.0-second claims as a folder.` The shared strings alone leave an over-broad cell and a genuine overlap identical, which is how a correct report was once read as the verb comparing folders rather than files.
+
+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.
+
+A citation resolving in neither the board nor the archive is `blocker-unresolved` rather than a settled row. Reading an absent file as archived states a specific fact about a file nobody ever wrote, which is what a renamed task or a typo produces, and only a task that genuinely closed releases the row waiting on it.
+
+The other three kinds rest on a person's judgment, so a row neither half reached lands in a second array rather than in the findings:
+
+```json
+{
+  "untested": [
+    {
+      "group": "Needs a plan",
+      "subject": "v50.6-a-standard-no-skill-reads",
+      "message": "..."
+    }
+  ]
+}
+```
+
+An untested row is not a finding and moves no exit code. Reading a clean findings list as a clean board is the failure the array exists to prevent, and `orchestrator-parked.md` is the pass that takes those rows by hand.
+
+A `## Run now` row whose Touches column names a bare folder lands in a third array on the same reasoning:
+
+```json
+{
+  "claims": [
+    {
+      "group": "Run now",
+      "subject": "v1.0-first",
+      "message": "claims the whole src/tasks folder, so it collides with every row written under it."
+    }
+  ]
+}
+```
+
+That claim collides with every row a later session writes under the folder, and it is legitimate whenever the row does rewrite the directory, so the array states the reach and moves no exit code. A measure failing on a cell that is right teaches a reader to skip it. Folder against file is decided by asking the tree for a path that resolves, and by the extension only for a path the row has yet to create, since the name alone reads a file carrying no extension as a folder.
+
+The scan reaches `## Run now` and stops, where the collision check stops. A cell in another group describes work nobody has planned, written as a sentence and rewritten once a plan exists, so a claim read off one reports on prose rather than on a file set. A parked folder claim surfaces when its row is promoted, which is when the cell becomes something a dispatcher can act on.
+
+Exit codes: `0` every check passed, `1` refused, `2` at least one finding. The `reason` field carries which gate refused: `no-board`, `no-ordering`, or `no-groups`. A board grouping under headings of its own trips `no-groups` rather than being read against columns it never declared.
+
+Columns are read from each table's own header rather than by position, so a project whose board differs from this one is reported for what it lacks. The `index`, `priority`, and `backlog` siblings are skipped, along with every pre-compaction handoff, which takes one file per session under a `session-` prefix. None of them is a task, and a handoff counted as one would be reported as a task carrying no row on every session that wrote one.
+
+Skills branch on the findings rather than on the exit code:
+
+```bash
+canon tasks validate --json | jq -r '.findings[] | "\(.kind): \(.subject)"'
+```
+
+For the board format, the `Pull request:` line, and the archive rules, see `standards/tasks.md`.

package/docs/agents/teach.md

@@ -0,0 +1,158 @@
+---
+title: Teach
+description: 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
+---
+
+# Teach
+
+Learning workspaces sit under `.claude/teach/<nn>-<topic>/`, and `standards/teach.md` fixes their layout, naming, and file formats, apart from the glossary, whose shape `standards/glossary.md` fixes, cited from the `claude-teach` skill, so it travels with the file wherever a promotion lands it. Every verb here resolves that folder against the main worktree root rather than against the working directory, so a session standing in a linked worktree reaches the one workspace the learner has rather than opening a second.
+
+That root resolution is also why the writing verbs exist at all. The file-editing tools refuse a main-root path from a linked worktree and offer a worktree copy instead, and a caller naming only the destination reports a success that did not happen. A whole-file create still goes out as a shell heredoc. Changing a line inside a file that already exists has no shell route, because the stream editors are banned, so `resource` and `glossary` are the route for the two files a running workspace edits.
+
+## List
+
+`canon teach list` reports the workspaces under `.claude/teach/`, or what one workspace holds. It reads and never writes.
+
+```bash
+canon teach list
+canon teach list regular-expressions --json
+```
+
+| Option          | Behavior                                    |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Teach root, defaulting to the main worktree |
+
+With no topic it reports one line per workspace, carrying the lesson, learning-record, reference-page, and glossary-term counts, plus `next`, the ordinal an open would take. With one it reports the filenames behind each count and the glossary entries themselves.
+
+A folder not named `NN-<topic>` is still listed rather than dropped, since dropping it hides the one folder that needs a fix. Its ordinal reads as absent, it sorts last, and it moves no ordinal, so a malformed name cannot push a new workspace into a number a reader already cites.
+
+The listing also names the required files a workspace does not carry, which is `MISSION.md`, `RESOURCES.md`, and `GLOSSARY.md`. That is a report rather than a refusal, because a workspace missing one is still a workspace a session can resume.
+
+## Open
+
+`canon teach open` creates a workspace at the next ordinal and writes all three required files.
+
+```bash
+canon teach open regular-expressions \
+  --subject "Reading and writing regular expressions" \
+  --starting-point "Comfortable with the shell, has never written a group" \
+  --success "Write a pattern matching a date" \
+  --success "Explain what a backreference does"
+```
+
+| Option                    | Behavior                                                    |
+| ------------------------- | ----------------------------------------------------------- |
+| `--subject <line>`        | One line stating what the workspace covers, required        |
+| `--starting-point <text>` | What the learner already knows, required                    |
+| `--success <line>`        | Observable thing the learner will be able to do, repeatable |
+| `--out-of-scope <line>`   | What the workspace does not cover, repeatable               |
+| `--title <text>`          | Title, defaulting to the topic in sentence case             |
+| `--date <YYYY-MM-DD>`     | Opening date, defaulting to today                           |
+| `--json`                  | Emit a machine-readable record on stdout                    |
+| `--root <path>`           | Teach root, defaulting to the main worktree                 |
+
+The ordinal comes from the highest already present, incremented, so the caller derives no name and composes no path. A topic another workspace already covers is refused rather than opened beside it, since two workspaces on one subject fork the learning records the folder exists to keep whole.
+
+`--starting-point` is required rather than defaulted because difficulty with no floor under it teaches nobody, and a mission written without one cannot say what the lessons sit above. At least one `--success` line is required for the same reason in the other direction: a mission nothing can test is a mission nothing can call finished.
+
+## Resource
+
+`canon teach resource` records sources in a workspace `RESOURCES.md`, keeping what was read apart from what was only found.
+
+```bash
+canon teach resource regular-expressions \
+  --read "MDN regular expressions=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions" \
+  --lead "RE2 syntax=https://github.com/google/re2/wiki/Syntax"
+```
+
+| Option               | Behavior                                           |
+| -------------------- | -------------------------------------------------- |
+| `--read <title=url>` | Source that stands behind the material, repeatable |
+| `--lead <title=url>` | Source found and not opened, repeatable            |
+| `--json`             | Emit a machine-readable record on stdout           |
+| `--root <path>`      | Teach root, defaulting to the main worktree        |
+
+The pair splits on the first `=`, so a URL carrying its own separator survives intact. Say in the title which claims rest on the source, since the entry is the only place a later session reads that from.
+
+A URL either heading already lists is refused rather than written twice. Two entries for one source split what rests on it across two lines, and a reader checking a claim then finds half of the answer.
+
+A URL a file displays inside a fence does not count as listed, which is how a workspace quoting the entry format in its own prose is read as the sample it is.
+
+## Glossary
+
+`canon teach glossary` adds terms to a workspace `GLOSSARY.md`, alphabetically.
+
+```bash
+canon teach glossary regular-expressions \
+  --term "capture group=A parenthesised part of a pattern whose match is kept" \
+  --first-seen 0002-groups.html
+```
+
+| Option                     | Behavior                                                  |
+| -------------------------- | --------------------------------------------------------- |
+| `--term <term=definition>` | Term the subject defines, repeatable                      |
+| `--first-seen <file>`      | Lesson or reference page the batch first defines these in |
+| `--json`                   | Emit a machine-readable record on stdout                  |
+| `--root <path>`            | Teach root, defaulting to the main worktree               |
+
+One call writes one file, which keeps a batch of terms from racing on the glossary every one of them shares. `--first-seen` names one page for the whole batch rather than one per term, because a batch comes from one lesson.
+
+A term already defined is refused rather than replaced. A definition the subject has moved under is a revision of the entry that exists, and nothing on the command line tells that apart from a second definition arriving by mistake.
+
+The entry lands as the standard's shape, leading with the term as a bolded span. A definition not ending in sentence punctuation is terminated before the citation is appended, so a bare phrase does not run into the sentence naming where the term first appears.
+
+## Lesson
+
+`canon teach lesson` resolves what the next lesson needs before it is written. It reads and never writes.
+
+```bash
+canon teach lesson regular-expressions \
+  --slug capture-groups \
+  --questions 3 \
+  --options 4
+```
+
+| Option            | Behavior                                                  |
+| ----------------- | --------------------------------------------------------- |
+| `--slug <kebab>`  | The lesson's own topic, required                          |
+| `--questions <n>` | How many questions the quiz carries, required             |
+| `--options <n>`   | How many options each question carries, defaulting to `4` |
+| `--json`          | Emit a machine-readable record on stdout                  |
+| `--root <path>`   | Teach root, defaulting to the main worktree               |
+
+It reports four things. `lesson` is the numbered path the lesson takes, derived from the highest ordinal already in `lessons/` the way an open derives a workspace ordinal. `stylesheet` names the one file every lesson in the workspace links, with `stylesheetExists` saying whether it is on disk yet and `stylesheetHref` carrying what the lesson's own link element holds. `success` carries the mission's success lines, so a session reports progress against the exit criteria without a second read of `MISSION.md`. `quiz` carries one entry per question.
+
+The stylesheet is reported rather than written. A verb that wrote it on every lesson would discard whatever the last lesson added, and the second lesson in a workspace is the one that needs the file the first one left.
+
+Each `quiz` entry carries `order`, the authored option indices in presentation order where index `0` is the correct answer, and `answer`, the one-based position that answer lands in. Both travel together because a caller deriving the position itself is a caller that can derive it wrongly.
+
+The order is drawn here rather than instructed, and that is the point of the verb. An author told to vary the position still varies it by judgment, and the judgment settles on the first slot, which is the defect this design departs from. The draw is uniform over the options, so the position carries no information about which answer is correct.
+
+## Opening a workspace
+
+No `canon teach` verb serves the workspace. `canon serve` does, taking the teach root as its directory and the workspace contents page as its entry:
+
+```bash
+canon serve .claude/teach --entry 03-fde-system-design/index.html --json
+```
+
+It stays general rather than becoming `canon teach serve`, because nothing about serving a directory is specific to a learning workspace, and the same verb carries a slide render and a design preview.
+
+Read `url` off the record rather than building one from the port that was asked for. The verb walks forward past a port already in use, which is routine when a second workspace is already open, and the port it took is the one thing a composed URL gets wrong.
+
+## Refusal reasons
+
+| Reason         | Raised when                                                     |
+| -------------- | --------------------------------------------------------------- |
+| `no-teach`     | The root carries no `.claude/teach/` folder                     |
+| `no-workspace` | No workspace matches the topic, with the folder names as detail |
+| `ambiguous`    | Two workspaces claim one topic, with both names as detail       |
+| `exists`       | A workspace already covers the topic an open names              |
+| `no-file`      | The workspace carries no file the verb writes into              |
+| `no-section`   | `RESOURCES.md` carries no heading the entries belong under      |
+| `listed`       | A URL is already listed under either heading                    |
+| `defined`      | A term already carries a glossary entry                         |
+| `bad-input`    | The command line is malformed, before any folder is read        |
+
+A `bad-input` refusal reports the working directory as its root rather than the resolved one, since the command line is rejected before the root is worth resolving. `lesson` raises it for a slug that is not kebab-case, for a quiz carrying no question, and for a question carrying fewer than two options, since a question with one option has nothing to confuse the right answer with.

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
+
+`canon 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
+canon gov test-order
+canon gov test-order --base origin/main --json
+canon 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. `canon 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/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
+
+`canon worktrees list` reports every worktree of the current repository with a reclaim verdict and the reason behind it.
+
+```bash
+canon worktrees list
+canon 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.