@erclx/canon 5.49.0 → 5.51.0

package/claude/skills/pick-by-eye/SKILL.md

@@ -124,15 +124,16 @@ Read `canon canvas selection --json` when the answer points at the canvas, such
 
 1. Apply the winning arm to the real surface, in one change.
 2. Close out any document stating the decision as open, in the same change, naming the winner and the arms that stayed defensible. Skip this where nothing stated the decision.
-3. Capture the picked round's frames with `canon canvas capture <page> --out <archive-dir> --json`. Each lands as `arm-<id>.png`, keeping the losing arms as a revert record.
-4. Resolve `<archive-dir>` as `.canon/picks/<slug>/` against the main worktree root, since shared session scratch resolves there rather than in a linked worktree.
-5. Delete every page folder on the run's list from under the `content` folder `canon canvas list --json` reports. Touch no page the run did not add, whatever its name.
-6. Stop the canvas server if this run started it, and leave one the operator started running.
-7. Leave the renders in a live track's `evidence/<slug>/renders/`, since `plan-groundwork` treats evidence as durable.
-8. Report each page whose delete is refused, naming the path for the operator to remove. The pick is applied either way.
-9. Report every surface that changed, each on its own line, name the winning arm by its id and its cost, and report the archive path.
+3. Hand the winning frame to `canon:design-record` by its page and frame, which lands it in the project's design record. Report it rather than proceeding silently when that skill does not resolve.
+4. Capture the picked round's frames with `canon canvas capture <page> --out <archive-dir> --json`. Each lands as `arm-<id>.png`, keeping the losing arms as a revert record.
+5. Resolve `<archive-dir>` as `.canon/picks/<slug>/` against the main worktree root, since shared session scratch resolves there rather than in a linked worktree.
+6. Delete every page folder on the run's list from under the `content` folder `canon canvas list --json` reports. Touch no page the run did not add, whatever its name.
+7. Stop the canvas server if this run started it, and leave one the operator started running.
+8. Leave the renders in a live track's `evidence/<slug>/renders/`, since `plan-groundwork` treats evidence as durable.
+9. Report each page whose delete is refused, naming the path for the operator to remove. The pick is applied either way.
+10. Report every surface that changed, each on its own line, name the winning arm by its id and its cost, and report the archive path.
 
-The picked round is the final one unless Step 4 resolved a revert. Archiving any other page lets item 5 delete the winning arm with nothing kept, and a variant left on the canvas is a second design nobody maintains.
+The picked round is the final one unless Step 4 resolved a revert. Archiving any other page lets item 6 delete the winning arm with nothing kept, and a variant left on the canvas is a second design nobody maintains.
 
 ## Reading a measurement
 
@@ -149,6 +150,7 @@ A capture proves appearance and a measurement proves a relationship, so reach fo
 Cite these rather than restating them. A step reimplemented here rots against the skill that owns it.
 
 - `plan-feature` plans the work once the pick is made, and declares the pull request boundary that plan carries
+- `design-record` lands the winning frame in the reference folder and its values in the design document, and runs before item 6 deletes the page its sync reads
 - `design-taste` carries the layer catalog, the ordering, grey-boxing, and the defaults an arm should reach past
 - `write-human` carries the voice for any copy an arm puts in front of a reader
 

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

@@ -152,9 +152,21 @@ Then output in chat:
 1. <question>
    - Suggested: <pick>, <reason or tradeoff>
 
