@erclx/canon 5.55.0 → 5.57.0

package/claude/skills/git-pr/references/publish.md

@@ -71,11 +71,10 @@ A link to one Claude Code session names the session that wrote the text rather t
 
 A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it and in backticks where it does not, so a reference moved between destinations is rewritten rather than copied.
 
-| Destination                                               | Form                                                                                                                                                         |
-| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Pull request or issue body, a comment on either, a commit | `#123`, or `owner/repo#123` across repositories <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy --> |
-| A markdown file browsed from the repository tree          | the number in backticks, since neither spelling links there                                                                                                  |
-| Content installed into another repository                 | qualified against a different, resolvable repository, or no number                                                                                           |
+- Pull request or issue body, a comment on either, a commit: `#123` <!-- canon-allow-reference: the bare spelling this section defines, which a qualified form would destroy -->
+- The same destinations when the reference crosses repositories: `owner/repo#123` <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy -->
+- A markdown file browsed from the repository tree: the number in backticks, since neither spelling links there
+- Content installed into another repository: qualified against a different, resolvable repository, or no number
 
 A commit message takes the bare form even though the log links nothing, since the remote is what the form is chosen for. Text quoted from another surface keeps the spelling it arrived with, since rewriting it reports the source as saying something it never said.
 

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

@@ -74,10 +74,17 @@ Classify the groups before generating commands, since the mode decides each bran
 
 Append the line for the run's mode to the preview.
 
-| Mode        | Line                                                                                                                                                                                                          |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Stacked     | `🔁 Sequential squash-merge loop. Squash-merge each PR bottom-up with --delete-branch. After each merge, signal me so I can restack the next branch onto main before you merge it.`                           |
-| Independent | `🔁 Squash-merge secondaries first, primary last. The primary keeps every cherry-picked commit, so merging it first lands every secondary's content on main and leaves the secondary PRs empty after rebase.` |
+Stacked mode appends this line:
+
+```plaintext
+🔁 Sequential squash-merge loop. Squash-merge each PR bottom-up with --delete-branch. After each merge, signal me so I can restack the next branch onto main before you merge it.
+```
+
+Independent mode appends this line:
+
+```plaintext
+🔁 Squash-merge secondaries first, primary last. The primary keeps every cherry-picked commit, so merging it first lands every secondary's content on main and leaves the secondary PRs empty after rebase.
+```
 
 After outputting the preview, execute the final commands immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 

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

@@ -14,7 +14,7 @@ Read the references below before a substantial markdown edit. Every rule in them
 
 Run `canon markdown audit <path>` after the edit, and fix every ban and density finding it reports before moving on. Rewrite the sentence carrying a ban hit rather than swapping the token for a near-synonym, and fix a density finding by its shape rather than trimming characters.
 
-A table finding reports without failing the run. Fix it the way `tables.md` gives for its limit.
+A table cell past its cap and a list after a table gate where density does, and the row count and the wide token report without failing the run. Fix each the way `tables.md` gives for its limit.
 
 ## Routes
 

package/claude/skills/markdown-craft/references/markdown.md

@@ -77,7 +77,7 @@ A bold section marker holding its line alone breaks a run the way a heading does
 
 ## Density
 
-Six limits keep a file scannable on sight, each a fact `canon markdown audit` measures that fails the push where the surface's gate is on. A table takes four more, in `tables.md` beside this file. Open an H3 with a lead sentence or a table, then a few bullets or a short paragraph, since monotone text is the defect whether all prose or all bullets.
+Six limits keep a file scannable on sight, each a fact `canon markdown audit` measures that fails the push where the surface's gate is on. A table takes four more in `tables.md`, two of them gating. Open an H3 with a lead sentence or a table, then a few bullets or a short paragraph, since monotone text is the defect.
 
 | Rule                | Limit                                             |
 | ------------------- | ------------------------------------------------- |
@@ -95,7 +95,7 @@ Rules, a requirements or design record, a changelog, examples, and `.canon/` rec
 A paragraph is read straight through and a bullet is scanned, so the paragraph limit sits above the bullet one. Four sentences to a paragraph stays advice rather than a limit.
 
 - A paragraph's length folds in the lines that wrap it. A paragraph inside a list item counts toward its bullet, never as a paragraph or toward a run.
