@erclx/canon 4.107.0 → 4.109.0

package/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/brand/mark-accent.svg">
-  <img src="assets/brand/mark-accent-light.svg" alt="canon" width="56" height="56">
+ <source media="(prefers-color-scheme: dark)" srcset="assets/brand/mark-accent.svg">
+ <img src="assets/brand/mark-accent-light.svg" alt="canon" width="56" height="56">
 </picture>
 
 # canon
@@ -17,12 +17,7 @@ canon is a CLI and Claude Code plugin that stops your AI conventions drifting ap
 
 </div>
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/arrival.png">
-  <img src="assets/evidence/arrival-light.png" alt="The first screen of the canon landing page, a project before and after one canon init, with the file counts each step lays down">
-</picture>
-
-The page is one real session the toolkit ran on itself, and every count on it is read from the repo when the page builds.
+That page is one real session the toolkit ran on itself, and every count on it is read from this repository when the page builds.
 
 ## Why
 
@@ -46,8 +41,8 @@ claude plugin install canon@canon
 ```
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/install.png">
-  <img src="assets/evidence/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
+ <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/install.png">
+ <img src="assets/evidence/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
 </picture>
 
 The skills land as `/canon:<name>`. If your session was already open, run `/reload-plugins` to pick them up.
@@ -73,35 +68,21 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
 | Slides         | A `SLIDES.md` source format with a layout catalog                                                                        | `canon slides render` writes PowerPoint                         |
+| Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                              | `canon teach`                                                   |
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
 | Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                               | `canon sandbox`                                                 |
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/catalog.png">
-  <img src="assets/evidence/catalog-light.png" alt="The canon catalog as a ledger of five rows, with the count each ships and a few real names: skills, rules, standards, commands, and stacks">
-</picture>
-
-Every count in that image is read from the catalogs when it is built, so they're what the repo ships today. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one. Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
-
-Two of the outputs are documents you open rather than files you run. A `SLIDES.md` renders to a deck, and a learning workspace renders to a small site.
+Those domains reach you in three shapes. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one.
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="examples/slides/evidence/showcase-dark-04.png">
-  <img src="examples/slides/evidence/showcase-light-04.png" alt="A slide from the showcase deck rendered by canon slides render, a bulleted list under a heading on a warm background">
-</picture>
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="examples/teach/evidence/root-listing.png">
-  <img src="examples/teach/evidence/root-listing-light.png" alt="The learning workspace listing rendered by canon teach, three workspaces with their lesson and term counts, one still a stub">
-</picture>
+Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
 
 ## It runs on itself
 
 The workflow this toolkit ships is the workflow that built it. Several Claude Code sessions run at once, each in its own git worktree on its own branch, and each opens its own pull request.
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="demos/agent-view.gif">
-  <img src="demos/agent-view-light.gif" alt="The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened">
+ <source media="(prefers-color-scheme: dark)" srcset="demos/agent-view.gif">
+ <img src="demos/agent-view-light.gif" alt="The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened">
 </picture>
 
 That recording is the landing page's own `dispatch` and `workers` sections, driven by `canon demo run` against a local build. The branch graph beside the pull request numbers is authored rather than read, because nothing on a build machine records which files four sessions held.
@@ -110,6 +91,8 @@ That recording is the landing page's own `dispatch` and `workers` sections, driv
 
 Scaffolding your first project? Start with target projects, then the AI workflow loop. Everything else answers questions that arrive later.
 
+Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at your project root first, then whichever rules under `.claude/rules/` match the paths it edits. Run `canon docs agents` for the command catalog with flags, exit codes, and JSON shapes.
+
 - [AI workflow](docs/workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design and wireframe authoring
@@ -165,7 +148,9 @@ git init
 canon init
 ```
 
-`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `canon standards <name>`, so no corpus is copied into your project. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. A snippet resolves the same way, reached at its `@` reference through the plugin's live `claude/snippets` symlink rather than a copy. Run `canon tooling list --json` to see the catalog.
+`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `canon standards <name>`, so no corpus is copied into your project.
+
+Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. A snippet resolves the same way, reached at its `@` reference through the plugin's live `claude/snippets` symlink rather than a copy. Run `canon tooling list --json` to see the catalog.
 
 For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target-projects.md).
 

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

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

package/claude/skills/document-health/REQUIREMENT.md

