@erclx/canon 5.55.0 → 5.57.0

package/claude/skills/search-craft/SKILL.md

@@ -54,13 +54,11 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 
 ## Excuses and rebuttals
 
-| Excuse                                   | Rebuttal                                                                                                                                    |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| The model already knows the good sites   | It does, and it does not use that knowledge unprompted. Left to rank, a search puts guides written to rank above a field's reference pages. |
-| One search was enough                    | One search gives nothing to check a wrong fact against. The scoped search is what catches the open summary's error.                         |
-| The open results look authoritative      | Ranking rewards pages written to rank, so advocates and thin guides sit beside the field's own record and tilt the summary.                 |
-| I scoped it, so every result is in scope | The domain filter is not strict, so a scoped search can return results from outside its list.                                               |
-| The summary already answers it           | A summary paraphrases. Fetch the page when two summaries disagree, since that is where the error sits.                                      |
+- **The model already knows the good sites.** It does, and it does not use that knowledge unprompted. Left to rank, a search puts guides written to rank above a field's reference pages.
+- **One search was enough.** One search gives nothing to check a wrong fact against. The scoped search is what catches the open summary's error.
+- **The open results look authoritative.** Ranking rewards pages written to rank, so advocates and thin guides sit beside the field's own record and tilt the summary.
+- **I scoped it, so every result is in scope.** The domain filter is not strict, so a scoped search can return results from outside its list.
+- **The summary already answers it.** A summary paraphrases. Fetch the page when two summaries disagree, since that is where the error sits.
 
 ## Red flags
 

package/claude/skills/session-worktree/SKILL.md

@@ -73,6 +73,8 @@ Resolve `<type>` here too, since Step 3 previews it and Step 5 renames onto it,
 | A plan, through tier 1 or tier 2             | The `type` field of `canon tasks plan-branch <plan> --json` |
 | A branch, a bare user name, or anything else | `feat`                                                      |
 
+The points below govern how the type is read.
+
 - The verb is the reading because a type read off a plan's sections is a judgment two sessions can grade differently, and the verb answers the same for both
 - Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero
 - Take `feat` and say the verb did not answer where it refuses, the record has no `type`, or the binary has no `plan-branch`

package/claude/skills/session-worktree/references/main-root-writes.md

@@ -22,6 +22,8 @@ Each kind of write takes one route, and none of them is a stream editor.
 | Change inside a file | A `canon` verb resolving the main root in-process, such as `canon tasks outcome` or `canon tasks pull-request` |
 | Delete or move       | One plain `rm` or `mv` per call rather than chained                                                            |
 
+Three habits keep those routes from being refused or silently wrong.
+
 - Send `mkdir -p` for a missing folder as its own command first, since a `&&` compound is refused for complexity
 - Where no verb covers an edit, read the whole file and write it back whole through the heredoc route
 - Never reach for a stream editor, which rewrites the line it anchored to and exits zero on a non-match

package/claude/skills/systematic-debugging/SKILL.md

@@ -23,7 +23,9 @@ No fixes without root-cause investigation first. If phase 1 is incomplete, no fi
    - State. Run the case alone and again after the others, and look for shared caches, globals, and fixtures one case leaks into the next.
    - None of these. Add logging at the suspect and record the conditions of each occurrence, which hands off to the no-root-cause section below rather than to a fix.
 3. Check what changed. Run `git diff` and `git log --oneline -10` from the project root to see recent changes.
-   - For a regression with a known good commit, bisect rather than reading the log by eye: `git bisect start HEAD <good commit>`, then `git bisect run <the project's focused test command>` where a test reproduces the failure. Run `git bisect reset` once it names the commit, since bisect leaves the checkout on an old one.
+   - For a regression with a known good commit, bisect rather than reading the log by eye, with `git bisect start HEAD <good commit>`
+   - Where a test reproduces the failure, run `git bisect run <the project's focused test command>`
+   - Run `git bisect reset` once it names the commit, since bisect leaves the checkout on an old one
 4. For multi-component systems, add instrumentation at each component boundary and run once to see which layer fails before investigating further.
 5. Trace bad values backward to their source. Fix at the origin, not the symptom.
 
@@ -69,14 +71,12 @@ Most "no root cause" conclusions are incomplete investigations. Exhaust phase 1
 
 ## Excuses and rebuttals
 
