@erclx/canon 5.50.0 → 5.51.0

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.50.0",
+  "version": "5.51.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/auto-ship/references/fan-in.md

@@ -48,12 +48,26 @@ Continue Step 2 with the integrator plan's own `**Files to touch:**`, then the r
 
 ### What the pull request carries
 
-Say in the pull request body that each member is one merge commit and name the members in merge order. Once the pull request merges, delete each member's branch on origin, its worktree, and its local branch:
+Say in the pull request body that each member is one merge commit, and name the members on one line in `## Summary`, backticked, in merge order:
 
-```bash
-git push origin --delete <member branch>
-git worktree remove <member worktree>
-git branch -D <member branch>
+```markdown
+Fan-in members: `feat/a`, `feat/b`, `feat/c`
 ```
 
-Read each member's worktree path off `git worktree list --porcelain` by its branch. The integrator holds the member list, so the deletion is its step rather than a sweep's. No member opens a pull request, so `canon worktrees reclaim` never reads a member's branch as merged and reports a leftover worktree as unmerged work on every run.
+The line names branches rather than plan stems, since the branch is what gets deleted. Nothing outside it is read, so a branch named in prose elsewhere in the body is never a candidate.
+
+### After the merge
+
+The post-merge hook runs `canon worktrees retire-members` for each merged pull request number, and the verb deletes each member's branch on origin, its worktree, and its local branch. No session runs a step.
+
+No member opens a pull request, so neither head-branch deletion nor `canon worktrees reclaim` ever reads one as merged. The member line is what reaches them.
+
+- A member half goes only when its tip is an ancestor of the integrator's merged head, so a commit added after the merge keeps that half
+- A worktree a live session holds, or one with uncommitted work, stays with its local branch
+- A line naming the trunk, the integrator's own branch, or a branch with an open pull request deletes nothing
+
+Run the verb by hand for a merge the hook missed, reading the dry run first:
+
+```bash
+canon worktrees retire-members --pull-request <number> --dry-run
+```

package/claude/skills/canon-cli/SKILL.md

@@ -18,13 +18,15 @@ Consult to pick the `canon` verb for a job, and before running a verb that write
 
 ## Project setup
 
-| Job                                          | Verb            |
-| -------------------------------------------- | --------------- |
-| Bootstrap a project with toolkit domains     | `canon init`    |
-| Bring every installed domain current         | `canon sync`    |
-| Reinstall the CLI itself                     | `canon upgrade` |
-| Move a project off a retired name or layout  | `canon migrate` |
-| List the projects the toolkit installed into | `canon targets` |
+| Job                                          | Verb                   |
+| -------------------------------------------- | ---------------------- |
+| Bootstrap a project with toolkit domains     | `canon init`           |
+| Bring every installed domain current         | `canon sync`           |
+| Reinstall the CLI itself                     | `canon upgrade`        |
+| Move a project off a retired name or layout  | `canon migrate`        |
+| Read what a project still needs to migrate   | `canon migrate status` |
+| Read the releases since a target's install   | `canon changelog`      |
+| List the projects the toolkit installed into | `canon targets`        |
 
 ## Domains
 

package/claude/skills/ci-workflow/REQUIREMENT.md

@@ -9,15 +9,15 @@ description: Scope boundary for pipeline structure against job contents, and the
 
 Without this skill, a session chains jobs with `needs` to express reading order rather than a data dependency, so the pipeline costs the sum of its jobs. The same session splits a one-minute gate into parallel jobs, each repaying checkout, install, and toolchain setup, so the gate gets slower while reporting no earlier.
 
-The rest surface as flakes. An action pinned to a moving ref changes under the project, a cache keyed on a static string serves a stale toolchain after a bump, artifacts upload on every run and never expire, a broad default token grants writes nobody needed, and a workflow with no manual trigger reproduces only by pushing a commit.
+The rest surface as flakes. A moving action ref changes under the project, a static cache key serves a stale toolchain, artifacts never expire, a broad default token grants unneeded writes, and a missing manual trigger leaves a run reproducible only by pushing a commit. A Linux-only pin also flags a supported macOS job as a departure.
 
 ## Must
 
 - A job is gated only on a data dependency or a cost that justifies the wait, and checks sharing setup stay in one job until a run log puts the gate past roughly two minutes
 - Every action is pinned to a tag that cannot cross a major version, and every cache is keyed on the version of what it caches
 - Every workflow carries a manual trigger beside its primary one, except one that commits back
-- The token defaults to read-only, with a write scope granted only on the job that needs it
-- Artifact upload is bounded to failures and expires
+- The token defaults to read-only, with a write scope granted only on the job that needs it, and artifact upload is bounded to failures and expires
+- A job runs on Linux unless the project states a platform for a layer that differs by platform
 
 ## Must not
 

package/claude/skills/ci-workflow/SKILL.md

@@ -20,7 +20,17 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 - Include `workflow_dispatch` alongside the primary trigger, except on a commit-back workflow, where a manual run has no branch to commit onto and would pass while doing nothing.
 - Set `permissions: contents: read` at the top level, and grant a write scope only on the job that needs it.
 - Pin all actions to major version tags (`@v4`, never `@latest` or `@main`).
-- Use `runs-on: ubuntu-latest` for all jobs.
+- Use `runs-on: ubuntu-latest` for every job, except one the runner platform rules below move to another platform.
+
+## Runner platform
+
+Linux stays the default. A job leaves it only for a layer whose result differs by platform, and only on a platform the project states.
+
+- Read the stated platforms from the project's requirements record or README. A platform stated in neither keeps every job on Linux.
+- Keep lint, build, and browser jobs on Linux, since their result does not differ by platform. Name the layers that may leave it and never the steps they run.
+- Name another runner by its `-latest` label, such as `macos-latest`, matching the `ubuntu-latest` convention above.
+- Resolve a macOS `$TMPDIR` or `mktemp` path with `realpath` before comparing it with a tool's output, since the `/var` to `/private/var` symlink hides the target. Treat `$RUNNER_TEMP` alike.
+- Expect a macOS job to cost more per minute than a Linux one. GitHub bills the two differently, so read the rate from its billing page rather than quoting a multiplier.
 
 ## Job naming
 
@@ -59,6 +69,14 @@ A workflow that pushes a regenerated file onto the pull request branch takes the
 - Set `HUSKY: 0` on the commit step when the runner lacks a tool a hook shells out to.
 - Fail a template's first step while a path list still holds its placeholder, so an unfinished install fails loudly rather than never firing.
 
+## Steps
+
+- Keep an inline `run:` step to five lines and one guard that exits or writes an output. Move other branching, a loop, trap, or function to a script, which runs on a laptop and under shellcheck.
+- Put the script at `scripts/<name>.sh`, or a `.ts` file for a Bun project, and call it after `actions/checkout`, since the runner holds no copy before that.
+- Pass inputs as arguments or `env`, never spliced into the script text, so a branch name with a quote or `$(...)` in it cannot run.
+- Keep `permissions` and secrets on the workflow step, with the script reading its token from `env`.
+- Open the script with `set -e` at least, since the runner gives a `run:` step `bash -e` and a script called directly gets no flags.
+
 ## Template
 
 Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow template. Adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed. The template already carries the folded shape, and the split beside it applies once the granularity rule above calls for it.
@@ -79,5 +97,12 @@ Before responding, also verify:
 
 - Artifacts upload on `if: failure()` only with `retention-days: 7`.
 - Job names use emoji + title format.
+- Every job runs on `ubuntu-latest`, except one that targets a platform the project states and runs a layer that differs by platform.
 - Deploy, publish, and release jobs carry a placeholder step and a named handoff, never a guessed deploy command.
 - Bun projects use `oven-sh/setup-bun@v2` with `bun install --frozen-lockfile`.
+
+### Steps
+
+Before responding, also verify:
+
+- No `run:` step passes five lines or carries more than one exit-or-output guard, a loop, a trap, or a function. A step that does calls a script, with its inputs as arguments or `env`.

package/claude/skills/ci-workflow/references/workflows.md

@@ -1,5 +1,13 @@
 # CI workflow template
 
+## Contents
+
+- [Base template](#base-template)
+- [Splitting the check job](#splitting-the-check-job)
+- [Targeting another platform](#targeting-another-platform)
+
+## Base template
+
 Copy this base template and adapt it to the project's stack, test commands, and build output. It carries the shape a new pipeline starts in, with the checks that share setup in one job, per the granularity rule in the skill body. `e2e` and anything gated on it stay separate jobs at either size.
 
 ```yaml
