@erclx/canon 5.48.0 → 5.50.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.48.0",
+  "version": "5.50.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -124,7 +124,7 @@ This chain adds one thing. Mark the pull request as a draft as soon as `git-ship
 
 ## Step 7: wait for the reviews
 
-Run this step only when the launch named a controlling session, since only a controller dispatches the reviewers. A hand-launched run has nobody reviewing, so it emits the Output block on the CI wake instead of waiting on a pass that cannot arrive.
+Run this step only when the launch named a controlling session, since only a controller dispatches the reviewers. A launch naming no controller has nobody reviewing, so it emits the Output block on the CI wake instead of waiting on a pass that cannot arrive. A `Controller: <sessionId>` line names one, whether the launch was by hand or not.
 
 Read review state through `canon pr review-state` alone, since both families post as pull request reviews, and a worker polling issue comments instead stalled with both reviewers idle. Run it in the background with the number Step 6 returned, since the wait outlasts a foreground shell call, and act on the wake.
 

package/claude/skills/canvas-board/REQUIREMENT.md

@@ -9,7 +9,7 @@ description: Scope boundary for driving the local design canvas, and the line be
 
 Without this skill, a session asked to draw on the canvas writes frames nothing is serving and reports them drawn. It trusts a passing capture, though a blank shell passes every capture while the operator sees an empty tab. From a linked worktree it writes a copy the canvas never serves, and it captures after every edit.
 
-It reads "this one" from the conversation rather than the operator's selection, or acts on a stale element pick and edits the wrong element. It restyles through a class while the operator's inspector edit sits inline, so the change never shows. A picked frame stays on the canvas as the only record, and the design document never learns it.
+It reads "this one" from the conversation rather than the operator's selection, or acts on a stale element pick and edits the wrong element. It restyles through a class while the operator's inspector edit sits inline, so the change never shows. A picked frame stays on the canvas as the only record, and the project's design record never learns it.
 
 ## Must
 
@@ -17,7 +17,7 @@ It reads "this one" from the conversation rather than the operator's selection,
 - Pages and frames go through the verbs, so the session and the operator's drags share one writer, and a frame from a linked worktree takes the main-root route
 - The operator's selection decides what "this one" means, and a stale element pick reads as unknown
 - A frame's inline styles are read before a restyle, the run names which operator edits it kept and dropped, and capture runs once per finished frame or page
-- A picked value lands in the project's stylesheet and its intent in the design document, while a picked layout stays on the canvas for the plan that builds it
+- A picked frame is handed to `design-record` by page and frame, while a picked layout stays on the canvas for the plan that builds it
 
 ## Must not
 
@@ -31,4 +31,5 @@ It reads "this one" from the conversation rather than the operator's selection,
 - Drafting candidates for a taste decision and taking the pick, which `pick-by-eye` owns
 - What the canvas verbs do internally, which the CLI's own contract owns
 - The content format a frame and a layout take, which the canvas standard owns
-- Tracing reference images into design values, writing the design document from code, and backing up the canvas folder, which no skill owns
+- Landing a pick in the reference folder and carrying its values into the design document, which `design-record` owns
+- Tracing reference images into design values and backing up the canvas folder, which no skill owns

package/claude/skills/canvas-board/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: canvas-board
-description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and carries a picked direction into the project's design document. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `pick-by-eye`.
+description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and hands a picked frame to `design-record`. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `pick-by-eye`.
 metadata:
   family: decide
 ---
@@ -16,7 +16,7 @@ Every verb below is `canon canvas`. Run `canon canvas --help` for the verbs and
 - If `canon` is not on PATH, stop: `❌ canon CLI not found.`
 - If `canon canvas --help` reports no such command, stop: `❌ The installed canon carries no canvas command. Update the CLI and re-run.`
 - Write no frame before the canvas is serving and the shell has loaded. A frame nobody can see is a draft reported as delivered.
