@erclx/canon 5.43.0 → 5.45.0

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

@@ -0,0 +1,161 @@
+---
+name: pick-by-eye
+description: Drafts several candidates for a decision judged by looking, lays them out side by side as frames on one canvas page, hands the operator the address, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write what to look at on a change already made, which is `ui-checklist`, or to script a recording, which is `script-screencast`.
+metadata:
+  family: decide
+---
+
+# Pick by eye
+
+Some decisions are settled by looking rather than by reasoning, and no draft is wrong until one is picked. Every step here puts several candidates in front of the operator and keeps the real surface untouched until they have chosen.
+
+The candidates live on the local design canvas, the surface `canon:canvas-board` drives. Every verb below is `canon canvas`, and `${CLAUDE_SKILL_DIR}/../canvas-board/references/canvas.md` fixes the content format a frame takes. Read that reference before writing the first frame.
+
+## Guards
+
+- If the request names one answer and asks for it to be built, stop: `❌ This names one answer, so there is nothing to pick between. Use /canon:plan-feature.`
+- If the decision has no visible form, stop: `❌ Nothing to look at. Drafting candidates needs a decision a render can show.`
+- Draft no candidate for a decision the operator has not asked to make, since options everywhere spend their attention rather than saving it
+
+## Step 1: name the decision and the arms
+
+1. State the decision in one sentence, naming what changes between arms and what stays fixed.
+2. Emit the design read in the run's output, in the form `design-taste` fixes, taking the layer from its ordered catalog. The arms differ at that layer, and a missing read is visible.
+3. Derive a kebab slug from that sentence. The first round's page is `<slug>`, and Step 5 names later rounds `<slug>-2`, `<slug>-3`, and so on.
+4. Write one arm per candidate, each carrying an id, a label, and what the arm costs. An arm with no stated cost is not an option.
+5. Make the current state arm `0`, so the baseline is a candidate rather than an absence. A decision with nothing shipped yet says so and starts at arm `1`.
+6. Stop at three to five arms. Two is a comparison the operator can hold in prose, and past five the pick stops being a look and becomes a sort.
+
+Inside a live `plan-groundwork` track, renders land in the track's own `evidence/<slug>/renders/`, since a candidate render is evidence its decision file cites. Everywhere else they land in session scratch.
+
+## Step 2: draft the arms as frames on one canvas page
+
+Every arm of a round sits as one frame on one canvas page, side by side. The operator judges that page, never a set of separate images compared from memory.
+
+1. Start the canvas the way `canon:canvas-board` Step 1 states, unless this run already has. Note whether this run started the server, since Step 6 stops only a server this run started.
+2. Add the round's page with `canon canvas page add <page> --json` and record it on the run's list of pages. A name `canvas list` already shows is somebody else's, so take the next free suffix.
+3. Add each arm with `canon canvas frame add <page> arm-<id> --width <px> --height <px> --json`. Step 6's archive keys on the `arm-<id>` names.
+4. Write each arm's whole document to the `path` the add verb reported. From a linked worktree, take the heredoc route `canon:canvas-board` Step 3 gives for a main-root write.
+5. Lay the frames out in one row, in arm order, with `canon canvas frame move <page> arm-<id> --x <px> --y <px> --json`.
+
+The `canvas-board` start reads `canon canvas list --json`, serves with `canon canvas serve --json` in the background unless the operator named an address that answers, and checks the shell's body holds a `<script` tag. A refused serve or a blank shell stops the run with its `reason`, and no file stands in for a canvas.
+
+Set each frame's width to the one the arm is judged at. A frame renders at its own layout width on the canvas and in a capture alike, so a layout decision needs no device toolbar.
+
+### What every frame carries
+
+Each frame carries its own label and follows the canvas theme, so the set reads as one comparison.
+
+- Label each arm inside its frame with its id and its cost, since the composite capture draws no captions
+- Theme every arm off the `data-theme` attribute the canvas sets on each frame's root, so the theme toggle sets the whole set at once. A set spanning both themes cannot be compared.
+- Give no arm a script that stores a theme and reapplies it on load. It overwrites the toggle, and a fresh browser profile hides the fault.
+
+### Default path and live app
+
+A running app under decision takes the live-app branch, and every other decision takes the default path.
+
+- Live app: lift the rendered markup and link a copy of the built stylesheet rather than inlining, per `${CLAUDE_SKILL_DIR}/references/live-arms.md`
+- Default path: inline every style, script, and asset. A frame resolves nothing outside its own page folder, so a build step or network font silently drops out.
+- Default path: name a real font first in the stack, one the machine has or the frame embeds, such as the project's own family. A generic keyword such as `system-ui` resolves differently per machine.
+
+The capture refuses a frame that would rewrap against a substitute font rather than ship a false comparison. A frame naming no font is refused on whatever the default resolves to.
+
+### What varies
+
+Vary one property across the arms, since a pick cannot say which of three differences decided it.
+
+- Vary the property the decision is about. Holding composition fixed and varying color produces five skins of one design, and a palette cannot be picked ahead of the composition it serves.
+- Grey-box the arms when the declared layer sits below typography, per `design-taste`, and say the set is grey-boxed when handing it over
+- Do not grey-box a set judged at composition that carries a finished palette, since the operator looks at the higher layers instead of the question
+
+## Step 3: render and hand off
+
+Render the page and look at what came back before handing anything over:
+
+```bash
+canon canvas capture <page> --composite --json
+```
+
+- Point `--out` at `evidence/<slug>/renders/<page>.png` inside a live track, and leave the scratch default elsewhere. Step 6 archives the picked round alone.
+- Read the PNG's `path` off the record. The composite shows each frame in its default theme, so check the other theme on the live canvas.
+- A capture refusing on a font names the family it read. Take the repair `canon:canvas-board` Step 6 gives and capture again.
+
+When `canon canvas capture` refuses for a missing browser binary, report it and name `bunx playwright install chromium` as the repair. Stop the canvas server if this run started it, then stop rather than describe an arm nobody has seen.
+
+### Handing over
+
+Hand over the address rather than a description. Emit the canvas link first on its own line, naming the page, then the PNG path on its own line.
+
+- A still answers how a thing looks and none of a hover, a scroll-linked position, or a pace, which the live frame does
+- Never report a visual result you have not looked at, since a claim about appearance with no render behind it is a guess
+- Look to judge rather than to confirm. Name the weakest thing on the page in a sentence, fix it where that sentence would embarrass the work, and say what remains.
+
+## Step 4: take the pick
+
+Put the choice to the operator through the structured question surface, since a call the operator's preference decides always routes through it rather than through prose.
+
+- Emit the link ahead of the question call and again in the question's text, since some surfaces render the card alone
+- One option per arm, labeled with the arm's id and carrying its cost as the description
+- Rank the recommendation first and mark it `(Recommended)`
+- Author the real arms only. The surface appends its own free-text and reopen escapes, and a duplicate is rejected.
+
+### Taking the answer
+
+Take no pick on the operator's behalf when two arms are both defensible and the difference is taste. That call is theirs, and a silent one is the failure this skill exists to prevent.
+
+Read `canon canvas selection --json` when the answer points at the canvas, such as "the selected one". Resolve it against the record's `page` as well as its `frame`, since every round reuses the `arm-<id>` names.
+
+| Selection                                                        | Reading                                        |
+| ---------------------------------------------------------------- | ---------------------------------------------- |
+| A frame on the current round's page                              | The pick                                       |
+| A frame on an earlier round's page                               | A revert, so name the round back before acting |
+| A fresh element inside a picked frame                            | A correction Step 5 carries by its `index`     |
+| `selection: null`, a page this run did not add, or `stale: true` | No answer, so ask again rather than guess      |
+
+## Step 5: loop on the pick
+
+1. Add each iteration as its own page, recorded on the run's list. An overwritten page cannot be reopened, and the losing round stops a correction re-proposing a rejected arm.
+2. Write fresh arms off the pick and return to Step 2 where the correction opens a new question. Revise the one arm's frame where it does not.
+3. Re-render, hand off again, and take the next answer.
+4. Repeat until the operator says it is right. A run stopping because the arms stopped differing has stopped early.
+5. Hold the real surface untouched across every iteration. Nothing outside the run's own canvas pages changes until the pick is final.
+
+## Step 6: close
+
+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.
+
+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.
+
+## Reading a measurement
+
+A capture proves appearance and a measurement proves a relationship, so reach for the second whenever the claim is a number, such as a contrast ratio, a column width, or a tap target. `canon drive` runs the probes and ships the failure modes each one carries.
+
+- Composite alpha before reading a color. A `color-mix` toward transparent resolves to channels plus an alpha, and reading them as opaque reports a color nobody sees.
+- Sample inside the shape. A patch at a bounding box corner misses a round control and reads the page behind it.
+- Ask whether a reader would see the thing. A panel sized a healthy 1517 by 639 passed every size check while sitting 1868px above the viewport.
+
+`canon drive` reports findings and never gates. Read its record as evidence for the operator rather than as a filter over the arms, since the probe catalog has not earned the right to drop one.
+
+## What this delegates
+
+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-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
+
+### Git and review
+
+Commits, review, and the canvas mechanics each have an owner.
+
+- `git-stage`, `git-pr`, and `git-followup` carry the commits and the pull request
+- `review-pr` and `review-address` run the review pass
+- `canon:canvas-board` carries the canvas start-and-check sequence, the main-root write route for a frame, and the selection and capture refusals

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