@@ -99,3 +107,23 @@ jobs:
           name: build-output
           path: dist/
 ```
+
+## Targeting another platform
+
+Add this job beside the Linux ones only when the project states macOS as a supported platform, per the runner platform rules in the skill body. It runs the unit layer, since that layer differs by platform, and the rest stay on `ubuntu-latest`.
+
+```yaml
+jobs:
+  unit-macos:
+    name: '🧪 Unit Tests (macOS)'
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - name: Resolve the temp folder
+        run: echo "TMPDIR=$(realpath "$RUNNER_TEMP")" >> "$GITHUB_ENV"
+      - run: bun run test
+```

package/claude/skills/design-record/references/folder.md

@@ -66,4 +66,4 @@ Each group holds accepted frames a build matches, light and dark.
 
 ## Lifetime
 
-Keep a reference while its surface exists. Redraw it only on an intentional design change, and remove its folder or files and its index row in the change that removes the surface.
+The design-reference governance rule states how long a reference stays, when it is redrawn, and when it goes with its surface.

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

@@ -154,9 +154,10 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 
 ### Other skills
 
-Four neighbors own the rest.
+Five neighbors own the rest.
 
 - The candidate loop, the arm set, the render, and the pick: `pick-by-eye`
 - The shape of the project's design document and where its values live: `${CLAUDE_SKILL_DIR}/../design-record/references/design.md`
+- The folder holding the accepted designs and how a reference lands in it: `${CLAUDE_SKILL_DIR}/../design-record/references/folder.md`
 - Reading source for roughness: `ux-audit`. Measuring what a running interface costs to paint: `ux-measure`
 - Prose on the surface being designed: the `write-human` skill

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

@@ -59,6 +59,7 @@ A missing tracking ref is not a guard, since an open pull request proves the bra
    - 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.
    - 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.

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

@@ -66,7 +66,7 @@ Past 5 bullets, group Key changes under bold labels, 5 bullets a group at most.
 
 ### Closing lines
 
-The closing lines end `## Summary`, one `Closes #NNN` per issue and no trailing period. A task shipped in slices carries them on its last slice only. `closing-issues.md` states how the list is decided, and `canon labels scan --closes` fails a body that disagrees with it.
+The closing lines end `## Summary`, one `Closes #NNN` per issue and no trailing period, and a sliced task carries them on its last slice. `closing-issues.md` decides the list. A fan-in member line sits above them, per `${CLAUDE_SKILL_DIR}/../auto-ship/references/fan-in.md`.
 
 ### Context section
 

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

@@ -18,4 +18,4 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [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/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
 

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/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,13 +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 |
-| 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 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
 
@@ -32,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

@@ -18,9 +18,10 @@ paths:
 
 - Build UI against `canon/design/`, never against the canvas directly.
 - 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 canvas design in `canon/design/` through the project's design sync, as its own pull request, before any feature builds against it.
+- 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
 
@@ -32,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.50.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"