@erclx/canon 5.43.0 → 5.44.0

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.

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

@@ -79,7 +79,7 @@ Dispatch parts from what it checked in three ways. The gate and the worker each
 - Name each self-dispatched worker explicitly with the `worker-` prefix, since that is the role the name marks and a client-derived name is a fragment of the session's identifier
 - Carry the dispatcher's `sessionId` in the launch prompt, since a worker owed two messages has no property on the roster that resolves a controller and a name goes stale inside the window it builds in
 - Report each self-dispatch and the row it fired against loudly enough to follow, since a person no longer watches the launch step happen
-- Stop dispatching once `## Run now` is empty or every row in it reads claimed, rather than waking again to fire on a board nobody is clearing
+- Stop dispatching once `## Up next` is empty or every row left in it is held, rather than waking again to fire on a board nobody is clearing
 - Launch a planner or worker the operator will talk with from the talk shape, with the `-talk` suffix and the brief sentence that tells it so, since a cold launch retires the session the moment its delivery lands while the operator still wants the conversation
 - Retire a talk session only on the operator's word and report it as held open until then, since its delivery says nothing about whether the conversation is over
 - Dispatch every non-release pull request's review to `role-reviewer`, leave each round's messages to it and the worker, and keep one cross-branch pass per wave here, since any pass or relay run here bills the context the wave shares

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

@@ -3,7 +3,7 @@ title: Orchestrator dispatch runbook
 description: The plan-answer gate, the collision check before a self-dispatch, the conflict check against the tracks in flight and the evidence it rests on, the branch the launch names, the one model test applied to each role, the fallback to a human launch, and the loop's stopping condition
 ---
 
-Run this at loop step 4, for a `## Run now` row whose plan is verified, in place of handing the worktree to a human. The conflict check below is where that row is tested against every track in flight, and it is the one statement of what holds a row there.
+Run this at loop step 4, for a `## Up next` row whose plan is verified, in place of handing the worktree to a human. The conflict check below is where that row is tested against every track in flight, and it is the one statement of what holds a row there.
 
 ## Contents
 
@@ -40,6 +40,7 @@ Never shorten a non-conforming slug here, since a rename parts the branch from t
 
 Run `canon tasks plan-answers <plan> --json` and read `launchable` off the record. Branch on `launchable` rather than on the exit code, which a wrapping shell function can flatten to zero and so read a held row as clear.
 
+- Hold a row whose `Waiting on` has not cleared, which no other check reads
 - `launchable: true`: the plan answers itself, so proceed to the branch check.
 - `launchable: false`: report every entry in `open`, each with its question label and stated reason, and hand the row to the human-launch line below
 - Never fill the slot on the operator's behalf, the one move the plan standard forbids outright
@@ -152,6 +153,8 @@ A row qualifies for that pick when its plan carries no open question and touches
 
 Read `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md` once every check above clears, and launch from its build template, which sits beside the review-address and planning shapes that skip these checks. A cloud row launches from `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md`, since the VM shares no plugin or board.
 
+Once the launch succeeds, run `canon tasks promote <stem>`.
+
 ## Fall back to the human
 
 Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one. A shared file alone is not listed.
@@ -171,4 +174,4 @@ Hand the person one command, `/canon:auto-ship <plan>`, naming the row, the plan
 
 ## Stop the loop
 
-Wrapped in `/loop`, re-run the check against `## Run now` on each wake, and stop once the group is empty or every row reads `claimed: true`. Report that once, on the wake that finds it, rather than polling a board nobody is clearing, the reasoning `orchestrator-poll.md` carries for the review trigger.
+Wrapped in `/loop`, re-run the check against `## Up next` on each wake, and stop once the group is empty or every row left in it is held. Report that once, on the wake that finds it, rather than polling a board nobody is clearing, the reasoning `orchestrator-poll.md` carries for the review trigger.

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

@@ -55,7 +55,7 @@ Every measurement this pass takes decides whether a row can start rather than ho
 
 Write the result into the row, since a re-test reported in chat is lost at the next compaction and measured again.
 
-- Rewrite a blocker cell whose test no longer holds, and move the row to the group its new state puts it in
+- Rewrite a blocker cell whose test no longer holds through `canon tasks block <stem> "<blocker>"`, and move the row to the group its new state puts it in through `canon tasks place`
 - Record the measurement in the task's `## Findings` as a line labeled with this session and the date, per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`
 - `### Writing the board` in `role-orchestrator` owns the method, and `canon tasks validate` runs once the board is rewritten and before the report
 