@@ -0,0 +1,46 @@
+---
+name: document-health
+description: What the document health check is for, the gap it closes, and why it reports three axes rather than one number
+---
+
+# Document health requirement
+
+## Gap
+
+Without this skill, a project learns which documents are missing and never learns which have rotted. `target-check` reports per domain what a target holds against what the toolkit ships, and every one of its domains asks a structural question: does the file exist, does it hold the required sections, do the bytes match what shipped. A document that exists, holds every section, and describes a tree that moved six months ago passes every one of them.
+
+The second half of the gap is the axes being read as one thing. Length, placement, and staleness answer to different evidence, and a run that reports them in one undifferentiated list hands the reader a judgment wearing the authority of a measurement. The operator's own complaint was staleness, which is the axis with nothing behind it, so the flattening runs in the direction that overstates the weakest finding.
+
+The third is silence on an unread axis. Both measured verbs resolve their folders by surface root, so a project whose layout differs resolves nothing and the verb refuses. A run reading that refusal as an empty finding set reports a healthy corpus for documents nothing looked at.
+
+## Must
+
+- Report per document across three named axes, so a reader can tell which question a finding answers
+- Read length and placement through the verb that already owns each measurement, rather than re-deriving either by hand
+- Mark every finding with its evidence class, so a judgment is never read as a measurement
+- Ship the staleness axis, and mark it as a reading rather than cutting it for lacking a verb
+- Report a refusal, an absent key, and a missing subcommand as an unread axis, naming the cause
+- Say which layer answered the classifier sweep, since its model layer being off narrows the read without refusing it
+- Take every checkpoint from the record the verb returns rather than from a number written into the skill
+- Run standalone, and stay callable from the structural check rather than reachable only through it
+
+## Must not
+
+- Repair a finding, write a file in the project, or open a pull request. A check that repaired as it read leaves the reader unable to tell a finding from a fix.
+- Emit a verdict across the three axes, or a score across the documents. Two axes answer from verbs and one answers from a reading, so any roll-up is a figure that lies about the third.
+- Report a finding against a file nobody hand-authors. A generated index, a gitignored file, and a copied reference each name a file an author cannot fix.
+- Answer an axis by file inspection where a verb answers it. The verb is the surface under test and a hand-rolled read of the same files is not.
+- Read a document's modification time as its staleness. A file untouched beside code untouched is current, and the timestamp answers a different question.
+
+## Guards
+
+- `canon` absent from the path: stop, since neither measured axis can be read
+- No tracked markdown under the working root: stop, since there is no corpus to read
+
+## Out of scope
+
+- Whether a document exists or holds its required sections, which is the structural question `target-check` answers across six domains
+- Conformance of changed markdown to the authoring standards declaring jurisdiction over its paths, which is `standards-audit`. That skill is diff-scoped and standard-declared, taking a changed file and reporting which stated rule it breaks with a line number. This one is corpus-scoped and reads rot in documents nobody changed, which is the case a diff-scoped audit never reaches. The two sit beside each other rather than one absorbing the other.
+- Rewriting a stale claim once this run has named it, which is `markdown-propose`
+- Running the toolkit's own checks as one gating set over its own corpus, which is `canon audits run`. That set gates a push and this reports to a reader.
+- Repairing anything an axis names. Each routes to the command or skill that owns it.