-- A bullet's length counts its continuation lines and excludes any bullet nested under it
+- A bullet's length counts its continuation lines and excludes any bullet nested under it, and a nested bullet is measured on its own
 - A heading, list, table, fence, or bold section marker ends a run of paragraphs
 - A blank line, a continuation, and a nested item do not break a run of bullets, and a paragraph or a heading does
 - A run whose every item opens with a bold label or a link is exempt from the run limit, since each item names its own subject. A task box is not a link, so a checklist counts as plain.

package/claude/skills/markdown-craft/references/tables.md

@@ -5,18 +5,20 @@ description: The four limits a markdown table takes, being cell length, row coun
 
 # Table limits
 
-None of the density limits in `markdown.md` reads inside a table, so content too long for a bullet tends to move into a cell. Four table limits close that gap. `canon markdown audit` measures them on the paths density covers, outside fences, and reports each one without failing a push for now.
+None of the density limits in `markdown.md` reads inside a table, so content too long for a bullet tends to move into a cell. Four table limits close that gap. `canon markdown audit` measures them on the paths density covers, outside fences.
+
+Cell length and a list after a table fail a push where density gates. Rows and a wide token report without failing one.
 
 ## Limits
 
 Each limit is a count or a shape a scan settles, read the way a renderer draws the table. An escaped pipe stays inside its cell, and pipe lines with no delimiter row are not a table.
 
-| Rule             | Limit                                                 |
-| ---------------- | ----------------------------------------------------- |
-| Cell length      | 120 visible characters, counting a link by its label  |
-| Rows             | 8 body rows, not counting the header                  |
-| List after table | A list is never the next block after a table          |
-| Wide token       | No code span in a cell holds a run past 30 characters |
+| Rule             | Limit                                                 | Effect       |
+| ---------------- | ----------------------------------------------------- | ------------ |
+| Cell length      | 120 visible characters, counting a link by its label  | Gates        |
+| Rows             | 8 body rows, not counting the header                  | Reports only |
+| List after table | A list is never the next block after a table          | Gates        |
+| Wide token       | No code span in a cell holds a run past 30 characters | Reports only |
 
 A paragraph or a heading between a table and a list clears the third limit, and a blank line alone does not.
 

package/claude/skills/plan-feature/REQUIREMENT.md

@@ -13,7 +13,7 @@ A constraint naming a surface to leave alone forbids two acts at once, conformin
 
 ## Must
 
-- Read the project's Claude setup before scanning source, and name every file the work touches with the reason it is touched
+- Read the project's Claude setup and the domain's context entry, run the existing thing once read-only, then scan source, and name every file touched with its reason
 - Reframe a vague ask as observable success criteria, carry each into the plan's verification, and ask when none can be predicted
 - Slice by user-visible path with the riskiest batch first, and fold a stacked batch sharing most of its files into its parent unless the plan says why they differ
 - Quote the fetched passage behind each outside source, mark an unfetched one unverified, and place each new path against the layout guidance with a one-clause reason
@@ -23,6 +23,7 @@ A constraint naming a surface to leave alone forbids two acts at once, conformin
 
 - Implement, or edit any file the plan describes
 - Read directories speculatively, since context spent on files the feature does not touch is context the plan does not get
+- Run a form that writes to the tree being planned against, since a planner writes its plan and nothing else
 - Bundle independent concerns into one plan
 - Restate the plan in chat during follow-up rounds, since the file is the source of truth
 

package/claude/skills/plan-feature/SKILL.md

@@ -13,6 +13,13 @@ metadata:
 - Do not implement anything. Output the plan and stop.
 - When the feature description spans two or more independent concerns, write one plan file per concern. Do not bundle them under a single slug.
 
+## Write scope
+
+Write the plan, and nothing else in the tree being planned against.
+
+- A file made only to look at goes to scratch under a topic slug, per `${CLAUDE_SKILL_DIR}/references/onboarding.md`
+- A fixture or headless session that must be its own project goes outside the repository, in a temporary directory
+
 ### Predict the next three questions
 
 Before Step 3, name the next three questions you would ask about what the ask must achieve, and predict the operator's answer to each. The test reads the ask's success criteria, never the plan's open questions.
@@ -33,7 +40,15 @@ Also read `canon/DESIGN.md` when the feature touches code or UI, for visual inte
 
 Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match.
 