-- Never present a frame as the project's design. The canvas is a drafting surface and the project's design document holds what was decided.
+- Never present a frame as the project's design. The canvas is a drafting surface and the project's design record holds what was decided.
 - Never promise the canvas survives a lost checkout. Its folder is gitignored and nothing backs it up.
 
 ## Step 1: start the canvas and confirm the shell
@@ -122,13 +122,12 @@ Capture once per finished frame or page, not after every edit. The live canvas i
 
 A capture refused because a font is not installed names the family it read off the frame's text. Set that text's `font-family` to a named family the machine has, never a generic keyword such as `sans-serif`, and capture again rather than reporting the frame as captured.
 
-## Step 7: carry a picked direction back
+## Step 7: hand a picked frame on
 
-When the operator picks a frame, the decision leaves the canvas. Leave structure and layout on the canvas, and name the frame in the plan that builds it.
+When the operator picks a frame, the decision leaves the canvas. Hand it to `canon:design-record`, which lands the frame in the project's reference folder and carries its values into the design document. Report it rather than proceeding silently when that skill does not resolve.
 
-- Carry color, type, spacing, and radius into the stylesheet the design document's lead names, and their intent into its sections under the `design.md` standard
-- A project with no stylesheet yet takes the values under `.claude/design/project/` after `canon design install`, and the lead names that path
-- Name the frame the decision came from in the reply, and leave the frame on the canvas until the operator clears it.
+- Name the page and frame the decision came from in the handoff and the reply, and leave the frame on the canvas until the operator clears it
+- Name the frame in the plan that builds a picked layout, since the layout reaches code through that plan
 - Never cite a frame path from a tracked file. The folder is gitignored, so the citation resolves on this machine alone.
 
 ## Output
@@ -138,7 +137,7 @@ When the operator picks a frame, the decision leaves the canvas. Leave structure
 Page:     <page>, <n> frames
 Selected: <page>/<frame>, element <index>, or none, or stale
 Capture:  <path of each capture written>
-Carried:  <the stylesheet and design document the pick went to, the plan that cites the frame, or not yet>
+Handed:   <the frame handed to design-record, the plan that cites it, or not yet>
 ```
 
-Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the carried line when no direction was picked. Emit every path from the project root.
+Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the handed line when no frame was picked. Emit every path from the project root.

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

@@ -88,9 +88,10 @@ Entries get read top-down and often partially, so the boundary sits above the fo
 
 ## The development entry
 
-Only the `development` entry carries this section, as an H3 under `## Layout`. It is not a general-purpose heading for other domains.
+Only the development entry carries this section, as an H3 under `## Layout`. That entry is the flat `development` entry or any entry directly under a `development/` folder, and the heading is not a general-purpose one for other domains.
 
-- `### Scripts`: a table of run commands (command plus purpose). The single discoverable surface for how to run the project. Keep run commands here, not scattered across `CLAUDE.md`.
+- `### Scripts`: run commands as tables of command plus purpose. The single discoverable surface for how to run the project. Keep run commands here, not scattered across `CLAUDE.md`.
+- Group a long set of commands into short tables, each under a lead sentence naming its group, since a table past 8 body rows breaks the table limits. This H3 alone may carry several lead paragraphs.
 
 ## What goes in
 
@@ -157,7 +158,7 @@ A domain outgrowing the ceiling splits into a folder, and small domains of one k
 - Name an entry inside either folder per the `codebase-layout` skill, which never repeats the folder's name as the entry's stem or prefix
 - Keep a split domain's `index.md` generated, since regen rewrites its body. The domain's own overview and layout go in a sibling file, which the `subtitle` names.
 
-Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and conflicts with any sibling branch.
+Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and conflicts with any sibling branch. The development entry's `### Scripts` is the one exception, kept small by grouping.
 
 ## Examples
 

package/claude/skills/design-record/REQUIREMENT.md