@@ -29,7 +29,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `canon/REQUIREMENTS.md`: feature scope and non-goals
 - `.canon/tasks/index.md`: current scope and status, then any task file the feature relates to
 
-Also read `canon/DESIGN.md` when the feature touches code or UI, for visual intent and component rules, with values read from the stylesheet its lead names. Skip it for prose, docs, catalog, or config-only changes.
+Also read `canon/DESIGN.md` when the feature touches code or UI, for visual intent and component rules, with values read from the stylesheet its lead names. Skip it for prose, docs, catalog, or config-only changes. For a UI feature, read `canon/design/index.md` too, if it exists, for the surfaces with an accepted design.
 
 Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match.
 
@@ -69,6 +69,7 @@ Every `- Suggested:` line takes senior judgment, picking the best option in one
 
 - 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
 

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

@@ -69,16 +69,17 @@ A staged batch is a concern of its own and takes its own file rather than a `**B
 
 The document opens with `# Feature: <short title>` and one paragraph stating what is being built and why now. The sections below follow in this order.
 
-| Section               | Holds                                                                     | Required                                   |
-| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------ |
-| `## Summary`          | three to five one-line bullets: the goal, the deliverables, the trade-off | Always                                     |
-| `**Constraints:**`    | durable rules the work must respect                                       | When supplied                              |
-| `**Files to touch:**` | each file with a one-line reason                                          | Always                                     |
-| `**Verification:**`   | the test or command that proves each outcome                              | Always                                     |
-| `**Risks:**`          | conflicts, coupling, and the tricky spots                                 | Always                                     |
-| `**Review focus:**`   | the inputs or states that would break the change, for the reviewer        | Always                                     |
-| `**Questions:**`      | numbered open decisions, each with a suggestion and an answer slot        | Always                                     |
-| `**Sources:**`        | the outside sources a decision rests on, each with its quoted passage     | When a decision rests on an outside source |
+| Section                  | Holds                                                                       | Required                                          |
+| ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------- |
+| `## Summary`             | three to five one-line bullets: the goal, the deliverables, the trade-off   | Always                                            |
+| `**Constraints:**`       | durable rules the work must respect                                         | When supplied                                     |
+| `**Files to touch:**`    | each file with a one-line reason                                            | Always                                            |
+| `**Design references:**` | the tracked design folders the change builds against, each with its surface | When Files to touch names a rendered-surface file |
+| `**Verification:**`      | the test or command that proves each outcome                                | Always                                            |
+| `**Risks:**`             | conflicts, coupling, and the tricky spots                                   | Always                                            |
+| `**Review focus:**`      | the inputs or states that would break the change, for the reviewer          | Always                                            |
+| `**Questions:**`         | numbered open decisions, each with a suggestion and an answer slot          | Always                                            |
+| `**Sources:**`           | the outside sources a decision rests on, each with its quoted passage       | When a decision rests on an outside source        |
 
 - Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the others are labels over lists rather than sections of prose.
 - A section in the other spelling is still that section, since `## Risks` and `**Risks:**` name one thing, and either spelling breaks a depth run