-Next: /session-worktree
+Next: <line from the table below>
 ```
 
+Pick the `Next:` line from the roster check `${CLAUDE_SKILL_DIR}/../task-board/SKILL.md` states under `### Check for a live orchestrator`, read there rather than restated here.
+
+| Roster read                                                                | `Next:` line                                                                                         |
+| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Found**                                                                  | `<name> places and dispatches <task>`, naming the orchestrator row the check matched                 |
+| **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`                                                                                  |
+
+- 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.
+
 Show only the path line and the `Next:` line when there are no questions. The `.canon/plans/` directory is gitignored, so do not stage or commit the file.
 
 Do not proceed to implementation until the user explicitly says to continue.

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

@@ -90,4 +90,4 @@ The integrator merges each member branch with `git merge --no-ff` in the order i
 
 - Say in the pull request body that each member is one merge commit, so a reviewer reads `git log --first-parent` one member at a time
 - Fix a semantic conflict a merge surfaces on the integrator's branch, since a member has no pull request to fix it on
-- Delete each member branch on origin with `git push origin --delete <branch>` once the pull request merges
+- Name the members on the body's `Fan-in members:` line, which the post-merge hook reads to delete each member's branches and worktree, per `${CLAUDE_SKILL_DIR}/../auto-ship/references/fan-in.md`

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

@@ -1,6 +1,6 @@
 ---
 name: session-worktree
-description: Enters a Claude Code worktree at `.claude/worktrees/<name>/` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or at the plan-to-execute boundary after `/plan-feature`. Also use when an `Edit` or `Write` to a main-root file such as a plan, a task, or a review report was refused for session isolation. Do NOT use to list, clean up, or rotate worktrees (use `git-worktree`).
+description: Enters a Claude Code worktree at `.claude/worktrees/<name>/` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or before building an approved plan in this session. Also use when an `Edit` or `Write` to a main-root file such as a plan, a task, or a review report was refused for session isolation. Do NOT use to list, clean up, or rotate worktrees (use `git-worktree`).
 metadata:
   family: build
 ---

package/claude/skills/target-check/references/domains.md

@@ -21,7 +21,7 @@ This domain is first because it conditions the other five. A target a release be
 
 ## 2. The `canon/` folder
 
-Read four fields off the same report, then two verbs:
+Read four fields off the same report, then three verbs:
 
 - `unmigrated`: a domain still at the root layout with nothing under `.claude/`. The most urgent finding, because such a domain reports no drift of its own while being entirely behind.
 - `superseded`: a file a newer seed folder replaced. No command moves it, since the content is the project's own.
@@ -34,19 +34,21 @@ The fourth field and the two verbs cover what the toolkit stopped shipping and w
 - `reverse`: `unclaimed` names folders at roots the toolkit stopped shipping, each with an `attribution` of `dropped`, `unattributed`, or `project`.
 - `canon context audit --json`: required sections, entry length, citations, and index drift across the context folder.
 - `canon records validate <kind> --json`, once per record folder the target carries.
+- `canon migrate status --json`: every migration in run order, each with a `state` of `pending`, `clean`, or `refused`. It exits 2 while any is pending.
 
 ### Verdicts
 
-Each of the three states takes all six reads together.
+Each of the three states takes all seven reads together.
 
-- Current: `unmigrated`, `superseded`, and `unmovedSurfaces` all empty, `reverse.unclaimed` carrying nothing outside `project` attribution, and both verbs finding nothing.
-- Behind: any of those carrying an entry. Name the entry and its attribution, and for `unmovedSurfaces` each `rel` with its `movesTo`.
-- Unread: `historyUnavailable` set on `reverse`, a `reverse` or `unmovedSurfaces` key the report does not carry, or either verb refusing
+- Current: `unmigrated`, `superseded`, and `unmovedSurfaces` all empty, `reverse.unclaimed` carrying nothing outside `project` attribution, and all three verbs finding nothing.
+- Behind: any of those carrying an entry, or a `pending` migration. Name the entry and its attribution, and for `unmovedSurfaces` each `rel` with its `movesTo`.
+- Unread: `historyUnavailable` set on `reverse`, a `reverse` or `unmovedSurfaces` key the report does not carry, or any verb refusing, a `refused` migration included
 - A missing key is a binary predating the field rather than a target with nothing to report, so name the installed version beside it
 
 Routes by finding.
 
-- `unmovedSurfaces` routes to `canon migrate surface-roots`, which only reports its plan until `--write` is passed. Name the verb with each entry's `rel` and `movesTo`, and run neither form.
+- A `pending` migration routes to its entry's `verb`, which only reports its plan until `--write` is passed. Name each in the order the status gives, and run neither form.
+- `unmovedSurfaces` is the `surface-roots` migration. Name each entry's `rel` and `movesTo` beside its verb.
 - `unmigrated` routes to a relocation the user runs, since no command moves it.
 - `superseded` routes to a split the user makes, since no command moves the content and no skill proposes it.
 - An `unclaimed` folder carrying `project` attribution routes nowhere, since history proved the project owns it.

package/docs/agents/index.md

@@ -12,10 +12,10 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Context audit](context-audit.md): Running the context audit, its folder scope, the exit codes, every check with the folders it reaches and whether it gates, the seed gate, and the citation exclusions
 - [Indexes](indexes.md): How canon indexes regen and canon indexes list resolve paths, what they stage, and the record and exit codes each emits
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, the drift report and its seven side sections, the rule detection record, and version skew states
-- [Markdown audit](markdown-audit.md): Running the markdown audit over any path, each finding it reports with whether it gates, the six density limits, the advisory measures, the exit codes, and where the audit runs
+- [Markdown audit](markdown-audit.md): Running the markdown audit over any path, each finding with whether it gates, the density and table limits, the advisory measures, the exit codes, and where the audit runs
 - [Migrate](migrate.md): What each canon migrate verb moves, the markers that keep an old spelling, and what each one refuses
 - [Output shape](output-shape.md): The framed output shape every command renders into, the JSON and color modes, the exit discipline, the runtime catalogs, and a headless invocation per domain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and how canon docs resolves a topic name
 - [Records](records.md): Backing the record folders to a private remote, restoring them on a new machine, reading folder size, and pruning stale scratch
 - [Sessions transfer](sessions-transfer.md): Moving a session to another machine with export and import, the manifest fields, the refusal reasons, and what a resume on the target depends on
-- [Targets](targets.md): The projects this toolkit installed into, where each answer comes from, and the cross-target pull request read
+- [Targets](targets.md): The projects this toolkit installed into, where each answer comes from, the cross-target pull request read, and the releases since a target's install

package/docs/agents/markdown-audit.md

@@ -1,6 +1,6 @@
 ---
 title: Markdown audit
-description: Running the markdown audit over any path, each finding it reports with whether it gates, the six density limits, the advisory measures, the exit codes, and where the audit runs
+description: Running the markdown audit over any path, each finding with whether it gates, the density and table limits, the advisory measures, the exit codes, and where the audit runs
 kind: reference
 ---
 
@@ -28,11 +28,14 @@ The ban set and checkpoints ship in `src/markdown/bans.ts` and `src/markdown/str
 | Links           | A relative link resolving to nothing on disk                                         | Always            |
 | Density         | The six limits below, under `density`                                                | On a gated prefix |
 | Reference shape | A `kind: reference` page breaking its shape, under `referenceShape`                  | On a gated prefix |