@@ -0,0 +1,33 @@
+---
+name: design-record
+description: What keeping the design record is for, the gaps it closes, and where it stops against the skills that pick and judge a design
+---
+
+# Design record requirement
+
+## Gap
+
+Without this skill, no surface sets up the design reference folder or keeps it. A pick reaches the folder only when the operator remembers the sync, or a session copies frames in by hand and they drift. A reference outlives the surface it showed, since nothing removes it.
+
+Each project invents its own grouping, and its index restates the file tree rather than naming the code a group governs. A picked color reaches the stylesheet with no intent written down, or lands as a hand-typed value in the design document.
+
+## Must
+
+- The folder takes the groups, file names, support folder, and index row form the folder standard fixes, and a project without one gets it set up rather than refused
+- A pick lands through the design sync after its index row, and a project with no sync is told before any write and still gets the design document half
+- A redraw keeps the index row and leaves the files to the sync, and a retired surface takes its files and row out in the change that removes it
+- The run looks at each landed picture in both themes before reporting it landed
+- A picked value lands in the stylesheet and its intent in the design document under the design document standard, and a generated record changes through its module alone
+
+## Must not
+
+- Write, copy, or delete a reference file by hand, or capture frames in place of a missing sync
+- Land a candidate the operator has not picked
+- Restate when a pick lands against the build, which the design-reference rule states
+- Be reached only by the author typing its name, since a pick from the picking or canvas skill should hand off to it
+
+## Out of scope
+
+- Drafting candidates and taking the pick, which `pick-by-eye` owns
+- Drawing, selecting, and capturing frames on the canvas, which `canvas-board` owns
+- Judging whether a design is good, which `design-taste` owns

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

