@erclx/canon 4.31.1 → 4.32.1

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

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

package/claude/skills/claude-docs/references/anchor-sweep.md

@@ -27,7 +27,7 @@ Most of these name a folder rather than a file, because the number an entry anch
 
 The third rule reaches folders alone, which is what keeps it off `CLAUDE.md`. Breadth is the whole reason it exists, and a root file has none: it names one path the diff either carries or does not.
 
-What it does stop is a citation of `.claude/` matching every branch. `src/`, `scripts/`, and `.claude/` each name a tree a project organizes most of its work under, so a prefix match on one fires constantly and rebuilds the ignored warning this sweep exists to avoid. Measured against this repository's record at `erclx/canon@87b11e87`, the skip drops 13 of the 26 folder citations and keeps the ones carrying a signal, among them `src/tooling/`, `.claude/rules/`, and `governance/rules/`.
+What it does stop is a citation of `.claude/` matching every branch. `src/`, `scripts/`, and `.claude/` each name a tree a project organizes most of its work under, so a prefix match on one fires constantly and rebuilds the ignored warning this sweep exists to avoid. Measured against this repository's record, the skip drops 13 of the 26 folder citations and keeps the ones carrying a signal, among them `src/tooling/`, `.claude/rules/`, and `governance/rules/`.
 
 A decision whose folder citations are all a single segment, and which cites no file, therefore never fires. That is the correct outcome rather than a gap: a count over a whole tree moves on nearly every branch, so flagging it every time tells a reader that time has passed and nothing else.
 

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

@@ -119,7 +119,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
    - Resolve the target at the moment of sending with `canon sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. The runbook read at step 5 routes on the count and the confidence it answers with
    - Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
    - Name the skill for the reader to run rather than writing an invocation, which arrives as text
-   - Read the pull request's own draft flag rather than the state a worker reports, and report what the read returned and when rather than the state alone. `canon docs pr-reads` states why a reported field can lag and say nothing about it. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft. That is how a poll on `erclx/canon#1307` told an operator the opposite of what the worker had said.
+   - Read the pull request's own draft flag rather than the state a worker reports, and report what the read returned and when rather than the state alone. `canon docs pr-reads` states why a reported field can lag and say nothing about it. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft and has told an operator the opposite of what the worker had said.
 
 A session is reachable when it appears in a live listing, which reads what each session registered on disk rather than probing it, and a message carries plain text and no authority. When no live session holds the branch, report the invocation for the human, naming the branch, the pull request, and the skill to run, then stop. Retrying or waiting leaves the loop believing it is open while nothing acts on it. Every dispatch in the trial behind this step found a live session, so this branch stands on reasoning rather than on observation.
 

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

@@ -103,15 +103,14 @@ The client expands a slash command at position zero of a launch prompt as a
 user invocation, which is the route `disable-model-invocation: true` permits
 and gates. Everything that reaches the session as prose instead falls to the
 model, which invokes it through the `Skill` tool, and that route answers a
-flagged skill inconsistently. `claude-autoship` has carried the flag since
-`erclx/canon#365` and seven other shipped skills carry it too.
+flagged skill inconsistently. `claude-autoship` has carried the flag since early in its life, and seven other
+shipped skills carry it too.
 
 Three launches on 2026-08-31 and 2026-09-02 bound what makes a command take
 that route. Observation A is the first refused worker, launched as `Run
 /canon:claude-worktree ..., then /canon:claude-autoship ...`, which expanded
 nothing. Observation B is a re-dispatch launched as `/canon:claude-autoship
-<plan>` with a space before the path, which expanded and shipped
-`erclx/canon#1382`.
+<plan>` with a space before the path, which expanded and shipped.
 
 Observation C is a planning dispatch launched as `/canon:claude-planner, then
 /canon:claude-feature <task>` with a comma glued to the command name at
@@ -178,7 +177,7 @@ Report the dispatch as loudly as the human-launch line it replaces: name the bra
 
 `claude-address-review` is a single pass, not a chain, so a launch naming it
 alone reaches no `claude-worker` and takes no role, which owes no message
-either. `erclx/canon#1251`'s replacement session was launched that way, onto the branch a
+either. A replacement session was launched that way once, onto the branch a
 review had already posted findings against, and it answered by posting a
 thread reply and telling its controller nothing. Reach the role directly on
 this launch instead of wrapping a second chain around one skill that has none

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

@@ -17,6 +17,8 @@ Name the planner as the case always in this set, and scope the act no narrower.
 
 Retire what this session dispatched. Report a hand-launched session and leave the act to the operator, since the knowledge making the act safe is a delivery this session received and it received nothing from a session it never launched. The `worker-` and `planner-` name prefixes separate the two populations, per `orchestrator-dispatch.md`.
 
+A capability gap sits beside the knowledge gap, and it holds even where delivery is somehow known. A hand-launched session is as often interactive as background, and `claude rm <id>` has no id to take for an interactive one at all, so the command cannot reach it whatever this session learned about its delivery.
+
 ### Telling a delivered session from a blocked one
 
 No status field carries the difference. `status` reads `busy` or `waiting` straight off the client record, and both describe the last turn rather than the work, so `waiting` is the ordinary answer for a session that reported and stopped, which is what a correct delivery looks like. The `statusDwellMs` beside it separates a long idle from a short one and separates nothing else.
@@ -25,7 +27,7 @@ The read is the report this session is holding. Retire a session whose delivery
 
 ### The act, and the order it runs in
 
