@erclx/canon 5.48.0 → 5.50.0

package/claude/skills/role-orchestrator/SKILL.md

@@ -38,10 +38,11 @@ No surface carries cross-version sequencing, so report none, since reasoning spa
 
 ## Runbooks on request
 
-A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook.
+The human asks for each side of a compaction, and this skill reads the runbook.
 
 - On a request to write the handoff, follow `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md`. It sends the generic half to `canon:session-map` and adds decisions taken under delegated authority.
 - That map follows `${CLAUDE_SKILL_DIR}/../session-map/references/session.md`. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
+- Hand launch: `${CLAUDE_SKILL_DIR}/references/orchestrator-hand-launch.md`
 - A lesson about how to work goes to the owning task's Findings, as a bold-labeled line per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`
 - On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work
 
@@ -108,7 +109,7 @@ The handback runbook holds how the message is addressed and worded, what to do w
 
 ### Constraints from the tracks in flight
 
-A plan written here targets a tree several branches are changing, so it names each in-flight track's file set as a constraint, read from that track's Touches column. State for each set which of the two acts it forbids, per Constraints in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+A plan written here targets a tree several branches are changing, so it names each in-flight track's file set as a constraint, read from the plan its row links. State for each set which of the two acts it forbids, per Constraints in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
 
 - A bare path list leaves the worker guessing, and can end up forbidding the repair of a citation the change broke
 - A shared path forbids an act only where the conflict check in `orchestrator-dispatch.md` holds the pair. Otherwise it names what the second branch to merge rebases over.

package/claude/skills/role-orchestrator/references/orchestrator-dispatch.md

@@ -125,7 +125,7 @@ No practitioner source serializes on a shared file. Each builds in parallel and
 Read `canon sessions list --json` for the branches in flight as well as the board, since a hand-launched track carries no row, and read the plan of any branch no row names.
 
 - `canon tasks validate` and `canon tasks plan-reach` report the paths two rows share, a candidate list for the five holds and the paths a dispatch names
-- A shared folder means a Touches cell claimed it bare, so narrow that cell rather than reading the folder as a sweep
+- A shared folder means a plan declared it bare, so narrow that plan's list rather than reading the folder as a sweep
 - A declared set predicts rather than bounds, since `canon:context-fold`, `canon:docs-sync`, and the drift stages write past every plan
 - Such a crossing changes what the second branch rebases over, not whether a row holds, and `canon tasks plan-reach` at `canon:git-ship` step 5 names it
 

package/claude/skills/role-orchestrator/references/orchestrator-hand-launch.md

@@ -0,0 +1,60 @@
+---
+title: Orchestrator hand launch
+description: The one lean prompts file the orchestrator writes when the operator launches sessions by hand, with its path, overwrite rule, shape, and a filled example
+---
+
+Run this when the operator launches sessions by hand rather than through `claude --bg`. The rules every launch shares stay in `orchestrator-launch.md`.
+
+# Hand launch
+
+When the operator launches sessions by hand, write every prompt to one file, `.canon/tmp/dispatch/prompts.md`, and overwrite it at each wave. It lists every row with a session not yet launched. A row launched from an older copy and again from a newer one would build twice, and the branch check in `orchestrator-dispatch.md` catches that.
+
+The operator opens the file, reads one lead line, and pastes one fence per session. The shape is fixed:
+
+- An H1, `# Dispatch prompts`, then one lead line carrying the measured head, the merge order, and the folder to open each session in
+- An H2 per task as `## <label>: <title>`, an H3 per role as `### Worker` or `### Reviewer`, a `Model: <model>.` line, and a `text` fence
+- In the fence, the command at position zero, then `Controller: <sessionId>`, then only context the plan does not carry, one line each
+
+Keep the command at position zero per `### Position zero` in `orchestrator-launch.md`, and carry only what `### What the brief may carry` there allows. Leave out the answer-slot default and anything else the plan states.
+
+The `Controller:` line replaces the background template's message clauses, which `role-worker` and `session-relay` already own. `auto-ship` Step 0 loads `role-worker`, so the fence needs nothing more.
+
+- A reviewer launched by hand takes the `### Reviewer` H3 under its row's H2, with the sibling facts `orchestrator-reviewer-launch.md` lists
+- Its `<number>` exists once the worker opened its pull request, so a later wave carries `### Reviewer` alone under the row, and the launched worker's H3 is gone
+
+The first wave carries the worker. The wave after its pull request opens carries the reviewer alone.
+
+````markdown
+# Dispatch prompts
+
+Head `<head>`. Merge `<label-a>` first, then `<label-b>`. Open each session in the repository root.
+
+## <label-b>: <title>
+
+### Worker
+
+Model: opus.
+
+```text
+/canon:auto-ship .canon/plans/feature-<slug>.md
+Controller: <sessionId>
+<branch-a> edits the section of <file> this plan leaves alone. Rebase over it when told.
+```
+````
+
+````markdown
+# Dispatch prompts
+
+Head `<head>`. Merge `<label-a>` first, then `<label-b>`. Open each session in the repository root.
+
+## <label-b>: <title>
+
+### Reviewer
+
+Model: opus.
+
+```text
+Run /canon:role-reviewer, then /canon:review-pr <number>
+Controller: <sessionId>
+```
+````