@@ -133,6 +134,15 @@ A batch in a fan-in set declares its side in a constraint bullet, ``Fan-in membe
 
 A constraint naming a `.canon/ready/` folder is a third shape beside the hold and the shared path. It makes that folder's files the verbatim source for the paths this plan's `**Files to touch:**` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
 
+### Design references
+
+A plan whose `**Files to touch:**` names a rendered-surface file (`.tsx`, `.jsx`, `.astro`, `.vue`, `.svelte`, `.html`, or `.css`) carries this section. It tells the building session which accepted design to open before it writes a line.
+
+- Give each entry a folder path under `canon/design/` and the surface it governs, as one bullet
+- Write `None identified.` when the project has no `canon/design/` folder or no folder governs the change, so the section reads as considered
+- Cite a tracked folder only, since the building session opens its light and dark images and its frame HTML from the working tree
+- `canon records validate plans` reports `section-missing` for a plan that names a rendered-surface file and omits the section
+
 ### Verification
 
 Every outcome reaches the review with its proof named.
@@ -233,6 +243,10 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 
 - `<path/to/file>`: <reason>
 
+**Design references:**
+
+- `canon/design/<surface>/`: <the surface it governs>
+
 **Verification:**
 
 - <outcome>: `<test or command that proves it>`

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