@@ -0,0 +1,84 @@
+---
+name: design-record
+description: Keeps the project's design record, being the design document at `canon/DESIGN.md` and the reference folder at `canon/design/` holding the accepted frames a build matches. Sets the folder up, lands a picked design through the project's design sync, keeps the index, redraws or retires a reference when its surface changes, and carries a pick's values into the stylesheet and its intent into the design document. Use whenever a picked frame or design moves into `canon/design/` or `canon/DESIGN.md`, before running the project's design sync or editing the index, including when asked to "land it in the design references", "add a design reference", "land this pick", "set up canon/design", "update the design index", "redraw the reference for X", "remove the reference for X", or "update DESIGN.md". Do NOT use to draft candidates or take a pick, which is `pick-by-eye`, to draw frames on the canvas, which is `canvas-board`, or to judge a design, which is `design-taste`.
+metadata:
+  family: ship
+---
+
+# Design record
+
+Keep the record of what the project's design is. The record has two halves, each with its own standard to read before writing it.
+
+| Half             | Path              | Standard                                   |
+| ---------------- | ----------------- | ------------------------------------------ |
+| Design document  | `canon/DESIGN.md` | `${CLAUDE_SKILL_DIR}/references/design.md` |
+| Reference folder | `canon/design/`   | `${CLAUDE_SKILL_DIR}/references/folder.md` |
+
+The document holds the rules and each role's intent, and the folder holds the pictures a build matches.
+
+## Guards
+
+- Write no reference file by hand, whether a copy, an edit, or a delete. The project's design sync writes the frames, so a hand-written file drifts from the frame it claims to show.
+- Never land a candidate the operator has not picked. The folder holds accepted designs, and a draft lives on the canvas.
+
+## Step 1: read the record
+
+Read `canon/design/index.md` from the project root, and list the group folders beside it.
+
+- A missing folder or index is set up at Step 3, once Step 2 has found the sync
+- An index carrying a file list or a canvas mapping is an older shape. Leave its rows in place, add new rows in the form `folder.md` gives, and say the index predates the standard.
+
+## Step 2: find the project's design sync
+
+Find the sync before writing anything, since every folder step runs through it. Read the project's scripts, such as the `scripts` block of `package.json`, for the command that writes frames into `canon/design/`. Run its `--help` when it offers one, for its mapping file and its check.
+
+When no sync resolves, skip Steps 3 to 5 and capture no frame in the sync's place. Report `⚠ No design sync found, so the pick did not land in canon/design/. Add one or name the command, then re-run.` and go on to Step 6, which needs no sync.
+
+## Step 3: set up the folder
+
+Skip this step when `canon/design/index.md` exists, even as a stub, since a stub the project's stack seeded is the setup.
+
+1. Write `canon/design/index.md` from the template in `folder.md`, with one row per group the first pick needs.
+2. Leave the group folders to the sync, since git tracks no empty folder and the sync creates each one as it writes.
+
+## Step 4: land a pick
+
+When the pick lands relative to the build is the design-reference rule's call, so follow it rather than choosing here.
+
+1. Name the group the surface belongs to, by where a user meets it in the app, per `folder.md`.
+2. Add or update the group's index row before running the sync, naming the code paths the surface governs and the states its frames show.
+3. Add the surface to the sync's mapping file, in the form the sync's own help gives.
+4. Run the sync, then its check, and report a missing or stray file the check names.
+5. Open each written PNG, light and dark, before reporting it landed, since a frame captured blank or in one theme passes the sync.
+
+## Step 5: redraw or retire a reference
+
+A redraw follows an intentional design change and nothing else. Keep the index row, change the sync's mapping only where the frame moved on the canvas, and run the sync so it rewrites the files.
+
+Retire a reference in the change that removes its surface from the app.
+
+- Drop the surface from the sync's mapping and run the sync, so the sync removes its files
+- Remove the group's index row when the group holds nothing else
+- When the sync leaves the files and its check reports them stray, name each path and ask the operator, since no session deletes a reference by hand
+
+## Step 6: carry a pick into the design document
+
+A pick that settles color, type, spacing, or radius changes the design document as well as the folder. Skip this step when the pick changed layout or structure alone, since the reference carries that.
+
+- Carry each value into the stylesheet the document's lead names, and its intent into the document's sections under `design.md`
+- A project with no stylesheet yet takes the values under `.claude/design/project/` after `canon design install`, and the lead names that path
+- A values record names in its lead the module it renders from and the command that renders it. Edit that module and run that command, never the document.
+
+Never cite a canvas frame path from the document or the index. The canvas folder is gitignored, so the citation resolves on one machine alone.
+
+## Output
+
+```plaintext
+✅ Design record: <landed, redrawn, retired, set up, or carried>
+Group:  <group>, <name>
+Files:  <each file the sync wrote or removed>
+Index:  <the row added, changed, or removed, or unchanged>
+Design: <the stylesheet and design document the values went to, or unchanged>
+```
+
+Emit every path from the project root. Omit the files line when nothing was written.

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