package/claude/skills/role-orchestrator/references/orchestrator-launch.md

@@ -12,6 +12,7 @@ Run this once `orchestrator-dispatch.md` has cleared a row, or from its planning
 - [Dispatch to address a review](#dispatch-to-address-a-review)
 - [Dispatch to plan a row](#dispatch-to-plan-a-row)
 - [Dispatch a talk session](#dispatch-a-talk-session)
+- [Hand launch](#hand-launch)
 - [Dispatch a reviewer](#dispatch-a-reviewer)
 
 ## Dispatch
@@ -156,6 +157,10 @@ Read the session's `sessionId` off the launch output, carry it in this session's
 
 The map exists only once the handoff writes it, so this session's own launches, read with the prior map, are what the first wind-down reads talk sessions from.
 
+## Hand launch
+
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-hand-launch.md` when the operator launches sessions by hand. It states the single prompts file at `.canon/tmp/dispatch/prompts.md`, the lean shape of each fence, and a filled example, while the background templates above keep their full controller paragraph.
+
 ## Dispatch a reviewer
 
 Read `${CLAUDE_SKILL_DIR}/references/orchestrator-reviewer-launch.md` when `orchestrator-review-dispatch.md` sends a pull request to a dispatched reviewer, for the code, cloud, and UI reviewer shapes.

package/claude/skills/role-orchestrator/references/orchestrator-parked.md

@@ -32,7 +32,7 @@ The blocker cell states what the row waits on, and each kind is tested different
 
 ### A hold behind a track in flight
 
-The validator tests the file the cell cites against the Touches column of every `## Run now` row. A track that merged since the row was parked is no longer in flight, whatever the sets still share.
+The validator tests the file the cell cites against the files every `## Run now` row's plans declare. A track that merged since the row was parked is no longer in flight, whatever the sets still share.
 
 - Re-test the cell under the conflict check in `orchestrator-dispatch.md` too, since a row parked on a shared file alone holds on nothing and moves up
 - A cell naming the file in prose rather than backticks cites nothing, so rewrite the hold in the board's spelling and the next run picks it up

package/claude/skills/role-orchestrator/references/orchestrator-reviewer-launch.md

@@ -9,7 +9,7 @@ Run this once `orchestrator-review-dispatch.md` has sent a pull request to a dis
 
 `review-pr` is a single pass rather than a role, so a launch naming it alone reaches no `role-reviewer` and owes no message. Reach the role first on this launch, the way the planning shape in `orchestrator-launch.md` reaches `role-planner`. `orchestrator-review-dispatch.md` decides whether a pull request takes this shape at all.
 
-No branch and no worktree are entered here. The reviewer reads the pull request at the head `review-pr` resolves and writes the comment and its body file alone.
+No branch and no worktree are entered here. The reviewer reads the pull request at the head `review-pr` resolves and writes the comment and its body file alone. A reviewer the operator launches by hand takes the `### Reviewer` H3 that `orchestrator-hand-launch.md` states.
 
 ```bash
 claude --bg --model <model> -n "reviewer-<project>-<number>" "Run /canon:role-reviewer, then /canon:review-pr <number>. Your controller is the session whose sessionId is <dispatcher-id>. Resolve its current name from that id through canon sessions list --json, which carries sessionId per row, at the moment you send, and never resolve an addressee by name prefix. When the pass posts under ## Review, message the worker holding the branch to run review-address, carrying your own sessionId, and send it to the controller instead when no worker resolves. When it posts ## Review closed, run canon pr lift <number> --json and message the controller with the heading, the count line, and the reason the verb returned, unless that reason names the UI review as still open or missing. Message the controller again if you stop on a question."

package/claude/skills/role-planner/SKILL.md

@@ -39,7 +39,7 @@ Each item below is something a record needed and a launch string did not carry.
 - The task file, and its `## Findings` before deciding anything, since a row can carry its own disproof under a title still stating the original claim
 - The source files themselves, opened rather than summarized. Never a count quoted from the task file, which goes wrong or stale.
 - `CLAUDE.md` and the context entries the row touches, for the decision and the alternative it was taken against rather than for the decision alone
-- `.canon/tasks/priority.md` for the row's Touches column and its blocker. Read it for the shared-path lines and holds of the constraint block, never as a gate a plan must clear.
+- `.canon/tasks/priority.md` for the row's blocker and the plan each running row links. Read those plans for the constraint block's shared paths and holds, never as a gate a plan must clear.
 
 ### Reads for a feature plan alone
 

package/claude/skills/role-worker/SKILL.md

@@ -50,6 +50,8 @@ A painted pull request needs a server in this worktree for `canon pr local` to f
 - Wait up to 60 seconds for the verb to read `ok`, then ship either way. A stack with no `dev` script gets no start, and `pr-evidence` reports `no-server`.
 - Never detach it with `nohup`, `setsid`, or `disown`, since the owning session is the stop. `canon worktrees reclaim` ends any listener left in a worktree it removes.
 
+Run `canon pr drive-copy --json` before starting `dev`. On `copied`, start it with `env` set to `copyRoot`, so the operator's address serves the copy. On `no-config`, start it as it is. On a refusal, start nothing and send the controller the `reason`, since a broken config would send drives into tracked folders.
+
 A hand-run `git-ship` or `git-pr` starts no server, since only a worker has a lifetime to own one.
 
 ### Building against a design reference
@@ -86,7 +88,7 @@ The controlling session cannot watch this one build, so the messages below are o
 
 ### The pull request announcement
 
-Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, and the task it closes. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch.
+Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, the head sha, the CI state, the task it closes, and each departure from the plan. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch.
 
 - Carry the reach in that message, being the paths this branch wrote that another live plan or `## Run now` row holds, and who holds each, which `canon tasks plan-reach` reports as `claimed`
 - Report each as a rebase the controller should order, never as a breach, since sharing a path is not a hold
@@ -123,7 +125,7 @@ A worker that improvised this read polled issue comments, never saw a UI close p
 
 ### Addressing
 
-Address the session the launch named, and the reviewer by its dispatch's sessionId, each as a `sessionId` rather than a name. `canon:session-relay` turns that id into an address and carries the send, falling back to a copyable block where no send tool exists.
+Address the session the launch named, and the reviewer by its dispatch's sessionId, each as a `sessionId` rather than a name. `canon:session-relay` turns that id into an address and carries the send, falling back to a copyable block where no send tool exists. A `Controller: <sessionId>` line names the controller.
 
 Ask the operator when the launch named nobody and a person is there, putting candidate rows through the structured question surface. The halt is the cheaper error, since a message sent to the wrong session reports success and is lost.
 

package/claude/skills/session-compact/references/handoff-note.md

@@ -39,7 +39,9 @@ Name what was not touched too. A session that changed no source says so, since a
 
 One bullet per decision, each naming what it beat. A decision with no rejected alternative reads as arbitrary and gets reopened by the next session that dislikes it.
 
-Where a decision rests on a measurement, give the number rather than the conclusion. `27 spacing values became 7` survives a reader disagreeing with it, where `the spacing was tidied` does not.
+- Keep each bullet under 200 characters, and give a decision needing more an H3 of its own and a short paragraph
+- The note holds to the six criteria under `### Structure` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`
+- Where a decision rests on a measurement, give the number rather than the conclusion. `27 spacing values became 7` survives a reader disagreeing with it, where `the spacing was tidied` does not.
 
 ### `## What is open`
 

package/claude/skills/session-map/references/session.md

@@ -66,7 +66,7 @@ Three sections form the core, in this order, and every session fills all three.
 - `## Mistakes worth not repeating`: what went wrong and the rule it yields
 - `## Standing cautions`: commands that lie, tools that measure the wrong tree, and anything unbacked
 
-Add a section only for content that fits none of the three and would otherwise be lost.
+Add a section only for content that fits none of the three and would otherwise be lost. Every section holds to the six criteria under `### Structure` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
 
 ## Writing one
 

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/task-board/references/board.md

@@ -91,9 +91,9 @@ A collision with running work blocks a task only where no merge settles it, bein
 
 ### The `Touches` cell
 
-A `Touches` cell is the first three paths of its plan's `**Files to touch:**` and a count of the rest, the union in line order for a sliced task. It states what the branch sets out to write, and a running branch outgrows it.
+A `Touches` cell counts its plans' declared files and names the two fullest folders, as in ``12 files under `src/tasks/`, `claude/skills/` ``. The linked plan holds the file list, which the overlap checks read.
 
-- `canon tasks plan-reach <plan>` reads the current reach off the branch's diff
+- `canon tasks plan-reach <plan>` reads the reach a running branch grew to
 - Change the plan's list to change the cell. A worker never edits this board.
 
 ### Cell width

package/claude/skills/task-board/references/tasks.md

@@ -83,7 +83,7 @@ Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable
 
 - Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
 - Outcomes stay a checklist, since the board tools read them by their `- [ ]` line
-- Open each finding with a bold label naming its source and date, as in `- **planner, 2026-10-11:** <finding>`. Keep it to a few sentences, moving anything longer into the plan or groundwork folder.
+- Open each finding with a bold label naming its source and date, as in `- **planner, 2026-10-11:** <finding>`. Past 200 characters it becomes a paragraph, and the plan holds anything longer.
 
 ### Sizing outcomes
 

package/docs/agents/index.md

@@ -12,7 +12,7 @@ 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

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

@@ -57,5 +57,5 @@ Branch on `reason` in the `--json` record, not the exit code.
 ## See also
 
 - `canon records ordinal <kind> <slug> --claim`: reserve the next intake or groundwork ordinal
-- `canon records validate <kind> --help`: where a record folder disagrees with its standard
+- `canon records validate <kind> [record] --help`: where a record disagrees with its standard, plus a `structure` report that never sets the exit
 - `canon records stale --help`: when the requirements record was last reviewed

package/docs/target/migrations.md

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

@@ -32,7 +32,7 @@ Assert the orchestrator role in one warm session with `canon:role-orchestrator`.
 
 - To pick otherwise, rewrite that line as `overridden at execution to <pick>,` plus the measurement, and add one line to the open task's `## Findings`
 
-- `canon records validate plans` reports a plan breaking its standard, and takes `groundwork`, `intake`, and `teach`
+- `canon records validate plans [plan]` reports a plan breaking its standard, plus `structure` misses that never set the exit, and takes `groundwork`, `intake`, and `teach`
 - `canon records push` and `canon records pull` carry `.canon/` to and from a private repository. See [records](../agents/records.md).
 - `canon records size`, `canon records prune-tmp`, and `canon records stale canonical` report folder size, idle scratch, and releases since the requirements review
 - `canon tasks archive` moves a shipped plan to `.canon/plans/archive/` and retargets the task's `Plan:` line
@@ -58,6 +58,6 @@ Merge order matters only when two branches touch the same file. Expect to rebase
 - A parked row is reported when its cited task reached the trunk, whether the cell links it or names its bare label
 - A group header must be the columns the group owns, a `Touches` cell must match its plan, and a `Waiting on` cell renders at most 120 characters
 
-`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 only when the merge carried a PR number and the task is closed.
+`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.

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/ledger/ui/design-reference.md

@@ -12,6 +12,7 @@ The rule states canon's own design handoff, generalized from Frameboard's projec
 | 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 |

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

@@ -17,6 +17,7 @@ paths:
 ## Where the design lives
 
 - 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.
 - 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.48.0",
+  "version": "5.50.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/misc.ts

@@ -39,6 +39,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Draw the signup screen as a frame on the canvas, then restyle the element I just selected there.',
     expect: 'canvas-board',
   },
+  {
+    prompt:
+      'The operator picked the new settings panel, so land it in canon/design with an index row for it.',
+    expect: 'design-record',
+  },
   {
     prompt:
       "We're about to hit the context limit, write the handoff before we lose state.",

package/src/commands/claude.ts

@@ -71,6 +71,9 @@ import {
   serializeSettings,
   writeSettings,
 } from '@/claude/settings'
+import { bodyLines } from '@/markdown/scan'
+import { scopedDensityFindings } from '@/markdown/scope'
+import { CAP } from '@/markdown/stacks'
 import { readSessionDefaults } from '@/migrate/session-defaults'
 import { copyPreservingMode } from '@/sync/copy'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
@@ -176,6 +179,22 @@ export function seededDirPath(resolved: string, name: string): string {
     ? surfaceDir(resolved, name)
     : recordDir(resolved, name)
 }
+
+/**
+ * Each bullet run past the limit in the target's `CLAUDE.md` Key paths, read
+ * through the scope the audit gates on. Sync warns rather than gates, since a
+ * target gates only the prefixes its own config lists.
+ */
+export async function longKeyPathsRuns(
+  resolved: string,
+): Promise<{ line: number; count: number }[]> {
+  const path = join(resolved, 'CLAUDE.md')
+  if (!existsSync(path)) return []
+  const lines = bodyLines(await readFile(path, 'utf8'))
+  return scopedDensityFindings('CLAUDE.md', lines)
+    .filter((finding) => finding.kind === 'bullet-run')
+    .map((finding) => ({ line: finding.line, count: finding.value ?? 0 }))
+}
 const USER_DIR = join('tooling', 'claude', 'user')
 const STATUSLINE = 'statusline-command.sh'
 const PLUGIN_MANIFEST = join('claude', '.claude-plugin', 'plugin.json')
@@ -244,7 +263,8 @@ export function register(program: Command): void {
         'Writes .gitignore alone: adds the entries the claude manifest lists',
         'and drops ones under its headers that the manifest no longer lists.',
         'A seeded file is reported, never rewritten, and a missing one points',
-        'at `canon claude init`.',
+        'at `canon claude init`. A CLAUDE.md Key paths running past 5 bullets',
+        'is reported with the H3 grouping that fixes it.',
         '',
         'Exit codes:',
         '  0  synced, already up to date, or the prompt was cancelled',
@@ -665,6 +685,11 @@ async function runSync(target: string): Promise<number> {
     if (isDirectory(seededDirPath(resolved, name))) logInfo(`${name}/`)
     else logWarn(`${name}/ missing. Run \`canon claude init\``)
   }
+  for (const run of await longKeyPathsRuns(resolved)) {
+    logWarn(
+      `CLAUDE.md:${run.line} runs ${run.count} Key paths bullets past ${CAP}. Group them under H3s, each opening on a lead sentence`,
+    )
+  }
 
   // Sync never rewrites an existing settings file, so a target seeded before
   // the session defaults learns of them only here.

package/src/commands/gate.ts

@@ -130,22 +130,9 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
       process.stderr.write(`${failed.label}: ${failed.failure}\n`)
     }
     process.stdout.write(
-      `${JSON.stringify({
-        ok: code === 0,
-        root,
-        scoped: changed.scoped,
-        changed: changed.files.length,
-        summary,
-        ms: results.reduce((total, result) => total + result.ms, 0),
-        stages: results.map(({ id, label, status, failure, ms, queuedMs }) => ({
-          id,
-          label,
-          status,
-          failure,
-          ms,
-          queuedMs,
-        })),
-      })}\n`,
+      `${JSON.stringify(
+        gateRecord({ ok: code === 0, root, changed, summary, results }),
+      )}\n`,
     )
     return code
   }
@@ -154,6 +141,60 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
   return code
 }
 
+/** Lines of a failed stage's output the record keeps, counted from the end. */
+const OUTPUT_TAIL_LINES = 200
+
+interface GateRecordInput {
+  readonly ok: boolean
+  readonly root: string
+  readonly changed: {
+    readonly scoped: boolean
+    readonly files: readonly string[]
+  }
+  readonly summary: Summary
+  readonly results: readonly StageResult[]
+}
+
+/**
+ * The `--json` record. A failed stage carries the tail of the output its
+ * checks printed, since a caller reading the record alone otherwise reruns
+ * the stage by hand to learn which test failed. The tail rather than a parse
+ * of the `FAIL` lines, so a generic stage stays free of one runner's format,
+ * and a dot-reporter run prints its failures and summary last.
+ */
+export function gateRecord(input: GateRecordInput) {
+  const { ok, root, changed, summary, results } = input
+  return {
+    ok,
+    root,
+    scoped: changed.scoped,
+    changed: changed.files.length,
+    summary,
+    ms: results.reduce((total, result) => total + result.ms, 0),
+    stages: results.map(
+      ({ id, label, status, failure, ms, queuedMs, emissions }) => ({
+        id,
+        label,
+        status,
+        failure,
+        ms,
+        queuedMs,
+        output: status === 'failed' ? outputTail(emissions) : undefined,
+      }),
+    ),
+  }
+}
+
+function outputTail(emissions: StageResult['emissions']): string {
+  const lines = emissions
+    .filter((emission) => emission.kind === 'output')
+    .map((emission) => emission.text.trimEnd())
+    .filter((text) => text !== '')
+    .join('\n')
+    .split('\n')
+  return lines.slice(-OUTPUT_TAIL_LINES).join('\n')
+}
+
 function report(result: StageResult): void {
   logStep(result.label)
   for (const emission of result.emissions) {