@erclx/canon 5.55.0 → 5.56.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [5.56.0](https://github.com/erclx/canon/compare/v5.55.0...v5.56.0) (2026-10-23)
+
+
+### Features
+
+* **markdown:** gate table cell and trailing list as density kinds ([#2630](https://github.com/erclx/canon/issues/2630)) ([1d1cbd3](https://github.com/erclx/canon/commit/1d1cbd3f78009dc6f748aee9579fd0245022aaf0))
+* **markdown:** measure nested bullets against the length cap ([#2632](https://github.com/erclx/canon/issues/2632)) ([b5b8f2b](https://github.com/erclx/canon/commit/b5b8f2b7765c801735b52f8bc22275f3ae478f74))
+
 ## [5.55.0](https://github.com/erclx/canon/compare/v5.54.0...v5.55.0) (2026-10-21)
 
 

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.55.0",
+  "version": "5.56.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/api-design/SKILL.md

@@ -61,16 +61,14 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 
 ## Excuses and rebuttals
 
-| Excuse                                                       | Rebuttal                                                                                                                                    |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Nobody depends on that field                                 | You can see the callers you opened. A script parsing the output or a project importing the module is the one you did not.                   |
-| It's internal, so renaming it is fine                        | Internal to whom? If anything outside the module reads it, it is a surface. Add the new name beside the old.                                |
-| The old name is wrong, so keeping it is clutter              | Clutter costs a line. A rename breaks every caller you did not open, and they learn about it from a failure.                                |
-| Returning the record directly saves a mapping                | The mapping is the contract. Without it, a change to the storage layout is a breaking change to every caller.                               |
-| The caller already validates, so checking again is redundant | The boundary checks once for every caller, including the next one, which may not.                                                           |
-| Retries are rare, so the write does not need a key           | Rare is a duplicate charge, a double send, or a second row once a week. The key is cheaper than the cleanup.                                |
-| The error message is clear, so callers can match on it       | A message is written for a person and reworded freely. Give the caller a code it can branch on.                                             |
-| I'll update every caller in this change, so renaming is safe | That holds only when every caller lives in the change. Check that no caller outside the repository reads the surface before you rely on it. |
+- **Nobody depends on that field.** You can see the callers you opened. A script parsing the output or a project importing the module is the one you did not.
+- **It's internal, so renaming it is fine.** Internal to whom? If anything outside the module reads it, it is a surface. Add the new name beside the old.
+- **The old name is wrong, so keeping it is clutter.** Clutter costs a line. A rename breaks every caller you did not open, and they learn about it from a failure.
+- **Returning the record directly saves a mapping.** The mapping is the contract. Without it, a change to the storage layout is a breaking change to every caller.
+- **The caller already validates, so checking again is redundant.** The boundary checks once for every caller, including the next one, which may not.
+- **Retries are rare, so the write does not need a key.** Rare is a duplicate charge, a double send, or a second row once a week. The key is cheaper than the cleanup.
+- **The error message is clear, so callers can match on it.** A message is written for a person and reworded freely. Give the caller a code it can branch on.
+- **I'll update every caller in this change, so renaming is safe.** That holds only when every caller lives in the change. Check that nothing outside the repository reads the surface first.
 
 ## Red flags
 

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

@@ -47,11 +47,10 @@ Resolve `<plan>` in this order, stopping at the first match. Only a path reaches
 
 Each tier stops with its own message on a file that does not resolve.
 
-| Tier    | Stop                                                                                                                                                                                                                |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Task    | `❌ No task at <path>. Path was supplied, not derived, so check it and re-run.`                                                                                                                                     |
-| Plan    | `❌ No plan at <path>. Path was supplied, not derived, so check it and re-run.`                                                                                                                                     |
-| Derived | `❌ No approved plan at .canon/plans/feature-<slug>.md, where <slug> was derived from the current branch, <branch>. The invocation carried no argument, so pass a plan or a task path, or run /plan-feature first.` |
+- Task: `❌ No task at <path>. Path was supplied, not derived, so check it and re-run.`
+- Plan: `❌ No plan at <path>. Path was supplied, not derived, so check it and re-run.`
+- Derived, which stops on the longer message below:
+  - `❌ No approved plan at .canon/plans/feature-<slug>.md, derived from branch <branch>. No argument was passed, so pass a plan or task path, or run /plan-feature first.`
 
 ### When a tier fails
 

package/claude/skills/auto-ship/references/failure-recovery.md

@@ -5,20 +5,40 @@ description: The step an operator resumes from after each auto-ship stop point,
 
 # Failure recovery
 
-Every stop point leaves recoverable state. The user resumes manually from the appropriate step.
-
-| Stop point                                 | Recovery                                                                                                                                           |
-| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| No plan (derived)                          | Run `/plan-feature` to create one                                                                                                                  |
-| No plan (caller-supplied)                  | Check the path or slug passed to autoship, then re-run                                                                                             |
-| No task (caller-supplied)                  | Check the task path passed to autoship, then re-run                                                                                                |
-| Task carries no `Plan:` line               | Write the plan, point the task's `Plan:` line at it, then re-run                                                                                   |
-| Task points at an archived plan            | The work already shipped. Reopen the task against a live plan, or pass that plan's path directly.                                                  |
-| Task's `Plan:` pointer resolves to nothing | Repoint the task's `Plan:` line at the plan that exists, then re-run                                                                               |
-| Resolved file carries no plan shape        | Point autoship at a plan under `.canon/plans/feature-<slug>.md` or at a task under `.canon/tasks/`, then re-run                                    |
-| Branch collision on worktree entry         | `session-worktree` Step 5 found `<slug>` already as a local branch. Resolve manually (rename or delete the stale branch), then re-run autoship.    |
-| Verify fails                               | Read logs, fix manually, run `/git-ship`                                                                                                           |
-| git-ship fails                             | Inspect hook or remote error, run again                                                                                                            |
-| Draft target is not this branch's          | Nothing was marked. Read the number and `head=` from `git-pr`'s output, confirm they match, then run the mark by hand                              |
-| Review wait timed out                      | The record went to the controller. Once the reviewers are dispatched, re-run `canon pr review-state <number> --wait 1200 --json` in the background |
-| Review wait refused                        | Fix what the `reason` names, such as an unreadable remote, then re-run `canon pr review-state <number> --wait 1200 --json` in the background       |
+Every stop point leaves recoverable state. The user resumes manually from the appropriate step, named below for each stop point.
+
+## Worktree entry
+
+The first stop comes at Step 0, ahead of any plan read:
+
+- Branch collision on worktree entry. `session-worktree` Step 5 found `<slug>` already as a local branch, so resolve manually (rename or delete the stale branch), then re-run autoship.
+
+## Plan and task reads
+
+The first plan read stops on a missing or misshapen file, and each repair differs:
+
+- No plan (derived). Run `/plan-feature` to create one.
+- No plan (caller-supplied). Check the path or slug passed to autoship, then re-run.
+- No task (caller-supplied). Check the task path passed to autoship, then re-run.
+- Task carries no `Plan:` line. Write the plan, point the task's `Plan:` line at it, then re-run.
+- Resolved file carries no plan shape. Point autoship at a plan under `.canon/plans/feature-<slug>.md` or at a task under `.canon/tasks/`, then re-run.
+
+A task's `Plan:` pointer can also fail after it is read:
+
+- Task points at an archived plan. The work already shipped, so reopen the task against a live plan, or pass that plan's path directly.
+- Task's `Plan:` pointer resolves to nothing. Repoint the task's `Plan:` line at the plan that exists, then re-run.
+
+## Build and ship
+
+These stops come after the plan reads:
+
+- Verify fails. Read logs, fix manually, run `/git-ship`.
+- git-ship fails. Inspect the hook or remote error, then run again.
+
+## Draft mark and review wait
+
+The last three stops sit after the pull request opens:
+
+- Draft target is not this branch's. Nothing was marked, so read the number and `head=` from `git-pr`'s output, confirm they match, then run the mark by hand.
+- Review wait timed out. The record went to the controller, so once the reviewers are dispatched, re-run `canon pr review-state <number> --wait 1200 --json` in the background.
+- Review wait refused. Fix what the `reason` names, such as an unreadable remote, then re-run `canon pr review-state <number> --wait 1200 --json` in the background.

package/claude/skills/auto-ship/references/tier-failures.md

@@ -25,16 +25,18 @@ The archived task is what makes that base matter. The standard points its line a
 
 Tier 1 stops on four failures, each naming a different repair. Test them in the order below.
 
-| Failure                      | Stop                                                                                                                                                |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| The line links several plans | `❌ <path> links <N> plans on its Plan: line (<every target>), so the task does not say which one this run builds. Pass one plan path directly.`    |
-| No `Plan:` line at all       | `❌ <path> carries no Plan: line, so nothing there names a plan to run. Write the plan and point the task at it, or pass the plan path directly.`   |
-| Pointer into a plans archive | `❌ <path> points at an archived plan, which describes work that already shipped. Reopen the task against a live plan, or pass that plan directly.` |
-| Pointer resolves to no file  | `❌ <path> points at <target>, which does not exist. The citation is stale, so repoint the task or pass the plan path directly.`                    |
+1. The line links several plans. The stop reads:
+   - `❌ <path> links <N> plans on its Plan: line (<every target>), so the task does not say which one this run builds. Pass one plan path directly.`
+2. No `Plan:` line at all. The stop reads:
+   - `❌ <path> carries no Plan: line, so nothing there names a plan to run. Write the plan and point the task at it, or pass the plan path directly.`
+3. Pointer into a plans archive. The stop reads:
+   - `❌ <path> points at an archived plan, which describes work that already shipped. Reopen the task against a live plan, or pass that plan directly.`
+4. Pointer resolves to no file. The stop reads:
+   - `❌ <path> points at <target>, which does not exist. The citation is stale, so repoint the task or pass the plan path directly.`
 
 ### Why each test sits where it does
 
-Each row carries a reason a shortcut would get wrong.
+Each test carries a reason a shortcut would get wrong.
 
 - Test several links first, since taking the first link runs whichever plan leads the line and reports success
 - A row still awaiting a plan is the ordinary case, so the no-line message names the missing pointer rather than the plan sections a reader would then hunt for

package/claude/skills/auto-ship/references/worktree-name.md

@@ -13,12 +13,15 @@ This step runs ahead of Step 1, so what it holds is the raw invocation argument
 canon tasks plan-branch <argument> --json
 ```
 
-| Record            | Route                                                                                                                                       |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `conforms: true`  | Pass the record's `branch`, already `<type>/<slug>`, and invoke nothing else to derive a name                                               |
-| `conforms: false` | The plan's filename breaks a cap in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`. Pass `branch` anyway and say the cap it broke |
-| Anything else     | Invoke `canon:session-worktree` bare and let its ladder derive the name, saying the verb did not answer                                     |
+| Record            | Route                                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------------------------- |
+| `conforms: true`  | Pass the record's `branch`, already `<type>/<slug>`, and invoke nothing else to derive a name           |
+| `conforms: false` | The plan's filename breaks a branch-name cap. Pass `branch` anyway and say the cap it broke             |
+| Anything else     | Invoke `canon:session-worktree` bare and let its ladder derive the name, saying the verb did not answer |
 
+Four notes on those routes:
+
+- The caps on a branch name sit in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`
 - On `conforms: false`, the alternative is a name this session shortened by hand, a second derivation and the thing this call exists to prevent. `git-branch` decides the rename at ship.
 - Anything else covers a refusal, a record carrying no `branch` key, and an installed binary carrying no `plan-branch` subcommand
 - Saying the verb did not answer lets a reader tell a derived name from a fallback one

package/claude/skills/backlog-triage/SKILL.md

@@ -73,10 +73,10 @@ For each row that reproduces, gather the evidence Step 5 reads, and record each
 
 Keep and promote carry the burden of proof, and a defect that still exists does not meet it. A row filed against the tree nearly always reproduces, so a reproduction test alone keeps almost every row. A row earns keep or promote only by naming a cost or a reach from Step 4's evidence.
 
-| Ground | What it takes                                                                                                                                                |
-| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Cost   | A wrong result this pass observed by running the verb or reading committed output, or an issue, run, person, or workaround commit it hit, not measured fixed |
-| Reach  | The defect sits on a shipped path, so everyone reaching it receives a wrong instruction, a broken or unbounded behavior, or a wrong output, hit or not       |
+The two grounds, and what each takes:
+
+- Cost. A wrong result this pass observed by running the verb or reading committed output, or an issue, run, person, or workaround commit it hit, not measured fixed.
+- Reach. The defect sits on a shipped path, so everyone reaching it receives a wrong instruction, a broken or unbounded behavior, or a wrong output, hit or not.
 
 A plausible cost names nothing. A row arguing what could go wrong off a shipped path, with no observed output and no hit, is declined however likely it sounds.
 
@@ -96,12 +96,12 @@ A missing feature earns keep through the cost arm when a user asked for it in an
 
 Age is evidence in neither direction. An old hit reads the same as a new one, by whether the pass measures it as still able to recur.
 
-| Verdict | When                                                                                                                                     |
-| ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| keep    | The defect reproduces this pass, with a count or a path, and the row names a cost or a reach with its observation, hit, or shipped path  |
-| promote | It qualifies for keep, and what it was waiting on has cleared, naming what cleared it                                                    |
-| archive | Every open outcome is measured shipped, naming the commit or pull request per outcome position                                           |
-| decline | Anything else, including a reproduction naming no cost or reach, a defect the tree no longer holds, superseded work, or the filing alone |
+Each verdict takes one condition:
+
+- keep. The defect reproduces this pass, with a count or a path, and the row names a cost or a reach with its observation, hit, or shipped path.
+- promote. It qualifies for keep, and what it was waiting on has cleared, naming what cleared it.
+- archive. Every open outcome is measured shipped, naming the commit or pull request per outcome position.
+- decline. Anything else, including a reproduction naming no cost or reach, a defect the tree no longer holds, superseded work, or the filing alone.
 
 ### Step 6: write the items
 

package/claude/skills/backlog-triage/references/apply.md

@@ -25,12 +25,12 @@ An item already applied, by the test in the skill's Step 1, is skipped silently,
 
 Take the task stem from the item heading. Every verdict leaves the folder slug on its task, which is how Step 1 and `task-board`'s unlinked-origin scan both see the folder as acted on.
 
-| Verdict | Command and board write                                                                                                          |
-| ------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| decline | `canon tasks decline <stem> --reason "<reason>, backlog triage <slug> item <cluster>#<n>" --json`, which clears the backlog line |
-| archive | `canon tasks outcome <stem> --close <p> ... --json` for the named positions, then `canon tasks archive <stem> --json`            |
-| keep    | Append the `## Findings` line naming what reproduced, leaving the backlog line                                                   |
-| promote | `canon tasks place <stem> --group needs-a-plan --bottom --waiting "<what cleared>. Last" --json`, which clears the backlog line  |
+The command and board write for each verdict:
+
+- decline. `canon tasks decline <stem> --reason "<reason>, backlog triage <slug> item <cluster>#<n>" --json`, which clears the backlog line.
+- archive. `canon tasks outcome <stem> --close <p> ... --json` for the named positions, then `canon tasks archive <stem> --json`.
+- keep. Append the `## Findings` line naming what reproduced, leaving the backlog line.
+- promote. `canon tasks place <stem> --group needs-a-plan --bottom --waiting "<what cleared>. Last" --json`, which clears the backlog line.
 
 ### Archive and missing files
 

package/claude/skills/context-fold/references/classify.md

@@ -38,14 +38,27 @@ The verb's own extraction already scopes to canonical doc types and reports noth
 
 Locate the finding by its `quote` in the file's current content. The quote is often a narrow fragment rather than the whole clause it sits in, since the regex layer's own match is a short pattern hit, so the edit below targets the sentence or bullet the quote sits in rather than the literal substring alone.
 
-- **Found exactly once.** Apply the verdict:
-  - `REPLACE`: rewrite the sentence or bullet carrying the quote in place with the fact that now stands, per Step 3's rewrite-in-place rule. State what is current and drop what the quote restated, in the one edit.
-  - `HISTORY`: rewrite the sentence or bullet carrying the quote to drop the narration and keep any current fact the same clause states. The quote narrates how the fact arrived rather than stating the fact, which a canonical doc excludes regardless of what wrote it, and a literal cut of the fragment alone would leave the rest of the clause grammatically stranded.
-  - `MOVE`: do not cut. The verdict means correct content sitting on the wrong surface, such as a rule written into a context entry that belongs in a path-scoped rule, and only the model layer returns it. Cutting would delete content a fold with no model configured would never have flagged at all. Report the finding instead, naming the surface the `reason` names as where the content belongs, and leave the file unedited.
+- **Found exactly once.** Apply the verdict under its heading below.
 - **Found more than once, or not found at all.** Report it as not located rather than guessing an occurrence or silently rewriting nothing. A model paraphrasing its quote is the usual cause.
 
 Run the classifier once per fold. Do not re-run it after applying a finding to check the edit, since a second pass over what this step wrote is the loop the verb's own reference already warns against.
 
+### REPLACE
+
+Rewrite the sentence or bullet carrying the quote in place with the fact that now stands, per Step 3's rewrite-in-place rule. State what is current and drop what the quote restated, in the one edit.
+
+### HISTORY
+
+Rewrite the sentence or bullet carrying the quote to drop the narration and keep any current fact the same clause states. The quote narrates how the fact arrived rather than stating the fact, which a canonical doc excludes regardless of what wrote it.
+
+A literal cut of the fragment alone would leave the rest of the clause grammatically stranded.
+
+### MOVE
+
+Do not cut. The verdict means correct content sits on the wrong surface, such as a rule written into a context entry that belongs in a path-scoped rule, and only the model layer returns it.
+
+Report the finding instead, naming the surface the `reason` names as where the content belongs, and leave the file unedited. Cutting would delete content a fold with no model configured would never have flagged at all.
+
 ## Keeping a finding
 
 Keep a non-`KEEP` finding without applying it only when the quote is itself the alternative a nearby decision states and lost, or the file already carries the current fact elsewhere. State the reason in one line in the report. A keep costs one line, where an incorrect apply costs a rewrite of prose nobody asked to change.

package/claude/skills/create-rule/references/rule.md

@@ -58,6 +58,8 @@ Every limit is a count a reviewer can take, so a rule passes or fails it without
 | Bullet length        | 200 characters                                                  |
 | Sentences per bullet | 2, one directive plus one exception, condition, or short reason |
 
+Two habits keep a rule inside those limits.
+
 - Name one concern in `description`. A rule needing a seventh H2 holds two concerns and splits into two files.
 - Keep a reason to the why of its directive, never a paragraph of background
 
@@ -71,6 +73,8 @@ A bullet loads on every matching edit, so it earns its place only when removing
 | A convention that differs from the default | Anything the linter, formatter, or type checker enforces |
 | A footgun that ships silently              | Information that changes often                           |
 
+Three habits keep each bullet worth its load.
+
 - Write every bullet concrete enough to verify against a line of code. "Prefer `pathlib.Path` over `os.path`" passes, since it names both sides.
 - Pair a ban with the alternative to take, unless the ban or a neighbor bullet already names it
 - Use no emphasis words such as "CRITICAL" or "You MUST", which newer models overtrigger on

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

@@ -36,7 +36,7 @@ Read these in the same pass:
 1. Answer three questions in writing before drafting anything.
    - Does a rule, a verb, or an existing skill already reach this moment? A folder that only wraps something already reachable duplicates it rather than adding to the catalog.
    - Does the body carry a procedure a session would get wrong from first principles? A one-line wrapper around a single command needs no skill.
-   - Will anything invoke it other than the author typing its name? Carry this one into the drafted `REQUIREMENT.md`'s `Must not` section as a review criterion instead, since nothing can answer it before the skill has run.
+   - Will anything invoke it other than the author typing its name? Carry this into the drafted `REQUIREMENT.md`'s `Must not` section as a review criterion, since nothing answers it before the run.
    - Tell the user and stop when the first answer is yes or the second is no. A non-interactive run stops on both too, reporting which question failed and writing no folder.
 2. Draft the full `SKILL.md` from the user's description, stating the current rule alone. An incident and the date it happened stay in git, never in the body, a reference, or the requirement.
 3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the requirement standard states.
@@ -51,7 +51,7 @@ Steps 5 to 7 write the folder and check what landed before the run reports.
 
 5. Resolve the root, then write `<root>/<name>/SKILL.md` and `<root>/<name>/REQUIREMENT.md`.
    - The root is `.claude/skills/` in a target project.
-   - Where the project root holds `claude/.claude-plugin/plugin.json`, which is the toolkit's own checkout, an `internal-*` skill goes under `.claude/skills/` and every other skill under `claude/skills/`, since the plugin ships that tree.
+   - In the toolkit's checkout, which holds `claude/.claude-plugin/plugin.json`, an `internal-*` skill goes under `.claude/skills/` and the rest under `claude/skills/`, since the plugin ships that tree.
 6. Run `canon claude skills audit --json` and read `findings.datedProvenance` for rows under `<root>/<name>/`.
    - Cut each row's date and incident from the file the row names, leaving them to git, and re-run until no row names the folder.
    - When `canon` does not resolve or its record carries no `datedProvenance` key, say the check did not run rather than reporting the skill clean.

package/claude/skills/deploy-app/SKILL.md

@@ -28,6 +28,8 @@ Read the tree for these signals before running any command. A file that exists c
 | `vercel.json` at the root                                                | vercel            |
 | a `wrangler` or `vercel` entry in `package.json` scripts or dependencies | the host it names |
 
+Read the signals together to settle the host.
+
 - Signals for one host only: take that host.
 - Signals for both, or for neither: ask the operator through the structured question surface, naming each signal found. Never default to a host, since a silent pick deploys to the wrong account.
 - A host the operator named in the request wins over the signals. Say which signals disagreed with it, if any.

package/claude/skills/deprecation-migration/SKILL.md

@@ -81,15 +81,13 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 
 ## Excuses and rebuttals
 
-| Excuse                                                   | Rebuttal                                                                                                                         |
-| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| I searched for the name and nothing calls it             | A search finds one spelling in the files it read. A handler looked up by string, a config key, or a published copy stays hidden. |
-| I'll keep the fallback until callers move                | With no date and no owner, the fallback outlives every caller it was kept for. State when it goes and who removes it.            |
-| The callers can migrate when they get to it              | They will not. The owner of the surface moves its callers, or the deprecation never finishes.                                    |
-| It's cleaner to add the new one and drop the old one now | One change that adds and removes leaves no state where a missed caller still works, and a revert undoes the migration too.       |
-| This only matters on one machine                         | One caller is still a caller. Migrate it, or record it as the reason the old path stays.                                         |
-| Nobody owns this, so I can just delete it                | No owner is not no caller. Run the zero-consumers check before deciding, since unowned code is often the code nobody dares move. |
-| I'll mark it deprecated and move on                      | A notice with no shipped replacement and no removal date tells callers nothing they can act on.                                  |
+- **I searched for the name and nothing calls it.** A search finds one spelling in the files it read. A handler looked up by string, a config key, or a published copy stays hidden.
+- **I'll keep the fallback until callers move.** With no date and no owner, the fallback outlives every caller it was kept for. State when it goes and who removes it.
+- **The callers can migrate when they get to it.** They will not. The owner of the surface moves its callers, or the deprecation never finishes.
+- **It's cleaner to add the new one and drop the old one now.** One change that adds and removes leaves no state where a missed caller still works, and a revert undoes the migration too.
+- **This only matters on one machine.** One caller is still a caller. Migrate it, or record it as the reason the old path stays.
+- **Nobody owns this, so I can just delete it.** No owner is not no caller. Run the zero-consumers check before deciding, since unowned code is often the code nobody dares move.
+- **I'll mark it deprecated and move on.** A notice with no shipped replacement and no removal date tells callers nothing they can act on.
 
 ## Red flags
 

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

@@ -19,7 +19,7 @@ The skill body holds the order, the guards, and the report shape. This holds the
 
 The record carries the checkpoints it read against under `checkpoints` and the per-file weights under `entries`. Read both from the record rather than from a number stated here, since the CLI moves a checkpoint on its own cadence and a copy goes stale in place.
 
-- `heavyBullets`: a top-level bullet past the character checkpoint, which is a paragraph wearing a dash
+- `heavyBullets`: a bullet past the character checkpoint, a nested one measured on its own, which is a paragraph wearing a dash
 - `heavyParagraphs`: a paragraph past the sentence or character checkpoint
 - `longestRun`, against `longestRunLine`: unbroken rendered lines between headings, which is the depth checkpoint
 - `cadence`, carrying `measured`, `flat`, and `repeating`: sentence-length spread and repeated openers

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

@@ -42,8 +42,8 @@ A missing tracking ref is not a guard, since an open pull request proves the bra
 2. Run `git add -A` to stage every change
 3. Invoke `canon:git-commit` to generate one conventional commit from the staged diff
 4. Push, in one of two cases.
-   - When `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null` is empty, the branch has an open pull request and no tracking ref, so run `git push -u origin HEAD` to send the commit and set the ref in one step.
-   - Otherwise push to the tracking branch with `git push`, and when `git merge-base --is-ancestor @{u} HEAD` exits non-zero, a caller rewrote the branch and a plain push is rejected, so push with `--force-with-lease` instead.
+   - When `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null` is empty, no ref tracks the branch, so run `git push -u origin HEAD` to push and set the ref in one step.
+   - Otherwise run `git push`, and when `git merge-base --is-ancestor @{u} HEAD` exits non-zero, a caller rewrote the branch, so use `--force-with-lease`, since a plain push is rejected.
 
    The lease is what stops the force from overwriting a commit this session never read. Run the ancestry test only where an upstream resolves, since it reads `@{u}`.
 
@@ -55,16 +55,27 @@ A missing tracking ref is not a guard, since an open pull request proves the bra
 
 6. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`.
 7. Sync the body and title on every invocation, before the routing below decides on the reply.
-   - Read the live title and body with `gh api repos/{owner}/{repo}/pulls/<number> --jq '{html_url, title, body}'`. Update the body with `gh api -X PATCH repos/{owner}/{repo}/pulls/<number> -F body=@<file> --silent` when the new commit changes scope, writing the new body to `<file>` first, and the title with `gh api -X PATCH repos/{owner}/{repo}/pulls/<number> -f title="<title>" --silent` when the scope shifted enough to make it inaccurate.
+   - Read the live title and body with `gh api repos/{owner}/{repo}/pulls/<number> --jq '{html_url, title, body}'`
+   - Update the body with `gh api -X PATCH repos/{owner}/{repo}/pulls/<number> -F body=@<file> --silent` when the new commit changes scope, writing the new body to `<file>` first
+   - Update the title with `gh api -X PATCH repos/{owner}/{repo}/pulls/<number> -f title="<title>" --silent` when the scope shifted enough to make it inaccurate
    - A fix commit answering a review changes what shipped exactly as much as an ordinary followup does, so the sync cannot wait on the invocation or the comment count below.
-   - A body a person edited by hand between rounds gets no special handling: judge it against the tree the same way regardless of who wrote it last, since a hand-edit the fix commit has made stale is the exact drift this sync exists to close.
+   - Judge a body a person edited by hand against the tree like any other, since a hand-edit the fix commit made stale is the drift this sync closes.
    - Carry a `UI pass` line marked `<!-- pr-ui-pass -->` into any rewritten body unchanged, since `canon pr tick` owns it and a dropped marker defeats the reset on a new head.
    - Carry a `Fan-in members:` line into any rewritten body unchanged, since the post-merge hook reads it to delete the members and a dropped line deletes nothing and says nothing.
 8. Route on the invocation and the comment count for the reply alone.
    - When invoked with `reply-owned`, skip this step: the caller posts its own reply.
-   - Otherwise, if the count is above zero, the followup addresses review feedback: write a one-line summary of the fix to `.canon/tmp/pr/followup/summary-<number>.md` in its own call, run `canon labels scan --body-file .canon/tmp/pr/followup/summary-<number>.md` against it, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`, then post it with `gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@.canon/tmp/pr/followup/summary-<number>.md --silent`. A hook on `Bash` runs the same scan on that body file and denies the post on a hit, and it refuses an inline `-f body=` value, so the body goes through a file. The `pull_request` check the git-pr surface carries triggers on a push or an open rather than a plain edit, so neither this comment nor the title and body step 7 synced reaches it.
+   - Otherwise, if the count is above zero, the followup addresses review feedback, so post the summary below.
    - If it is zero, nothing further runs. The sync in step 7 already did this branch's job.
 
+### Posting the step 8 reply
+
+The body goes through a file, since a hook on `Bash` refuses an inline `-f body=` value and runs `canon labels scan` on the file before it allows the post.
+
+- Write a one-line summary of the fix to `.canon/tmp/pr/followup/summary-<number>.md` in its own call
+- Run `canon labels scan --body-file .canon/tmp/pr/followup/summary-<number>.md` against it, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`
+- Post it with `gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@.canon/tmp/pr/followup/summary-<number>.md --silent`
+- The `pull_request` check the git-pr surface carries triggers on a push or an open rather than a plain edit, so neither this comment nor the step 7 sync reaches it
+
 ## After completion
 
 Output one line:

package/claude/skills/git-issue/references/issue.md

@@ -59,17 +59,15 @@ A bug or task body carries up to four `##` sections, in this order.
 
 One `## Toolkit feedback` wrapper holds every field as a nested `###` heading. A flat `##` field is not recognized.
 
-| Field                            | Holds                                                                                                                        |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `### From project` (optional)    | the reporting project's name or kind.                                                                                        |
-| `### Surface` (required)         | the toolkit surface and its type, and the specific file or name when known.                                                  |
-| `### Observed` (required)        | the observed behavior.                                                                                                       |
-| `### Expected` (optional)        | the expected behavior, or `unclear`.                                                                                         |
-| `### Repro` (optional)           | repro details, or `none`.                                                                                                    |
-| `### Proposed fix` (required)    | a proposed fix, or `open` when the session settled on no direction.                                                          |
-| `### Suggested shape` (optional) | the template, output, or field list the change should take, inside a `<details>` block. Omit the heading when there is none. |
-| `### Why` (optional)             | the reasons for the fix, one bullet each. Omit the heading when there are none.                                              |
-| `### Links` (optional)           | the issues, pull requests, or documents the report cites, one per line. Omit the heading when there are none.                |
+- **`### From project`** (optional): the reporting project's name or kind.
+- **`### Surface`** (required): the toolkit surface and its type, and the specific file or name when known.
+- **`### Observed`** (required): the observed behavior.
+- **`### Expected`** (optional): the expected behavior, or `unclear`.
+- **`### Repro`** (optional): repro details, or `none`.
+- **`### Proposed fix`** (required): a proposed fix, or `open` when the session settled on no direction.
+- **`### Suggested shape`** (optional): the template, output, or field list the change should take, inside a `<details>` block. Omit the heading when there is none.
+- **`### Why`** (optional): the reasons for the fix, one bullet each. Omit the heading when there are none.
+- **`### Links`** (optional): the issues, pull requests, or documents the report cites, one per line. Omit the heading when there are none.
 
 A required field is refused when present but empty. Write the fallback literal for From project, Expected, and Repro rather than leaving one blank.
 

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

@@ -163,6 +163,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/plan.md

@@ -81,6 +81,8 @@ 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        |
 
+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.