@@ -0,0 +1,69 @@
+---
+title: Design reference folder
+description: Shape and content rules for canon/design, the tracked folder of accepted design frames a build matches
+---
+
+# Design reference folder
+
+Applies to `canon/design/`. Each file is an accepted design a build matches, kept as a picture for a reader and as frame HTML for exact values. The folder holds what was picked, never a draft.
+
+## Scope
+
+Governs the folder's groups, the file names inside them, the support folder, and the index at `canon/design/index.md`.
+
+Does not govern:
+
+- The design document at `canon/DESIGN.md`, which `design.md` beside this file governs
+- When a pick lands and how a build is held to a reference, which the design-reference governance rule states
+- The canvas content format a frame is drawn in, which the canvas standard owns
+
+## What a working folder looks like
+
+A folder works when a builder opening it finds the reference for the surface they are changing without asking anyone:
+
+- Does the group a surface sits in match where a user meets it in the app?
+- Does each reference carry both themes, as a picture and as frame HTML?
+- Does the index say which code each group governs?
+
+## Groups
+
+Group by app part, being the places a user sees, such as `home`, `inspector`, or `menus`. A component folder splits one screen across many folders, and a concern folder mixes surfaces a builder edits apart.
+
+- Give each app part one plain kebab-case folder directly under `canon/design/`
+- Put the inputs every app part draws on, such as tokens, colors, and the logo, under `foundations/`, so they read apart from places in the app
+- Gather a surface shown on several app parts, such as a toast, under the part a user meets it in first
+
+## Files
+
+Each reference is one name in two themes, with a PNG and its frame HTML per theme.
+
+- Name each file `<name>-dark` or `<name>-light`, as in `grid-dark.png` beside `grid-dark.html`
+- Keep one HTML file without a theme suffix only for a frame that switches theme itself, beside both PNGs
+- Put what every frame HTML loads, being its stylesheet, script, fonts, and vendored files, under `kit/`
+
+## The index
+
+`canon/design/index.md` is prose for a reader. It names the link a file listing lacks, from a group to the code it governs.
+
+- Write one row per group, carrying the group, what the user sees there, the code paths it governs, and the states its frames show
+- List no files, since the tree and the sync's own check already answer what exists
+- Keep the sync's canvas mapping out of the index, in a file the sync owns beside it
+
+### Template
+
+The column headers stay verbatim. A row per group, `foundations` included.
+
+```markdown
+# Design references
+
+Each group holds accepted frames a build matches, light and dark.
+
+| Group         | What the user sees | Code               | States           |
+| ------------- | ------------------ | ------------------ | ---------------- |
+| `home`        | <the surface>      | `<path in source>` | <states shown>   |
+| `foundations` | Tokens and colors  | `<stylesheet>`     | <themes covered> |
+```
+
+## 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.

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

@@ -157,6 +157,6 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 Four 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}/../canvas-board/references/design.md`
+- The shape of the project's design document and where its values live: `${CLAUDE_SKILL_DIR}/../design-record/references/design.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/markdown-craft/REQUIREMENT.md

@@ -14,6 +14,7 @@ The rules also have three carriers, a standard, a generated rule pointing at it,
 ## Must
 
 - Hold the format and structure reference in `references/markdown.md`, the one copy, read by sibling path from every skill that writes markdown
+- Hold the table limits in `references/tables.md`, the one copy, since `markdown.md` sits at the document ceiling and points at it
 - Send the session to `canon markdown audit` after an edit, since the audit reads the bans from the package and a restated list would drift
 - Route voice to `write-human` and a Mermaid fence to `draw-figure` rather than restating either
 

package/claude/skills/markdown-craft/SKILL.md

@@ -7,10 +7,15 @@ metadata:
 
 # Markdown craft
 
-Read `${CLAUDE_SKILL_DIR}/references/markdown.md` before a substantial markdown edit. Every rule in it is a fact a scan can settle, so do not work the banned characters from memory.
+Read the references below before a substantial markdown edit. Every rule in them is a fact a scan can settle, so do not work the banned characters from memory.
+
+- `${CLAUDE_SKILL_DIR}/references/markdown.md`: headings, density, code spans, punctuation, and every other format rule
+- `${CLAUDE_SKILL_DIR}/references/tables.md`: the four table limits and their fixes, read before writing a table or fixing a table finding
 
 Run `canon markdown audit <path>` after the edit, and fix every ban and density finding it reports before moving on. Rewrite the sentence carrying a ban hit rather than swapping the token for a near-synonym, and fix a density finding by its shape rather than trimming characters.
 
+A table finding reports without failing the run. Fix it the way `tables.md` gives for its limit.
+
 ## Routes
 
 - Voice, rhythm, sentence construction, and information density: load `write-human`.

package/claude/skills/markdown-craft/references/markdown.md

@@ -63,7 +63,7 @@ Two kinds of block are exempt from the 40-line checkpoint, since a subheading dr
 - A block whose lines are all list items at one level averaging under roughly 130 characters, since a flat list of short peers is already navigable
 - Weight decides rather than count, since a catalog of one-liners and a stack of paragraphs reach one count and read nothing alike. The cap on a bullet run is a separate rule.
 - Mixing prose into that list, or nesting levels in it, ends the exemption at any weight