@@ -37,7 +37,7 @@ Write only inside `.canon/groundwork/<nn>-<slug>/`. A feature plan, source chang
 
 What a spike produces stays inside the track, under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches only top-level entries, so a nested folder cannot be mistaken for a track, and scratch holds only what can be deleted without loss.
 
-A `draft-and-pick` run invoked from inside a live track follows its own branch for this. It writes its renders to `evidence/` here, and drafts its candidates as canvas pages under `.canon/canvas/` that its close deletes.
+A `pick-by-eye` run invoked from inside a live track follows its own branch for this. It writes its renders to `evidence/` here, and drafts its candidates as canvas pages under `.canon/canvas/` that its close deletes.
 
 ### Reading and backing
 

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

@@ -105,7 +105,7 @@ This overrides the paths-only reporting the project states generally, which stay
 - `.canon/intake/<nn>-<slug>/05-coverage.md` gains items 6 to 8 under a new `## What the merge gate covers`
 - `.canon/intake/<nn>-<slug>/00-overview.md` cluster rows and verdict counts updated
 
-**Routing:** <N> plan-ready, <N> groundwork candidates, <N> already settled
+**Routing:** <N> ready to plan, <N> groundwork candidates, <N> already settled
 
 **Open questions:** <N> awaiting your call
 

package/claude/skills/plan-ready/REQUIREMENT.md