-## Step 2: scan relevant source files
+### Read the domain's context entry
+
+Onboard to each domain the feature touches before reading its code, through its context entry. Read `${CLAUDE_SKILL_DIR}/references/onboarding.md` for the lookup.
+
+## Step 2: run the surface, then scan relevant source files
+
+When the feature changes a verb, a route, or a rendered surface that already exists, run it once before reading its code and record what it showed. Read `${CLAUDE_SKILL_DIR}/references/onboarding.md` for the safe form per surface kind, the rules that keep the run from writing, and the not-run record.
+
+### Read the code
 
 Read the source files directly relevant to the feature, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
 
@@ -59,6 +74,7 @@ The section list, what each section holds, and the suggested-and-answer contract
 
 What this skill adds on top of the standard:
 
+- Record each command Step 2 ran and what it showed, or the not-run reason, under `## Current behavior`, and omit the section when nothing ran
 - Reframe a vague ask as success criteria before `## Files to touch`, each an observable result and its check, which becomes one `## Verification` bullet. "Make it faster" names none.
 - Confirm a concrete project or use case drives the feature, and lift patterns from it where precedent exists. A feature with no named user is a guess.
 - Prefer one layout that serves both a new and a grown project over a dual-mode toggle or a migration shim. Two modes double what every later change has to hold.
@@ -163,6 +179,8 @@ Pick the `Next:` line from the roster check `${CLAUDE_SKILL_DIR}/../task-board/S
 | **Not found**, and this session's name starts with `worker-` or `planner-` | `Hand <task> to a worker`, naming no session, since none is live and the operator dispatches by hand |
 | **Not found otherwise**, or the read fails                                 | `/session-worktree`                                                                                  |
 
+Three rules apply to the `Next:` choice:
+
 - With a live orchestrator and no planner role held, send the plan path to it through `canon:session-relay`, resolved from its `sessionId`
 - A session holding `canon:role-planner` already owes that announcement through its own channel, so it sends none
 - Say which row fired in one clause, since a line with no stated reason is one the next reader re-derives.

package/claude/skills/plan-feature/references/onboarding.md

@@ -0,0 +1,51 @@
+---
+title: Onboarding to a domain
+description: The context lookup, the safe run form per surface kind, and the not-run record a planner takes before reading code
+---
+
+# Onboarding to a domain
+
+Applies to the first two reads of `plan-feature` Step 1 and Step 2, taken ahead of the source. They go cheapest first, being the context entry, then one run of the existing thing, then the code. A plan starting from the source alone inherits whatever the running code gets wrong.
+
+## Read the context entry
+
+- Run `canon indexes list --json canon/context` and read the entries whose title or description matches the domain, rather than walking the folder
+- Report none and continue to the run when the project has no `canon/context/` folder or no entry matches
+- Treat an entry as a claim about the code, to be confirmed by the run
+
+## Run the existing thing once
+
+When the feature changes a verb, a route, or a rendered surface that already exists, run it once in a form that writes nothing. Record the command and what it showed.
+
+| Surface kind     | Safe form                                                                    |
+| ---------------- | ---------------------------------------------------------------------------- |
+| CLI verb         | its read verb, or the `--check` or `--dry-run` form, with `--help` for flags |
+| Route or API     | one read request against a running instance                                  |
+| Rendered surface | a capture against a running preview                                          |
+| Anything else    | the project's own read command, or a sandbox scenario                        |
+
+Three rules hold across every kind:
+
+- Write nothing into the planned tree beyond the plan, so never run a form that writes there. The exceptions are the scratch and outside-repository writes below.
+- Send a verb with no read form to a sandbox scenario or a temporary copy, and name which
+- Skip the step for a feature touching nothing that runs, such as prose or a config seed
+
+## Place the run and its output
+
+A checkout is often shared with sessions building other branches, so where a run happens matters as much as what it runs.
+
+- Keep a read-only run in the checkout and never switch its branch, since a switch changes the files under every other session reading it
+- Serve a preview on a free port only when it writes nothing, and run one that builds from a temporary copy, since a build leaves caches and output under the checkout
+- Send a file made only to look at, such as a capture or a dump, to a scratch topic slug under the scratch rule, which owns the path and the reserved slugs
+- Put an own-project fixture or headless session outside the repository, since a tool that walks up to a project root measures the enclosing repository
+- Keep the plan's own text as the record of what a run showed, since scratch is gitignored and no later session reads it
+
+### Name the binary a run measured
+
+A run against the toolkit itself can reach the installed binary or the checkout's own build, and the two answer differently once the branch has moved. State which one ran, with its version or path, beside the command in `## Current behavior`.
+
+## Record a run that did not happen
+
+Write the surface as not run with the reason, such as a broken build, a preview that will not start, or a verb with no read form that no sandbox scenario or temporary copy can reach. A skipped run with no record reads the same as one nobody considered.
+
+Step 3 writes each run, or its not-run reason, into `## Current behavior`.