+| Tables          | The four table limits below, under `tables`                                          | Never             |
 | Colons          | A colon followed by more text in a prose line, under `colons`                        | Never             |
 | Heading case    | A capital after the first word of a heading or `title`, under `headingCase`          | Never             |
 
 A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, and `See also` as H2s, each at most once and in that order. It takes no H3 and no table headed `Flag` or `Option`. An unmarked page is never measured.
 
+Tables take the four limits in the `markdown-craft` skill's `tables.md`, on the density paths but never `CLAUDE.md`. A cell past 120 visible characters reports as `table-cell`, more than 8 body rows as `table-rows`, a list after a table as `table-then-list`, and a code span with a run past 30 characters as `table-token`. None sets the exit code.
+
 | Density limit       | Finding                                                    |
 | ------------------- | ---------------------------------------------------------- |
 | Paragraph length    | A prose paragraph past 350 characters                      |
@@ -45,7 +48,7 @@ A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, an
 - A paragraph under a list item counts toward that bullet, never as a paragraph
 - A table, fence, list, heading, or bold section marker ends a run of paragraphs
 - A run whose every item opens with a bold label or a link is exempt, and numbered items never count
-- Only context entries, docs, skill bodies, references, and requirements, tooling seeds and stack references, the wiki, `README.md`, and `CONTRIBUTING.md` take a finding
+- Only context entries, docs, skills, tooling seeds and references, the wiki, `README.md`, and `CONTRIBUTING.md` take a finding, plus the Key paths of `CLAUDE.md` on the run and H3 limits
 - A requirement gates only once the gated list below names its own file, never through its skill's prefix and never on a bullet run alone
 
 | Root              | A density or reference shape finding gates                                                                 |

package/docs/agents/migrate.md

