@erclx/canon 5.51.0 → 5.52.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [5.52.0](https://github.com/erclx/canon/compare/v5.51.0...v5.52.0) (2026-10-21)
+
+
+### Features
+
+* **labels:** fail the scan on pull request body density ([#2585](https://github.com/erclx/canon/issues/2585)) ([121216f](https://github.com/erclx/canon/commit/121216fa258de521ff2b077aa0b897b5f2b9d519))
+* **skills:** add target-update to catch a target up to the toolkit ([#2583](https://github.com/erclx/canon/issues/2583)) ([065b971](https://github.com/erclx/canon/commit/065b9716df290bd87a94b16bed1e54e4ebf29f4e))
+
+
+### Bug Fixes
+
+* **hooks:** anchor the method flag in review-post-scan on whitespace ([#2584](https://github.com/erclx/canon/issues/2584)) ([32c52a2](https://github.com/erclx/canon/commit/32c52a25e4eef6d7d9a88d83aed3d16ab433dcf7))
+
 ## [5.51.0](https://github.com/erclx/canon/compare/v5.50.0...v5.51.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.51.0",
+  "version": "5.52.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -129,7 +129,7 @@ A live agent session is never the human a box waits on.
 
 ### Density
 
-`canon labels scan` reports each section's density under `density`, naming the section, the kind, and the line in the whole body. Its help lists every limit.
+`canon labels scan` fails on a density finding, naming the section, the kind, and the line in the whole body under `density`. Its help lists every limit.
 
 - Every section but Testing holds bullets to 200 characters and 5 in a row, and paragraphs to 350 characters and 2 in a row
 - Any section reports a `subheading`, and Technical context reports a `mixed-form`

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

@@ -124,7 +124,7 @@ canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md --json
 The hook skips `.canon/tmp/`, and the `pull_request` check reads only a pull request's own title and body, so this scan is the only gate on the reply.
 
 - Fix any hit, and stop on a `density` entry too, shortening the line it names
-- Read the record rather than the exit, since density never sets the exit code
+- Read the record rather than the exit, since a post's density never sets the exit code
 
 Then post and keep the `id` the POST answers with, since Step 7 edits this exact comment:
 

package/claude/skills/review-address/references/post-review-findings.md

@@ -13,7 +13,7 @@ Write the body the way Step 6 writes a reply.
 
 - Load `write-human` for voice and word choice, and follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` for punctuation
 - Run the `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` scan before posting, with `canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md --json`
-- Stop on a `density` entry as on any hit, since density never sets the exit code
+- Stop on a `density` entry as on any hit, since a post's density never sets the exit code
 - Open with `## Post-review findings` rather than `## Review response`, since nothing on the thread is being answered
 - Close the body with `🤖 Addressed by Claude Code` on its own line, matching the reply's footer
 

package/claude/skills/review-pr/references/post.md

@@ -114,7 +114,7 @@ Run `canon labels scan --title "<title>" --body "<body>" --head <headRefName>` a
 
 - Name the token quoted from the title or body for a phase label, a board identifier, or a session link
 - Name the broken rule, being `structure`, a casing issue, or `length`, for a title-format hit
-- A heading in `sections.outside` or `sections.missing`, or a character in `bannedCharacters`, is a hit of the same weight, naming the heading or the character
+- A heading in `sections.outside` or `sections.missing`, an entry in `density`, or a character in `bannedCharacters`, is a hit of the same weight, naming the heading, the line and kind, or the character
 - This reads the pull request under review, distinct from the comment this pass posts, which the scan later in this step covers
 
 ### Why the threshold ignores the grade
@@ -175,7 +175,7 @@ The marker is the read-time record those fields are not.
 Before posting, run `canon labels scan --body-file .canon/tmp/pr/review/body-<number>-<short-sha>.md`, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`. Pass `--json` and fix the body and scan again on a finding.
 
 - A `density` entry is a finding here, naming a subject or nested bullet past 200 characters, a run past 5 plain bullets, or a paragraph past its limits, by its line in the whole body
-- Density never sets the exit code, so the hook below lets the post through on it and this step is the one that stops
+- A post's density never sets the exit code, so the hook below lets the post through on it and this step is the one that stops
 
 - A finding phrased against an internal phase label is what the label half of the scan catches here
 - The call carries no `--title`, so the scan reads the text as a review

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

@@ -98,3 +98,5 @@ No overall verdict. The harness row is unchecked rather than passing.
 ```
 
 Keep the harness row `unchecked` on every run until a verb reads it. A domain left out of the table reads as a domain that passed, which is the one shape the row exists to prevent.
+
+Close on one line naming `/canon:target-update` as the skill that applies the catch-up, when a domain reads behind and `target-update` did not invoke this check.

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

@@ -59,7 +59,7 @@ Three states reach this skill that the chain does not serve. Name the destinatio
 
 ### An existing project
 
-Stop and hand off to `target-check`, which reports what the target already carries before anything is repaired. This chain never reads that, so a per-domain install picked here is a guess against configs nobody read.
+Stop and hand off to `target-check`, which reports what the target already carries before anything is repaired. This chain never reads that, so a per-domain install picked here is a guess against configs nobody read. Name `target-update` when the operator wants the catch-up applied.
 
 ### The `.claude/` folder alone
 

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

@@ -0,0 +1,33 @@
+---
+name: target-update
+description: What catching a target up to the toolkit is for, the judgment it holds, and where it hands off to the check and the setup
+---
+
+# Target update requirement
+
+## Gap
+
+Without this skill, a session catching a target up after a release improvises the order. It runs a sync before the migrations that move its paths, writes a record-tree rewrite with no backup, and lets a sync replace a rule the project customized without saying what was lost.
+
+The verbs report every fact, so the gap is the judgment between them. A session reads a refused migration as a step to force, picks rules and seed merges with nobody asked, and ends with no way to tell a current target from one it stopped partway through.
+
+## Must
+
+- Show the changelog summary, the pending migrations, and the drift before the first write to the target, and apply only on the operator's go-ahead
+- Read every fact from a `canon` verb, so a later release changes what the skill reports with no edit to its body
+- Stop and ask on a refused migration, a stranded file, an unattributed folder, and a rule the stack newly ships
+- Keep a customized file and a drifted seed as the project wrote them, naming the toolkit change each one skipped
+- End on a clean `target-check` or on named remainders, with nothing written when nothing is pending
+
+## Must not
+
+- Detect pending migrations or parse the changelog inside the body, since `canon migrate status` and `canon changelog` own both
+- Name a toolkit version in an update commit's subject
+- Run from the toolkit's own checkout, or write into a target from another repository's session
+- Rely on being typed by name. It is reached through its description and `target-check`'s close, and a quarter of releases with no migration and no drift is the signal to fold it in there.
+
+## Out of scope
+
+- First-time scaffold, which `target-setup` owns
+- Reporting drift without repairing it, which `target-check` owns
+- Opening the target's pull request, which `git-ship` owns

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

@@ -0,0 +1,136 @@
+---
+name: target-update
+description: Catches a target project up to the toolkit after a release. Upgrades the binary and plugin, previews the changelog summary, the pending migrations, and the drift, then on the operator's go-ahead migrates, syncs, regenerates the indexes, and ends on a clean `target-check` or named remainders. Use when asked to "update this project to the latest canon", "catch this target up", "apply the new release here", "run the pending migrations", or "bring this project current with the toolkit". Do NOT use on a project without the toolkit, which is `target-setup`, or to report drift without repairing it, which is `target-check`.
+metadata:
+  family: upkeep
+---
+
+# Target update
+
+Takes a target from behind the toolkit to current. Every fact comes from a `canon` verb, and this body holds the order and the judgment calls the verbs leave open. It names no migration, rule, or stack, so a later release reaches it with no edit here.
+
+Read `canon docs migrate` for what each migrate verb moves and refuses, and `canon docs sync` for the drift causes. This body cites them rather than restating them.
+
+## Guards
+
+Stop with the line beside each state.
+
+| State                                       | Stop                                                                                              |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `canon` absent from the path                | `❌ canon is not on PATH, so nothing can be read.`                                                |
+| No `.claude/` directory at the working root | `❌ No .claude/ here, so the toolkit is not installed. Run /canon:target-setup instead.`          |
+| A `claude/skills/` folder, no leading dot   | `❌ This is the toolkit itself rather than a target. Run this from the target's own session.`     |
+| A dirty working tree                        | `❌ Uncommitted changes here. Commit or stash them first, since canon sync refuses a dirty tree.` |
+
+Then hold two rules for every verb this body runs.
+
+- Run it under `CANON_NON_INTERACTIVE=1` from the target root
+- Branch on its record's fields rather than its exit, which a shell function wrapping `canon` can flatten
+
+## Step 1: bring the binary and plugin forward
+
+Read `skew` off `canon sync --check . --json`. When `installed` trails `latest`, run `canon upgrade --json`, then `canon claude plugin-update --json` whatever the skew reads.
+
+Both write to the machine rather than the target, and the preview needs the verbs and the changelog a newer binary carries, so they run before it. The permission dialog gates each. Report a refusal from either and continue on the installed binary, saying the preview reads against it.
+
+## Step 2: read the pending work
+
+Run these in parallel from the target root:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon changelog --json
+CANON_NON_INTERACTIVE=1 canon migrate status --json
+CANON_NON_INTERACTIVE=1 canon sync --check . --json
+```
+
+Then take `<stack>` from the first name in the report's `tooling.chain` and run `canon tooling diff <stack> . --json`. Never run it bare, since the stack prompt resolves to the catalog's first entry under the non-interactive variable. Report tooling unmeasured when `tooling.measured` is false or `chain` names nothing.
+
+### When a read refuses
+
+A refusal is a fact for the preview, never a gap to fill by reading files.
+
+- `changelog` refusing `no-stamp` or `unknown-version`: say the summary is unread and why. Offer `--since <version>` when the operator names one, and never guess a start.
+- `migrate status` carrying no such subcommand: the binary predates it. Stop, since pending migrations cannot be listed without detecting them here, which this skill never does.
+- A missing report key is an older binary rather than an empty answer. Name the installed version beside it.
+
+## Step 3: preview and wait
+
+Write the preview from those records alone, then stop and wait for the operator. Nothing in the target is written before the go-ahead.
+
+```markdown
+Target update: `<path>`, canon `<installed>` to `<running>`.
+
+**What changed since `<since>`:** <three to six bullets from the changelog entries, each naming what this project will notice, never the version>
+
+**Migrations, in run order:** <each pending or refused entry from migrate status, with its verb>
+
+**Drift:** <each non-empty cause from sync --check, with its count and paths>
+
+**Calls for you:** <each judgment call below this run meets, with the default this skill takes>
+
+**Commands, in order:** <the exact commands Steps 4 to 6 will run>
+```
+
+Summarize the changelog for this project, not for the toolkit. Drop an entry that touches nothing the target holds, and lead with anything a migration or a sync will change.
+
+### Nothing pending
+
+When the changelog range is empty, `migrate status` lists nothing pending or refused, and the drift lines hold nothing a step here would take, write nothing. Invoke `canon:target-check` and report the target current with its table.
+
+## Step 4: migrate
+
+Run each pending migration in the order `migrate status` gave, one at a time, as the entry's `verb` with `--write --json` appended. The verb carries the flags its dry run used, so a bare `canon migrate <name>` would apply a plan the preview never showed.
+
+- Run `canon migrate status --json` again after each write, since an applied move can turn a clean entry pending
+- Stop and ask on a `refused` entry, quoting its reason and the remedy it names. Run the remedy only on the operator's word, since a refusal guards a destination the project may own.
+- Stage each write with `git add -A`, since no migrate verb stages and the tree was clean before it, then commit through `canon:git-commit`, one commit per migration
+- Skip the commit when the write changed no tracked file, as `record-tree` does by touching only gitignored records
+
+### Markers
+
+A planned rewrite can reach a line that names an old spelling on purpose, such as a dated note or a quoted history. Propose a marker for each such line in the preview, and add it before the write. `canon docs migrate` names the marker for each spelling.
+
+### The record-tree backup
+
+The record tree is untracked, so a `record-tree` rewrite has no undo. Run `canon records push --json` before its write. When that reports no backup repository, copy `.canon/` to a dated folder outside the project and name the path in the report.
+
+## Step 5: sync
+
+Run `canon sync .`, then `canon tooling sync <stack> . --write` when the tooling diff named files to change. Treat each drift cause the way the preview stated:
+
+| Cause                       | This skill                                                                                       |
+| --------------------------- | ------------------------------------------------------------------------------------------------ |
+| `stale`, `retired`, renamed | Takes the sync's write                                                                           |
+| `customized`                | Keeps the project's file. Shows `git diff -- <rel>` as the toolkit's change, then `git restore`s |
+| `stranded`                  | Names where the file sits and where the toolkit now installs, and moves it only on the word      |
+| `seeds` drifted             | Merges by hand against `canon claude seeds list --json`, keeping the project's edits             |
+| `seeds` stale or missing    | Takes the toolkit's copy whole                                                                   |
+| `newRules`                  | Lists them, and installs only the ones the operator picks, with `canon gov install --add`        |
+
+A `customized` rule is the file `canon sync` replaces, so read it back after the sync rather than trusting the report from Step 2. Report each kept file with the toolkit's change summarized in a line, so the operator can take it later.
+
+### What the toolkit dropped
+
+Read `reverse.unclaimed` by attribution. Delete a `dropped` folder, read an `unattributed` one and ask before deleting it, and leave a `project` one alone.
+
+Read the report's top-level `superseded` and `unmigrated` lists apart from it. Each names a move only the operator can make, being a file a newer seed replaced or a domain still at the root layout, so name each and move nothing.
+
+## Step 6: regenerate and verify
+
+Run `canon indexes regen`, then the project's own check script when it carries one. Invoke `canon:target-check` last.
+
+Stage the sync, the merges, and the regenerated indexes with `git add -A`, since `canon sync` leaves its writes unstaged, then commit through `canon:git-stage`. Name what changed in the project in each subject, such as the rules refreshed or the seeds merged, and never the toolkit version.
+
+## Output
+
+```markdown
+Target update: `<path>`, now on canon `<version>`.
+
+<the target-check table>
+
+**Kept for you:** <each customized or drifted file left as the project wrote it, with the toolkit change it skipped>
+
+**Remaining:** <each refusal, stranded file, or unread domain, with the command or decision it waits on>
+```
+
+Omit a section that holds nothing. End on the commits and the check, and leave the pull request to `canon:git-ship`.

package/docs/agents/migrate.md

@@ -33,7 +33,8 @@ kind: reference
 - `record-tree` reports closed groundwork and intake trails, the scratch folder, and backup history as counts and rewrites none
 - `records` reports skipped record folders as a count on its own line
 - A `record-tree` rewrite has no undo in version control, so read the report before `--write`
-- `status` runs each verb as a dry run and exits 2 while any is pending, with a refusal outranking that. A clean entry can turn pending once an earlier one applies, so run it again after each `--write`.
+
+`status` runs each verb as a dry run and exits 2 while any is pending, with a refusal outranking that. Each entry's `verb` carries the flags its dry run used, so append `--write` to it. A clean entry can turn pending once an earlier one applies, so run it again after each `--write`.
 
 Three markers keep an old spelling on a line. Each also covers the nearest non-blank line, below it for `canon-keep-record-root` and above it for `canon-keep-surface-root`.
 

package/docs/target/migrations.md

@@ -8,6 +8,8 @@ category: Agent surface
 
 Each section is a move a project runs once, when it was scaffolded before the change it names. Run `canon upgrade` first, then `canon migrate status --json` to list the moves a project still needs in the order to run them. The recurring sync that follows is in [target sync](sync.md).
 
+`canon:target-update` is the guided path through both. It runs the moves in that order once you approve its preview.
+
 ## Move the records first, once
 
 Gitignored session records, being the task board, plans, review reports, and scratch, moved from `.claude/` to `.canon/`. Run these from inside the project, and read the `ok` field of the `--json` record rather than the exit code.

package/docs/target/projects.md

@@ -47,7 +47,7 @@ The chain runs these phases:
 - The `verify` phase runs the installed `package.json` scripts and reports pass or fail
 - The `indexes` phase bootstraps `index.md` over the project's documentation folders, confirming candidates with you
 
-An existing project goes to `canon:target-check` first. For the Claude layer alone, run `canon claude init` and then `canon:target-setup indexes`. Run `canon:target-setup verify deep` by hand for the heavier smoke and screenshot pass.
+An existing project goes to `canon:target-check` first, then to `canon:target-update` to apply the catch-up. For the Claude layer alone, run `canon claude init` and then `canon:target-setup indexes`. Run `canon:target-setup verify deep` by hand for the heavier smoke and screenshot pass.
 
 Keep the `## Scripts` table in `canon/context/development/local-loop.md` current as scripts are added. A split entry keeps it in any entry directly under `development/`, grouping a long set into short tables under lead sentences. <!-- audit-ignore-citations: canon/context/development/local-loop.md -->
 

package/docs/target/sync.md

@@ -10,7 +10,7 @@ A target pulls toolkit changes per domain, through one catch-all and several tar
 
 ## Check first
 
-`canon sync --check <path>` reports drift without writing, split by cause. `canon:target-check` groups the same state by domain and repairs nothing.
+`canon sync --check <path>` reports drift without writing, split by cause. `canon:target-check` groups the same state by domain and repairs nothing. `canon:target-update` is the guided path, previewing the drift and then applying it on your go-ahead.
 
 The report opens with the binary version against the newest published one, and a version behind means run `canon upgrade` first.
 

package/docs/workflow/skill-map.md

@@ -103,6 +103,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | Skill                         | When to use                                             |
 | ----------------------------- | ------------------------------------------------------- |
 | `canon:target-check`          | In a target, to compare each domain with the toolkit    |
+| `canon:target-update`         | After a release, to catch a target up to the toolkit    |
 | `canon:document-repair`       | Rewrite a failing docs folder to the limits and gate it |
 | `canon:canon-feedback`        | The toolkit is broken, missing, or off                  |
 | `canon:canon-feedback-triage` | In the toolkit repo, to file feedback issues            |

package/package.json

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

package/src/claude/cases/setup.ts

@@ -66,6 +66,13 @@ export const SETUP_CASES: readonly SkillCase[] = [
       'Report what this project has fallen behind the toolkit on, domain by domain, and fix nothing.',
     expect: 'target-check',
   },
+  // The applying half of the same moment. It previews what the check would
+  // report and then writes, which is the line between the two.
+  {
+    prompt:
+      'A new toolkit release is out, bring this project up to it and run whatever migrations it needs.',
+    expect: 'target-update',
+  },
   {
     prompt:
       "This project needs its own coding rule that the toolkit doesn't ship.",

package/src/commands/labels.ts

@@ -249,8 +249,8 @@ export function register(program: Command): void {
         '## Summary or ## Key changes, fails. A review, a release-please body,',
         'and a scan carrying no title skip this check.',
         '',
-        'It reports the density of that same body per section under `density`,',
-        'without failing on it: a bullet past 200 characters, more than 5 plain',
+        'It fails the density of that same body, reported per section under',
+        '`density`: a bullet past 200 characters, more than 5 plain',
         'bullets or 2 paragraphs in a row, a paragraph past 350 characters, any',
         'H3 or deeper heading, and Technical context mixing bullets with',
         'paragraphs. A bold label alone on a line splits a Key changes run, a',
@@ -279,11 +279,12 @@ export function register(program: Command): void {
         'not read, as GitHub does not read it.',
         '',
         'Exit codes:',
-        '  0  none of the eight found',
+        '  0  none of the nine found',
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  the title or body carries a phase label, a board identifier, a',
         '     session link, a banned character, a heading outside the closed',
-        '     list or a required one missing, a missing or stray closing line',
+        '     list or a required one missing, a density finding in the body, a',
+        '     missing or stray closing line',
         '     under --closes, or a title',
         "     breaking claude/skills/git-pr/references/pr.md's format, casing, or length",
         '',
@@ -718,9 +719,9 @@ async function runScan(opts: ScanOptions): Promise<number> {
     }
   }
 
-  // Reported and never gated yet. New bodies come back clean under the
-  // shape in pr.md first, so an older open pull request fails no edit event.
-  // A post is never gated, since CI reads one only after it is published.
+  // A body's density fails the scan. A post's never does, since the review
+  // post hook denies on exit 2 and scans with no title, so a post-density
+  // fail would block every dense review or reply post.
   const post = !sectionsChecked && isPost(resolved.body)
   const density = sectionsChecked
     ? bodyDensity(resolved.body)
@@ -859,6 +860,7 @@ async function runScan(opts: ScanOptions): Promise<number> {
     titleFormatIssues.length === 0 &&
     sections.outside.length === 0 &&
     sections.missing.length === 0 &&
+    !(sectionsChecked && density.length > 0) &&
     banFindings.length === 0 &&
     closing.missing.length === 0 &&
     closing.stray.length === 0

package/src/migrate/status.ts

@@ -68,7 +68,11 @@ async function readOne(
   run: RunCommand,
   migration: Migration,
 ): Promise<MigrationStatus> {
-  const verb = `canon migrate ${migration.name}`
+  // The flags ride in the verb, since a caller appending --write to a bare
+  // name would apply a different plan than the one this dry run read.
+  const verb = ['canon', 'migrate', migration.name, ...migration.flags].join(
+    ' ',
+  )
   const result = await run([
     'migrate',
     migration.name,

package/tooling/claude/seeds/.claude/hooks/review-post-scan.sh

@@ -121,7 +121,7 @@ check() {
 
   # gh sends POST when a field flag is present and no method is named, and the
   # explicit method wins when one is. A call naming neither is a read.
-  if [[ $call =~ (-X|--method)[[:space:]=]*([A-Za-z]+) ]]; then
+  if [[ $call =~ [[:space:]](-X|--method)[[:space:]=]*([A-Za-z]+) ]]; then
     method=$(printf '%s' "${BASH_REMATCH[2]}" | tr '[:lower:]' '[:upper:]')
   elif [[ $call =~ [[:space:]](-f|-F|--field|--raw-field|--input)([[:space:]=]|$) ]]; then
     method=POST