@@ -69,7 +69,7 @@ A backlog row carries no blocker cell, since `${CLAUDE_SKILL_DIR}/../task-board/
 
 ### Moving a cleared row
 
-A cleared row moves out of `backlog.md` onto the bottom of `## Needs a plan`, with a `Waiting on` cell stating what changed and ending with the word `last`.
+A cleared row moves out of `backlog.md` onto the bottom of `## Needs a plan` in one call, `canon tasks place <stem> --group needs-a-plan --bottom --waiting "<what changed>. Last"`.
 
 - `canon tasks validate`'s ordering check reads `last` as the ordinal the bottom placement claims
 - A cell stating only what changed matches neither the ordinal nor the rank reading, raising a finding against the pass's own row

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

@@ -25,7 +25,7 @@ The third trigger reaches a window the first two cannot. A session with three wo
    - Run `task-complete` to archive one the hook left in place
    - A task whose outcomes are standing policy never closes, so hand it to a worker to encode the policy where it is enforced, then cut the outcomes with the reason and archive once that branch merges
    - Encoding it from this session would write a tracked file, which `## Boundaries` in the skill body forbids
-4. Read `.canon/tasks/priority.md` and count entries under its `## Run now` heading that carry a written plan. Keep one in reserve beyond what is running.
+4. Read `.canon/tasks/priority.md` and count the `## Up next` rows whose `Waiting on` has cleared, since a blocked row is no reserve. `## Run now` is what is running, so keep one in reserve beyond it.
 5. Promote from the top of `## Needs a plan`, where the last sweep recorded what to plan next.
    - Depart from that order when something changed under it and say what, since a position nobody honors is the ordering going stale
    - The order is set by whether a task establishes functionality, so prefer one that adds or proves a mechanism over one that trims, tidies, or audits
@@ -53,27 +53,32 @@ That block is the detail. Lead the reply with the three slots under `## Every la
 
 ## Writing the board
 
-Promoting, demoting, and archiving a row all write `.canon/tasks/priority.md`, and this session is the only writer apart from `canon tasks archive`. Moving a task between the board and `.canon/tasks/backlog.md` writes both files, and this session is that file's only writer.
+Write `.canon/tasks/priority.md` through the `canon tasks` verbs alone, each reading the file once, rendering every table, and writing it once. Beside this session, `canon tasks archive` drops a shipped row and `plan-link` promotes a parked one.
 
-- Edit with the file-editing tool, which errors on a non-match, where a shell stream editor or an inline replace exits clean and leaves the board wrong
-- Write both halves of a move before reporting it, since a row on neither surface leaves a task file nothing names in a gitignored folder with no history
-- `canon tasks validate` reports that state, so run it after any move
-- Put the reason a row sits where it does in its Waiting on cell, since a row promoted with the cell left alone carries an order the next sweep cannot check
+| Move                                      | Verb                                                       |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| A backlog row onto the board, or across   | `canon tasks place <stem> --group <group> --waiting "..."` |
+| A planned row to `## Run now` on dispatch | `canon tasks promote <stem>`                               |
+| A row up or down inside its group         | `canon tasks move <stem> --before <stem>`                  |
+| What a row waits on, or why it sits there | `canon tasks block <stem> "<reason>"`                      |
+
+- `place` removes the task's backlog line in the same call, so a row never sits on both surfaces or on neither
+- Demoting a row to `backlog.md` has no verb yet. Add the backlog line first, then delete the row with the file-editing tool, which errors on a non-match.
+- Put the reason a row sits where it does in its Waiting on cell through `block`, since a row promoted with the cell left alone carries an order the next sweep cannot check
+- Run `canon tasks validate` after any move, which reports a hand edit the verbs would have refused
 
 ### Columns and read-back
 
-Each column carries a fact a later reader checks rather than reasons again.
+The verbs derive the Task, Touches, and Plan cells from the task file and its live plans, so a later reader checks them rather than reasoning again.
 
-- Put a pointer in the Plan column, never prose, since `auto-ship` refuses at its guard when the column leads to no plan, spending a dispatch
-- `## Run now` claims a written plan covers every open outcome, which is what the pointer backs
-- Name the file set in the Touches column, which feeds the merge order and the shared paths a dispatch names, so step 6's hold call stays checkable later
-- Re-resolve every Plan pointer after anything archives a plan
-- Read the file back after writing it, since the row that lands is the row a worker acts on
+- `place` and `promote` refuse a row the target group's test fails, so a Plan cell never leads `auto-ship` to no plan and spends a dispatch
+- A Touches cell differing from its plan's list is `touches-stale`. Change the plan's list rather than the cell, and step 6's hold call reads the result.
+- Read the board back after a write, since the row that lands is the row a worker acts on
 
 ### Stale plan pointers
 
 A Plan pointer goes stale from a merge this board never sees. The `post-merge` hook moves a plan to `.canon/plans/archive/` through `canon tasks archive` and rewrites the citation in the archived task file alone.
 