@@ -10,6 +10,7 @@ kind: reference
 
 | Verb               | Moves                                                                                                                                       |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status`           | Nothing. It lists every migration the project still needs, in run order.                                                                    |
 | `rename`           | The retired `aitk` name. `--scope target` rewrites toolkit-owned folders only.                                                              |
 | `skill-names`      | Plugin skills off their `claude-` and `draft-` prefixes and other retired names, with every citation                                        |
 | `records`          | Session records from `.claude/` to `.canon/`, with every tracked citation                                                                   |
@@ -32,6 +33,7 @@ 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`.
 
 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/agents/targets.md

@@ -1,6 +1,6 @@
 ---
 title: Targets
-description: The projects this toolkit installed into, where each answer comes from, and the cross-target pull request read
+description: The projects this toolkit installed into, where each answer comes from, the cross-target pull request read, and the releases since a target's install
 kind: reference
 ---
 
@@ -12,6 +12,13 @@ kind: reference
 - Each stamping sync records its target in `$XDG_STATE_HOME/canon/targets.json`, and no row is removed
 - A sweep finds installs the index never held
 
+`canon changelog` prints the releases a target has not seen, from the `CHANGELOG.md` the installed package ships. It reads no registry and needs no `gh`.
+
+- The start defaults to the oldest `version` across the target's stamp domains. `--since <version>` overrides it, and `--root <path>` names the target.
+- `--json` carries `since`, `running`, and `entries`, each with its `version` and raw `markdown`, oldest first
+- A start equal to the running version is the one empty range, since that target is current
+- A refusal names its `reason` instead of printing an empty range, being `no-stamp`, `no-changelog`, or `unknown-version`. The last covers a pre-release and a start newer than the binary.
+
 ## Output
 
 - `bound` on a sweep names the roots walked, the depth, and what it skipped. Read it before trusting a count.

package/docs/target/migrations.md

@@ -6,7 +6,7 @@ category: Agent surface
 
 # Target migrations
 
-Each section is a move a project runs once, when it was scaffolded before the change it names. Run `canon upgrade` first. The recurring sync that follows is in [target sync](sync.md).
+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).
 
 ## Move the records first, once
 
@@ -180,3 +180,10 @@ A project holding `.claude/rules/canon/ui/a11y.md` adds the new rule alone:
 ```bash
 canon gov install --add keyboard --yes .
 ```
+
+## Group a long paths section in `CLAUDE.md`, once
+
+The `## Key paths` section of `CLAUDE.md` now keeps to 5 bullets in a row, and every other section stays exempt. `canon claude sync` never rewrites a `CLAUDE.md` you hold, so it warns with the line of each longer run.
+
+- Regroup the section by hand under H3s, each opening on a one-sentence lead.
+- List `CLAUDE.md` in `canon/config/markdown.toml` to gate it from then on.

package/docs/target/projects.md

@@ -49,7 +49,7 @@ The chain runs these phases:
 
 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.
 
-Keep the `## Scripts` table in `canon/context/development/local-loop.md` current as scripts are added. A split entry keeps it in `overview.md`. <!-- audit-ignore-citations: canon/context/development/local-loop.md -->
+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 -->
 
 ### From scaffold to first feature
 

package/docs/workflow/parallel-features.md

@@ -60,4 +60,4 @@ Merge order matters only when two branches touch the same file. Expect to rebase
 
 `canon:task-board` creates a task file, and `canon:task-complete` marks outcomes. The `post-merge` hook archives the task a merged pull request closed, with its plan, and a `post-rewrite` hook does the same for a rebase pull. Both archive a closed task whose merge carried a PR number, and a slice merged before then moves only its own plan.
 
-`CANON_SKIP_RECLAIM`, `CANON_SKIP_UPGRADE`, and `CANON_SKIP_PLUGIN_UPDATE` turn off the three hook steps that act on the machine.
+The hook also deletes the member branches and worktrees a merged fan-in integrator names, and `canon worktrees retire-members --pull-request <n>` does it for a merge the hook missed. `CANON_SKIP_RECLAIM` turns off that step and the reclaim, and `CANON_SKIP_UPGRADE` and `CANON_SKIP_PLUGIN_UPDATE` turn off the other two.

package/docs/workflow/skill-map.md

@@ -35,7 +35,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 
 | Skill                         | When to use                                        |
 | ----------------------------- | -------------------------------------------------- |