-- A block whose lines are all table rows, at any length, since a subheading inside one splits the table rather than the run
+- A block of table rows, since a heading splits the table rather than the run
 - Prose either side of the table ends that exemption, since the block has a seam and a heading breaks it there
 
 ### Bold section markers
@@ -77,7 +77,7 @@ A bold section marker holding its line alone breaks a run the way a heading does
 
 ## Density
 
-Six limits keep a file scannable on sight, each a fact `canon markdown audit` measures that fails the push wherever the surface's gate is on. Open an H3 with a lead sentence or a table, then a few bullets or a short paragraph, since monotone text is the defect whether all prose or all bullets.
+Six limits keep a file scannable on sight, each a fact `canon markdown audit` measures that fails the push where the surface's gate is on. A table takes four more, in `tables.md` beside this file. Open an H3 with a lead sentence or a table, then a few bullets or a short paragraph, since monotone text is the defect whether all prose or all bullets.
 
 | Rule                | Limit                                             |
 | ------------------- | ------------------------------------------------- |
@@ -88,7 +88,7 @@ Six limits keep a file scannable on sight, each a fact `canon markdown audit` me
 | Heading depth       | H3 at most, no H4                                 |
 | H3 opening          | First block under an H3 is a paragraph or a table |
 
-Rules, `CLAUDE.md`, a requirements or design record, a changelog, examples, and `.canon/` records take no density finding, since a rule is one imperative per bullet and each record keeps its own shape.
+Rules, a requirements or design record, a changelog, examples, and `.canon/` records take no density finding, since each keeps its own shape. `CLAUDE.md` takes the run limit and the H3 opening inside `## Key paths` alone.
 
 ### How each limit counts
 

package/claude/skills/markdown-craft/references/tables.md

@@ -0,0 +1,30 @@
+---
+title: Table limits
+description: The four limits a markdown table takes, being cell length, row count, a list after a table, and a wide code token, with the fix each one takes
+---
+
+# Table limits
+
+None of the density limits in `markdown.md` reads inside a table, so content too long for a bullet tends to move into a cell. Four table limits close that gap. `canon markdown audit` measures them on the paths density covers, outside fences, and reports each one without failing a push for now.
+
+## Limits
+
+Each limit is a count or a shape a scan settles, read the way a renderer draws the table. An escaped pipe stays inside its cell, and pipe lines with no delimiter row are not a table.
+
+| Rule             | Limit                                                 |
+| ---------------- | ----------------------------------------------------- |
+| Cell length      | 120 visible characters, counting a link by its label  |
+| Rows             | 8 body rows, not counting the header                  |
+| List after table | A list is never the next block after a table          |
+| Wide token       | No code span in a cell holds a run past 30 characters |
+
+A paragraph or a heading between a table and a list clears the third limit, and a blank line alone does not.
+
+## Fixes
+
+Each limit has its own fix, and none of them is trimming characters until the count passes.
+
+- Move a long cell's overflow into a bullet under the table's lead sentence, or under a lead of its own
+- Split a long table into groups, each under a lead sentence naming its group, since a heading inside a table splits it and H4 is banned
+- Give a list that follows a table a lead sentence of its own
+- Move a wide token out of the table into a bullet, since a preview either widens its column or splits it at a hyphen or a slash

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

@@ -17,8 +17,8 @@ metadata:
 
 Before Step 3, name the next three questions you would ask about what the ask must achieve, and predict the operator's answer to each. The test reads the ask's success criteria, never the plan's open questions.
 
-- A predictable answer settles its criterion, which Step 3 writes as a `**Verification:**` bullet rather than a question
-- Only a prediction still open goes under `**Questions:**` with a `- Suggested:` line, so a fully specified ask carries none and Small mode stays reachable
+- A predictable answer settles its criterion, which Step 3 writes as a `## Verification` bullet rather than a question
+- Only a prediction still open goes under `## Questions` with a `- Suggested:` line, so a fully specified ask carries none and Small mode stays reachable
 - When you can predict none of the three, ask before Step 3 through whatever route reaches the operator, including a message to a dispatching session
 
 ## Step 1: read the Claude setup