package/claude/skills/plan-feature/references/plan.md

@@ -72,6 +72,7 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | Section                | Holds                                                                       | Required                                          |
 | ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------- |
 | `## Summary`           | three to five one-line bullets: the goal, the deliverables, the trade-off   | Always                                            |
+| `## Current behavior`  | each command run against the thing being changed and what it showed         | When the change touches something that runs       |
 | `## Constraints`       | durable rules the work must respect                                         | When supplied                                     |
 | `## Files to touch`    | each file with a one-line reason                                            | Always                                            |
 | `## Design references` | the tracked design folders the change builds against, each with its surface | When Files to touch names a rendered-surface file |
@@ -81,6 +82,10 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | `## Questions`         | numbered open decisions, each with a suggestion and an answer slot          | Always                                            |
 | `## Sources`           | the outside sources a decision rests on, each with its quoted passage       | When a decision rests on an outside source        |
 
+### Writing a section
+
+Four rules govern how a section is written:
+
 - Write each section as the H2 the table gives, so a reader scans the plan by its outline
 - A section written as a bold label, the spelling before this one, is still that section to every parser. Leave an existing plan's spelling alone.
 - Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
@@ -124,6 +129,15 @@ State every count and every claim about the tree as measured during the pass tha
 
 Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
 
+### Current behavior
+
+A plan changing a verb, a route, or a rendered surface starts from what that thing does today, so the section records the run the planner made and not a reading of the source.
+
+- Write one bullet per run, leading with the command or request in backticks and ending on what it showed
+- Run only a read form, per the safe forms in `onboarding.md`, since a planner writes its plan and nothing else
+- Record a run that could not happen as not run with the reason. Never leave it out silently.
+- Leave the section out of a plan touching nothing that runs, such as prose or a config seed
+
 ### Constraints
 
 Work in flight reaches a plan as a hold or as a shared path. A hold leaves a surface alone and says which of two acts it forbids, rather than leaving the executing session to guess. Neither act is forbidden over a shared path.
@@ -257,6 +271,10 @@ Each H3 below shows where a section groups once it passes 5 bullets. A section o
 - <one-line bullet covering the main deliverables>
 - <one-line bullet covering the key decision or trade-off>
 
+## Current behavior
+
+- `<command or request>`: <what it showed, or not run and why>
+
 ## Constraints
 
 Measured against `<commit>` on <YYYY-MM-DD>.

package/claude/skills/plan-groundwork/SKILL.md

@@ -98,7 +98,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `canon/REQUIREMENTS.md`: scope and non-goals
 - `.canon/tasks/index.md`: what is already tracked, and what a prior track concluded. Open a task file only when its entry looks related.
 
-Then read only what a live question needs, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+Then read only what a live question needs, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at. For each domain the topic touches, read its context entry ahead of measuring, through the lookup in `${CLAUDE_SKILL_DIR}/../plan-feature/references/onboarding.md`.
 
 Do not dispatch subagents. A groundwork track is a conversation, and fanning out loses the reasoning that makes the folder worth keeping. A search too large to run inline is a finding that the question is too broad.
 

package/claude/skills/plan-intake/REQUIREMENT.md

@@ -7,15 +7,15 @@ description: Why a brain dump gets a filed inventory rather than ten plans, and
 
 ## Gap
 
-A brain dump reaches a session with nowhere to put it. One plan per concern turns forty findings into ten plans before anything is measured, and what gets filed instead is a list of opinions, because nothing forces a count against the tree.
+A brain dump reaches a session with nowhere to put it. One plan per concern turns forty findings into ten plans before anything is measured, and what gets filed instead is a list of opinions, because nothing forces a count against the tree. A defect confirmed from source alone reads the same as one that was run.
 
 An empty operator slot reads as consent under a blank-means-accept contract, which ships changes nobody approved. A report naming only a path hides what moved. A question filed without a pick comes back unresolved, and a pass with no write scope starts fixing what it files.
 
 ## Must
 
 - Route each item on whether the repository can answer it today, sending experiments to `plan-groundwork` and decided work to `plan-feature`