-| `canon:session-worktree`      | At plan-to-execute, for an isolated tree           |
+| `canon:session-worktree`      | Before building a plan in this session             |
 | `canon:auto-ship`             | After plan approval, to chain implement through PR |
 | `canon:test-first`            | Before implementing a planned change               |
 | `canon:test-craft`            | Writing or changing a test                         |
@@ -64,6 +64,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | --------------------- | --------------------------------------------- |
 | `canon:git-ship`      | To run the post-feature chain through open PR |
 | `canon:context-fold`  | The diff left a context entry untrue          |
+| `canon:design-record` | A picked design needs landing in the record   |
 | `canon:task-complete` | After the fold, to mark shipped outcomes      |
 | `canon:docs-sync`     | A change left `README.md` or `docs/` stale    |
 | `canon:git-stage`     | Staged changes span several concerns          |

package/docs/workflow/visual-design-workflow.md

@@ -20,7 +20,8 @@ These skills cover the tier:
 
 - `canon:ui-checklist`, `canon:ux-audit`, and `canon:ux-measure` review and measure a UI
 - `canon:pick-by-eye` drafts candidates as frames on the canvas and takes your pick
-- `canon:canvas-board` works a direction out as HTML frames you edit in the browser. Only the pick moves into `canon/DESIGN.md`.
+- `canon:canvas-board` works a direction out as HTML frames you edit in the browser, and hands the pick on
+- `canon:design-record` lands a pick in `canon/design/` and carries its values into `canon/DESIGN.md`
 - `canon:design-identity` drafts a logo mark and social card
 
 Pick tier 0 when the UI is not the core product, decisions fit in sentences, and stakeholders review code.

package/governance/detect.toml

@@ -207,4 +207,4 @@ files = [".canon/canvas"]
 
 ["design-reference"]
 deps = []
-files = ["canon/design"]
+files = ["canon/design/*/"]

package/governance/ledger/tooling/ci-workflow.md

@@ -22,6 +22,12 @@ The field is continuous integration on GitHub Actions, and the authority is GitH
 | Skip a fork's pull request             | [Workflow syntax, permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax): "if the workflow was triggered by a pull request event other than `pull_request_target` from a forked repository, and the Send write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read only" | 2026-10-18 |
 | Never commit back to the trunk         | House choice: a workflow pushing onto the trunk lands a change no pull request carried and no reviewer read                                                                                                                                                                                                                                                                                         | 2026-10-18 |
 