@@ -0,0 +1,54 @@
+---
+name: plan-ready
+description: Why writing a ready folder, its overview, the thin plan, and the task row is one invocation rather than four hand writes, and where the boundary against the planning and shipping skills falls
+---
+
+# Plan ready requirement
+
+## Gap
+
+Without this skill, a session holding finished files that hands them to a worker:
+
+- Writes the folder, the overview, the plan, and the task row as four separate hand writes, and the four drift from each other because nothing compares them.
+- Lists a destination in the overview that the plan's `**Files to touch:**` omits, or the reverse. The omitted path is invisible to `plan-reach`, so a second track writes the same file and neither side finds out.
+- Picks the next ordinal by reading only the live folder, and reuses a number an archived folder already spent, which the pull request that shipped it cites by name.
+- Picks a phase label by scanning the live board alone, which is the scan that let two sessions hand out one label within minutes of each other.
+- Reads the label bare, which reserves nothing and returns one a live claim already holds until that claim's task file lands.
+- Leaves the plan's `**Constraints:**` without a line naming the folder as the verbatim source, so the worker reads the files as inspiration and writes its own version.
+- Leaves a note, an alternate, or a draft passage in the folder beside the real files, so the worker guesses which one is the source.
+- Writes into the main worktree root from a linked worktree with `Edit` or `Write`, which the isolation guard refuses, and takes the refusal's redirect into a second gitignored copy no later session reads.
+- Reports the handoff as done while the archive move at the end, which no verb performs, is left for someone to remember.
+
+## Must
+
+- Refuse before writing when the operator has named no finished file, since a folder assembled from a description is a plan with extra steps.
+- Read the ordinal from the live folder and its archive together, so a spent number is never reused.
+- Take the phase label from `canon tasks next-label --claim` rather than from a scan of its own or a bare read, and stop on a binary that predates the flag rather than falling back.
+- Derive the overview's `destinations` and the plan's `**Files to touch:**` from one list, and compare the two before reporting, so neither can name a path the other lacks.
+- Write the plan's `**Constraints:**` line naming the folder as the verbatim source.
+- Copy each finished file whole to its destination path inside the folder, and carry nothing else into it.
+- Write the plan and the task through `canon tasks plan-link`, `canon records validate plans`, and `canon markdown audit` rather than by restating what those verbs check.
+- Place the task's row by the three branches `task-board` Step 4 states, so a solo project never ends with a task file on no surface.
+- Route a write at the main root from a linked worktree through `Bash`, the way `session-worktree` routes it.
+- Name the archive move in the closing report, since the skill writes a folder that stays live until someone moves it.
+
+## Must not
+
+- Edit a finished file. The worker copies verbatim, so a change made here is a change the warm session should have made before invoking the skill.
+- Hardcode a branch type, which `branch.md` owns, or restate the folder shape, which `ready.md` owns.
+- Write `priority.md` or `backlog.md` where an orchestrator is on the roster or the session is a worker or planner, since one board writer at a time is what keeps a gitignored board safe. Those two cases report the row instead.
+- Automate the archive move. No verb owns the relocation, and a skill doing it by hand would be the second copy of a step the standard already states.
+- Dispatch or start the worker, which belongs to whoever runs the board.
+
+## Guards
+
+- No finished file named, stop: `❌ No finished file named. A ready folder carries text that already exists, so write the files first or use /canon:plan-feature.`
+- A named file that does not resolve, stop: `❌ <path> does not exist. Name a file that is already written.`
+
+## Out of scope
+
+- `plan-feature` writes a plan describing a change nobody has written yet. This begins from text already written and writes a plan thin enough to point at it.
+- `role-worker` copies the folder into a worktree and ships it. This stops once the three artifacts exist.
+- `task-board` creates a task file for a row with no ready folder. This writes the row it needs beside the folder and calls the same verbs.
+- `git-ship` ships a branch, and a ready folder never reaches one.
+- `references/ready.md` owns the folder's shape and lifecycle, and this skill owns the procedure that produces it, the way `write-human` and the `markdown` rule split.

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

