@erclx/canon 5.55.0 → 5.56.0

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

@@ -90,13 +90,15 @@ Once the fixes are commits, re-run step 5's staleness test against the new head.
 
 Write a summary reply to `.canon/tmp/pr/reply/reply-<number>.md`, keyed on the PR number so two sessions addressing different pull requests never overwrite each other. Load `write-human` for voice, follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`, and keep each mapping to one line.
 
-| Part     | Content                                                                                                                                        |
-| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| Heading  | `## Review response`, distinct from human threads and subordinate to the review's own `## Review`                                              |
-| Summary  | One sentence. After a step 5 rebase, say so and name files resolved by hand and those the regen rebuilt, since the next review is a full pass. |
-| Findings | One line per finding under 200 characters, naming its outcome and the commit that carries it, in the shape below                               |
-| Docs     | Any `.claude/` docs refreshed as a result of the fixes                                                                                         |
-| Close    | `🤖 Addressed by Claude Code` on its own line, so the reply reads as a machine pass rather than a human sign-off                               |
+| Part     | Content                                                                                                          |
+| -------- | ---------------------------------------------------------------------------------------------------------------- |
+| Heading  | `## Review response`, distinct from human threads and subordinate to the review's own `## Review`                |
+| Summary  | One sentence, plus the rebase note below                                                                         |
+| Findings | One line per finding under 200 characters, naming its outcome and the commit that carries it, in the shape below |
+| Docs     | Any `.claude/` docs refreshed as a result of the fixes                                                           |
+| Close    | `🤖 Addressed by Claude Code` on its own line, so the reply reads as a machine pass rather than a human sign-off |
+
+After a step 5 rebase, the summary says so and names the files resolved by hand and those the regen rebuilt, since the next review is a full pass.
 
 ```markdown
 - **<severity>**, `<file>` line <n>: fixed in `<sha>`. <What now holds, in one sentence.>

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

@@ -87,15 +87,13 @@ Three scope checks follow the walk:
 
 ## Excuses and rebuttals
 
-| Excuse                                                      | Rebuttal                                                                                                                        |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| The tests pass, so the change works                         | Read what the diff did to the tests first. A test skipped, deleted, or stripped of its assertions passes by proving nothing.    |
-| The hunk reads clean, so the review is done                 | The hunk is where the author looked. A consumer, a doc a section away, and the commit that added a removed guard are not in it. |
-| The checker passes on the branch                            | Read the checker's config and the inline suppressions in the diff. A path excluded from the run passes by not being read.       |
-| It was split into smaller functions, so it is simpler       | Count the concepts a reader holds before and after. Moved complexity reads as simpler only to the person who moved it.          |
-| Nothing calls it, so deleting it is safe                    | Read why it was added. Code nobody calls today can still be guarding a path nobody exercised in the change.                     |
-| The description says it is faster                           | A claimed speedup with no measurement, or one run each side, is asserted. Ask for runs that beat the noise.                     |
-| The change only touches styles, so the screenshots can wait | A stylesheet diff says what changed and only the image says what a user sees. Open them, or say none exist.                     |
+- **The tests pass, so the change works.** Read what the diff did to the tests first. A test skipped, deleted, or stripped of its assertions passes by proving nothing.
+- **The hunk reads clean, so the review is done.** The hunk is where the author looked. A consumer, a doc a section away, and the commit that added a removed guard are not in it.
+- **The checker passes on the branch.** Read the checker's config and the inline suppressions in the diff. A path excluded from the run passes by not being read.
+- **It was split into smaller functions, so it is simpler.** Count the concepts a reader holds before and after. Moved complexity reads as simpler only to the person who moved it.
+- **Nothing calls it, so deleting it is safe.** Read why it was added. Code nobody calls today can still be guarding a path nobody exercised in the change.
+- **The description says it is faster.** A claimed speedup with no measurement, or one run each side, is asserted. Ask for runs that beat the noise.
+- **The change only touches styles, so the screenshots can wait.** A stylesheet diff says what changed and only the image says what a user sees. Open them, or say none exist.
 
 ## Red flags
 

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

@@ -13,14 +13,16 @@ The `addyosmani/agent-skills` citations below all pin commit `addyosmani/agent-s
 
 ### Design and scope
 