+## Steps
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Long steps call a script, 5 max | House choice, from [issue 2531](https://github.com/erclx/canon/issues/2531): a 33-line publish check copied out of a workflow carried a program no laptop or shellcheck could run. [Workflow syntax, run](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax) documents `run` as a command run in the shell, with no limit on its size. One guard stays inline, since a placeholder or secrets guard of three lines gains nothing from a script | 2026-10-21 |
+
 ## Token scopes
 
 | Bullet                      | Source                                                                                                                                                                                                                                                                                                                                       | Read       |

package/governance/ledger/ui/design-reference.md

@@ -9,12 +9,14 @@ The rule states canon's own design handoff, generalized from Frameboard's projec
 
 ## Where the design lives
 
-| Bullet                         | Source                                                                                                                                                              | Read       |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Build against the tracked copy | House choice: a canvas changes under the build with no history, so a reviewer cannot tell which version a surface was built against                                 | 2026-10-18 |
-| Land a design first            | House choice: a design landing inside a feature pull request is reviewed as code, and a second feature building against it meanwhile reads a design nobody accepted | 2026-10-18 |
-| No hand edits                  | House choice: a reference edited by hand drifts from its canvas source, and the next sync overwrites the edit or reports it as a change nobody made                 | 2026-10-18 |
-| Index row before the sync      | House choice: the sync writes only the surfaces the index names, so a missing row drops the new surface's reference, and a stale row keeps a removed surface's      | 2026-10-18 |
+| Bullet                         | Source                                                                                                                                                            | Read       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Build against the tracked copy | House choice: a canvas changes under the build with no history, so a reviewer cannot tell which version a surface was built against                               | 2026-10-18 |
+| Load the keeper skill          | House choice: the rule governs an edit and carries no procedure, so a session without the skill copies frames in by hand or skips the index row                   | 2026-10-21 |
+| Land a design with its build   | House choice: a design merged as its own pull request waits on a review that reads a picture with no build beside it, and the pick drifts before anything uses it | 2026-10-21 |
+| No hand edits                  | House choice: a reference edited by hand drifts from its canvas source, and the next sync overwrites the edit or reports it as a change nobody made               | 2026-10-18 |
+| Index row before the sync      | House choice: the sync writes only the surfaces the index names, so a missing row drops the new surface's reference                                               | 2026-10-21 |
+| Reference lifetime             | House choice: a reference kept past its surface misleads the next build, and one redrawn without a design change hides a departure the review should see          | 2026-10-21 |
 
 ## Building against a reference
 
@@ -31,12 +33,6 @@ The rule states canon's own design handoff, generalized from Frameboard's projec
 | Name each departure                | House choice: an unnamed departure reads as an accident, and the next build against the same reference repeats or reverts it | 2026-10-18 |
 | Unexplained departure is a finding | House choice: without the finding, an unexplained departure merges as the new design with no one having chosen it            | 2026-10-18 |
 
-## Naming
-
-| Bullet                  | Source                                                                                                                                 | Read       |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| One folder per app part | House choice: a fixed folder and theme suffix let the sync and a reviewer find a surface's pair of references without reading an index | 2026-10-18 |
-
 ## Declined
 
 The rewrite kept every bullet. Each was already under 200 characters and states a step a reviewer can check against the pull request.

package/governance/rules/tooling/ci-workflow.md

@@ -17,6 +17,10 @@ paths:
 - Skip a pull request from a fork with `github.event.pull_request.head.repo.full_name == github.repository`, since the default token cannot push to a fork's branch.
 - Never commit back to the trunk. A commit with no pull request and no reviewer needs an operator's decision, not a workflow's.
 
+## Steps
+
+- Keep an inline `run:` step to five lines at most with one guard allowed and no other branching, loop, trap, or function, and call a script for anything longer, per the `canon:ci-workflow` skill.
+
 ## Token scopes
 
 - In a workflow with more than one job, add a write scope to the job that needs it, never to the workflow-level block, so every other job keeps the read-only token.

package/governance/rules/ui/design-reference.md

@@ -17,9 +17,11 @@ paths:
 ## Where the design lives
 
 - Build UI against `canon/design/`, never against the canvas directly.
-- Land a picked or changed canvas design in `canon/design/` through the project's design sync, as its own pull request, before any feature builds against it.
+- Load the `canon:design-record` skill before adding, redrawing, or removing a reference under `canon/design/`, and report it rather than proceeding silently when it does not resolve.
+- Land a picked or changed design in `canon/design/` through the project's design sync, in the first commit of the branch that builds against it or with its design round, never as its own pull request.
 - Never copy, edit, or delete a reference file under `canon/design/` by hand.
-- Add a new surface's row to the index in `canon/design/` before running the sync, and remove it only in the change that removes the surface.
+- Add a new surface's row to the index in `canon/design/` before running the sync.
+- Keep a reference while its surface exists, redraw it only on an intentional design change, and remove it with its index row in the change that removes the surface.
 
 ## Building against a reference
 
@@ -31,7 +33,3 @@ paths:
 - Put each changed surface's reference image beside its built capture, light and dark, in the pull request description.
 - Name each place the build departs from its reference, with its reason, in the pull request description.
 - Report an unexplained departure from a reference as a review finding.
-
-## Naming
-
-- Give each app part one plain kebab-case folder under `canon/design/`, and name each file `<name>-dark` or `<name>-light`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.49.0",
+  "version": "5.51.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -14,6 +14,7 @@
     "tooling",
     "claude",
     "docs",
+    "CHANGELOG.md",
     "tsconfig.json",
     "assets/brand/mark.svg",
     "!scripts/eval",

package/scripts/ci/check-browsers.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Fails when a Playwright browser named in the arguments is missing from the
+# cache, called after the cache restore in pr-visual-checks.yml. A cache hit
+# skips the install step, so a restore that came back empty would otherwise
+# surface later as a launch error.
+set -e
+
+for browser in "$@"; do
+  if ! compgen -G "$HOME/.cache/ms-playwright/${browser}-*" >/dev/null; then
+    echo "Missing Playwright browser: ${browser}" >&2
+    exit 1
+  fi
+done

package/scripts/ci/delete-previews.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Deletes the Cloudflare Pages preview deployments minted for one branch, called
+# by the cleanup-preview job in deploy-site.yml with the Pages project name and
+# the branch. CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID come from the step
+# env.
+#
+# Deployments are listed through the REST API rather than wrangler, whose
+# listing carries no branch filter. `force=true` is what lets a deployment
+# still holding its branch alias be deleted.
+#
+# tooling/cloudflare/configs/scripts/delete-previews.sh is the seeded copy,
+# which adds a skip for an absent secret. Keep the two otherwise the same.
+set -e
+
+PROJECT_NAME=$1
+BRANCH=$2
+
+api="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/pages/projects/$PROJECT_NAME/deployments"
+auth="Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+page=1
+ids=""
+while :; do
+  listing=$(curl -fsS -H "$auth" "$api?env=preview&per_page=25&page=$page")
+  [ "$(echo "$listing" | jq '.result | length')" -eq 0 ] && break
+  ids="$ids $(echo "$listing" | jq -r --arg branch "$BRANCH" '.result[] | select(.deployment_trigger.metadata.branch == $branch) | .id')"
+  page=$((page + 1))
+done
+deleted=0
+for id in $ids; do
+  curl -fsS -X DELETE -H "$auth" "$api/$id?force=true" >/dev/null
+  echo "Deleted $id"
+  deleted=$((deleted + 1))
+done
+echo "Deleted $deleted preview deployments for $BRANCH."

package/scripts/ci/publish-check.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Reports whether the newest GitHub release reached npm, called by the
+# publish-check job in release-please.yml. The step passes GH_TOKEN and GH_REPO
+# for gh. A release inside the publish job's 15-minute window passes, since its
+# publish may still be running.
+set -e
+
+package=@erclx/canon
+
+if ! release=$(gh release view --json tagName,publishedAt --jq '"\(.tagName) \(.publishedAt)"') || [ -z "$release" ]; then
+  echo "::error::Could not read the newest GitHub release, so whether it reached npm is unknown."
+  exit 1
+fi
+read -r tag published <<<"$release"
+age=$(($(date +%s) - $(date -d "$published" +%s)))
+if [ "$age" -lt 900 ]; then
+  echo "$tag is ${age}s old, inside the 15-minute window its publish job runs in."
+  exit 0
+fi
+# A missing version is an E404, so read the whole list to tell it from an outage
+if ! versions=$(npm view "$package" versions --json); then
+  echo "::error::Could not read $package from npm, so whether $tag reached it is unknown."
+  exit 1
+fi
+if ! jq -e --arg v "${tag#v}" '[.] | flatten | index($v) != null' <<<"$versions" >/dev/null; then
+  echo "::error::$tag has a GitHub release but npm does not serve it. Publish it with: gh workflow run release-please.yml -f tag=$tag"
+  exit 1
+fi
+echo "$tag is on npm."

package/scripts/ci/refresh-frames-pr.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Commits the regenerated capture frames onto the refresh branch and opens or
+# updates its pull request, called by refresh-capture-frames.yml after the
+# capture steps. The step holds GH_TOKEN and HUSKY, since the token scope is
+# read off the workflow.
+#
+# Hooks stay off, since pre-push runs a check whose format step needs shfmt,
+# which the runner lacks. verify.yml checks the pull request.
+#
+# The frames commit where they rendered, then only the files that commit wrote
+# or dropped carry onto main fetched now, so a merge landing mid-run neither
+# leaves the branch on an older base nor loses a frame it moved. The pull
+# request resolves by number, since every merged refresh leaves a closed one on
+# the same head.
+set -e
+
+branch=chore/refresh-capture-frames
+title="chore(web): refresh capture frames"
+
+if [ -z "$(git status --porcelain assets/captures assets/frames assets/evidence)" ]; then
+  echo "Frames are current, nothing to refresh."
+  exit 0
+fi
+git config user.name "github-actions[bot]"
+git config user.email "41898282+github-actions[bot]@users.noreply.github.com" # canon-allow-reference: the bot account id, not a commit
+git add assets/captures assets/frames assets/evidence
+git commit -m "$title"
+rendered=$(git rev-parse HEAD)
+written=$(git diff --name-only --no-renames --diff-filter=d HEAD~1 HEAD)
+dropped=$(git diff --name-only --no-renames --diff-filter=D HEAD~1 HEAD)
+git fetch --depth=1 origin +refs/heads/main:refs/remotes/origin/main
+git checkout -B "$branch" origin/main
+if [ -n "$written" ]; then
+  printf '%s\n' "$written" | xargs -d '\n' git checkout "$rendered" --
+fi
+if [ -n "$dropped" ]; then
+  printf '%s\n' "$dropped" | xargs -d '\n' git rm -q --ignore-unmatch --
+fi
+if git diff --cached --quiet -- assets/captures assets/frames assets/evidence; then
+  echo "Main already carries these frames, nothing to refresh."
+  exit 0
+fi
+git commit -m "$title"
+git push --force origin "$branch"
+number=$(gh pr list --head "$branch" --state open --json number --jq '.[0].number')
+if [ -z "$number" ]; then
+  gh pr create \
+    --base main \
+    --head "$branch" \
+    --title "$title" \
+    --body "## Summary
+
+- Refreshes the capture frames from main so their counts and tokens stay current.
+
+## Key changes
+
+- Regenerates the count and token bearing frames, their images, and their stamps from main.
+- Recaptures the home page baseline under assets/evidence/home.
+- Merges itself by squash once its required check passes."
+  number=$(gh pr list --head "$branch" --state open --json number --jq '.[0].number')
+fi
+# Every run, so a force-push from a later run leaves it queued either way
+gh pr merge "$number" --auto --squash

package/scripts/ci/report-baseline.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Writes the step summary saying whether the captured landing page frames match
+# the committed baseline, called by the capture job in pr-visual-checks.yml. A
+# moved capture is expected when a catalog the page counts has moved, so it
+# reports and never fails.
+set -e
+
+if git diff --quiet -- assets/evidence/home; then
+  echo "The captured frames match the committed baseline." >>"$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+{
+  echo "### The landing page capture moved"
+  echo
+  echo "These frames differ from the committed baseline. That is expected"
+  echo "when a catalog this page counts has moved, and it is not a failure."
+  echo
+  echo '```'
+  git diff --stat -- assets/evidence/home
+  echo '```'
+  echo
+  echo "Download the \`landing-page-capture\` artifact to view them."
+} >>"$GITHUB_STEP_SUMMARY"