package/claude/skills/document-health/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: document-health
+description: Reports which of a project's documents have rotted, one section per document, across length, placement, and staleness. Reads each axis through the verb that owns it and marks the evidence class each answer carries. Use when asked to "check document health", "which docs have gone stale", "audit the docs for rot", "are these documents still accurate", "which docs are too long", or after a target check reports the structural side. Do NOT use to repair a finding, which the owning command or skill does, and do NOT use to check whether a document exists or holds the right sections, which is `target-check`.
+---
+
+# Document health
+
+Reports which documents have rotted rather than which are missing. `target-check` answers whether a project's documents exist and hold the right kind of content, and this answers whether the ones that exist still earn their place. It reports and never repairs, matching the structural check beside it.
+
+Three axes carry the report. Two answer from a verb and the third answers from a reading, which it says rather than hiding. `${CLAUDE_SKILL_DIR}/references/axes.md` holds what each axis measures, the checkpoint it reads against, and where a finding routes. This body holds the order, the guards, and the report shape.
+
+## Guards
+
+- `canon` absent from the path: stop. `❌ canon is not on PATH, so neither measured axis can be read.`
+- `git ls-files '*.md'` listing nothing: stop. `❌ No tracked markdown here, so there is no corpus to read.`
+- Run every command under `CANON_NON_INTERACTIVE=1` and prompt at no point. A caller reaching this from a rollout wave has nobody present to answer.
+- Branch on each record's own fields rather than on an exit status. An operator's shell profile may wrap `canon` in a function whose status comes from a trailing command, which reports every refusal as success.
+- Repair nothing, write no file in the project, and open no pull request. Whoever read the report decides what to fix.
+
+## Step 1: scope the corpus
+
+Take the documents the project hand-authors, defaulting to every tracked markdown file the two measured verbs reach. Narrow to a path the caller named when one was given, and say which scope the run took.
+
+Drop what nobody hand-authors before reporting a finding against it: a generated `index.md`, a file under a gitignored folder, and a bundled reference a generator copied out to its consumers. A finding against a copy names a file an author cannot fix, since the next regeneration overwrites it.
+
+## Step 2: read the two measured axes
+
+Run these from the project root, in parallel:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon markdown audit --json
+CANON_NON_INTERACTIVE=1 canon context audit --json
+```
+
+The first answers length, carrying the bullet, paragraph, and depth checkpoints and the per-file weights read against them. The second answers placement for the folders it resolves, carrying entry length, reference form, and index drift.
+
+Then read which classifier would run, and deepen placement with the verdicts per section:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon context classifier show
+CANON_NON_INTERACTIVE=1 canon context classify sweep --json
+```
+
+The first names the backend, the model, and the source that decided both. Report which layer answered, since a project with the model layer off reads from the regex layer alone and the sweep says nothing about which one it used.
+
+Take the checkpoints from the record each verb returns rather than from a number written here. A checkpoint the CLI moves reaches this report with no edit, and a number held in this body goes stale on its own cadence.
+
+### An unread axis is not a healthy one
+
+A refusal, an absent key, and a subcommand the project's binary does not carry each leave an axis unread. Report it as unread against the documents it would have covered, name the read that could not be taken, and name the cause.
+
+`canon context audit` refuses with `reason: "no-folders"` in a project whose folders resolve to nothing, which is the ordinary shape where the layout differs from the one the verb looks for. That refusal is the honest answer rather than a failure, and reading it as an empty finding set reports a healthy corpus for documents nothing looked at.
+
+A narrower read is not an unread one. The sweep running on its regex layer alone still answered, so it is reported with the layer named rather than as an axis nothing reached.
+
+## Step 3: read the staleness axis
+
+No verb answers whether a document still describes the tree it was written about. Read each document against the surfaces it names and report where the two have parted, taking the file paths, commands, and counts it states as the claims to test.
+
+Mark every staleness finding as a reading. It is this session's judgment rather than a measurement, and a report that sets it beside two verb-backed axes without marking it implies evidence the axis does not carry.
+
+## Step 4: report per document
+
+Give each document its three axes, and give each axis three things: the state, the evidence class, and the command or skill that repairs it. Naming the repair is not running it.
+
+The three classes are what keep the axes apart:
+
+- `measured`: a verb returned a number read against a stated checkpoint
+- `classified`: a verb returned a verdict carrying its own confidence
+- `read`: this session's judgment, backed by no verb
+
+Emit no verdict across the three. Two answer from verbs and one answers from a reading, so a roll-up is a figure that lies about the third. Emit no score across the documents either, for the same reason one level up.
+
+## Output
+
+Lead with the table, then one detail block per document carrying a finding:
+
+```markdown
+Document health: `<scope>`, <n> documents read.
+
+| Document         | Length              | Placement           | Staleness        |
+| ---------------- | ------------------- | ------------------- | ---------------- |
+| `path/to/doc.md` | ok / heavy / unread | ok / moved / unread | ok / stale / n/a |
+
+Length and placement are measured. Staleness is a reading.
+```
+
+Keep the evidence line under the table on every run. A table read without it flattens a judgment into a measurement, which is the one shape the three classes exist to prevent.

package/claude/skills/document-health/references/axes.md