@@ -0,0 +1,136 @@
+---
+name: plan-ready
+description: Writes a ready folder for finished files, its `00-overview.md`, the thin plan that points at it, and the task with a board row placed, reported to an orchestrator, or left to the operator, in one invocation. Use when asked to "write a ready folder", "hand these files to a worker", "package these finished files for a worker", "make a ready handoff", or when a session already holds the exact text of a skill, rule, or doc and a worker should copy it rather than author it. Do NOT use to plan a change nobody has written yet, which is `plan-feature`, to copy a folder into a worktree and ship it, which is `role-worker`, or to file a task with no finished files behind it, which is `task-board`.
+metadata:
+  family: generate
+---
+
+# Plan ready
+
+A warm session that has already written a change hands the exact text to the worker that ships it. This skill writes the three artifacts that handoff needs and stops before anyone is dispatched.
+
+Read these in parallel before writing:
+
+- `${CLAUDE_SKILL_DIR}/references/ready.md`: the folder layout, the overview frontmatter, the mirrored tree, and the thin-plan contract
+- `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`: the plan's sections and its answer contract
+- `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`: the task file's shape and origin lines
+- `${CLAUDE_SKILL_DIR}/references/assembly.md`: the overview and thin-plan templates and the destination match check
+
+## Guards
+
+- If the operator named no finished file, stop: `❌ No finished file named. A ready folder carries text that already exists, so write the files first or use /canon:plan-feature.`
+- If a named file does not resolve, stop: `❌ <path> does not exist. Name a file that is already written.`
+- Resolve `<main-root>` as `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. The folder, the plan, and the task all live there.
+
+## Step 1: read the finished files
+
+1. Take each finished file with the destination path the operator gave it. A file arriving with no destination is asked for once, since the mirrored tree cannot place it.
+2. Read every file whole. The overview states what the worker still owns beyond copying, and that comes off the files, not off the operator's description of them.
+3. Take the branch type from `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`, never from a list carried here.
+4. Derive one kebab slug for the change. The folder, the plan, and the task all carry it.
+
+## Step 2: allocate the ordinal and the label
+
+Read `<main-root>/.canon/ready/` and `<main-root>/.canon/ready/archive/` together and take the highest `<nn>` across both, plus one. A folder set with no entry takes `01`. Keep this skill-local. No verb allocates a ready ordinal, and two writers running at once can claim one number, so re-read the folder immediately before Step 3 writes.
+
+Claim the label through the verb rather than reading it bare or scanning for it:
+
+```bash
+canon tasks next-label --claim --json
+```
+
+The claim reserves the label under `.canon/ordinal-locks/`, so a second session allocating at the same moment gets the next one. A bare read reserves nothing and can return a label a live claim already holds.
+
+Branch on the record's `reason` rather than on the exit code, taking `label` from a record that carries one.
+
+- `label-contended` means re-run the claim
+- Report the verb as unavailable and stop when the binary carries no `next-label` subcommand, or prints no record for an unknown `--claim`, since it predates the flag
+- Never fall back to a bare read or a label picked by hand, which reopens the collision the claim exists to prevent
+
+## Step 3: write the overview
+
+Write `<main-root>/.canon/ready/<nn>-<slug>/00-overview.md` from the template in `${CLAUDE_SKILL_DIR}/references/assembly.md`. Set `destinations` from the Step 1 list and nothing else, and state in prose what the worker still owns, or `nothing further` where the files are the whole change.
+
+## Step 4: mirror the tree
+
+Copy each finished file to `<main-root>/.canon/ready/<nn>-<slug>/<destination path>`, one command per file, so the tree mirrors the destinations exactly.
+
+```bash
+install -D -m 0644 <source> <main-root>/.canon/ready/<nn>-<slug>/<destination path>
+```
+
+- Copy whole and edit nothing. A change wanted now is made in the source file first and copied after.
+- Carry no notes, alternates, or drafts into the folder. Anything else belongs in the plan or the pull request body.
+- Write each of these at the main root, routed the way `session-worktree` states. Create a whole new file with a heredoc.
+
+## Step 5: write the thin plan
+
+Write `<main-root>/.canon/plans/feature-<slug>.md` from the template, by heredoc, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+
+- List every Step 1 destination under `**Files to touch:**`, each with one clause on why it changes, pointing at the folder's copy rather than restating it.
+- Add a `**Constraints:**` line naming the ready folder as the verbatim source for those paths.
+- Name the branch type from Step 1 in `## Summary`. Write `None identified.` under `**Questions:**` unless a call is genuinely the operator's.
+
+Run the match check in `${CLAUDE_SKILL_DIR}/references/assembly.md` before going further. The two lists are one list, and a path in either without the other stops the run.
+
+## Step 6: write the task
+
+Write `<main-root>/.canon/tasks/<label>-<slug>.md` by heredoc from the label Step 2 claimed, never calling the verb again, which would claim another. Its frontmatter, H1, and `## Outcomes` follow `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`.
+
+Write a `Ready:` line beside the `Plan:` line pointing at the folder, then point the task at the plan through the verb:
+
+```bash
+canon tasks plan-link <task-stem> .canon/plans/feature-<slug>.md --json
+```
+
+Branch on the record rather than on the exit. The `Ready:` line orients a worker reading the task, and `canon tasks archive` reads it to move the folder on ship.
+
+### Place the row
+
+A task file with no row is a dropped task, so place the row in the same pass. The plan exists and no worker holds it yet, so the row takes `## Up next`, per the tests in `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`.
+
+A path `canon tasks plan-reach` reports as claimed is a shared file rather than a hold. Name each one and its holder wherever the row is reported, so whoever controls the board decides whether a contract, a relocation, or a sweep holds the row.
+
+### Check the roster
+
+Check the roster the way `canon:task-board` Step 4 does, reading `canon sessions list --self --json` for this session and `canon sessions list --json` for a same-repository row under another `sessionId` whose `name` starts with `orchestrator-`. A refused read counts as failed.
+
+- **Orchestrator found.** Write neither file. Message that session with the row's title, the plan link, and the group with its reason, so two sessions never write the board at once.
+- **Not found, and this session's name starts with `worker-` or `planner-`.** Write neither file, since both role bodies ban a board write. Report the row and its group in Step 8.
+- **Not found otherwise, or the roster read fails.** Run `canon tasks place <stem> --group up-next --waiting "Planned, not dispatched yet"`, since stopping on a failed read strands the task.
+
+Say which branch fired in Step 8.
+
+Regenerate the task index after writing, since a hook on `Write|Edit` never fires on `Bash`:
+
+```bash
+canon indexes regen .canon/tasks
+```
+
+## Step 7: validate
+
+```bash
+canon records validate plans --json
+canon markdown audit <main-root>/.canon/ready/<nn>-<slug>/00-overview.md
+canon markdown audit <main-root>/.canon/plans/feature-<slug>.md
+```
+
+Fix what the records name in the files this run wrote and re-run once. Report a finding on a file it did not write, such as a neighbor folder missing its overview, without repairing it.
+
+## Step 8: report
+
+```plaintext
+✅ Ready folder written: .canon/ready/<nn>-<slug>/
+   Plan: .canon/plans/feature-<slug>.md
+   Task: .canon/tasks/<label>-<slug>.md
+   Row: <label> <title>, <written under ## Up next | reported to <orchestrator name> | left for the operator to place>, <reason>
+   Archive on ship: canon tasks archive moves the folder to .canon/ready/archive/<nn>-<slug>/
+```
+
+Name the archive move every time, so whoever ships knows the verb carries the folder and needs no step of their own.
+
+## Rules
+
+- Edit no finished file. The worker copies verbatim, so a change belongs in the source before this runs.
+- Restate nothing the standards own. A shape question is answered by `ready.md` and a plan question by `plan.md`.
+- Dispatch nothing. Starting the worker belongs to whoever runs the board.