package/scripts/ci/stack-issues.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Opens, updates, or closes one issue per stack from the outcomes stack-verify.yml
+# recorded under results/<stack>, called by its report job. Takes the stacks as
+# arguments and reads GH_TOKEN, GH_REPO, and RUN_URL from the step env.
+set -euo pipefail
+
+for stack in "$@"; do
+  title="stack-verify: $stack"
+  # A job that died before recording counts as a failure
+  outcome=failure
+  [ -f "results/$stack" ] && outcome=$(cat "results/$stack")
+  number=$(gh issue list --state open --search "\"$title\" in:title" --json number,title \
+    --jq "[.[] | select(.title == \"$title\")][0].number // empty")
+  if [ "$outcome" = success ]; then
+    if [ -n "$number" ]; then
+      gh issue close "$number" --comment "Passing again in $RUN_URL"
+    fi
+  elif [ -n "$number" ]; then
+    gh issue comment "$number" --body "Still failing in $RUN_URL"
+  else
+    gh issue create --title "$title" \
+      --body "\`canon tooling verify $stack\` failed in $RUN_URL. The issue closes itself when a later run passes."
+  fi
+done

package/scripts/ci/verify-npm-token.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Checks that the npm publish credential is set and authenticates, so a release
+# is never cut it cannot publish. release-please.yml passes NPM_TOKEN from the
+# step env, which keeps the secret named in the workflow.
+set -e
+
+if [ -z "$NPM_TOKEN" ]; then
+  echo "::error::NPM_TOKEN is not set. Add the secret before a release can be cut."
+  exit 1
+fi
+if ! curl -sf -H "Authorization: Bearer $NPM_TOKEN" https://registry.npmjs.org/-/whoami >/dev/null; then
+  echo "::error::NPM_TOKEN did not authenticate. It is likely expired or revoked."
+  exit 1
+fi