@@ -0,0 +1,78 @@
+---
+title: Document health axes
+description: What each axis measures, the verb behind it, the evidence class it carries, and where a finding routes
+---
+
+# Document health axes
+
+One section per axis. Each states what it measures, the verb that answers it, the evidence class the answer carries, and the surface a finding routes to.
+
+The skill body holds the order, the guards, and the report shape. This holds the detail a run dereferences once it has a finding to place.
+
+## Length
+
+**Measures:** whether a document, or a passage inside it, has grown past what a reader takes in one pass.
+
+**Verb:** `canon markdown audit --json`.
+
+**Evidence class:** `measured`.
+
+The record carries the checkpoints it read against under `checkpoints` and the per-file weights under `entries`. Read both from the record rather than from a number stated here, since the CLI moves a checkpoint on its own cadence and a copy of one goes stale in place.
+
+Four weights answer this axis, each naming a different shape of overgrowth:
+
+- `heavyBullets`: a top-level bullet past the character checkpoint, which is a paragraph wearing a dash
+- `heavyParagraphs`: a paragraph past the sentence or character checkpoint
+- `longestRun`, against `longestRunLine`: unbroken rendered lines between headings, which is the depth checkpoint
+- `cadence`, carrying `measured`, `flat`, and `repeating`: sentence-length spread and repeated openers
+
+Weight is a judgment a reader settles rather than a defect, which the verb states for itself and which this axis carries forward. A finding here is an argument for a split or a trim rather than a rule broken.
+
+**Routes to:** a split of the document, or a move of the overgrown passage to the surface that owns it. Where the project states what a given document may hold, that statement decides whether the passage belongs in it at all, and the finding routes there rather than to a trim.
+
+**Caveat:** the cadence numbers are drawn from prose a person reads straight through. Terse reference prose sits below that range correctly, so a flat paragraph in a table-heavy or bullet-heavy file is not a finding.
+
+## Placement
+
+**Measures:** whether a document's content sits in the file that owns it, and whether the catalogs pointing at it still resolve.
+
+**Verbs:** `canon context audit --json` for the structural half, `canon context classify sweep --json` for the per-section verdicts.
+
+**Evidence class:** `measured` for the audit's findings, `classified` for the sweep's verdicts.
+
+The audit answers required sections, entry length, citation resolution, reference form, catalog tables, provenance, and index drift. A citation resolving to nothing is a fact and gates. Entry length, reference form, table shape, and provenance are judgments under every flag.
+
+The sweep classifies each section as keep, replace or rewrite, history, or move. A `move` verdict is the placement finding proper, naming content sitting in the wrong document. Each verdict carries its own confidence, which is why the class is `classified` rather than `measured`, and a low-confidence `move` is a prompt to look rather than an instruction to cut.
+
+**Routes to:** the document the verdict names as the owner. Where the move crosses a tier rather than a file, the project's own content-ownership rules decide the destination.
+
+**Caveat:** both verbs resolve their folders by surface root rather than by a path written into them, so a project whose layout differs from the one they look for resolves nothing. The audit says so, refusing with `reason: "no-folders"` and naming the folders it looked for. Report that refusal as an unread axis. The sweep degrades differently: with the model layer off it answers from its regex layer alone, which is a narrower read rather than a refusal, so say which layer answered.
+
+## Staleness
+
+**Measures:** whether a document still describes the tree it was written about.
+
+**Verb:** none.
+
+**Evidence class:** `read`.
+
+This is the axis the operator names first and the one nothing measures. A document goes stale by the tree moving under it rather than by anything changing in the document, so no property of the file answers it and a timestamp answers a different question. A file untouched for a year beside code untouched for a year is current, and one edited yesterday against a refactor from this morning is stale.
+
+Read each document against the surfaces it names. Four claim shapes are testable without leaving the project:
+
+- A file or folder path the document states, against whether it resolves
+- A command or verb the document names, against whether it exists and carries the flags shown
+- A count the document states over a tree, against the tree
+- A cross-reference to another document, against what that document now says
+
+A claim resting on none of the four is unverifiable from here. Report it as unread rather than as passing, which is the same rule the measured axes take when a verb refuses.
+
+**Routes to:** the skill that rewrites a stale claim against an answer, rather than a direct edit from here. A document health run reports and never repairs.
+
+**Caveat:** a reading is the weakest evidence in the report and the most consequential finding in it, which is the tension this axis ships with. Marking the class is what keeps the two facts together in the reader's hands.
+
+## Why the three stay apart
+
+The axes are not equally actionable and a report flattening them implies they are. A length finding is a number against a checkpoint, a placement finding is a verdict carrying a confidence, and a staleness finding is a judgment with nothing behind it. Each is worth reporting and each is worth a different response, so the class travels beside the state on every row rather than being stated once in a preamble a reader skims.
+
+Shipping staleness on weaker evidence than the other two is the trade taken deliberately. Cutting it would leave the report answering the two questions that were never the operator's complaint.

package/claude/skills/git-ship/SKILL.md

@@ -31,7 +31,7 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 6. Invoke `canon:git-stage` to group staged changes and commit by concern
 7. Invoke `canon:git-branch` to rename branch to match conventional format
 8. Invoke `canon:git-pr` to push branch and open pull request
-9. After the PR opens, watch CI. Poll `canon pr checks <number> --json` until the record's `state` leaves `pending`, branching on that field rather than on the exit, and fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb. On `passing`, continue. On `failing`, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
+9. After the PR opens, watch CI. Poll `canon pr checks <number> --json` until the record's `state` leaves `pending` or the record carries `conflicted: true`, branching on those fields rather than on the exit, and fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb. On `passing`, continue. On `failing`, stop the sequence and report the failing check with its URL. On `conflicted`, stop the sequence and report that the branch conflicts with its base, since no run will start for it and polling on never ends. A rebase is the repair. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
 
 A caller wrapping this sequence may act between step 8 and step 9, which is the one gap the order leaves open, since the pull request exists there and nothing has read its checks yet. `auto-ship` marks the pull request draft in it. Nothing else may go there, and a caller that needs a step anywhere else in the sequence is asking for a change to this body rather than for a place to stand.
 

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

@@ -30,7 +30,7 @@ Also read the CI check status so the fixes cover failing checks, not only review
 canon pr checks <number> --json
 ```
 
-Read the verdict off the record's `state` rather than off the exit. Treat `failing` as a finding to resolve alongside the review comments. A `pending` covers a tip whose runs have yet to conclude and a tip carrying no run at all, which the record separates on `matched`, and neither is a green to continue on. Fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb.
+Read the verdict off the record's `state` rather than off the exit. Treat `failing` as a finding to resolve alongside the review comments. A `pending` covers a tip whose runs have yet to conclude and a tip carrying no run at all, which the record separates on `matched`, and neither is a green to continue on. A record carrying `conflicted: true` is a third case: the branch conflicts with its base, so no run will start and the wait never ends. Stop and report it, since a rebase is the repair. Fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb.
 
 ## Step 2: address each finding
 
@@ -170,8 +170,9 @@ echo "${comment_url##*issuecomment-}" > .canon/tmp/pr/reply/reply-<number>.id
 ## Step 7: confirm resolution
 
 After the follow-up push, watch CI on the PR. Poll
-`canon pr checks <number> --json` until the record's `state` leaves `pending`,
-then read it. When every finding is addressed and the state is `passing`, append
+`canon pr checks <number> --json` until the record's `state` leaves `pending`
+or it carries `conflicted: true`, then read it. On `conflicted`, stop and report
+that a rebase is the repair rather than polling on. When every finding is addressed and the state is `passing`, append
 the closing confirmation to the reply file Step 6 already posted, so the thread
 carries one terminal state rather than a second comment under no heading:
 

package/claude/skills/task-board/REQUIREMENT.md

@@ -18,7 +18,7 @@ Placing a row without checking for another writer collides the same way. Two ses
 - Resolve the board at the main worktree root, since a linked worktree writing to `pwd` creates a second board nothing reads
 - Read the tasks standard before writing, rather than working the filename and frontmatter from memory
 - Require an origin at creation, because that is the only moment the invariant is enforceable
-- Read the phase label from `canon tasks next-label` rather than proposing one by hand
+- Claim the phase label with `canon tasks next-label --claim` rather than reading or proposing one by hand
 - Check the roster for a live orchestrator before writing a row, and hand off rather than write when one is found
 - Confirm the work reached the default branch before archiving
 - Run the archive command and route on the reason it refuses, since each reason has one resolution

package/claude/skills/task-board/SKILL.md

@@ -29,13 +29,13 @@ Accept work whose origin is the conversation itself only when the user says so e
 
 ### Step 2: allocate the phase label
 
-Run `canon tasks next-label --json` and take its `label` field. The verb reads the live board and its `archive/` sibling together, so the label it returns accounts for what the board alone no longer shows.
+Run `canon tasks next-label --claim --json` and take its `label` field. The verb reads the live board and its `archive/` sibling together, so the label it returns accounts for what the board alone no longer shows, and `--claim` reserves it under `.canon/ordinal-locks/` so a second session filing at the same moment gets the next one. Branch on the record's `reason` rather than the exit: `label-contended` means re-run the claim, and a usage error from an unknown `--claim` means the installed binary predates the flag, so report the verb as unavailable rather than falling back to a bare read, which reopens the race.
 
 Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the verb's two folders are the only surface that knows what a label currently means.
 
 ### Step 3: write the file
 
-Write `.canon/tasks/vXX.Y-<slug>.md` following the format in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`. Include a link line only when the file or folder it names exists. A link to a plan nobody has written yet is the broken pointer the archive rules exist to prevent.
+Write `.canon/tasks/vXX.Y-<slug>.md` under the claimed label, reading the file first if a session ever stubbed it, following the format in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`. Include a link line only when the file or folder it names exists. A link to a plan nobody has written yet is the broken pointer the archive rules exist to prevent.
 
 Write `Plan:`, `Groundwork:`, and `Intake:` as markdown links relative to `.canon/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`. Leave `Issue:` a bare `#NNN`. A task written in the older bare-path form still parses, so it costs the board a clickable line rather than an archive, but it leaves the board in two shapes for every reader after.
 

package/docs/agents/capture.md

@@ -18,11 +18,11 @@ canon capture https://example.com --selector .window --out preview.png
 
 ## What this repository captures
 
-A capture set here spans two folders. `assets/captures/` holds five sources and the three templates they are written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them. A branch commits none of them for a moved count or token, since the refresh workflow regenerates them from `main` and opens one pull request, and `bun run check` runs the script with `--check`, which fills every template into a temp folder and fails when the regeneration cannot run.
+A capture set here spans two folders. `assets/captures/` holds three sources and the two templates they are written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them. A branch commits none of them for a moved count or token, since the refresh workflow regenerates them from `main` and opens one pull request, and `bun run check` runs the script with `--check`, which fills every template into a temp folder and fails when the regeneration cannot run.
 
-Two of the three templates take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
+The `hero` template takes catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
 
-The README shows each still in two themes through `<picture>`, so a frame is a pair named `<name>` and `<name>-light`. `catalog` and `install` take the light half from the same template, which `regen-hero.sh` fills a second time with the plain color roles pointed at the light ones, and each half is its own capture set with its own stamp. `arrival-light.png` is the same `.fold` capture of the same address taken without forcing dark, so it is retaken by hand alongside `arrival.png`, and nothing catches one drifting from the other.
+The README shows each still in two themes through `<picture>`, so a frame is a pair named `<name>` and `<name>-light`. `install` takes the light half from its template, which `regen-hero.sh` fills a second time with the plain color roles pointed at the light ones, and each half is its own capture set with its own stamp. `arrival-light.png` is the same `.fold` capture of the same address taken without forcing dark, so it is retaken by hand alongside `arrival.png`, and nothing catches one drifting from the other.
 
 A stamp for a URL source digests the address string rather than the page it served, so two themes of one address carry one `source-sha256` and only `image-sha256` tells the frames apart. That holds for `examples/teach/evidence/root-listing-light.png`, which is retaken by serving a copy of the fixture with `data-theme="light"` on its `<html>` element at the same address, since the page follows the dark default and the command takes no scheme.
 

package/docs/agents/commands.md

@@ -5,7 +5,7 @@ description: Every project-level command and every domain subcommand, plus the s
 
 # Command catalog
 
-Full help: `canon <command> --help`. Bare `canon --help` lists every top-level command under five headings, Project, Domains, Author and render, Session and ship, and Repo reports, with descriptions cut at 80 columns. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
+Full help: `canon <command> --help`. Bare `canon --help` lists every top-level command under five headings, Project, Domains, Author and render, Session and ship, and Repo reports, with descriptions cut at 80 columns. Piped into another command, the block prints without its frame glyphs and carries the same text. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
 
 ## Project-level
 
@@ -92,7 +92,7 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 | `canon autoship classify`        | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                                                                                                                                                                                  |
 | `canon pr key-changes`           | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                                                                                                                                                                            |
 | `canon pr head`                  | Compare the head a pull request object reports against the branch tip the remote carries, naming both shas (`--root`, `--json`)                                                                                                                                                                                              |
-| `canon pr checks`                | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean (`--root`, `--json`)                                                                                                                                                                                            |
+| `canon pr checks`                | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean, and `conflicted` when the branch conflicts with its base (`--root`, `--json`)                                                                                                                                  |
 | `canon pr review-state`          | Report the commit and instant the last review pass covered, off the pass's own marker rather than the fields GitHub stamps at submission (`--root`, `--json`)                                                                                                                                                                |
 | `canon pr evidence`              | Render a before-and-after comment comparing changed `evidence/` images against the merge base, editing its own prior comment in place rather than posting a second (`--root`, `--json`, `--preview`)                                                                                                                         |
 | `canon pr preview`               | Dispatch the Pages deploy on a pull request's branch and report the preview address the run prints, refusing a deploy that passes no `--branch` (`--root`, `--json`, `--timeout`)                                                                                                                                            |

package/docs/agents/pr-reads.md

@@ -74,6 +74,8 @@ Both empty cases report `pending` instead: a tip carrying no run yet, and a list
 
 The verb keeps the newest run per check name rather than rolling every matched run into the state. A workflow that fires twice on one commit used to leave its first, stale run beside the rerun, where a failing one could outvote a passing rerun. Grouping the matched set by name and keeping the highest `id` per group removes that stale run before the rollup runs. `collapsed` on the record counts what the fold discards, so a caller reading it against `matched` sees the dedupe directly, instead of reading a `matched` above the check count as the verb disagreeing with `gh pr checks`.
 
+A conflicted branch produces no `pull_request` check runs rather than a failing one. GitHub builds no merge ref for it, so no `pull_request` workflow starts and a repository running only that trigger leaves the listing empty, which reads as `pending` and never leaves it. A workflow triggered by a push to the branch still runs on the tip, so `matched` rises above zero, `conflicted` stays false, and the wait ends on those runs rather than on the reading. `mergeStateStatus` is the field that separates the two, and the record carries `conflicted: true` and `mergeState` when it reads `DIRTY` with no run belonging to the tip. A `DIRTY` reading beside runs on the tip leaves the state as those runs say, since a conflict arising after they completed does not unsay them. `UNKNOWN` is transient while GitHub computes the merge state, right after a push, so it reads as not conflicted and costs one more poll. A binary predating the field keeps answering `pending`.
+
 A listing carrying even one foreign run reports `pending` whatever the matching half says. A set that describes another commit says nothing about this one, so answering off the rows that happen to match would put a verdict on a set already known to be incomplete.
 
 A count above the rows returned reports `pending` for the same reason. The query asks for 100 rows against the endpoint's default of 30, and a commit carrying more than that comes back short, so the verb reports the tip as unread rather than collapsing the page it happens to hold. `reported` against `matched` and `foreign` is where a reader sees which of the three shapes produced the answer.

package/docs/agents/tasks.md

@@ -7,25 +7,27 @@ description: Selecting a shipped task by stem or pull request, recording a numbe
 
 ## Next label
 
-`canon tasks next-label` reports the next unused phase label, reading `.canon/tasks/` and its `archive/` sibling together. A scan confined to the live board is blind to every label the archive already spent, which is what let two sessions hand out the same label within minutes of each other. It reports and never writes.
+`canon tasks next-label` reports the next unused phase label, reading `.canon/tasks/` and its `archive/` sibling together. A scan confined to the live board is blind to every label the archive already spent, which is what let two sessions hand out the same label within minutes of each other. Bare, it reports and never writes. With `--claim` it reserves the label first.
 
 ```bash
 canon tasks next-label
 canon tasks next-label --json
+canon tasks next-label --claim --json
 ```
 
-| Option          | Effect                                      |
-| --------------- | ------------------------------------------- |
-| `--json`        | Emit a machine-readable record on stdout    |
-| `--root <path>` | Board root, defaulting to the main worktree |
+| Option          | Effect                                           |
+| --------------- | ------------------------------------------------ |
+| `--json`        | Emit a machine-readable record on stdout         |
+| `--claim`       | Reserve the label so a second claim gets another |
+| `--root <path>` | Board root, defaulting to the main worktree      |
 
-The record carries `label`, the next free `vXX.Y`, and `highest`, the label it was derived from. `highest` is absent when neither folder carries a label yet, and `label` reads `v01.0` in that case, matching the zero-padded-major shape every other label already takes. <!-- canon-allow-reference: illustrates the verb's answer for a board holding no label yet, not a citation of a real task -->
+The record carries `label`, the next free `vXX.Y`, `claimed`, whether the label was reserved, and `highest`, the label it was derived from. `highest` is absent when neither folder carries a label yet, and `label` reads `v01.0` in that case, matching the zero-padded-major shape every other label already takes. <!-- canon-allow-reference: illustrates the verb's answer for a board holding no label yet, not a citation of a real task -->
 
-Exit codes: `0` derived, `1` refused with `no-board`.
+Exit codes: `0` derived, `1` refused with `no-board`, `2` refused with `label-contended` after five lost reservations, on `--claim` only.
 
 The minor digit rolls from 9 to 0 on the next major rather than growing a second digit, which is the single-digit-minor shape every phase label already takes. `canon tasks archive` moves a task's file from the live folder into the archive without renumbering it, so the same label counts toward the maximum wherever it currently sits, and a label claimed by two different files folds into the same scan without a dedicated check.
 
-It reports rather than gates. Two sessions calling it in the same second can still take the same answer, since the board is gitignored files rather than a store with a lock, and `standards/versioning.md` permits free renumbering, so a collision costs a rename rather than anything worse.
+A claim is an exclusive `mkdir` at `.canon/ordinal-locks/<label>`, and the scan counts every reservation beside the task files, since the file lands after the verb returns. Reservations never expire, so a claim that died leaves a gap, which `standards/versioning.md` permits. A bare read still reports without reserving, and it does not count reservations either, so it can return a label a claim already holds until that claim's task file lands. Two bare reads in the same second can also take the same answer.
 
 ```bash
 canon tasks next-label --json | jq -r '.label'

package/docs/workflow/ai-workflow.md

@@ -240,6 +240,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | ------------------------ | --------------------------------------------------------------------------------------- |
 | `canon:review-branch`    | On the local branch diff, before anything is pushed                                     |
 | `canon:standards-audit`  | When changed markdown has to answer to the authoring standards                          |
+| `canon:document-health`  | When the documents themselves have to answer for length, placement, and staleness       |
 | `canon:markdown-propose` | When a markdown claim needs rewriting and the change should wait for an answer per file |
 | `canon:ux-audit`         | To read UI source for missing states, edge cases, and inconsistencies                   |
 | `canon:ux-measure`       | To start the interface and measure paint, processor, and layout cost                    |

package/package.json

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

package/scripts/core/regen-hero.sh

@@ -96,11 +96,8 @@ GOV_JSON="$(catalog gov list)"
 STANDARDS_JSON="$(catalog standards list)"
 SNIPPETS_JSON="$(catalog snippets list)"
 TOOLING_JSON="$(catalog tooling list)"
-# The catalog ledger names three commands, and the registered set is only
-# readable from the root help, which lists one per line under `Commands:`.
-COMMANDS_HELP="$(cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts --help 2>/dev/null)"
 
-for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON" "$COMMANDS_HELP"; do
+for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
   if [ -z "$payload" ]; then
     echo "regen-hero: a catalog returned nothing, refusing to write a zeroed hero" >&2
     exit 1
@@ -120,7 +117,6 @@ printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
 printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
 printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
 printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
-printf '%s' "$COMMANDS_HELP" >"$PAYLOAD_DIR/commands-help.txt"
 printf '%s' "$TOKEN_CSS" >"$PAYLOAD_DIR/tokens.css"
 
 export PAYLOAD_DIR
@@ -349,36 +345,8 @@ for (const [label, rows] of [
   }
 }
 
-// The ledger names a few real entries per domain. Chosen by hand for the same
-// reason FEATURED_SKILLS is, and asserted against the catalog so a rename fails
-// the run rather than leaving a name the repository no longer ships.
-const commandNames = readFileSync(PAYLOAD_DIR + "/commands-help.txt", "utf8")
-  .split("\n")
-  .map((line) => line.match(/^[│\s]{2,}(?<name>[a-z][a-z-]*)\s/)?.groups?.name)
-  .filter(Boolean)
-const LEDGER = [
-  ["skills", skills.length, ["plan-feature", "role-orchestrator", "review-pr"], skills],
-  ["rules", rules.length, ["behavior", "memory", "testing"], rules],
-  ["standards", standards.length, ["markdown", "plan", "teach"], standards],
-  ["commands", commandCount, ["gov", "tasks", "design"], commandNames],
-  ["stacks", toolingStacks.length, ["astro", "python", "web"], toolingStacks.map((stack) => stack.name)],
-]
-for (const [domain, , chosen, names] of LEDGER) {
-  const known = new Set(names)
-  const missing = chosen.filter((name) => !known.has(name))
-  if (missing.length > 0) {
-    console.error(`regen-hero: ledger ${domain} names missing from the catalog: ${missing.join(", ")}`)
-    process.exit(1)
-  }
-}
-const ledgerRows = LEDGER.map(
-  ([domain, count, chosen]) =>
-    `      <div class="row"><span class="count">${count}</span><span class="domain">${domain}</span><span class="names">${escape(chosen.join(", "))}</span></div>`,
-).join("\n")
-
 const values = {
   TOKENS: tokenCss,
-  LEDGER_ROWS: ledgerRows,
   GOV_STACK_ROWS: govStackRows,
   GOV_RULE_ROWS: govRuleRows,
   STANDARD_ROWS: standardRows,
@@ -417,7 +385,7 @@ if (templates.length === 0) {
 // same template with the plain roles pointed at the light ones rather than a
 // second copy of any hex value. The hero is a landing-page frame no README
 // shows, so it stays dark.
-const LIGHT_TEMPLATES = new Set(["catalog.html.tmpl", "install.html.tmpl"])
+const LIGHT_TEMPLATES = new Set(["install.html.tmpl"])
 
 const lightRoles = [...tokenCss.matchAll(/--color-light-([a-z-]+):/g)].map((match) => match[1])
 if (lightRoles.length === 0) {

package/src/claude/cases/workflow.ts

@@ -117,6 +117,16 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Check whether the markdown I changed violates any authoring standards.',
     expect: 'standards-audit',
   },
+  // Rot across documents nobody changed is what separates this from
+  // `standards-audit`, which is diff-scoped and reports a stated rule broken on
+  // a given line. It is also not `target-check`, which asks whether a document
+  // exists and holds its sections rather than whether it still describes the
+  // tree.
+  {
+    prompt:
+      'Which of our docs have gone stale, grown too long, or ended up in the wrong file?',
+    expect: 'document-health',
+  },
   {
     prompt: 'Open a new entry on the task board for this piece of work.',
     expect: 'task-board',