package/claude/skills/{draft-ready → plan-ready}/references/assembly.md

@@ -5,7 +5,7 @@ description: The overview and thin-plan templates for a ready folder, and the ma
 
 # Assembly
 
-Loaded from Step 3 and Step 5 of `draft-ready`. The shape rules live in `${CLAUDE_SKILL_DIR}/references/ready.md` and `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, so this file holds the fill-in forms and the one check that compares them.
+Loaded from Step 3 and Step 5 of `plan-ready`. The shape rules live in `${CLAUDE_SKILL_DIR}/references/ready.md` and `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, so this file holds the fill-in forms and the one check that compares them.
 
 ## The overview
 

package/claude/skills/{draft-ready → plan-ready}/references/ready.md

@@ -27,7 +27,7 @@ The folder holds the finished files at their destination paths, so the worker co
 
 ## Scope
 
-The `draft-ready` skill owns the procedure, and this standard owns the shape. It governs a ready folder under `.canon/ready/<nn>-<slug>/`, being its layout, ordinal naming, the overview's frontmatter, what the mirrored tree holds, the thin-plan contract that ships it, and the lifecycle from the live folder to the archive.
+The `plan-ready` skill owns the procedure, and this standard owns the shape. It governs a ready folder under `.canon/ready/<nn>-<slug>/`, being its layout, ordinal naming, the overview's frontmatter, what the mirrored tree holds, the thin-plan contract that ships it, and the lifecycle from the live folder to the archive.
 
 Does not govern:
 

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