-- A row for a task still on the board keeps pointing into `.canon/plans/` at a file that has moved
+- A row for a task still on the board keeps pointing into `.canon/plans/` at a file that has moved, until the next verb call re-derives every Plan cell from the live plans
 - `task-complete` marks outcomes on each worker's branch and moves nothing, so the move lands at the merge
 - The board then reads as correct until a pointer is followed

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

@@ -72,7 +72,8 @@ The plan standard fixes that block for a feature plan, and a groundwork or intak
 
 ## The board is read-only
 
-- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md`. Both are gitignored, so an overwrite drops a row with no history to recover it from.
+- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md` by hand. Both are gitignored, so an overwrite drops a row with no history to recover it from.
+- `canon tasks plan-link` is the one board write this role makes. It moves the row out of `## Needs a plan` once the plan is linked, in one read and one write a hand edit cannot match.
 - Never write the task file. The record is the whole output, and a row edited from here changes what the controller reads back as the board's state.
 - Report what the row got wrong rather than repairing it, such as a stale count or a dead path, in the record and the handback. The controller decides which carries the correction.
 - Leave the cross-feature call alone. `priority.md` shows enough to write a confident merge order off a partial picture, which is the failure this boundary prevents.

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

@@ -51,6 +51,15 @@ A painted pull request needs a server in this worktree for `canon pr local` to f
 
 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
+
+A plan carrying a `**Design references:**` section names the accepted design for the surface it changes. Open it before building, since the build matches it and a worker that reads the dark image alone ships a light theme nobody saw.
+
+- Open each cited folder's light and dark images and its frame HTML before the first edit to that surface
+- Take sizes, spacing, and colors from the frame HTML rather than from the image
+- Report a reference that does not resolve in the working tree, naming the path, rather than building without it
+- Leave `None identified.` as it stands and build without a reference
+
 ## Scope after dispatch
 
 The plan is the scope from the dispatch on. A late ask restarts both reviews, and one pull request took about four UI review rounds from asks that arrived mid-build.

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

@@ -0,0 +1,40 @@
+---
+name: script-screencast
+description: Why a recording script ships pre-seeded rather than blank, what the four discovery questions buy, and why the draft stays stack-agnostic
+---
+
+# Script screencast requirement
+
+## Gap
+
+Without this skill, a recording plan arrives as a wall of blank fields, so the user fills a template instead of editing a draft and the work the skill was meant to do lands back on them. The opposite failure costs more. A session that skips discovery guesses the audience, the length, and the hero moment, then writes five beats for a video nobody asked for, and every one of them has to be thrown away rather than edited.
+
+A draft that names the recording software, the editing software, or the window manager pins the script to one machine and one person's setup, so it stops being reusable the moment anyone else records. And re-invoking to refine silently overwrites the edits the user made in the file, which is the one failure that destroys work rather than wasting it.
+
+## Must
+
+- Read project context and recent commits before proposing, since what shipped recently is usually the subject
+- Ask exactly four discovery questions, each carrying a default derived from that context
+- Wait for answers rather than reading silence as acceptance
+- Pre-seed every section with concrete content so the draft is shippable as written and the user edits down
+- Derive the slug from the topic and the discovery answers
+- Write to `demos/<slug>/beats.md` at the project root, the committed folder the rest of the demo lives in, and print that path on its own line
+- Seed a wrap section naming intro, outro, and music with a default each, so the choice of what surrounds the take is made at draft time rather than discovered at compose time
+
+## Must not
+
+- Name recording software, editing software, fonts, or window managers
+- Record, edit video, or generate captions
+- Re-run against an existing draft to refine it, since re-running overwrites
+- Infer the hero moment without asking, which is the beat the whole script is built around
+
+## Guards
+
+- No topic provided: stop rather than guessing what is being recorded
+
+## Out of scope
+
+- Producing the recording, which `record-screencast` owns
+- Refining an existing draft, which is a direct edit of the file
+- Slide decks, which `make-deck` owns
+- Where the recording ships, which the draft lists and the user decides