-`claude rm <id>` removes a background session and its worktree together, and it takes one target per call, so a wave costs one call per session. The argument is the id rather than the name, which `claude agents --json` carries beside the name on every row, so a session read off a roster by name is matched to its id there before the call. Both readings are from 2026-09-02, where the name form answered `No job matching`.
+`claude rm <id>` is meant to remove a background session and its worktree together, though its own report is not reliable, so `canon worktrees list` is the reading to trust afterward. It takes one target per call, so a wave costs one call per session. The argument is the id rather than the name, which `claude agents --json` carries beside the name on every row, so a session read off a roster by name is matched to its id there before the call. Both readings are from 2026-09-02, where the name form answered `No job matching`.
 
 The command belongs to the client rather than to this toolkit, so a target running another client performs whatever removal that client offers.
 

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

@@ -70,7 +70,7 @@ The state reaches every stalled dispatch, since one threshold governs the headin
 
 The report is also where the count in `## Parallelism` is legible. That threshold trips on open pull requests awaiting a first pass, which is what `OPENED` and a pull request with no prior pass name here and what `SEEN` excludes, so read the count off these lines rather than off `gh pr list`, which counts a branch closed out and waiting on a merge the same as one nobody has read. It is a separate condition from the poll-start fallback above, which decides when this loop runs rather than where a review runs.
 
-The count reads low, and it errs in the direction that breaks the trigger. A review's `commit.oid` is stamped with the head at submission rather than with the commit the reviewer read, so an author pushing between the diff read and the post leaves the pass recorded against a commit it never saw, and `SEEN` then fires on a head still awaiting its first look at that delta. Measured on `erclx/canon#1299` on 2026-08-31, where a pass written against `erclx/canon@5653721` landed stamped `erclx/canon@a5ceb40` and the delta it skipped was a real fix. So a `SEEN` on a head you do not recognize is worth one `gh pr view --json reviews` before it is believed, and a wave past three is likelier to trip the fallback late than early.
+The count reads low, and it errs in the direction that breaks the trigger. A review's `commit.oid` is stamped with the head at submission rather than with the commit the reviewer read, so an author pushing between the diff read and the post leaves the pass recorded against a commit it never saw, and `SEEN` then fires on a head still awaiting its first look at that delta. That has fired for real, and the delta it skipped once was a genuine fix. So a `SEEN` on a head you do not recognize is worth one `gh pr view --json reviews` before it is believed, and a wave past three is likelier to trip the fallback late than early.
 
 The other side of that comparison used to lag as well, which made the two errors compound rather than cancel. `gh pr view --json headRefOid` answers from the pull request object and that object trails the branch ref by up to a minute after a push, reporting nothing about the trail, so a pass stamped ahead of the commit it read was compared against a head stamped behind the commit that exists. Two sessions were wrong off that field on 2026-09-01: a reviewing session posted a finding calling a pushed commit unpushed, and a worker fired a green claim it retracted on its own thread minutes later. The head now comes from `canon pr head`, which resolves the tip through `git ls-remote` and reports which commit each source names, and the object's head stays behind it as the fallback for a target whose CLI predates the verb. The review stamp is unchanged, so the paragraph above still holds on its own half.
 

package/claude/skills/claude-pr-review/SKILL.md

@@ -95,7 +95,7 @@ A non-empty result carries the comment id Step 4 needs for the third filename se
 
 A `## Post-review findings` reply carries no argued finding behind it, since it asserts a new defect rather than answering one, and this pass is its first independent reader. Restating it as a finding without opening anything is repeating the worker's claim rather than checking it. Read the file the comment names at `<headRefOid>`, the same `git show <headRefOid>:<path>` read Step 3 already runs to confirm a ticked box, and confirm the defect before it becomes a finding of this pass's own.
 
-A moved head has its own way to add nothing, which the ancestor test cannot see. When `<prior-heading>` reads `## Review closed`, the standing verdict already reports the branch clear, so a pass over the new commits that raises nothing posts a comment saying what the one above it said. Two close-outs landed on `erclx/canon#1201` that way on 2026-08-28, and the operator caught the pair rather than any check.
+A moved head has its own way to add nothing, which the ancestor test cannot see. When `<prior-heading>` reads `## Review closed`, the standing verdict already reports the branch clear, so a pass over the new commits that raises nothing posts a comment saying what the one above it said. Two close-outs landed that way on 2026-08-28, and the operator caught the pair rather than any check.
 
 The producing shape is narrow. A prior pass tells the author a change is their own call, the author makes it, and the delta reaching the next pass has nothing left to say by construction.
 

package/claude/skills/create-skill/SKILL.md

@@ -29,4 +29,4 @@ Read these files in parallel:
 
 Every skill carries a requirement. A skill created without one is a gap someone closes in a later sweep, and the sweep has to reconstruct what the skill was for from the body it already shipped.
 
-The two-question check has a shipped precedent. Pull request `erclx/canon#516` dropped `git-stash` for wrapping a single git command that needed no skill body, and `release-changelog` for being low-frequency and invoked by no other skill. The first is question one, and the second is question three read back after the fact, which is why it stays a review criterion rather than something this skill can gate on.
+The two-question check has a shipped precedent. A pull request dropped `git-stash` for wrapping a single git command that needed no skill body, and `release-changelog` for being low-frequency and invoked by no other skill. The first is question one, and the second is question three read back after the fact, which is why it stays a review criterion rather than something this skill can gate on.

package/claude/skills/write-human/REQUIREMENT.md

@@ -13,7 +13,7 @@ The output of that arrangement is specific rather than general. Paragraphs come
 
 A session also has no name for the patterns no closed word set can match. Rule-of-three, synonym cycling, false ranges, inline-header lists, and adverb propping each survive a clean scan, so a passage carrying all five reports zero findings and still reads wrong. Nothing tells the session those patterns exist, and a ban list cannot be extended to reach them, because each is a shape rather than a token.
 