@@ -59,7 +59,7 @@ The section list, what each section holds, and the suggested-and-answer contract
 
 What this skill adds on top of the standard:
 
-- Reframe a vague ask as success criteria before `**Files to touch:**`, each an observable result and its check, which becomes one `**Verification:**` bullet. "Make it faster" names none.
+- Reframe a vague ask as success criteria before `## Files to touch`, each an observable result and its check, which becomes one `## Verification` bullet. "Make it faster" names none.
 - Confirm a concrete project or use case drives the feature, and lift patterns from it where precedent exists. A feature with no named user is a guess.
 - Prefer one layout that serves both a new and a grown project over a dual-mode toggle or a migration shim. Two modes double what every later change has to hold.
 
@@ -68,16 +68,16 @@ What this skill adds on top of the standard:
 Every `- Suggested:` line takes senior judgment, picking the best option in one line with its reason or main tradeoff, and naming alternatives only when they change the pick.
 
 - Suggest a real default when best practice, the codebase, or prior context points to one
-- Load `canon:codebase-layout` before `**Files to touch:**` when an entry names a path that does not exist yet, and give each new path its placement reason. Report it if it does not resolve.
-- Fill `**Design references:**` with the `canon/design/<surface>/` folder for each surface a UI file in `**Files to touch:**` renders, and write `None identified.` in a project with no folder
-- Write `**Verification:**` as one bullet per outcome naming the test or command that proves it
-- Write `**Review focus:**` as the inputs or states that would break the change, carrying the risk you understood to the executor and the reviewer
+- Load `canon:codebase-layout` before `## Files to touch` when an entry names a path that does not exist yet, and give each new path its placement reason. Report it if it does not resolve.
+- Fill `## Design references` with the `canon/design/<surface>/` folder for each surface a UI file in `## Files to touch` renders, and write `None identified.` in a project with no folder
+- Write `## Verification` as one bullet per outcome naming the test or command that proves it
+- Write `## Review focus` as the inputs or states that would break the change, carrying the risk you understood to the executor and the reviewer
 
 ### Sources and size
 
 A small feature produces a short plan, not a padded one.
 
-- Cite the `**Sources:**` entry for every decision Step 2 sourced, each with its quoted passage or the word `unverified`
+- Cite the `## Sources` entry for every decision Step 2 sourced, each with its quoted passage or the word `unverified`
 - Prefer `None identified.` over low-signal fillers
 - When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
 
@@ -99,21 +99,21 @@ A consumer list is a `Risks` entry, which already forces Full. A resource with m
 Output the plan to chat and write no plan file. The markers match the standard's, so a plan that later grows into a file keeps its shape.
 
 ```markdown
-**Files to touch:**
+## Files to touch
 
 - `path/to/file`: reason
 
-**Verification:**
+## Verification
 
 - <outcome>: `<test or command that proves it>`
 ```
 
-Small mode carries no `**Review focus:**`, since its Risks already came out `None identified.` and the reviewer has no breaking input to name.
+Small mode carries no `## Review focus`, since its Risks already came out `None identified.` and the reviewer has no breaking input to name.
 