-**The design procedure.** The nine ordered steps under the design axis draw on four sources, each restated without a language, a framework, or a transport so the walk holds on any stack.
+**The design procedure.** The nine ordered steps under the design axis draw on four sources, each restated without a language, a framework, or a transport so the walk holds on any stack. Each source below carries the step it backs.
 
-| Source                                                                                                                                                                               | Step it backs                                                                               |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| Ousterhout's deep modules, information hiding, and pass-through methods, [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php)                        | Asking what each unit hides, and flagging a unit that passes its arguments straight through |
-| Parnas's criterion that a boundary hides a decision likely to change, [On the Criteria To Be Used in Decomposing Systems into Modules](https://dl.acm.org/doi/10.1145/361598.361623) | The opening step, naming the next likely change and counting what it touches                |
-| Beck's design rules as Fowler records them, especially no duplication and fewest elements, [BeckDesignRules](https://martinfowler.com/bliki/BeckDesignRules.html)                    | The one-place step, and matching each pattern to a problem the code has today               |
-| Google's reviewer guide on design, complexity, and over-engineering, [What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)    | The frame for the whole walk, and the reason a speculative abstraction is a finding         |
+- Ousterhout's deep modules, information hiding, and pass-through methods, [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php)
+  - Backs asking what each unit hides, and flagging a unit that passes its arguments straight through
+- Parnas's criterion that a boundary hides a decision likely to change, [On the Criteria To Be Used in Decomposing Systems into Modules](https://dl.acm.org/doi/10.1145/361598.361623)
+  - Backs the opening step, naming the next likely change and counting what it touches
+- Beck's design rules as Fowler records them, especially no duplication and fewest elements, [BeckDesignRules](https://martinfowler.com/bliki/BeckDesignRules.html)
+  - Backs the one-place step, and matching each pattern to a problem the code has today
+- Google's reviewer guide on design, complexity, and over-engineering, [What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  - Backs the frame for the whole walk, and the reason a speculative abstraction is a finding
 
 The procedure stays in the body rather than a reference, since every review reads the design axis and a reference would cost a read on every run.
 
@@ -55,7 +57,7 @@ From `skills/security-and-hardening/SKILL.md`, the threat model first and the de
 
 ### Closing sections
 
-The excuses, red flags, and closing checklist follow the shape every practice skill in this toolkit carries, from [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md). Each excuse row rebuts a reason a review stops at the hunk, such as passing tests against a test the diff skipped.
+The excuses, red flags, and closing checklist follow the shape every practice skill in this toolkit carries, from [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md). Each excuse rebuts a reason a review stops at the hunk, such as passing tests against a test the diff skipped.
 
 ## Declined
 

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

@@ -33,6 +33,8 @@ Both headings anchor as a section distinct from human threads. The full set is e
 | Evidence | `## Evidence`                                                | `canon pr evidence`, through `pr-evidence` from `git-pr` and `git-followup` |
 | UI       | `## UI review`, `## UI review closed`                        | `review-ui`, posted as a review beside this one and read by nothing here    |
 
+Three notes qualify the table.
+
 - The reply headings in order answer a finding, report a stale branch resolved without one, and carry a finding a worker produced after a close-out
 - `## Evidence` answers no comment on the thread, so the poll leaves it out of the unclassified count rather than reading it as a reply owing a re-review
 - A comment under any other heading reaches the poll as unclassified rather than as silence, so an invented ninth heading is a gap the next run reports

package/claude/skills/review-pr/references/key-changes.md