-| Excuse                                        | Rebuttal                                                                                                                                    |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| "I know what the bug is, so I'll just fix it" | Then reproducing it costs a minute. When the reading is wrong, the fix moves the symptom and reports success over a cause still in place.   |
-| "Quick fix for now, investigate later"        | Later never reads the code again. The quick fix becomes the record of what the bug was, and it names the wrong place.                       |
-| "It's probably flaky, rerun it"               | A rerun that passes says the failure is intermittent, not that it is gone. Take the timing, environment, or state branch in phase 1.        |
-| "It works on my machine"                      | That is the environment branch's first data point. Diff versions, config, and data against where it fails rather than closing on it.        |
-| "The error says to run this, so I'll run it"  | The error is data about the failure. Whatever wrote it is the thing that is broken, so surface the step to the user rather than running it. |
-| "I'll verify manually instead of a test"      | A manual check leaves nothing behind. The failing test is what shows the fix reached the cause, and what catches the bug's return.          |
+- **"I know what the bug is, so I'll just fix it."** Then reproducing it costs a minute. When the reading is wrong, the fix moves the symptom and reports success over a cause still in place.
+- **"Quick fix for now, investigate later."** Later never reads the code again. The quick fix becomes the record of what the bug was, and it names the wrong place.
+- **"It's probably flaky, rerun it."** A rerun that passes says the failure is intermittent, not that it is gone. Take the timing, environment, or state branch in phase 1.
+- **"It works on my machine."** That is the environment branch's first data point. Diff versions, config, and data against where it fails rather than closing on it.
+- **"The error says to run this, so I'll run it."** The error is data about the failure. Whatever wrote it is the thing that is broken, so surface the step to the user rather than running it.
+- **"I'll verify manually instead of a test."** A manual check leaves nothing behind. The failing test is what shows the fix reached the cause, and what catches the bug's return.
 
 ## Red flags
 

package/claude/skills/systematic-debugging/references/adopted.md

@@ -20,7 +20,7 @@ External sources were read and filtered rather than imported. This file is the r
 
 The excuses, red flags, and closing checklist follow the shape every practice skill in this toolkit carries, from `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md).
 
-Each excuse row rebuts a reason a session gives to skip the investigation rather than an objection nobody raised. Three come from the source's own rationalizations table and the rest from this skill's earlier red flags.
+Each excuse rebuts a reason a session gives to skip the investigation rather than an objection nobody raised. Three come from the source's own rationalizations table and the rest from this skill's earlier red flags.
 
 ### Default shelf
 

package/claude/skills/target-update/REQUIREMENT.md

@@ -17,6 +17,7 @@ The verbs report every fact, so the gap is the judgment between them. A session
 - Read every fact from a `canon` verb, so a later release changes what the skill reports with no edit to its body
 - Stop and ask on a refused migration, a stranded file, an unattributed folder, and a rule the stack newly ships
 - Keep a customized file and a drifted seed as the project wrote them, naming the toolkit change each one skipped
+- Keep the shared checkout on its branch, writing on a worktree or a declined-worktree branch the preview names
 - End on a clean `target-check` or on named remainders, with nothing written when nothing is pending
 
 ## Must not

package/claude/skills/target-update/SKILL.md

@@ -66,6 +66,8 @@ Target update: `<path>`, canon `<installed>` to `<running>`.
 
 **Drift:** <each non-empty cause from sync --check, with its count and paths>
 
+**Where it lands:** <the linked worktree this run is already in, or the worktree `.claude/worktrees/<name>/` it will enter, or the branch it will create in place when the operator declines a worktree>
+
 **Calls for you:** <each judgment call below this run meets, with the default this skill takes>
 
 **Commands, in order:** <the exact commands Steps 4 to 6 will run>
@@ -77,6 +79,26 @@ Summarize the changelog for this project, not for the toolkit. Drop an entry tha
 
 When the changelog range is empty, `migrate status` lists nothing pending or refused, and the drift lines hold nothing a step here would take, write nothing. Invoke `canon:target-check` and report the target current with its table.
 
+### Take a branch after the go-ahead
+
+The migrations, the sync, and the commits write the project, so they land on their own branch rather than on the one the shared checkout holds, where every other session in it would follow. Step 1 stays where it ran, since it writes the machine rather than the project.
+
+Compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`, then take the first row that fits:
+
+| State                                      | This skill                                                                                        |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| Different, so already in a linked worktree | Uses it and enters nothing, since a second worktree would nest inside the first                   |
+| Equal, and the operator took the worktree  | Invokes `canon:session-worktree` with `chore/update-canon`, then runs Steps 4 to 6 from inside it |
+| Equal, declined, on `main` or `master`     | Invokes `canon:git-branch` for `chore/update-canon`, then runs Steps 4 to 6 in place              |
+| Equal, declined, on any other branch       | Stops and says so, since `canon:git-branch` would rename that branch under every session on it    |
+
+Four points govern the choice:
+
+- Offer the worktree as the default in the preview's `Where it lands` line, and take a decline from the operator's reply to it
+- Report it rather than proceeding silently when `canon:session-worktree` does not resolve, as in a project that installed governance without the plugin, then fall back to `canon:git-branch`
+- Stop when neither skill resolves, saying the run would otherwise write onto the shared checkout's branch
+- Run the Guards' dirty-tree test again from the new tree. A fresh worktree starts clean, so a refusal there is a real one.
+
 ## Step 4: migrate
 
 Run each pending migration in the order `migrate status` gave, one at a time, as the entry's `verb` with `--write --json` appended. The verb carries the flags its dry run used, so a bare `canon migrate <name>` would apply a plan the preview never showed.

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