-If real questions exist, include a numbered `**Questions:**` section below, each with a `- Suggested:` line and an `- Answer:` slot:
+If real questions exist, include a numbered `## Questions` section below, each with a `- Suggested:` line and an `- Answer:` slot:
 
 ```markdown
-**Questions:**
+## Questions
 
 1. <question>
    - Suggested: <pick>, <reason or tradeoff>
@@ -132,7 +132,10 @@ The plan is a main-root write, from a linked worktree and from a background sess
 
 Two commands check the file once it lands, and both write nothing.
 
-- Run `canon records validate plans` when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold.
+- Run `canon records validate plans feature-<slug>` when the CLI is on PATH. Its `findings` name a section, a filename, or an answer slot that does not hold.
+- Fix each entry its `structure` array names before reporting, against `### Structure` in `${CLAUDE_SKILL_DIR}/references/plan.md`
+- Read that array rather than the exit code, since a structure entry never sets the exit
+- Say the check did not run when the binary refuses the plan argument or carries no `structure` key, rather than reporting the plan clean
 - Run `canon markdown audit .canon/plans/feature-<slug>.md`, naming the file, since the gitignored plan reaches no other gate. Rewrite a hit's sentence rather than swapping the token.
 
 When Step 1 resolved an existing task, run `canon tasks plan-link <task> .canon/plans/feature-<slug>.md` right after the file lands, naming the stem Step 1 read. Skip it when Step 1 found no task, and report a refusal rather than stopping, since `canon tasks validate` still catches an unlinked task through `plan-uncited`.
@@ -144,14 +147,26 @@ Then output in chat:
 ```markdown
 📝 Wrote .canon/plans/feature-<slug>.md
 
-**Questions:**
+## Questions
 
 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

@@ -11,18 +11,18 @@ Applies to a feature plan that sequences its work into more than one batch. A de
 
 One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename. A fan-in member is the exception, keeping its own file and branch and opening no pull request, per `## Fan-in`.
 
-- A `**Batch N**` sub-heading inside one file's `**Files to touch:**` shares that branch across every batch, so the first merge strands the rest
+- A `**Batch N**` sub-heading inside one file's `## Files to touch` shares that branch across every batch, so the first merge strands the rest
 - Write a plan opening five batches as five files before the first line of any of them
 
 ## Dependent batches
 
-State a dependent batch's dependency on the ones before it in its own `**Constraints:**`, naming the earlier batch's slug and stacking rather than merging into it.
+State a dependent batch's dependency on the ones before it in its own `## Constraints`, naming the earlier batch's slug and stacking rather than merging into it.
 
 A batch that builds after another and shares most of its files folds into that batch as contiguous commits on one branch. Each pull request pays a fixed cost a same-file slice cannot earn back, and the rebases between stacked slices land on the same files.
 
 ### Judged apart
 
-Keep a batch apart only where a reviewer or the operator would judge it apart. Write that reason as ``Judged apart from `feature-<parent>`: <reason>`` in the batch's `**Constraints:**`.
+Keep a batch apart only where a reviewer or the operator would judge it apart. Write that reason as ``Judged apart from `feature-<parent>`: <reason>`` in the batch's `## Constraints`.
 
 - A contract a later batch is built against
 - A taste call the operator judges in its own sitting
@@ -61,12 +61,12 @@ Keep separate pull requests when the pieces are independent features, when one n
 
 ### Declaring the set
 
-Each side names the other in its `**Constraints:**`, and `canon records validate plans` reports `fan-in-unmatched` wherever the two disagree.
+Each side names the other in its `## Constraints`, and `canon records validate plans` reports `fan-in-unmatched` wherever the two disagree.
 
 - A member writes ``Fan-in member of `feature-<integrator>` ``, naming one integrator
 - The integrator writes ``Fans in `feature-<a>`, `feature-<b>`, and `feature-<c>` ``, in the order it merges them
 - The task's `Plan:` line cites every member and the integrator, since the merge archives only the plans that line cites and a live integrator listing archived members reports `fan-in-unmatched`
-- The integrator is its own plan, since its writes, being the shared lists, the citer repoints, and the index regeneration, need a `**Files to touch:**` of their own
+- The integrator is its own plan, since its writes, being the shared lists, the citer repoints, and the index regeneration, need a `## Files to touch` of their own
 
 `canon tasks plan-answers` holds a member whose integrator is missing or does not list it with a `Fan-in set` entry. It holds the integrator with a `Fan-in pending` entry until every member branch is on origin.