-- Measure every problem line against the tree, close every item with a verdict, and pair every open question with a suggested pick
-- Treat an empty operator slot as unread, and keep answers on items with the index pointing at them
+- Measure every problem line against the tree, running a defect's one-command repro read-only or marking it not reproduced here
+- Close every item with a verdict and a suggested pick on each question, and treat an empty operator slot as unread
 - Reserve the index number, carry the domain in every other filename, and number a new folder past the highest ordinal across intake and groundwork
 - Confine writes to the intake folder and name the heading and the act beside every path written
 

package/claude/skills/plan-intake/SKILL.md

@@ -63,10 +63,14 @@ Read these in parallel from the project root, skipping any that do not exist:
 
 Then read only what a live item needs, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
 
+For each domain an item touches, read its context entry through the lookup in `${CLAUDE_SKILL_DIR}/../plan-feature/references/onboarding.md`, since the entry records the traps a grep will not show.
+
 ## Step 3: measure against the tree
 
 Grep for each construct an item names and count the sites. Every problem line carries a number or a file path taken during this pass.
 
+When an item reports a defect with a one-command repro, run it in a read-only form and say on the `Problem:` line what it showed, or that it was not reproduced here. Read `${CLAUDE_SKILL_DIR}/references/intake.md` for where one command ends and groundwork begins.
+
 - Never carry a figure from an earlier session, a summary, or another document. The tree states the size of a complaint, and that is what separates an inventory from opinions.
 - Confirm any work an item sequences behind is still open, so no item leads with something already shipped
 - Name the commit the pass measured against in the overview body, since that is the half a later reader can check

package/claude/skills/plan-intake/references/intake.md

@@ -19,6 +19,7 @@ The folder is gitignored. Where a records remote is configured, `canon records p
 - [Files](#files)
 - [Frontmatter and dating](#frontmatter-and-dating)
 - [00-overview.md](#00-overviewmd) <!-- canon-allow-reference: a heading anchor, not a pull request number -->
+- [Repro versus groundwork](#repro-versus-groundwork)
 - [Item format](#item-format)
 - [The answer contract](#the-answer-contract)
 - [Retrieval](#retrieval)
@@ -99,6 +100,15 @@ The index carries no answer slot. One question in two answerable places has no r
 
 Where an item touches a task already on the board, say so in the index rather than only inside the item. A reader deciding what to promote reads the index first.
 
+## Repro versus groundwork
+
+An item whose claim is a defect may carry one run of its repro, and the run is where intake's measuring stops. A repro that needs more is groundwork's.
+
+- Run one command in a form that writes nothing, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/onboarding.md`, and put what it showed on `Problem:`
+- Mark the item `not reproduced here` on the same line when the repro needs a fixture project, repeated runs, a write, or another project's paths
+- Send the marked item to `plan-groundwork` only when its answer decides a plan, since a claim read from code alone is a reported defect and not a confirmed one
+- Never adapt a repro silently, because a changed command measures something the reporter did not
+
 ## Item format
 
 ```markdown

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

@@ -82,7 +82,7 @@ This skill owns the reply, so do not reimplement the followup flow here.
 
 - `git-followup` syncs the body and title on every invocation, `reply-owned` included, so the merge record reflects this pass. The reply still maps fixes to findings in the review's own thread.
 - A rebase in step 5 rewrote the branch, so the push is a force-push `git-followup` resolves from the tracking branch. Worker branches are single-owner, which makes that safe.
-- `git-followup` stops on an unchanged tree, as when every finding was a conscious-accept and the rebase left generated files alone. Push that with `git push --force-with-lease`.
+- `git-followup` runs on a clean tree too, since the rebased commits are ahead of the tracking branch. A pass of conscious-accepts after a rebase pushes through it and syncs the body like any other.
 
 Once the fixes are commits, re-run step 5's staleness test against the new head. A conflict appearing only now is one the fixes introduced against lines `main` moved, so rebase again under `${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md` and force-push.
 
@@ -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.