@@ -74,10 +74,8 @@ Write `.canon/tasks/vXX.Y-<slug>.md` under the claimed label, reading the file f
 
 A task file with no row is a dropped task, so name its surface in the same pass that creates it. The test and both file shapes are in `${CLAUDE_SKILL_DIR}/references/board.md`.
 
-| Task                                        | Surface                                                                                                                                   |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Plausibly planned within the next few waves | A row under `## Needs a plan` in `.canon/tasks/priority.md`, through `canon tasks place <stem> --group needs-a-plan --waiting "<reason>"` |
-| Anything else                               | A line in `.canon/tasks/backlog.md`, which is unordered                                                                                   |
+- A task plausibly planned within the next few waves takes a row under `## Needs a plan` in `.canon/tasks/priority.md`, through `canon tasks place <stem> --group needs-a-plan --waiting "<reason>"`.
+- Any other task takes a line in `.canon/tasks/backlog.md`, which is unordered.
 
 Position the row against its siblings with `--before <stem>` or `--after <stem>`, and state what it ranks against in the reason.
 

package/claude/skills/task-board/references/tasks.md

@@ -147,11 +147,11 @@ A task with no origin is lost context or work nobody decided to do. The reverse
 
 `Plan:` points at `../plans/feature-<slug>.md` while the task is open. Retarget both halves of the link as things move rather than dropping it, so a completed task still leads to its reasoning.
 
-| State                         | Target                                  |
-| ----------------------------- | --------------------------------------- |
-| Open                          | `../plans/feature-<slug>.md`            |
-| Shipped, plan archived        | `../plans/archive/feature-<slug>.md`    |
-| Task archived a folder deeper | `../../plans/archive/feature-<slug>.md` |
+- Open: `../plans/feature-<slug>.md`
+- Shipped, plan archived: `../plans/archive/feature-<slug>.md`
+- Task archived a folder deeper: `../../plans/archive/feature-<slug>.md`
+
+Three rules cover the line itself:
 
 - One plan per task, or one per slice as distinct plans on one line. A plan cited by two tasks is a misfile.
 - `canon tasks plan-link <task> <plan>` writes or corrects the line, and `--add` appends a slice's plan, so it is never hand-edited

package/claude/skills/task-complete/references/archive.md

@@ -56,8 +56,11 @@ An empty `plans` means the task cited no live plan, or a sibling still holds eve
 Each reason has one resolution, and none of them is to archive around it.
 
 - `open-outcomes`: the named outcomes are unmarked or genuinely open. Run `task-complete` when the work shipped unmarked, and leave the task on the board when the outcome is real.
-  - An outcome only the operator can check is marked `- [ ] Operator check: <outcome>` rather than struck, which the archive passes and the record lists under `operatorChecks`. The mark has to land before the pull request opens.
-  - Abandoned work, an outcome another repository owes, and an operator outcome nobody marked in time take the strike. The orchestrator's merge sweep strikes it with its reason and lists it in the report, per `${CLAUDE_SKILL_DIR}/../role-orchestrator/references/orchestrator-refill.md`, and the archive then runs. An outcome this repository owes is never struck for that.
+  - An outcome only the operator can check is marked `- [ ] Operator check: <outcome>` rather than struck, so the archive passes it and lists it under `operatorChecks`
+  - The mark has to land before the pull request opens
+  - Abandoned work, an outcome another repository owes, and an operator outcome nobody marked in time take the strike
+  - The orchestrator's merge sweep strikes it with its reason and lists it in the report, per `${CLAUDE_SKILL_DIR}/../role-orchestrator/references/orchestrator-refill.md`, and the archive then runs
+  - An outcome this repository owes is never struck for that
 - `ambiguous`: two tasks name one pull request, the misfile `${CLAUDE_SKILL_DIR}/references/tasks.md` rules out. Resolve the citation by hand, since no sweep repairs it.
 - `earlier-slice`: the number is listed on the task but is not the last. Leave the task on the board, and its last slice's merge archives it.
 

package/claude/skills/test-craft/SKILL.md