@@ -13,12 +13,14 @@ Test what `## Key changes` claims against the diff it describes, with `canon pr
 
 Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero. Each field the record carries takes its own reading.
 
-| Field        | Reading                                                                                                                             |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `unmet`      | a `should-fix` finding under the `**PR body**` block the stale box takes, one per path, quoting the `preview` bullet and the `head` |
-| `unnamed`    | read for yourself and raise nothing off the count                                                                                   |
-| `unresolved` | reported nowhere, since it was judged in neither direction                                                                          |
-| `incidental` | reported nowhere, since it owes no bullet                                                                                           |
+| Field        | Reading                                                                                |
+| ------------ | -------------------------------------------------------------------------------------- |
+| `unmet`      | a `should-fix` finding under the `**PR body**` block the stale box takes, one per path |
+| `unnamed`    | read for yourself and raise nothing off the count                                      |
+| `unresolved` | reported nowhere, since it was judged in neither direction                             |
+| `incidental` | reported nowhere, since it owes no bullet                                              |
+
+Each `unmet` finding quotes the `preview` bullet and the `head`.
 
 ### Before filing an unmet path
 

package/claude/skills/review-ui/references/driving.md

@@ -45,14 +45,16 @@ A taste box takes the shot twice, once per theme, naming the theme in the file a
 
 ## The four verdicts
 
-Each box takes exactly one.
-
-| Verdict             | When                                                    | Evidence it carries                                                                                                                                                    |
-| ------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| pass or fail, read  | The result is a fact the page reports                   | The value read, quoted, such as `scrollWidth 436 against clientWidth 320`                                                                                              |
-| pass or fail, frame | The result has a stated criterion only an image settles | The matching evidence stem or the pushed frame's link, inline under the failed box's heading, and what the frame shows, in words                                       |
-| needs eyes          | The box ends in `(taste)`                               | The dark and the light shot as a pair, each the matching evidence stem or a pushed frame's link, and what the frames showed, with nothing about whether it looks right |
-| not driven          | The state could not be reached                          | The reason, such as an unreachable address, a `(local only)` box on a hosted preview, or a target the snapshot does not hold                                           |
+Each box takes exactly one, keyed here by the state it answers.
+
+- **pass or fail, read.** The result is a fact the page reports.
+  - The evidence is the value read, quoted, such as `scrollWidth 436 against clientWidth 320`.
+- **pass or fail, frame.** The result has a stated criterion only an image settles.
+  - The evidence is the matching evidence stem or the pushed frame's link, inline under the failed box's heading, and what the frame shows, in words.
+- **needs eyes.** The box ends in `(taste)`.
+  - The evidence is the dark and the light shot as a pair, each the matching evidence stem or a pushed frame's link, and what the frames showed, with nothing about whether it looks right.
+- **not driven.** The state could not be reached.
+  - The evidence is the reason, such as an unreachable address, a `(local only)` box on a hosted preview, or a target the snapshot does not hold.
 
 A fail names what was expected beside what was read. A not driven never reads as a fail, since it says the pass could not look rather than that the page is wrong. Its reason says whether the cause sits on the page or off it, since only a cause on the page opens the heading Step 7 picks.
 

package/claude/skills/role-orchestrator/references/orchestrator-parked.md

@@ -9,10 +9,12 @@ Re-test every parked row as orchestrator. A blocker cell is a measurement taken
 
 Two triggers start this pass, and they differ in scope rather than in procedure.
 
-| Trigger                                                                                           | Scope                                                                                                                                |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `orchestrator-sweep.md` sends the rows `canon tasks validate` listed untested                     | Those rows alone, since a merge changes the tree under every parked row and the validator already re-took the two kinds it settles   |
-| An idle session, with nothing merged, workers building, and no pull request awaiting a first pass | Every parked row, since no event narrowed them, plus every `backlog.md` row, which carries no blocker cell for the validator to name |
+- **Sweep.** `orchestrator-sweep.md` sends the rows `canon tasks validate` listed untested.
+  - Scope: those rows alone, since a merge changes the tree under every parked row and the validator already re-took the two kinds it settles
+- **Idle.** The session has nothing merged, workers building, and no pull request awaiting a first pass.
+  - Scope: every parked row, since no event narrowed them, plus every `backlog.md` row, which carries no blocker cell for the validator to name
+
+Three points hold for both triggers.
 
 - Neither trigger is a scheduler. `orchestrator-poll.md` owns the one recurring trigger, and a second loop firing into a static board is the always-on failure it warns about.
 - The sweep asks which parked row to promote next, taking the blocker cell as read, and this pass asks whether the cell is still true

package/claude/skills/role-orchestrator/references/orchestrator-refill.md

@@ -25,10 +25,14 @@ The third trigger reaches a window the first two cannot. A session with three wo
    - Run `task-complete` to archive one the hook left in place
    - A task whose outcomes are standing policy never closes, so hand it to a worker to encode the policy where it is enforced, then cut the outcomes with the reason and archive once that branch merges
    - Encoding it from this session would write a tracked file, which `## Boundaries` in the skill body forbids