@@ -7,7 +7,7 @@ description: Why compiling and running a screencast draft needs a routed skill r
 
 ## Gap
 
-Without this skill, `draft-screencast` writes a draft and names `canon demo compile` as the next step, and nothing after that routes a session there or to `canon demo run`. An operator has to know both verbs, type them in order, and read the compile record for unresolved fields by hand. A session that fills one in on its own reproduces the exact failure `canon demo run`'s `plan-unresolved` reason exists to catch, one layer up where nothing enforces it.
+Without this skill, `script-screencast` writes a draft and names `canon demo compile` as the next step, and nothing after that routes a session there or to `canon demo run`. An operator has to know both verbs, type them in order, and read the compile record for unresolved fields by hand. A session that fills one in on its own reproduces the exact failure `canon demo run`'s `plan-unresolved` reason exists to catch, one layer up where nothing enforces it.
 
 ## Must
 
@@ -25,7 +25,7 @@ Without this skill, `draft-screencast` writes a draft and names `canon demo comp
 - Guess or fill a target, a URL, or any other unresolved field
 - Drive the application through anything other than `canon demo run`
 - Install HyperFrames, vendor it, or restate its composition rules, which its own skills own
-- Assume this skill's own invocation frequency needs no check. `draft-screencast`'s closing block names it by hand, but whether anything else reaches for it beyond that pointer or an operator typing its name has no answer at creation time, so a review pass some months in should read that back rather than take it on faith.
+- Assume this skill's own invocation frequency needs no check. `script-screencast`'s closing block names it by hand, but whether anything else reaches for it beyond that pointer or an operator typing its name has no answer at creation time, so a review pass some months in should read that back rather than take it on faith.
 
 ## Guards
 
@@ -33,6 +33,6 @@ Without this skill, `draft-screencast` writes a draft and names `canon demo comp
 
 ## Out of scope
 
-- Drafting the beats, which `draft-screencast` owns
+- Drafting the beats, which `script-screencast` owns
 - Filling an existing plan's target or URL, which is the operator's own edit
 - Verifying a recording beyond its own caption, which nothing in the toolkit does yet

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

@@ -1,6 +1,6 @@
 ---
 name: record-screencast
-description: Drives a screencast draft through to a recording. Compiles it with `canon demo compile` when no plan exists yet at the default path, skipping compile when one is already there, runs `canon demo run` once nothing is unresolved, then composes the take into a finished mp4 through HyperFrames when the draft's wrap section asks for anything. Reports every unresolved field from the compile or run record and stops rather than guessing one. Use when asked to "record the screencast", "run the demo", "compile and record this draft", or right after `draft-screencast` prints its next-step line. Do NOT use to draft the beats, which is `draft-screencast`, or to fill in a plan's target or URL, which is the operator's own edit.
+description: Drives a screencast draft through to a recording. Compiles it with `canon demo compile` when no plan exists yet at the default path, skipping compile when one is already there, runs `canon demo run` once nothing is unresolved, then composes the take into a finished mp4 through HyperFrames when the draft's wrap section asks for anything. Reports every unresolved field from the compile or run record and stops rather than guessing one. Use when asked to "record the screencast", "run the demo", "compile and record this draft", or right after `script-screencast` prints its next-step line. Do NOT use to draft the beats, which is `script-screencast`, or to fill in a plan's target or URL, which is the operator's own edit.
 metadata:
   family: generate
 ---
@@ -9,7 +9,7 @@ metadata:
 
 ## Guards
 
-- If no draft path is given, stop: `❌ No draft path. Pass the path draft-screencast printed.`
+- If no draft path is given, stop: `❌ No draft path. Pass the path script-screencast printed.`
 - Never guess or fill an unresolved field, a target, a URL, or anything else the compile or run record names. Report it and stop.
 - Filling one in reproduces the failure `canon demo run`'s `plan-unresolved` reason exists to catch, one layer up where nothing enforces it
 - Never pass `--force` to compile. A plan at the default output path may carry timing tuned by hand that the draft cannot reproduce.