-Importing that catalog wholesale fails on a different measurement. External material of this kind bans abstract metaphor nouns and names `surface` among them, which this corpus uses 593 times in tracked markdown at `erclx/canon@57ee7467`. A session handed the catalog with no stated position either rewrites established vocabulary or silently ignores the item, and neither outcome is recoverable by a later reader who cannot tell which happened.
+Importing that catalog wholesale fails on a different measurement. External material of this kind bans abstract metaphor nouns and names `surface` among them, which this corpus uses 593 times in tracked markdown. A session handed the catalog with no stated position either rewrites established vocabulary or silently ignores the item, and neither outcome is recoverable by a later reader who cannot tell which happened.
 
 ## Must
 

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

@@ -24,7 +24,7 @@ The ambiguity rules travel with that layer for the same reason. Compression is w
 - **Any restatement of a banned word set.** The bans ship as package data that `canon 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 `erclx/canon@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.
+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 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
 

package/docs/agents/context-audit-checks.md

@@ -55,7 +55,7 @@ The table check reports a catalog that grows a row per shipped thing, not a tabl
 
 The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open.
 
-A date stamping a measurement is excluded, because the standard cuts a date attached to a change and permits one dating a figure. The check reads the clause in front of the date, back to the nearest sentence boundary, for one of five verbs: measured, verified, driven, passed, and fired. The noun `run` counts only where it sits against the date, so `A run on 2026-08-14` is excluded and `Runs on erclx/canon#632 and erclx/canon#634 landed 2026-08-02` reports. The set is closed, and a date it cannot place reports as a change marker rather than as a state of its own, which names one date too many rather than clearing one the rule cuts.
+A date stamping a measurement is excluded, because the standard cuts a date attached to a change and permits one dating a figure. The check reads the clause in front of the date, back to the nearest sentence boundary, for one of five verbs: measured, verified, driven, passed, and fired. The noun `run` counts only where it sits against the date, so `A run on 2026-08-14` is excluded and `Runs on erclx/canon#632 and erclx/canon#634 landed 2026-08-02` reports. The set is closed, and a date it cannot place reports as a change marker rather than as a state of its own, which names one date too many rather than clearing one the rule cuts. <!-- canon-allow-reference: illustrates the input shape the rule reads -->
 
 A release label reports with or without its leading `v` at three segments, since the rule cuts the label rather than a spelling of it. Two segments still need the `v`, which keeps a dollar cost and a duration out. Another tool's version reports too, and the check cannot tell one from a release, so treat a version beside a tool name as a line to read rather than one to cut.
 

package/docs/agents/key-changes.md

@@ -28,7 +28,7 @@ The positional is the pull request to read, defaulting to the one open on this b
 
 Without `--body` the body, the file list, and the head commit come back from one `gh pr view` call, because the three have to describe the same commit and reading them apart leaves a window where a push between them compares a body against another head's files.
 
-That view caps its file list at 100 rows and says nothing about having done so, which was measured against `erclx/canon#1250`: the pull request carries 101 files and the view reports 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.
+That view caps its file list at 100 rows and says nothing about having done so, measured against a pull request carrying 101 files where the view reported 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.
 
 ## The two directions
 
@@ -105,7 +105,7 @@ The bound is that the corpus is one repository writing to one house style. A pro
 
 What it cannot see is a bullet claiming a change to a file the branch did touch for another reason, and a path written without backticks. A claim in a second coordinated clause after the comma is read and credited, and it stays out of the graded direction, since nothing here separates it from a file the same clause cites for context.
 
-One class stays open and is named rather than closed. A bullet can cite where something is defined while claiming an edit somewhere else, as `erclx/canon#1274` does with "Name the slug transform in `standards/slug.md` inline in the same step". The path is a definition site, the edit target is the step, and separating the two needs the sentence parsed rather than cut. A finding on such a bullet is this class rather than a stale claim, and a reader weighing an `unmet` path checks whether the bullet's real target is a locative the path does not name.
+One class stays open and is named rather than closed. A bullet can cite where something is defined while claiming an edit somewhere else, as `erclx/canon#1274` does with "Name the slug transform in `standards/slug.md` inline in the same step". The path is a definition site, the edit target is the step, and separating the two needs the sentence parsed rather than cut. A finding on such a bullet is this class rather than a stale claim, and a reader weighing an `unmet` path checks whether the bullet's real target is a locative the path does not name. <!-- canon-allow-reference: illustrates the input shape the rule reads -->
 
 ## Where it runs
 

package/docs/agents/markdown-audit.md

@@ -120,7 +120,7 @@ The unit is the paragraph and each file names its worst on each measure, which f
 
 Neither number gates and neither names a file wrong. This is a weaker claim than the one the weight checkpoints make, because a healthy range differs by surface: a catalog entry is several short sentences carrying one fact each, and a page arguing a decision is not, so one range applied across the corpus would report the surfaces that are correct. The run therefore states where the numbers came from beside them, and the counts are what a reader compares against.
 
-Measured at `erclx/canon@6c273324` across the corpus, 2119 paragraphs reached the floor, 165 sat at or under the spread checkpoint and 50 past the opener checkpoint. Over the 60 files carrying at least ten measured paragraphs the flat rate runs from zero to 21 percent with a median near 6, which is the spread that makes the measure worth reading. Two wiki pages sit at either end of it: a server catalog reports 19 percent, its flattest paragraph five sentences within four words of each other and three of them verbless, while a page arguing where the prose rules came from reports none.
+A reading of that spread across the whole corpus is what backs the range above, taken once against this repository's own tracked markdown rather than against a target project's.
 
 That reading travels with the command rather than staying here. `BASELINE` in `src/markdown/structure.ts` carries the overall share, the per-file range, and the ten-paragraph floor beneath which a file's own rate says nothing, and the run prints all four in the legend beside the rate it measured. A count with no range beside it reads as a finding, and naming that a healthy range differs by surface states that a range exists rather than what it looks like. This page is toolkit-internal, so a reader running the command in a project that installed no standards would otherwise have two counts and nothing to place them against.
 
@@ -138,7 +138,7 @@ Exit codes are `0` for a completed run with no gating finding, `1` for a refusal
 
 A banned character is a fact rather than a judgment, which is the test that admits it to a gate. What held it back was that gating on day one against a corpus never checked mechanically fails loudly on work nobody has had a chance to fix. The order was to land the verb reporting, measure the corpus once, fix what it finds, and turn the gate on as its own change, and the gate is the last of the four.
 
-Measured at `erclx/canon@4b7b13a2` across 444 files with the paragraph checkpoint at 600: 8 word hits, no character or spelling hits, 119 heavy bullets, 221 heavy paragraphs across 86 files, and 41 files carrying a run past the depth checkpoint. Of the paragraphs, 88 fire on weight alone. That is the baseline the corpus sweep started from, and the ban count is the only one of the five a gate should ever read.
+Of the five measures a first full reading took, the ban count is the only one a gate should ever read.
 
 The ban half reached zero, which was the precondition the gate waited on, and it was re-measured against the same corpus at the moment the gate landed. Three sweep slices then took the structural half, and the corpus reports 1 heavy bullet and 22 heavy paragraphs across 6 files on 2026-08-06, every one on a ground the triage record holds as exempt.
 

package/docs/agents/sessions.md

@@ -42,6 +42,10 @@ A bare run reports every repository and carries a `repository` field on each row
 
 The match can return more than one session. Read the count rather than the first row, since nothing stops two sessions holding one branch, and a caller that treats the result as singular picks among candidates without knowing it.
 
+Resolution reads a session's registered `cwd`, taken at whatever `locate()` finds there rather than wherever it has since worked. That registration updates whenever the harness enters a worktree: a worker dispatched onto `main` re-registers at its own branch once `claude-autoship` Step 0 runs. What stays fixed is a session moved by shell command, `cd` or `git -C` against another root, with no worktree entry behind it, so it answers only for the branch its last registered `cwd` sits in.
+
+A session whose `cwd` reflects a harness worktree entry, at launch or mid-session, resolves fully, covering every dispatched worker once Step 0 runs. A zero for a different branch it is genuinely working on is not evidence the branch is unclaimed, only that a shell-moved registration cannot see it.
+
 ## Whether a branch is already claimed
 
 With `--branch`, the JSON record also carries `worktree` (the path of any worktree already checked out to it, or `null`), `refs` (the refs that already name the branch, the local head and the `origin` remote-tracking ref alike), and `claimed` (`true` when any of the three holds it).

package/docs/agents/superseded.md

@@ -38,7 +38,7 @@ Pass an empty replacement to retire a value outright, as in `canon gov supersede
 
 ## The templated citation
 
-A citation naming a family as a pattern carries neither value. `canon-*` and `internal-<X>` are the two forms this corpus writes, and a literal comparison matches neither, so a rename running the verb once per name reports clean while the family citations stay stale. Two of those on `erclx/canon#1250` had inverted, stating the old prefix as a guard, which left a rule instructing the next session to flag the correct naming as a mismatch.
+A citation naming a family as a pattern carries neither value. `canon-*` and `internal-<X>` are the two forms this corpus writes, and a literal comparison matches neither, so a rename running the verb once per name reports clean while the family citations stay stale. Two such citations have inverted this way, stating the old prefix as a guard, which left a rule instructing the next session to flag the correct naming as a mismatch.
 
 Beside the literal comparison the run matches a family stem, derived from the segment the two values actually differ on, with everything they share carried ahead of it. `toolkit-operator` to `canon-operator` derives `toolkit`, and `canon-cli` to `canon-shell` derives `canon-cli` rather than `canon`, which is what keeps a rename of one folder off every sibling in its family.
 

package/docs/agents/worktrees.md

@@ -89,11 +89,14 @@ The read is one `gh pr list --state merged` for the whole repository rather than
 
 `route` names which one applies rather than choosing it, since picking wrong strands state.
 
-- `session`: a live session holds the directory, and `claude rm <id>` removes the session and its worktree together. The `sessions` field carries names rather than ids, and a name is whatever string the session was launched under, spaces included, so quote it and match it against `claude agents --json`, which carries the id beside the name on every row.
+- `session`: a live session holds the directory, and the `sessions` field carries `{name, kind, id}` per holder rather than a bare name, since `claude rm <id>` takes the id and never the name. `kind` reads `bg` or `interactive` off this repository's session registry.
+  - A resolved background holder: `id` carries the value `claude agents --json` reports, so `claude rm <id>` is the command to run. Its own report is not reliable: two runs under matched conditions on 2026-09-03 both printed `kept`, and one of them had already removed the worktree, so read `canon worktrees list` again afterward rather than trust what the command printed.
+  - An unresolved background holder: `id` is `null` because the binary is missing, fails, or has not reported that pid yet, so its id has to come from a manual read of `claude agents --json` instead.
+  - An interactive holder: `id` is always `null`, since no id exists for one at all, and nothing removes it until a person closes its terminal.
 - `worktree`: the session has ended, and `canon worktrees reclaim` is what runs the remove and the branch delete.
 - `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.
+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, and an interactive holder is the one shape inside that refusal with no removal route at all.
 
 ## What an unreadable input does
 

package/package.json

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

package/src/client-commands.ts

@@ -0,0 +1,99 @@
+import { escapeForPattern, isMarked } from '@/exempt-marker'
+
+/**
+ * A client command this repository quotes, with the argument spelling every
+ * quotation of it has to carry.
+ *
+ * `source` is the fact grounding `canonicalArgument`, so a reader correcting a
+ * flagged line can see why the flagged form is wrong rather than taking the
+ * table on faith.
+ */
+export interface ClientCommand {
+  readonly command: string
+  readonly canonicalArgument: string
+  readonly source: string
+}
+
+export const CLIENT_COMMANDS: readonly ClientCommand[] = [
+  {
+    command: 'claude rm',
+    canonicalArgument: 'id',
+    source:
+      '`claude rm <id>` takes the session id `claude agents --json` carries beside a name, never the name itself, confirmed against `claude rm --help` on 2026-09-02.',
+  },
+]
+
+export const CLIENT_COMMAND_MARKER = 'canon-allow-client-command'
+
+/**
+ * A bracketed placeholder or a template interpolation, each optionally
+ * single-quoted, which is the one call form this scanner reads. A sentence
+ * naming the command with no bracketed argument carries no placeholder at all
+ * and never matches, which is deliberate: the defect this closes is a wrong
+ * argument shown as an invocation, not a sentence that never showed one.
+ *
+ * The interpolation half admits a dotted path, since a property access is the
+ * ordinary shape a real call site interpolates, such as `${session.id}`, and a
+ * bare `${id}` is the rarer one that only a fixture writes. A capture stopping
+ * at the first `.` matched the command literal and missed the property access
+ * beside it entirely, which is how the check went unable to read the one call
+ * form this repository's own worktree listing writes.
+ */
+const PLACEHOLDER = `'?(?:<([\\w-]+)>|\\$\\{(\\w+(?:\\.\\w+)*)\\})'?`
+
+export interface ClientCommandCitation {
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly command: string
+  /** The invocation as written, so a report names the text to correct. */
+  readonly text: string
+  readonly argument: string
+}
+
+/**
+ * Every quotation of a listed command in one file whose argument disagrees
+ * with the table, and no marker mutes.
+ *
+ * `commands` defaults to the shipped table and takes a narrower one only for
+ * the empty-table case a measure guards against, since production code never
+ * has a reason to check against anything else.
+ */
+export function clientCommandCitationsIn(
+  file: string,
+  text: string,
+  commands: readonly ClientCommand[] = CLIENT_COMMANDS,
+): ClientCommandCitation[] {
+  const lines = text.split('\n')
+  const citations: ClientCommandCitation[] = []
+
+  for (const { command, canonicalArgument } of commands) {
+    const pattern = new RegExp(
+      `${escapeForPattern(command)}\\s+${PLACEHOLDER}`,
+      'g',
+    )
+
+    for (const [index, line] of lines.entries()) {
+      if (isMarked(lines, index, CLIENT_COMMAND_MARKER)) continue
+
+      for (const match of line.matchAll(pattern)) {
+        const dotted = match[2]
+        const argument =
+          dotted !== undefined
+            ? (dotted.split('.').at(-1) ?? dotted)
+            : (match[1] ?? '')
+        if (argument === canonicalArgument) continue
+
+        citations.push({
+          file,
+          line: index + 1,
+          command,
+          text: match[0],
+          argument,
+        })
+      }
+    }
+  }
+
+  return citations
+}

package/src/commands/worktrees.ts

@@ -145,10 +145,12 @@ export function register(program: Command): void {
         ...CONDITIONS,
         '',
         'This reports and removes nothing. "route" names which removal shape',
-        'applies: "session" when a live session holds the directory, where',
-        '`claude rm <id>` takes the session and its worktree together, and',
-        '"worktree" when the session has ended, where `canon worktrees',
-        'reclaim` is the pair of a remove and a branch delete.',
+        'applies: "session" when a live session holds the directory,',
+        'where `claude rm <id>` is meant to remove it and its worktree',
+        'together, but its own report is not reliable, so run this command',
+        'again afterward to see what happened. "worktree" is the shape once',
+        'the session has ended, where `canon worktrees reclaim` is the pair',
+        'of a remove and a branch delete.',
         '',
         'Examples:',
         '  canon worktrees list',
@@ -185,8 +187,10 @@ export function register(program: Command): void {
         'gone sweeps stale registrations once before the branch deletes.',
         '',
         'It deletes only what a reading called reclaimable. A worktree a live',
-        'session holds is refused rather than removed, since `claude rm <id>`',
-        'is what takes a session and its worktree together.',
+        'session holds is refused rather than removed here. `claude rm <id>`',
+        'is meant to remove the session and its worktree together, but its',
+        'own report is not reliable, so run `canon worktrees list` again',
+        'afterward to see what happened.',
         '',
         'The stale-registration sweep is the one step that reaches wider, since',
         'git takes no path to scope it. It clears the bookkeeping for every',
@@ -429,20 +433,27 @@ function reportWorktrees(worktrees: readonly WorktreeVerdict[]): void {
  * what to remove, so a row phrased for the first alone leaves the second
  * removing a directory on a conclusion it cannot check.
  */
-function describe(verdict: WorktreeVerdict): string {
+export function describe(verdict: WorktreeVerdict): string {
   const held = verdict.branch ?? 'detached'
   const head = `${verdict.path}  ${held}`
 
   if (!verdict.reclaimable) {
     const reasons = verdict.refusals.map((refusal) => REFUSALS[refusal])
-    // A name is quoted because a session carries whatever string it was
-    // launched under, spaces included, and one command per name because a
-    // joined list reads as a single argument.
+    // Three cases rather than one line, since only a resolved background
+    // holder has a real command to print. An interactive holder has no id to
+    // look up at all, and an unresolved background one has an id somewhere in
+    // `claude agents --json` that this reading could not cross-reference.
     const routes =
       verdict.route === 'session'
-        ? verdict.sessions.map(
-            (name) => `\n  Removal there goes through: claude rm '${name}'`,
-          )
+        ? verdict.sessions.map((session) => {
+            if (session.kind === 'interactive') {
+              return `\n  ${session.name}: interactive, so nothing removes it until its terminal closes.`
+            }
+            if (session.id === null) {
+              return `\n  ${session.name}: match it against claude agents --json for its id, then claude rm '<id>'.`
+            }
+            return `\n  Removal there goes through: claude rm '${session.id}'`
+          })
         : []
     return `${head}\n  Refused: ${reasons.join('; ')}.${routes.join('')}`
   }

package/src/exempt-marker.ts

@@ -7,7 +7,7 @@
  * wrong lines and one holding a parenthesis throws, and neither failure is the
  * caller's to anticipate.
  */
-function escapeForPattern(token: string): string {
+export function escapeForPattern(token: string): string {
   return token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 

package/src/gate/measures.ts

@@ -1,6 +1,13 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import {
+  CLIENT_COMMAND_MARKER,
+  CLIENT_COMMANDS,
+  type ClientCommand,
+  clientCommandCitationsIn,
+} from '@/client-commands'
+import { listRepositoryFiles } from '@/git-files'
 import {
   isShippedCorpus,
   REFERENCE_MARKER,
@@ -522,13 +529,78 @@ export const shippedReferences: Measure = async (ctx) => {
   return {
     emissions: found.map((reference) =>
       warn(
-        `${reference.file}:${reference.line} carries ${reference.text}, a ${reference.kind === 'commit' ? 'commit sha that resolves nowhere' : 'pull request number that resolves elsewhere'} for a reader in a target`,
+        reference.selfCitation
+          ? `${reference.file}:${reference.line} carries ${reference.text}, a citation of this repository's own history that resolves for no reader outside it, qualified or not`
+          : `${reference.file}:${reference.line} carries ${reference.text}, a ${reference.kind === 'commit' ? 'commit sha that resolves nowhere' : 'pull request number that resolves elsewhere'} for a reader in a target`,
+      ),
+    ),
+    failure:
+      found.length === 1
+        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, state a same-repository citation as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
+        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, state a same-repository citation as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
+  }
+}
+
+/**
+ * Every git-tracked file quoting a listed client command with the wrong
+ * argument, over the whole tree rather than one corpus, since a wrong
+ * quotation can land in any file this repository writes.
+ *
+ * `commands` defaults to the shipped table and takes a narrower one only to
+ * cover the case where that table ships empty, which is a broken check rather
+ * than a clean tree, exactly as an empty ban set is for `markdownBans`.
+ */
+export const clientCommandCitations = async (
+  ctx: MeasureContext,
+  commands: readonly ClientCommand[] = CLIENT_COMMANDS,
+): Promise<MeasureReport> => {
+  if (commands.length === 0) {
+    return {
+      emissions: [],
+      failure:
+        'The client command table is empty, so the corpus was walked and nothing was looked for. Check src/client-commands.ts.',
+    }
+  }
+
+  const files = await listRepositoryFiles(ctx.root)
+  if (files === undefined) {
+    return {
+      emissions: [],
+      unmeasured:
+        'The tracked file list could not be read, so no client command citation was checked.',
+    }
+  }
+
+  const found = files.flatMap((file) => {
+    let text: string
+    try {
+      text = readFileSync(join(ctx.root, file), 'utf8')
+    } catch {
+      return []
+    }
+    return clientCommandCitationsIn(file, text, commands)
+  })
+
+  if (found.length === 0) {
+    return {
+      emissions: [
+        info(
+          `No client command carries a wrong argument across ${files.length} tracked files`,
+        ),
+      ],
+    }
+  }
+
+  return {
+    emissions: found.map((citation) =>
+      warn(
+        `${citation.file}:${citation.line} carries ${citation.text}, which quotes \`${citation.command}\` with the wrong argument`,
       ),
     ),
     failure:
       found.length === 1
-        ? `One reference in the shipped corpora names this repository without saying so. Qualify it as owner/repo#123 or owner/repo@abc1234, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
-        : `${found.length} references in the shipped corpora name this repository without saying so. Qualify each as owner/repo#123 or owner/repo@abc1234, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
+        ? `One tracked citation quotes a client command with the wrong argument. Match it against the canonical form in src/client-commands.ts, or mark the line ${CLIENT_COMMAND_MARKER}: <reason> where the argument differs on purpose.`
+        : `${found.length} tracked citations quote a client command with the wrong argument. Match each against the canonical form in src/client-commands.ts, or mark the line ${CLIENT_COMMAND_MARKER}: <reason> where the argument differs on purpose.`,
   }
 }
 

package/src/gate/stages.ts

@@ -1,6 +1,7 @@
 import {
   auditSet,
   captureStamps,
+  clientCommandCitations,
   markdownBans,
   type Measure,
   pluginManifests,
@@ -370,6 +371,13 @@ export const STAGES: readonly Stage[] = [
     label: 'Markdown bans',
     checks: [{ kind: 'measure', measure: markdownBans }],
   },
+  {
+    // Unscoped, since a wrong quotation of a client command can land in any
+    // tracked file rather than in one corpus.
+    id: 'client-command-citations',
+    label: 'Client command citations',
+    checks: [{ kind: 'measure', measure: clientCommandCitations }],
+  },
   {
     // Scoped to the corpora it reads rather than run unconditionally, so a
     // branch touching only `src/` or `.claude/` skips it and says so. The

package/src/shipped/references.ts

@@ -105,6 +105,26 @@ const PULL_REQUEST = /(?<![0-9A-Za-z_])#([0-9]+)(?![0-9A-Za-z_])/g
  */
 const COMMIT_SHA = /(?<![0-9A-Za-z_@/#])([0-9a-f]{7,40})(?![0-9A-Za-z_])/g
 
+/**
+ * A same-repository citation, qualified or not. Qualifying `#123` or a sha
+ * against `erclx/canon` is the repair `PULL_REQUEST` and `COMMIT_SHA` above
+ * read as the fix, and it fixes nothing here: a reader holding only the
+ * plugin cache or the published package still cannot open this repository's
+ * own history, so the qualified form resolves exactly as badly as the bare
+ * one.
+ *
+ * The literal is hardcoded rather than read from `package.json` or
+ * `git remote`, matching `src/github-format.ts` and `src/commands/repo.ts`,
+ * which already hardcode it.
+ *
+ * Same word-boundary discipline as the two patterns above: a word character
+ * ahead of `erclx` would mean this match is a suffix of some other token, and
+ * a word character behind the digits would mean the citation continues past
+ * what was captured.
+ */
+const SAME_REPOSITORY =
+  /(?<![0-9A-Za-z_/])erclx\/canon(#[0-9]+|@[0-9a-f]{7,40})(?![0-9A-Za-z_])/g
+
 export interface ShippedReference {
   readonly file: string
   /** One-based, matching the `file:line` form a reader clicks. */
@@ -112,6 +132,12 @@ export interface ShippedReference {
   readonly kind: 'pull-request' | 'commit'
   /** The reference as written, so a report names the token to qualify. */
   readonly text: string
+  /**
+   * Set only for a citation of this repository's own history. Qualifying it
+   * is not the fix `kind` alone would suggest, so a caller reads this before
+   * choosing a remedy.
+   */
+  readonly selfCitation?: true
 }
 
 /**
@@ -154,6 +180,16 @@ export function referencesIn(file: string, text: string): ShippedReference[] {
         text: match[0],
       })
     }
+
+    for (const match of line.matchAll(SAME_REPOSITORY)) {
+      references.push({
+        file,
+        line: index + 1,
+        kind: match[1]?.startsWith('#') ? 'pull-request' : 'commit',
+        text: match[0],
+        selfCitation: true,
+      })
+    }
   }
 
   return references

package/src/worktrees/reclaim.ts

@@ -16,6 +16,9 @@ import {
 
 const GH_TIMEOUT_MS = 30_000
 
+/** A local binary read, not a network round trip, so the bound is tighter. */
+const CLAUDE_AGENTS_TIMEOUT_MS = 10_000
+
 /**
  * How many merged pull requests one read covers. A worktree older than this
  * many merges reads as having none and is refused, which is the safe direction:
@@ -47,6 +50,21 @@ export type Route = 'session' | 'worktree'
 /** No removal shape reaches the main worktree, which is what `null` says. */
 export type RemovalRoute = Route | null
 
+/**
+ * One live session holding a worktree, enriched with the id `claude rm` takes.
+ *
+ * `id` is null on two occasions a caller cannot tell apart from the name
+ * alone: an interactive holder, which carries no id at all since nothing but a
+ * person closing its terminal removes it, and a background holder whose id
+ * `claude agents --json` could not resolve, whether the binary is missing,
+ * failing, or simply has not reported that pid.
+ */
+export interface HeldSession {
+  readonly name: string
+  readonly kind: string
+  readonly id: string | null
+}
+
 export interface WorktreeVerdict {
   readonly path: string
   readonly branch: string | null
@@ -55,12 +73,8 @@ export interface WorktreeVerdict {
   readonly refusals: readonly Refusal[]
   /** The pull request that retired the branch, so a report can name what it read. */
   readonly pullRequest: number | null
-  /**
-   * The names of the live sessions holding this worktree. `claude rm` takes an
-   * id rather than a name, so a caller acting on this matches each name to the
-   * id `claude agents --json` carries beside it.
-   */
-  readonly sessions: readonly string[]
+  /** The live sessions holding this worktree. */
+  readonly sessions: readonly HeldSession[]
   readonly route: RemovalRoute
   /**
    * True when the directory is already gone and only the registration remains,
@@ -107,6 +121,9 @@ export interface ReclaimOptions {
   readonly mergedPullRequests?: (cwd: string) => Promise<MergedReport>
   readonly worktreeStatus?: (path: string) => Promise<StatusReport>
   readonly resolve?: () => Promise<SessionReport>
+  readonly claudeAgentIds?: (
+    cwd: string,
+  ) => Promise<ReadonlyMap<number, string>>
 }
 
 /**
@@ -170,6 +187,45 @@ async function mergedPullRequests(cwd: string): Promise<MergedReport> {
   }
 }
 
+/**
+ * Reads every live agent's session id, keyed by its process id, from `claude
+ * agents --json`.
+ *
+ * Guarded like `mergedPullRequests`, reading the same way, but degrading
+ * rather than refusing: the id enriches a caller's report and is never an
+ * input the reclaim logic depends on, where the merge state decides whether a
+ * removal is safe at all. A missing or failing binary leaves every entry
+ * unresolved instead of refusing the whole reading.
+ */
+async function claudeAgentIds(
+  cwd: string,
+): Promise<ReadonlyMap<number, string>> {
+  if (Bun.which('claude') === null) return new Map()
+
+  try {
+    const result = await execa('claude', ['agents', '--json'], {
+      cwd,
+      timeout: CLAUDE_AGENTS_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    const rows = JSON.parse(result.stdout) as readonly {
+      pid?: unknown
+      id?: unknown
+    }[]
+
+    const ids = new Map<number, string>()
+    for (const row of rows) {
+      if (typeof row.pid === 'number' && typeof row.id === 'string') {
+        ids.set(row.pid, row.id)
+      }
+    }
+    return ids
+  } catch {
+    return new Map()
+  }
+}
+
 /**
  * Reports whether a worktree holds work no history is behind.
  *
@@ -214,16 +270,14 @@ function holders(
   entry: WorktreeEntry,
   sessions: readonly ResolvedSession[],
   repository: string | null,
-): readonly string[] {
-  return sessions
-    .filter(
-      (candidate) =>
-        candidate.worktree === entry.path ||
-        (entry.branch !== null &&
-          candidate.branch === entry.branch &&
-          candidate.repository === repository),
-    )
-    .map((candidate) => candidate.name)
+): readonly ResolvedSession[] {
+  return sessions.filter(
+    (candidate) =>
+      candidate.worktree === entry.path ||
+      (entry.branch !== null &&
+        candidate.branch === entry.branch &&
+        candidate.repository === repository),
+  )
 }
 
 function verdict(
@@ -234,8 +288,20 @@ function verdict(
   merged: ReadonlyMap<string, number>,
   sessions: readonly ResolvedSession[],
   repository: string | null,
+  agentIds: ReadonlyMap<number, string>,
 ): WorktreeVerdict {
   const held = holders(entry, sessions, repository)
+  // An interactive holder carries no id to look up at all, so the branch is
+  // explicit rather than relying on `claude agents --json` never reporting one
+  // for a pid this repository's own registry marked interactive.
+  const heldSessions: HeldSession[] = held.map((session) => ({
+    name: session.name,
+    kind: session.kind,
+    id:
+      session.kind === 'interactive'
+        ? null
+        : (agentIds.get(session.pid) ?? null),
+  }))
   const pullRequest =
     entry.branch === null ? null : (merged.get(entry.branch) ?? null)
   const refusals: Refusal[] = []
@@ -262,7 +328,7 @@ function verdict(
     reclaimable: refusals.length === 0,
     refusals,
     pullRequest,
-    sessions: held,
+    sessions: heldSessions,
     // No removal shape reaches the main worktree, and reporting one there
     // offers a command whose only effect is to break the checkout. Deciding it
     // here rather than in the reporter keeps the record and the framed output
@@ -301,14 +367,17 @@ export async function reclaimReport(
   const readMerged = opts.mergedPullRequests ?? mergedPullRequests
   const readStatus = opts.worktreeStatus ?? worktreeStatus
   const resolve = opts.resolve ?? resolveSessions
-
-  const [entries, merged, sessions, repository, current] = await Promise.all([
-    listAll(cwd),
-    readMerged(cwd),
-    resolve(),
-    repositoryOf(cwd),
-    currentWorktreeRoot(cwd),
-  ])
+  const readAgentIds = opts.claudeAgentIds ?? claudeAgentIds
+
+  const [entries, merged, sessions, repository, current, agentIds] =
+    await Promise.all([
+      listAll(cwd),
+      readMerged(cwd),
+      resolve(),
+      repositoryOf(cwd),
+      currentWorktreeRoot(cwd),
+      readAgentIds(cwd),
+    ])
 
   if (merged.kind === 'unreadable') {
     return {
@@ -344,6 +413,7 @@ export async function reclaimReport(
       byBranch,
       sessions.sessions,
       repository,
+      agentIds,
     ),
   )
 

package/standards/publish.md

@@ -62,9 +62,13 @@ A number referring to a pull request or an issue takes the form its destination
 
 Text published to a remote is the auto-linking half: a pull request body, an issue body, a comment on either, and a commit message. Write `#123` there, and `owner/repo#123` where the reference crosses repositories, which the same auto-linking reaches. A markdown file browsed from the repository tree is the other half, where neither spelling links and the backticked one marks the number as an identifier. <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy -->
 
-Content that installs into another repository is the third destination, and there the qualified form is required rather than chosen. A skill body loads from a plugin cache, a docs page is read through `canon docs`, and a standard through `canon standards`, so the reader holds their own repository rather than the one the number belongs to. A bare number resolves against theirs and reaches something else, and a bare sha resolves nowhere at all.
+Content that installs into another repository is the third destination, and it splits on which repository the number names. A skill body loads from a plugin cache, a docs page is read through `canon docs`, and a standard through `canon standards`, so the reader holds their own repository rather than the one a bare number belongs to. Qualifying a number against a different, resolvable repository fixes that, since the reader can open that repository even without this one.
 
-Write `owner/repo#123` and `owner/repo@abc1234` across every such surface. `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or on the line above.
+Qualifying it against `erclx/canon` fixes nothing, because a reader holding only the plugin cache or the published package still cannot open this repository's own history. A same-repository citation takes no number here at all, bare or qualified. State the fact the citation was standing in for instead, and where the identifier is the only trace of a one-off incident rather than a reproducible count, carry it into the `.claude/context/` entry that owns the surface.
+
+Write `owner/repo#123` and `owner/repo@abc1234` for a citation of a different, resolvable repository, across every such surface. `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or on the line above.
+
+Choose the number over the sha where the citation names a decided change, since a pull request number resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape `.claude/ARCHITECTURE.md` already uses. The choice holds for both spellings this section fixes, the bare form a remote auto-links and the qualified form a cross-repository citation carries.
 
 A commit message takes the bare form even though it is also read through the log, where nothing links. The remote is what the form is chosen for, since a reader in the log loses only a link that plain text never carried.