-   - An outcome marked `- [ ] Operator check: <outcome>` never blocks the archive. The hook prints no record, so read the archived file's `Operator check:` lines into the report's `Operator checks:` line and leave them unticked.
-   - A merged task whose only open outcomes another repository owes, or that an operator owns and nobody marked, never archives, since `canon tasks archive` refuses `open-outcomes`. Strike each one on the task file as `- ~~<outcome>~~ <reason>`, with the reason on the same line, then archive. The task files are gitignored scratch, so this session may edit them.
+   - An outcome marked `- [ ] Operator check: <outcome>` never blocks the archive, so leave it unticked
+   - The hook prints no record, so read the archived file's `Operator check:` lines into the report's `Operator checks:` line
+   - A merged task whose only open outcomes another repository owes, or that an operator owns and nobody marked, never archives, since `canon tasks archive` refuses `open-outcomes`
+   - Strike each one on the task file as `- ~~<outcome>~~ <reason>` with the reason on the same line, then archive. The task files are gitignored scratch, so this session may edit them.
    - Strike only an outcome the operator or another repository owes. An open outcome this repository owes stays on the board, and the task stays with it.
-   - Send a struck outcome that another repository owes to that repository's orchestrator through `session-relay`, which resolves the address, and let the receiver file it with `task-board` on its own board. `task-board` here would file it on this board. Name it in the report for the operator when no such session is live.
+   - Send a struck outcome that another repository owes to that repository's orchestrator through `session-relay`, which resolves the address
+   - Let the receiver file it with `task-board` on its own board, since `task-board` here would file it on this board
+   - Name it in the report for the operator when no such session is live
    - List every struck outcome in the report's `Struck:` line, so the work is carried by a named owner rather than lost to the strike
 4. Read `.canon/tasks/priority.md` and count the `## Up next` rows whose `Waiting on` has cleared, since a blocked row is no reserve. `## Run now` is what is running, so keep one in reserve beyond it.
 5. Promote from the top of `## Needs a plan`, where the last sweep recorded what to plan next.
@@ -69,6 +73,8 @@ Write `.canon/tasks/priority.md` through the `canon tasks` verbs alone, each rea
 | A row up or down inside its group         | `canon tasks move <stem> --before <stem>`                  |
 | What a row waits on, or why it sits there | `canon tasks block <stem> "<reason>"`                      |
 
+The points below govern writing the board through those verbs.
+
 - `place` removes the task's backlog line in the same call, so a row never sits on both surfaces or on neither
 - Demoting a row to `backlog.md` has no verb yet. Add the backlog line first, then delete the row with the file-editing tool, which errors on a non-match.
 - Put the reason a row sits where it does in its Waiting on cell through `block`, since a row promoted with the cell left alone carries an order the next sweep cannot check

package/claude/skills/role-reviewer/SKILL.md

@@ -19,11 +19,11 @@ This body states the role, the reads, the boundaries, and the channel, and start
 
 The session writes its comment and nothing tracked. Each kind of reviewer writes only these:
 
-| Reviewer | May write                                                                                                                                                      |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Code     | The comment through `review-pr` and the body file it names under `.canon/tmp/pr/review/`                                                                       |
-| UI       | The comment `review-ui` posts, its body file, and the browser's snapshots and frames under `.canon/tmp/pr/review-ui/`, plus `canon pr tick` on boxes it passed |
-| Either   | The draft flag, through `canon pr lift` and no other way                                                                                                       |
+- **Code:** the comment through `review-pr` and the body file it names under `.canon/tmp/pr/review/`
+- **UI:** the comment `review-ui` posts, its body file, and the browser's snapshots and frames under `.canon/tmp/pr/review-ui/`, plus `canon pr tick` on boxes it passed
+- **Either:** the draft flag, through `canon pr lift` and no other way
+
+The rules below close off everything else.
 
 - A tracked file, a branch, a worktree, a board file, and a commit all sit outside what this session may touch
 - Never enter a worktree or check the branch out. The pass reads a change, and a checkout is the first step toward editing it.

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/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.