@@ -31,6 +31,8 @@ Size a test by what it touches rather than by what it covers. Pick the first row
 | Rendered behavior: states, interactions, conditional rendering, validation, focus    | Component                             |
 | A journey across routes, or what only a real browser renders: layout, scroll, motion | End to end                            |
 
+Four rules govern how a session reads the table.
+
 - Read the row off the behavior, never off the file. A component file holding a pure formatter takes a unit test for the formatter.
 - Split a behavior that spans rows. Test the copy at unit and the render at component, rather than asserting both in one browser run.
 - Write the lower test when a higher one catches a break no lower test did. A red end to end run with every unit and component test green names a missing lower test.

package/claude/skills/test-craft/references/adopted.md

@@ -19,6 +19,8 @@ Three sources settle which layer a test belongs at and how the decision table re
 | Sizing by what a test touches          | Google's small, medium, and large sizes ([Software Engineering at Google, ch. 11](https://abseil.io/resources/swe-book/html/ch11.html))                                         |
 | The component layer carrying UI weight | Kent C. Dodds's trophy ([Write tests](https://kentcdodds.com/blog/write-tests)) and Testing Library's [guiding principles](https://testing-library.com/docs/guiding-principles) |
 
+Each source below is read for what it settles.
+
 - Fowler writes a lower test when a higher one catches what no lower one did. It is the body's layer rule and the decision table's reason.
 - Google's sizes name what a test may touch rather than cover. The table keys on the same, so it transfers across stacks without naming a runner.
 - Testing Library holds that tests resembling use give more confidence

package/claude/skills/ui-checklist/SKILL.md

@@ -33,15 +33,14 @@ The evidence comment already heads the list with `## What to look at`, so the fi
 - [ ] <route>[, <width>]: <verb> <target> → <expected visual result>
 ```
 
-Write each box so a session driving the running app can run it without guessing:
-
-| Part  | Rule                                                                                                                                                                            |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Route | A path or the control that reaches it. A box naming none is driven from the address the driver opens. Write "from the page the app opens on" for a state reached by a sequence. |
-| Width | Only when the change can differ by width, such as layout, spacing, or anything responsive. Copy, color, or a state rendering the same everywhere leaves it off.                 |
-| Verb  | An action a driver performs, such as "scroll to", "click", "resize to", or "tab to". Never "read" or "look at", which name no action.                                           |
-| Taste | End the line with `(taste)` when the result is a judgment of look or feel. A driver reports such a box as needing a person's eyes rather than passing it.                       |
-| Setup | State inline any setup the page does not open in. End the line with `(local only)` when a hosted preview cannot reach that state, such as a stopped service or a seeded record. |
+Write each box so a session driving the running app can run it without guessing, with one rule for each part:
+
+- **Route.** A path or the control that reaches it. A box naming none is driven from the address the driver opens.
+  - Write "from the page the app opens on" for a state reached by a sequence.
+- **Width.** Only when the change can differ by width, such as layout, spacing, or anything responsive. Copy, color, or a state rendering the same everywhere leaves it off.
+- **Verb.** An action a driver performs, such as "scroll to", "click", "resize to", or "tab to". Never "read" or "look at", which name no action.
+- **Taste.** End the line with `(taste)` when the result is a judgment of look or feel. A driver reports such a box as needing a person's eyes rather than passing it.
+- **Setup.** State inline any setup the page does not open in. End the line with `(local only)` when a hosted preview cannot reach that state, such as a stopped service or a seeded record.
 
 When the plan cites `canon/design/<surface>/` under `**Design references:**`, name the reference as the comparison on each box for that surface, such as "→ matches `canon/design/<surface>/` in light and dark". The reviewer then judges the build against the accepted design instead of against taste.
 

package/claude/skills/write-doc/SKILL.md

@@ -13,12 +13,12 @@ Drafts one brand-new project document end to end: resolve its kind, read the sta
 
 Each kind has one standard and one reference. Load the reference for the resolved kind and no other, since every step below that differs by kind lives there.
 
-| Kind    | Lands at                                                 | Standard                                                    | Reference                                     |
-| ------- | -------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------- |
-| docs    | a page under `docs/`                                     | `${CLAUDE_SKILL_DIR}/../docs-sync/references/docs.md`       | `${CLAUDE_SKILL_DIR}/references/docs.md`      |
-| context | an entry under `canon/context/`                          | `${CLAUDE_SKILL_DIR}/../context-fold/references/context.md` | `${CLAUDE_SKILL_DIR}/references/context.md`   |
-| wiki    | a reference page on a subject owned outside this project | `${CLAUDE_SKILL_DIR}/references/wiki.md`                    | `${CLAUDE_SKILL_DIR}/references/wiki-kind.md` |
-| readme  | a `README.md`, at the root or in a folder                | `${CLAUDE_SKILL_DIR}/../docs-sync/references/readme.md`     | `${CLAUDE_SKILL_DIR}/references/readme.md`    |
+- **docs** lands at a page under `docs/`. Standard `${CLAUDE_SKILL_DIR}/../docs-sync/references/docs.md`, reference `${CLAUDE_SKILL_DIR}/references/docs.md`.
+- **context** lands at an entry under `canon/context/`. Standard `${CLAUDE_SKILL_DIR}/../context-fold/references/context.md`, reference `${CLAUDE_SKILL_DIR}/references/context.md`.
+- **wiki** lands at a reference page on a subject owned outside this project. Standard `${CLAUDE_SKILL_DIR}/references/wiki.md`, reference `${CLAUDE_SKILL_DIR}/references/wiki-kind.md`.
+- **readme** lands at a `README.md`, at the root or in a folder. Standard `${CLAUDE_SKILL_DIR}/../docs-sync/references/readme.md`, reference `${CLAUDE_SKILL_DIR}/references/readme.md`.
+
+Resolve the kind from the request by the rules below.
 
 - Read the kind off the destination the request names: a path, a folder, or the document's own name, such as "a context entry" or "a wiki page".
 - Ask which kind when the request names no destination, offering the candidates the subject fits with the likeliest first
@@ -30,10 +30,10 @@ Each kind has one standard and one reference. Load the reference for the resolve
 
 Read these in parallel, from the project root where a path is relative:
 
-- The kind's standard from the table above: the reader the document serves, its frontmatter, its structure, and what it links out to rather than restates
+- The kind's standard from the kind list above: the reader the document serves, its frontmatter, its structure, and what it links out to rather than restates
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for all generated text
 - The `write-human` skill: voice, rhythm, and sentence construction for all generated text
-- The kind's reference from the table above
+- The kind's reference from the kind list above
 
 ## Guards
 

package/claude/skills/write-doc/references/readme.md

@@ -23,6 +23,8 @@ Read the target if it exists, and branch on its headings.
 | Carries no H1, or only headings restating the scaffolding tool | Generator output | Continue, drafting over it rather than syncing its sections                           |
 | Does not exist                                                 | Nothing to read  | Continue                                                                              |
 
+Three notes qualify those routes.
+
 - On the authored branch, report rather than offering to overwrite it or to conform it, since the project's own citations into its README are invisible from here
 - A hand-authored README opening with a badge block, or a title the H1 test misses, falls into the no-H1 branch the same as a scaffold page
 - The Confirm step catches that case before the write, so it is load-bearing. Never skip it on the reasoning that the guard already decided.

package/claude/skills/write-doc/references/wiki-kind.md

@@ -17,10 +17,17 @@ If `<wiki-root>` does not resolve, say so and ask whether to create it before dr
 
 The standard sets two tests and a page has to pass both. Run them before drafting anything, since a page failing either is non-conforming however well it is written.
 
-| Test                                        | Fails on                                                                        | Refusal                                                                                                                                    |
-| ------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| Owned outside this repository               | A subject describing how this repository works                                  | `❌ <subject> is owned by this project, so it belongs in the docs surface or a context entry. Re-run write-doc naming that destination.`   |
-| Owned by the vendor the folder split covers | A third-party tool or a vendor-neutral concept, however reference-like it reads | `❌ <subject> is outside the wiki's folder split. Route it to the docs surface or a skill body rather than adding a second folder for it.` |
+The first test is owned outside this repository, and it fails on a subject describing how this repository works. Refuse with this line:
+
+```plaintext
+❌ <subject> is owned by this project, so it belongs in the docs surface or a context entry. Re-run write-doc naming that destination.
+```
+
+The second test is owned by the vendor the folder split covers, and it fails on a third-party tool or a vendor-neutral concept, however reference-like it reads. Refuse with this line:
+
+```plaintext
+❌ <subject> is outside the wiki's folder split. Route it to the docs surface or a skill body rather than adding a second folder for it.
+```
 
 On the first test, offer the docs or context kind of this skill. The standard names one owner and one subfolder for the second.
 

package/docs/agents/context-audit.md

@@ -22,19 +22,19 @@ canon context audit tooling/base/seeds --gate
 
 ## Output
 
-| Check               | Reports                                                                                                                                               | Reaches                 | Finding                                                     |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------- |
-| Citations           | A path into an audited folder that resolves nowhere                                                                                                   | Every audited folder    | Gates always                                                |
-| Requirements record | Words past the cap the record states as `This record holds at most 600 words.`                                                                        | `canon/REQUIREMENTS.md` | Gates past a stated cap, never under `--citations-only`     |
-| Required sections   | An entry missing `Overview` or `Layout`. A split folder answers by any sibling                                                                        | `canon/context/`        | Gates under `--gate`                                        |
-| Closed set          | An H2 outside `Overview`, `Layout`, and `Gotchas`, under `extraSections`                                                                              | `canon/context/`        | Gates under `--gate`                                        |
-| Shape               | `retired-section`, `gotcha-count`, `gotcha-heading`, `gotcha-paragraph`, `layout-heading`, `layout-bullets`, `layout-paragraphs`, `layout-depth`      | `canon/context/`        | Gates under `--gate` in a `SHAPE_GATED_FOLDERS` folder only |
-| Index drift         | An entry its index does not link, or a link resolving to nothing                                                                                      | Every audited folder    | Gates under `--gate`                                        |
-| Coverage            | A folder directly under a code root that no Layout names, one with a Layout H3 in two entries, and a declared root matching nothing, under `coverage` | `canon/context/`        | Gates under `--gate`, never under `--citations-only`        |
-| Reference form      | A backticked bare filename matching a sibling entry, under `bareReferences`                                                                           | Split folders           | Reports                                                     |
-| Length              | An entry past about 150 rendered lines at 80 columns, with its `causes`                                                                               | Every audited folder    | Reports                                                     |
-| Tables              | Six or more body rows whose first column mostly carries a path, command, or link                                                                      | Every audited folder    | Reports                                                     |
-| Provenance          | A date, change number, or release label. A date after measured, verified, driven, passed, or fired is excluded                                        | `canon/context/`        | Reports                                                     |
+| Check               | Reports                                                                                                                 | Reaches                 | Finding                                                     |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------- |
+| Citations           | A path into an audited folder that resolves nowhere                                                                     | Every audited folder    | Gates always                                                |
+| Requirements record | Words past the cap the record states as `This record holds at most 600 words.`                                          | `canon/REQUIREMENTS.md` | Gates past a stated cap, never under `--citations-only`     |
+| Required sections   | An entry missing `Overview` or `Layout`. A split folder answers by any sibling                                          | `canon/context/`        | Gates under `--gate`                                        |
+| Closed set          | An H2 outside `Overview`, `Layout`, and `Gotchas`, under `extraSections`                                                | `canon/context/`        | Gates under `--gate`                                        |
+| Shape               | A break of the entry shape, in any kind listed under the table                                                          | `canon/context/`        | Gates under `--gate` in a `SHAPE_GATED_FOLDERS` folder only |
+| Index drift         | An entry its index does not link, or a link resolving to nothing                                                        | Every audited folder    | Gates under `--gate`                                        |
+| Coverage            | A folder directly under a code root no Layout names, a Layout H3 in two entries, or an unmatched root, under `coverage` | `canon/context/`        | Gates under `--gate`, never under `--citations-only`        |
+| Reference form      | A backticked bare filename matching a sibling entry, under `bareReferences`                                             | Split folders           | Reports                                                     |
+| Length              | An entry past about 150 rendered lines at 80 columns, with its `causes`                                                 | Every audited folder    | Reports                                                     |
+| Tables              | Six or more body rows whose first column mostly carries a path, command, or link                                        | Every audited folder    | Reports                                                     |
+| Provenance          | A date, change number, or release label. A date after measured, verified, driven, passed, or fired is excluded          | `canon/context/`        | Reports                                                     |
 
 The coverage roots come from `roots` in `canon/config/context.toml`, a list of folders or globs such as `packages/*/src`.
 
@@ -42,7 +42,7 @@ The coverage roots come from `roots` in `canon/config/context.toml`, a list of f
 - A file that is not valid TOML, or holds no list of strings under `roots`, gates under `--gate`
 - With no declaration and no `src/`, the audit reports no code root and never gates
 
-A shape break is any of these:
+The shape kinds are `retired-section`, `gotcha-count`, `gotcha-heading`, `gotcha-paragraph`, `layout-heading`, `layout-bullets`, `layout-paragraphs`, and `layout-depth`. A shape break is any of these:
 
 - A `## Decisions` H2, or a `Gotchas` section past five bullets or holding a heading or paragraph
 - A `Layout` H3 titled neither a code-spanned path nor `Other folders`, or a heading below H3 under `Layout`
@@ -56,6 +56,8 @@ The development entry may carry a `Scripts` H3 exempt from both folder caps. `SH
 | `1`  | Refused, with the reason on stderr         |
 | `2`  | A gating finding for the mode the run took |
 
+The exit code follows the mode the run took. The bullets cover where the gate runs, what refuses, and how a seed opts out.
+
 - `bun run check` runs `--gate` against every `tooling/<stack>/seeds/` directory carrying a `.claude/` folder
 - A root resolving no audited folder refuses with `1` and warns, a root measuring no entry warns, and a seed short a section fails with `2`
 - A seed omitting a required section on purpose sets `stub: true` in its frontmatter. Only the value `true` counts, and both install paths strip the field.

package/docs/agents/markdown-audit.md

@@ -26,24 +26,31 @@ The ban set and checkpoints ship in `src/markdown/bans.ts` and `src/markdown/str
 | --------------- | ------------------------------------------------------------------------------------ | ----------------- |
 | Bans            | The two characters `markdown.md` bans, outside frontmatter, fences, spans, and links | Always            |
 | Links           | A relative link resolving to nothing on disk                                         | Always            |
-| Density         | The six limits below, under `density`                                                | On a gated prefix |
+| Density         | The six limits and two table limits below, under `density`                           | On a gated prefix |
 | Reference shape | A `kind: reference` page breaking its shape, under `referenceShape`                  | On a gated prefix |
-| Tables          | The four table limits below, under `tables`                                          | Never             |
+| Tables          | The row count and wide token limits below, under `tables`                            | Never             |
 | Colons          | A colon followed by more text in a prose line, under `colons`                        | Never             |
 | Heading case    | A capital after the first word of a heading or `title`, under `headingCase`          | Never             |
 
 A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, and `See also` as H2s, each at most once and in that order. It takes no H3 and no table headed `Flag` or `Option`. An unmarked page is never measured.
 
-Tables take the four limits in the `markdown-craft` skill's `tables.md`, on the density paths but never `CLAUDE.md`. A cell past 120 visible characters reports as `table-cell`, more than 8 body rows as `table-rows`, a list after a table as `table-then-list`, and a code span with a run past 30 characters as `table-token`. None sets the exit code.
+Tables take the four limits in the `markdown-craft` skill's `tables.md`, on the density paths but never `CLAUDE.md`.
+
+- A cell past 120 visible characters reports as `table-cell` and a list after a table as `table-then-list`, both under `density`
+- More than 8 body rows reports as `table-rows` and a code span with a run past 30 characters as `table-token`, both under `tables` and neither setting the exit code
 
 | Density limit       | Finding                                                    |
 | ------------------- | ---------------------------------------------------------- |
 | Paragraph length    | A prose paragraph past 350 characters                      |
 | Paragraphs in a row | More than 2 paragraphs with nothing else between them      |
-| Bullet length       | A top-level bullet past 200 characters                     |
+| Bullet length       | A bullet past 200 characters, a nested one on its own      |
 | Bullets in a row    | More than 5 plain top-level bullets                        |
 | Heading depth       | Any heading past H3                                        |
 | H3 opening          | An H3 whose first block is neither a paragraph nor a table |
+| Table cell          | A table cell past 120 visible characters                   |
+| List after table    | A list as the block directly after a table                 |
+
+Five notes fix how the limits count and where they apply.
 
 - A paragraph under a list item counts toward that bullet, never as a paragraph
 - A table, fence, list, heading, or bold section marker ends a run of paragraphs

package/docs/agents/migrate.md

@@ -8,21 +8,23 @@ kind: reference
 
 `canon migrate <verb>` moves a project off a retired name or layout. Each verb reports its plan and writes nothing until `--write`, takes `--json`, and, except `rename`, takes `--root`. A second run rewrites nothing, which confirms the exclusions and markers fired.
 
-| Verb               | Moves                                                                                                                                       |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status`           | Nothing. It lists every migration the project still needs, in run order.                                                                    |
-| `rename`           | The retired `aitk` name. `--scope target` rewrites toolkit-owned folders only.                                                              |
-| `skill-names`      | Plugin skills off their `claude-` and `draft-` prefixes and other retired names, with every citation                                        |
-| `records`          | Session records from `.claude/` to `.canon/`, with every tracked citation                                                                   |
-| `surface-roots`    | `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the stamp folder from `.claude/` to `canon/`, by `git mv` |
-| `record-tree`      | Citations inside `.canon/` folders a session still follows: `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, `teach`          |
-| `rule-layout`      | A flat installed-rule layout onto the `canon/`-wrapped one                                                                                  |
-| `scratch-evidence` | A folder a durable record cites out of `.tmp/`, with its citations                                                                          |
-| `record-layout`    | Review receipts, memory archives, feedback, renders, picks, and evidence into their current folders                                         |
-| `session-defaults` | The seeded session defaults into an existing `.claude/settings.json`: `Agent`, `Task`, and both merge commands denied, auto memory off      |
+| Verb               | Moves                                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `status`           | Nothing. It lists every migration the project still needs, in run order.                                        |
+| `rename`           | The retired `aitk` name. `--scope target` rewrites toolkit-owned folders only.                                  |
+| `skill-names`      | Plugin skills off their `claude-` and `draft-` prefixes and other retired names, with every citation            |
+| `records`          | Session records from `.claude/` to `.canon/`, with every tracked citation                                       |
+| `surface-roots`    | Records such as `context/` and `REQUIREMENTS.md`, and the stamp folder, from `.claude/` to `canon/` by `git mv` |
+| `record-tree`      | Citations inside the `.canon/` folders a session still follows, listed below the table                          |
+| `rule-layout`      | A flat installed-rule layout onto the `canon/`-wrapped one                                                      |
+| `scratch-evidence` | A folder a durable record cites out of `.tmp/`, with its citations                                              |
+| `record-layout`    | Review receipts, memory archives, feedback, renders, picks, and evidence into their current folders             |
+| `session-defaults` | The seeded session defaults into an existing `.claude/settings.json`, listed below the table                    |
+
+`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies `Agent`, `Task`, and both merge commands, and turns auto memory off. The bullets below add detail per verb.
 
 - `skill-names` takes no `--scope`, and skips the changelog, eval transcripts, and the pointer each renamed `draft-` skill leaves at its old name
-- `surface-roots` leaves `rules/`, `skills/`, `hooks/`, and `settings.json` where Claude Code reads them
+- `surface-roots` moves `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the stamp folder, and leaves `rules/`, `skills/`, `hooks/`, and `settings.json` in place
 - `rule-layout` classifies each flat file against the stamp as clean, edited, or unclaimed. Clean and edited files move untouched, and an unclaimed name stays.
 - `record-layout` labels each evidence folder `(pick)` or `(evidence)` in the dry run
 - `session-defaults` adds a key only when absent, merge entries included, and each older project runs it once. `--write` restores a removed `Agent` or `Task` and never removes a deny entry.

package/docs/agents/output-shape.md

@@ -54,6 +54,8 @@ Discover names at runtime rather than hardcoding them.
 | `canon docs list --json`          | Consumer docs plus per-domain context                            |
 | `canon audits list --json`        | Audits the set runs, the corpus each reads, and whether it gates |
 
+The table names the verbs, and three notes cover what some of them carry.
+
 - `gov list` expands each stack to its rules and carries `unreferenced`, the rules no stack reaches, which install only through `--add`
 - `claude skills list` reports shipped skills only. Each carries `family` (or `null`) and `requirement`, and a `false` requirement is a gap to close. `--names` and `--by-family` change the render.
 - A skill with unparseable frontmatter returns an empty description rather than failing the listing

package/docs/target/migrations.md

@@ -62,19 +62,19 @@ The seven `draft-` skills took verb-first names for what each makes. `canon migr
 | `draft-ready`      | `plan-ready` <!-- canon-keep-retired -->        |
 | `draft-screencast` | `script-screencast` <!-- canon-keep-retired --> |
 
+Replace a citation of a skill with no successor by hand, or delete the sentence.
+
 - `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare prose mention by hand. <!-- canon-keep-retired -->
 - `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request. Replace a bare mention of the skill by hand. <!-- canon-keep-retired -->
 - `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
 - `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, and `canon-rollout` have no successor <!-- canon-keep-retired -->
 - `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, and `ux-walkthrough` have no successor <!-- canon-keep-retired -->
 
-Replace a citation of a skill with no successor by hand, or delete the sentence.
+The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
 
 - `canon repo metadata`, `canon autoship`, and the `120-bash` rule are gone, and `canon gov sync` removes the rule <!-- canon-keep-retired -->
 - `memory-capture`, the `603-memory` rule, and the `memory` standard are gone, so send a lesson to the context entry that owns the fact <!-- canon-keep-retired -->
 
-The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
-
 Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack.
 
 ```bash

package/docs/workflow/operating-model.md

@@ -17,6 +17,8 @@ One warm session holds the cross-feature call and reviews. Cold worker sessions
 | Planner      | One session per row, warm or cold     | Measure the row against the tree, write one plan     | Enter a worktree, write the board  |
 | Worker       | One cold worktree session per feature | Implement, self-check, open PR, answer the reviewer  | Write the shared board, merge      |
 
+Each role keeps to its own writes, and five rules cover how the roles meet.
+
 - The orchestrator loads `role-orchestrator`, a worker loads `role-worker` through `auto-ship` Step 0, and a planner and a reviewer load theirs from the launch that dispatches them
 - The orchestrator decides which rows conflict, what merges first, and whether a row runs at all. Per-row planning can go cold.
 - A dispatched planner writes only the plan, and reports what the task file got wrong rather than repairing it

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.55.0",
+  "version": "5.57.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {