@erclx/canon 5.25.0 → 5.27.0

package/README.md

@@ -43,8 +43,8 @@ claude plugin install canon@canon
 ```
 
 <picture>
- <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/install.png">
- <img src="assets/evidence/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
+ <source media="(prefers-color-scheme: dark)" srcset="assets/frames/install.png">
+ <img src="assets/frames/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
 </picture>
 
 The skills land as `/canon:<name>`. If your session was already open, run `/reload-plugins` to pick them up.
@@ -68,7 +68,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Standards      | Authoring conventions for commits, branches, plans, tasks, and markdown                                                  | Opened by name, read by name with `canon standards <name>`      |
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
-| Slides         | A `SLIDES.md` source format with a layout catalog, or a folder of HTML slides rebuilt as editable shapes                 | `canon slides render` writes PowerPoint                         |
+| Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                           | `canon slides render` writes PowerPoint                         |
 | Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                              | `canon teach`                                                   |
 | Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                         | `canon canvas serve`                                            |
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
@@ -98,6 +98,7 @@ Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at
 - [AI workflow](docs/workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Skill map](docs/workflow/skill-map.md): plugin skills grouped by the moment a project meets them
+- [Skill map on request](docs/workflow/skill-map-on-request.md): plugin skills that serve a request rather than a moment
 - [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design and wireframe authoring
 - [Target projects](docs/target/projects.md): scaffold, add a domain later, sync upstream drift
 - [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes

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

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

@@ -1,6 +1,8 @@
 ---
 name: api-design
 description: Carries the rules for shaping what a caller of code can see and come to depend on, being a function's exports, a command's flags and output, a file format, an endpoint, or a module boundary, so a change keeps every existing caller working and exposes nothing by accident. Use when adding or changing a public function, a flag, an output shape, a schema, an error a caller handles, or a retried write, or when asked "is this a breaking change", "can I rename this field", "what should this return", "how do I make this safe to retry", or "how should I version this". Do NOT use for a visual interface, which is `design-taste`, to decide where a file sits, which is `codebase-layout`, or to list the consumers a finished change breaks during review, which is `review-craft`.
+metadata:
+  family: build
 ---
 
 # API design

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

@@ -2,6 +2,8 @@
 name: auto-ship
 description: Chains implement → verify → review → ship after a feature plan is approved. Reads the plan the caller names, the plan a named task points at, or the plan for the current branch when none is named, runs the full pipeline in one session, and stops on any failure or non-minor review finding. Use when asked to "autoship", "ship this feature end to end", or "run the chain". Do NOT auto-trigger. Requires an approved plan file.
 disable-model-invocation: true
+metadata:
+  family: build
 ---
 
 # Auto ship
@@ -121,17 +123,7 @@ Never read an absent subcommand as a skip, since failing open would ship every b
 
 ## Step 7: evaluate findings
 
-Skip this step when Step 6 skipped review. Otherwise read `.canon/review/branch-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited.
-
-- **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop or offer the fix as a choice.
-- **It predates this run, critical or should-fix.** Stop: `❌ Review found non-minor issues that predate this run. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
-- **It predates this run, minor only.** Continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
-
-Read origin as causation rather than authorship, so staleness this run induced in a file it never opened is a finding it caused.
-
-Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `❌ A self-introduced finding survived one fix pass. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
-
-This chain owns the receipt's lifetime. The `context-fold` sweep under Step 8 reaches only reports whose branch is gone, so it collects this one a branch later.
+Skip this step when Step 6 skipped review. Otherwise read `${CLAUDE_SKILL_DIR}/references/review-findings.md` before opening the review receipt. It carries how every finding splits by origin, which ones this run repairs and which stop the chain, and the one-pass bound on the repair.
 
 ## Step 8: ship
 

package/claude/skills/auto-ship/references/review-findings.md

@@ -0,0 +1,20 @@
+---
+title: Review findings
+description: How auto-ship Step 7 splits the review receipt's findings by origin, which ones it repairs in place and which stop the chain, and the one-pass bound on the repair
+---
+
+# Evaluate the review findings
+
+Step 7 of `auto-ship`. The session reads this file when Step 6 ran review rather than skipping it.
+
+Read `.canon/review/branch-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited.
+
+- **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop or offer the fix as a choice.
+- **It predates this run, critical or should-fix.** Stop: `❌ Review found non-minor issues that predate this run. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
+- **It predates this run, minor only.** Continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
+
+Read origin as causation rather than authorship, so staleness this run induced in a file it never opened is a finding it caused.
+
+Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `❌ A self-introduced finding survived one fix pass. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
+
+This chain owns the receipt's lifetime. The `context-fold` sweep under Step 8 reaches only reports whose branch is gone, so it collects this one a branch later.

package/claude/skills/backlog-triage/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: backlog-triage
 description: Files a measured verdict for every backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, then applies the verdicts the operator approved through the task verbs. Use when asked to "triage the backlog", "prune the backlog", "which backlog rows are still worth doing", "clear out the backlog", or "apply the backlog triage". Do NOT use to file a brain dump, which is `plan-intake`, to answer the filed items, which is `plan-intake-answer`, or to create, archive, or decline one named task, which is `task-board`.
+metadata:
+  family: decide
 ---
 
 # Backlog triage

package/claude/skills/bash-cli-script/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bash-cli-script
 description: Generates a small non-interactive Bash wrapper for automation, CI, and agent-run tasks, with strict mode, logs on stderr, a clean stdout, and explicit exit codes. Stops at 100 lines and routes the work to TypeScript on Bun. Use when asked for "a shell script", "a wrapper script", an automation or CI script, a cron job, or a pipeline helper. Do NOT use for a tool that prompts a person or draws a terminal UI, or for a script that will run past 100 lines. Both are written in TypeScript on Bun.
+metadata:
+  family: generate
 ---
 
 # Bash CLI script

package/claude/skills/build-in-slices/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: build-in-slices
 description: Carries how a building session works through an approved plan in thin slices, each one tested, committed, and left green before the next starts, and how it records what it noticed outside the plan rather than fixing it. Use before implementing a plan that touches more than one behavior or file, when a branch is piling up uncommitted work, or when asked "how should I build this", "how do I avoid one giant diff", "should I commit this now", or "should I fix this while I'm here". Do NOT use for the red, green, refactor loop inside one behavior, which is `test-first`, to shape the code a slice writes, which is `code-craft`, or to decide what a worker may write, which is `role-worker`.
+metadata:
+  family: build
 ---
 
 # Build in slices

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

@@ -1,6 +1,8 @@
 ---
 name: canon-cli
 description: Reference for what a canon verb does before you run it. Run `canon docs agents` for the full command catalog, `canon docs` for any other reference doc, and read this skill's own table for what a sync or install command overwrites, merges, or leaves untouched in a target project. Use when asked "which canon command do I run", "is there a doc for X", "will this overwrite my changes", or before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`. Do NOT use to execute a sync, an install, or a docs lookup, only to know which command answers the question.
+metadata:
+  family: answer
 ---
 
 # Toolkit CLI contract

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

@@ -1,6 +1,8 @@
 ---
 name: canon-feedback
 description: Format a report about something broken, missing, or off in canon and open it as a GitHub issue on the toolkit repo via `canon feedback --github`, where the toolkit's triage reads it. Use when asked to "send this to the toolkit", "report this to canon", "file toolkit feedback", or "give the toolkit feedback about X". Do NOT use for general complaints about other tooling, IDE issues, or in-project bugs that do not implicate canon surfaces.
+metadata:
+  family: upkeep
 ---
 
 # Canon feedback

package/claude/skills/canon-feedback-triage/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: canon-feedback-triage
 description: Triage open GitHub issues labeled `feedback` in the toolkit repo. List them, pick one, classify it as a direct fix or plan-worthy work, route to the right skill, and link the issue for close-out. Use when asked to "triage toolkit feedback", "work through the feedback issues", "process feedback issues", or "what feedback is open". Do NOT use to file new feedback (that is `canon-feedback`), or for general GitHub issue triage unrelated to toolkit feedback.
+metadata:
+  family: upkeep
 ---
 
 # Canon feedback triage

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

@@ -2,6 +2,8 @@
 name: canon-operator
 description: Front door to the toolkit in a target project. Orients on the toolkit's own docs and live `canon` catalogs, then runs or routes any toolkit operation from a plain-language intent. Use when you want one entry point instead of picking a specific setup or sync skill, or when asked to "use the toolkit", "what can the toolkit do", "sync my standards", "install rules", or "help me set up this project". User-invoked only. Defers first-time scaffold to setup and seed drift to seed-sync.
 disable-model-invocation: true
+metadata:
+  family: setup
 ---
 
 # Canon operator

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

@@ -2,6 +2,8 @@
 name: canon-rollout
 description: Takes one toolkit change out to every consuming project and brings each to a mergeable pull request. Carries an orchestrator role that enumerates the targets, dispatches a worker into each, reviews every pull request, and routes what each review posts, and a worker role that builds inside one target and answers its review. Use when asked to "roll this out to the targets", "take this change to every project", "run a rollout wave", "update the consuming projects", or when a session was dispatched into a target by a wave. Do NOT use for this repository's own board, which is `role-orchestrator`, and merge nothing.
 disable-model-invocation: true
+metadata:
+  family: upkeep
 ---
 
 # Canon rollout
@@ -135,14 +137,4 @@ Report a target whose `reviewReadable` reads `false` as unread rather than as cl
 
 ## Failure recovery
 
-| Stop point                              | Recovery                                                                                      |
-| --------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `gh` absent                             | Install it and authenticate, then re-run the wave                                             |
-| Target index unknown                    | Re-run with `--sweep <root...>` and read the `bound` before trusting the count                |
-| Every clone of a target is behind       | Pull that clone, or name a current one, then dispatch that target alone                       |
-| Claim check refuses or reads unverified | Launch that target's worker by hand and report that it went out outside the check             |
-| Branch already claimed in a target      | Resolve what holds `chore/agents` there, then dispatch that target alone                      |
-| A target refuses the pull read          | Read the `reason`, repair it, and re-poll that target. Never record it as having no work      |
-| Diff too large to review here           | Dispatch a reviewer into that clone and route its findings back through Phase 3               |
-| Two sessions hold one branch            | Report both and stop. Sending findings to either puts two sessions on one ref                 |
-| A target fails to converge              | Stop that target's loop, report the rounds it took and what each pass found, and hand it over |
+Read `${CLAUDE_SKILL_DIR}/references/failure-recovery.md` on a stop for the recovery that stop point takes.

package/claude/skills/canon-rollout/references/failure-recovery.md

@@ -0,0 +1,20 @@
+---
+title: Failure recovery
+description: The recovery canon-rollout takes at each stop point, from an absent gh to a target that fails to converge
+---
+
+# Failure recovery
+
+The stops of `canon-rollout`. The session reads this file on any stop, for the recovery that stop point takes.
+
+| Stop point                              | Recovery                                                                                      |
+| --------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `gh` absent                             | Install it and authenticate, then re-run the wave                                             |
+| Target index unknown                    | Re-run with `--sweep <root...>` and read the `bound` before trusting the count                |
+| Every clone of a target is behind       | Pull that clone, or name a current one, then dispatch that target alone                       |
+| Claim check refuses or reads unverified | Launch that target's worker by hand and report that it went out outside the check             |
+| Branch already claimed in a target      | Resolve what holds `chore/agents` there, then dispatch that target alone                      |
+| A target refuses the pull read          | Read the `reason`, repair it, and re-poll that target. Never record it as having no work      |
+| Diff too large to review here           | Dispatch a reviewer into that clone and route its findings back through Phase 3               |
+| Two sessions hold one branch            | Report both and stop. Sending findings to either puts two sessions on one ref                 |
+| A target fails to converge              | Stop that target's loop, report the rounds it took and what each pass found, and hand it over |

package/claude/skills/canvas/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: canvas
 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 trace reference images into design values, which is `sketch-design`, or to write the design document from code, which is `design-extract`.
+metadata:
+  family: decide
 ---
 
 # Canvas
@@ -57,6 +59,17 @@ Write the frame's whole document to the `path` the add verb reported. The open c
 - Change one property of one element with `canon canvas edit <page>/<frame> --element <index> --set <property>=<value> --json` when the set it accepts covers the change, since it leaves every other byte as it was.
 - Use the project's custom properties for every value the token stylesheet defines. The record from `serve` names the token source under `tokens`, and a `none` source means frames render unstyled, so say so rather than inventing values to cover it.
 
+Mark the frame before the first write, so the operator sees which frame is being worked on before anything lands, and clear the mark once the edits to it are done:
+
+```bash
+canon canvas editing <page>/<frame> --json
+canon canvas editing <page>/<frame> --done --json
+```
+
+- A mark lapses after five minutes, so mark the frame again during a longer edit.
+- Clear it on every exit from the edit, including one that stopped on a refusal. Clearing a frame that holds no mark succeeds.
+- When the mark call fails with `unknown command 'editing'`, the installed CLI predates the mark, so go on without it rather than stopping. Never run `canvas edit` in its place, whatever the error suggests, since that verb writes the frame.
+
 ## Step 4: read what the operator pointed at
 
 Read the selection when the operator says "this one", "the selected frame", or "that button":
@@ -83,7 +96,7 @@ The operator restyles elements from the inspector, and each edit lands as inline
 - Capture a whole page once its frames are finished: `canon canvas capture <page> --composite --json`. The image shows each frame clipped to its box at its layout position.
 - Capture once per finished frame or page, not after every edit. The live canvas is the working view, and a capture is the record handed on.
 - Read each `path` off the record rather than composing one.
-- A capture refused because a font is not installed names the family it read off the frame's `html` element. Set that element's `font-family` to a family the machine has and capture again, rather than reporting the frame as captured.
+- 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
 

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

@@ -1,6 +1,8 @@
 ---
 name: ci-workflow
 description: Generates GitHub Actions CI workflow files with parallel jobs, emoji job names, and gated deploy stages. Use when asked to "write a CI workflow", add GitHub Actions, set up a CI pipeline, or create a `.github/workflows` file.
+metadata:
+  family: generate
 ---
 
 # CI workflow

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

@@ -1,6 +1,8 @@
 ---
 name: code-craft
 description: Carries the rules for shaping code while it is being written, being a function, a class, or a module's internals, so a session picks the shape the next change needs rather than copying its neighbor, splitting by step, or building for a case nobody asked for. Use before writing a new function, class, or module, when deciding whether to extract duplicated code, add an abstraction, a pattern, or a seam, or when asked "should I extract this", "is this abstraction worth it", "should this be a strategy", "is this class doing too much", or "should I just copy this". Do NOT use for the red, green, refactor loop, which is `test-first`, to decide where a file sits, which is `codebase-layout`, to shape what a caller sees, which is `api-design`, or to judge a finished diff, which is `review-craft`.
+metadata:
+  family: build
 ---
 
 # Code craft

package/claude/skills/codebase-layout/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: codebase-layout
 description: Carries the rules that decide where a new file goes, when a folder splits, and when a file moves from its one consumer to shared code, so a plan places each new path by role and feature with a one-clause reason rather than beside its nearest neighbor. Use when a plan names a file or folder that does not exist yet, when `plan-feature` reaches its placement step, or when asked "where should this file go", "this folder is flat", "restructure this folder", or "should this be its own folder". Do NOT use to choose which layer a test belongs at, which is `test-craft`, or to shape what a module's interface exposes, which is `api-design`.
+metadata:
+  family: decide
 ---
 
 # Codebase layout

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

@@ -7,7 +7,7 @@ description: What the planning-doc reconcile is for, the gaps it closes, and why
 
 ## Gap
 
-Without this skill, the planning docs describe the scope the session opened with. An outcome the diff shipped stays unchecked, so the board reports finished work as open and the next session re-plans it. A requirement or architecture decision that changed mid-cycle lives only in the conversation and dies with it. Plans for closed tasks accumulate in the live folder, so the folder stops indicating what is in flight.
+Without this skill, the planning docs describe the scope the session opened with. An outcome the diff shipped stays unchecked, so the board reports finished work as open and the next session re-plans it. An architecture decision a plan settled mid-cycle lives only in the conversation and dies with it. Plans for closed tasks accumulate in the live folder, so the folder stops indicating what is in flight.
 
 A decision's verification anchor has the same shape of gap in the other direction. The reasoning keeps reading as current while the number it cites moves underneath, and an amendment written without an anchor leaves nothing recording which numbers were checked and which nobody has read since.
 
@@ -17,6 +17,8 @@ The receipt half of that sweep was missing entirely. A review receipt was delete
 
 The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the planning surface the request was about goes untouched.
 
+The opposite gap opened from the same write. A fold allowed to touch the requirements and architecture records on every ship rewrote both one reasonable edit at a time, and nothing read either for whether it still stated the project's identity. Each ship looked correct and the sum drifted.
+
 This skill writes canonical docs at the end of a long build and never reviews what it wrote. An appended figure or a branch-narrated re-measurement lands unchecked the same way a session's own edits do, so what the fold produces carries the exact defect the standards it cites already ban.
 
 ## Must
@@ -28,7 +30,8 @@ This skill writes canonical docs at the end of a long build and never reviews wh
 - Write tracked docs at the current worktree root and the task board at the main root, since only the first commits with the branch
 - Count every other citation before archiving a plan, comparing resolved targets rather than raw strings or bare filenames
 - Retarget a closed task at the archived plan, so the reasoning behind finished work stays reachable
-- Write a decision to the domain context entry it constrains unless it fills an architecture slot, since reach admits nearly every decision to an always-loaded file
+- Write a decision to the domain context entry it constrains unless a plan this run folds states it and it fills an architecture slot, since reach admits nearly every decision to an always-loaded file and a slot decision only the conversation carries was never reviewed
+- Report a requirements or direction change in one line naming `document-health`, rather than writing it, so the identity record changes only when the operator reviews it
 - Merge or retire an architecture entry before adding one at the record's stated cap, and name which in the report, so the cap never turns into compressed prose or two decisions packed under one heading
 - Anchor a decision entry this run writes or amends whose reasoning cites a measured number, re-reading the number against the tree before writing the marker
 - Report an anchored decision whose cited path the diff touched, since the number was read before the branch moved what it counted
@@ -48,6 +51,7 @@ This skill writes canonical docs at the end of a long build and never reviews wh
 - Infer a new task from the diff. Only outcomes already on the board get marked.
 - Touch task files the session did not change
 - Widen what a writing step reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
+- Write the requirements record. It states identity, and a fold reads one session where a review reads the whole project.
 - Edit `CLAUDE.md` inline. Every change there goes through a diff-and-approve gate, so this skill only flags.
 - Create a context entry, or move or delete a plan. A plan is settled by the merge, and `canon tasks archive` carries it.
 - Overwrite a file a promotion block routes to. A destination that already holds a page is a merge for a person, and folding over it discards work this skill never read.

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

@@ -1,6 +1,8 @@
 ---
 name: context-fold
-description: Folds a session into the project's context entries, requirements, architecture, and wireframes, marks the outcomes the diff shipped `[x]` on the task board, and archives the plans those tasks cite. Use when asked to "fold the session into context", "update the context entries", "sync the planning records", when design or requirements changed mid-cycle, after a pivot, or before shipping. Do NOT use for `README.md` or `docs/`, which is `docs-sync`, or to create or archive a task file, which is `task-board`.
+description: Folds a session into the project's context entries, architecture, and wireframes, marks the outcomes the diff shipped `[x]` on the task board, and archives the plans those tasks cite. Use when asked to "fold the session into context", "update the context entries", "sync the planning records", when design or requirements changed mid-cycle, after a pivot, or before shipping. Do NOT use for `README.md` or `docs/`, which is `docs-sync`, or to create or archive a task file, which is `task-board`.
+metadata:
+  family: ship
 ---
 
 # Context fold
@@ -82,13 +84,15 @@ The verb resolves the board at the main worktree root in-process, which is the r
 
 Read `ok` and `reason` out of that record rather than the exit. An operator's shell profile may wrap `canon` in a function that runs the binary and then a second command and takes the second status, which flattens every non-zero exit to zero. A refusal arriving as success leaves the outcome unmarked while the chain moves on, so the board reports shipped work as open and the next session re-plans it.
 
-**REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md, a wireframe surface file (flat or nested)**
+**ARCHITECTURE.md, DESIGN.md, a wireframe surface file (flat or nested)**
 
+- Never write `canon/REQUIREMENTS.md`. Report a requirements change in After completion.
 - Update only the sections affected by session decisions.
 - Do not rewrite sections unrelated to what changed.
 - Rewrite a restated or superseded statement in place rather than appending the replacement beside it. State the fact that stands and keep the earlier reasoning only where it is the alternative that lost, per `${CLAUDE_SKILL_DIR}/../../standards/context.md` and `${CLAUDE_SKILL_DIR}/../../standards/architecture.md`.
 - Follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` and the `write-human` skill for all edits.
-- Write a session decision into the `canon/context/` entry for the domain it constrains, under that entry's `## Decisions`, by default. Touch `canon/ARCHITECTURE.md` only for a decision that fills one of the slots `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` names, however many domains its reasoning reaches.
+- Write a session decision into the `canon/context/` entry for the domain it constrains, under that entry's `## Decisions`, by default.
+- Touch `canon/ARCHITECTURE.md` only when a plan a matched task's `Plan:` line names states a decision filling a slot `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` names. A slot decision no plan carries goes to the domain entry.
 - Read the entry cap the record states before adding a decision to it. At the cap, merge two decisions or retire one to the domain entry it constrains, and name which in the report. Never compress a decision's prose to fit, and never pack two decisions under one heading.
 - Close a decision entry in `canon/ARCHITECTURE.md` with its verification anchor whenever this run writes that entry or amends its reasoning and that reasoning cites a measured number. Re-read the number against the tree first, since the marker records the read rather than the edit. `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` fixes the sentence.
 - Leave every decision entry this run did not write alone, anchored or not. The rule is scoped forward, so an entry written before it is dated by blame rather than by a read. Step 5 reports a stale anchor and no step writes one on an entry it did not amend.
@@ -107,9 +111,7 @@ Skip silently when the filter leaves nothing, which is every branch touching no
 
 Skip this step silently when `canon/ARCHITECTURE.md` does not exist at `pwd` or carries no decision entry with a verification anchor. A record written before the rule holds none, and a project is not told on every ship that nothing has been checked when the standard calls that state correct. When the baseline is unusable, scope the sweep to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the anchor sweep.`
 
-This step reports and never writes. The record carries no frontmatter, so an anchor is a sentence sharing a paragraph with the claim it marks, and a pass editing prose to mark prose has no structural guard against editing the claim beside it. A surface whose marker sits in YAML gets that separation for free and this one cannot.
-
-Step 3 holds the writer, and the two never meet. Anchoring fires when this run amends a decision, and this sweep fires when the diff moves a path under one, so a single step covering both would gate the anchor obligation on a signal that has nothing to do with it.
+This step reports and never writes. An anchor is a sentence sharing a paragraph with the claim it marks rather than a frontmatter field, and a pass editing prose to mark prose has no structural guard against editing the claim beside it. A surface whose marker sits in YAML gets that separation for free and this one cannot.
 
 Follow `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` for the anchor sentence this step matches on.
 
@@ -145,18 +147,4 @@ Otherwise read `${CLAUDE_SKILL_DIR}/references/classify.md` for the invocation,
 
 ## After completion
 
-Output one line per file updated:
-
-`✅ Updated: <path written>`
-
-When Step 3 met the architecture record's cap, add one line naming what it did there:
-
-`↪ Architecture at cap: merged <heading> into <heading>` or `↪ Architecture at cap: retired <heading> to <context entry>`
-
-Step 10 adds its own lines when it applied or reported a finding, in the exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives them under its own Report section. Do not shorten or paraphrase those lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
-
-If no files were updated and nothing was swept, output:
-
-`✅ No changes needed.`
-
-Suppress that line when Step 2 already reported no doc updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.
+Read `${CLAUDE_SKILL_DIR}/references/completion-report.md` before printing anything, for the line each outcome prints, the lines Step 3, Step 2, and Step 10 add, and when the closing line is suppressed.

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

@@ -43,11 +43,11 @@ What this misses is a claim whose number moved with no matching citation in the
 
 ## What the sweep never does
 
-- Write into the entry. The record carries no frontmatter, so the marker and the claim share one paragraph and an edit reaching one reaches the other.
+- Write into the entry. The anchor is a sentence rather than a frontmatter field, so the marker and the claim share one paragraph and an edit reaching one reaches the other.
 - Refresh an anchor. Re-reading the number is the act the marker records, so a date written by a pass that measured nothing is the false confidence the marker exists to prevent.
 - Flag an unanchored entry. The standard scopes the rule forward, and an entry written before it is dated by blame rather than by a read.
 
-The session amending a decision writes its anchor, which Step 3 already requires.
+The session amending a decision writes its anchor, which Step 3 already requires. Step 3 holds the writer, and the two never meet. Anchoring fires when this run amends a decision, and this sweep fires when the diff moves a path under one, so a single step covering both would gate the anchor obligation on a signal that has nothing to do with it.
 
 ## Output
 

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

@@ -0,0 +1,26 @@
+---
+title: Completion report
+description: The lines context-fold prints once every step has run, being one per file updated, the architecture cap and direction-change notes, Step 10's own lines, and the closing line with when it is suppressed
+---
+
+# Completion report
+
+The close of `context-fold`. The session reads this file once every step has run, before printing anything.
+
+Output one line per file updated:
+
+`✅ Updated: <path written>`
+
+When Step 3 met the architecture record's cap, add one line naming what it did there:
+
+`↪ Architecture at cap: merged <heading> into <heading>` or `↪ Architecture at cap: retired <heading> to <context entry>`
+
+When Step 2 noted a requirements change: `↪ Direction changed this session: run document-health on canon/REQUIREMENTS.md`
+
+Step 10 adds its own lines when it applied or reported a finding, in the exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives them under its own Report section. Do not shorten or paraphrase those lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
+
+If no files were updated and nothing was swept, output:
+
+`✅ No changes needed.`
+
+Suppress that line when Step 2 already reported no doc updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.

package/claude/skills/create-rule/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: create-rule
 description: Scaffolds a project-specific governance rule into `.claude/rules/project/<subdir>/<n>-<slug>.md` with correct frontmatter and a non-colliding number. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
+metadata:
+  family: generate
 ---
 
 # Create rule

package/claude/skills/create-skill/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: create-skill
 description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to "create a skill", add a skill, or make a new skill.
+metadata:
+  family: generate
 ---
 
 # Create skill

package/claude/skills/create-standard/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: create-standard
 description: Creates a new standard file in `standards/`. Use when asked to "create a standard", add a standard, or write a new authoring convention. Do NOT use to edit an existing standard.
+metadata:
+  family: generate
 ---
 
 # Create standard

package/claude/skills/decision-escalate/SKILL.md

@@ -2,6 +2,8 @@
 name: decision-escalate
 description: Collects every open decision whose answer turns on the operator's preference, since only they know what they need, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
 disable-model-invocation: true
+metadata:
+  family: decide
 ---
 
 # Decision escalate

package/claude/skills/deploy-app/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: deploy-app
 description: Sets up a deploy for the current project on Cloudflare Pages or Vercel by picking the host the project already carries, creating the host's project, setting the IDs it needs as repository secrets, and stopping for the operator to issue the API token and attach the custom domain. Calls `wrangler`, `vercel`, and `gh` rather than reimplementing them. Use when asked to "set up the deploy", "deploy this to Cloudflare Pages", "deploy this to Vercel", "set up the Pages project", "set up a Vercel project", or "connect this repo to Cloudflare". Do NOT use to run an already-configured deploy, which the host's own push trigger does, or to reconfigure an existing project's build settings.
+metadata:
+  family: setup
 ---
 
 # Deploy app

package/claude/skills/deprecation-migration/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: deprecation-migration
 description: Carries how a session retires a function, a flag, a field, a file, or a command without stranding whoever still calls it, from deciding whether to deprecate at all through proving no caller remains, migrating callers through an adapter or a strangler, and removing the old surface in its own change after the new one has carried every caller. Use when deleting or replacing code something may still call, when a deprecated path has lingered with no date, when finding dead or unowned code, or when asked "can I delete this", "how do I retire this", "how do I migrate callers off X", or "is anything still using this". Do NOT use to move or rename a file with no caller change, which is `codebase-layout`, to migrate a database schema, which the project's persistence rule governs, or to shape a new field or flag added beside an old one, which is `api-design`.
+metadata:
+  family: build
 ---
 
 # Deprecation and migration

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

@@ -1,6 +1,8 @@
 ---
 name: design-extract
 description: Drafts `canon/DESIGN.md` from a project's existing prose and shell UI surfaces, or proposes token values from `REQUIREMENTS.md` and a `## Personality` section when no UI code exists yet. Use when asked to "extract the design system", "draft DESIGN.md", "bootstrap design tokens", "capture the visual system", "propose a design system", "bootstrap DESIGN.md from scratch", "draft tokens for a greenfield project", or "replace Claude Design onboarding". Do NOT use to mutate an existing `canon/DESIGN.md`.
+metadata:
+  family: setup
 ---
 
 # Design extract

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

@@ -46,7 +46,7 @@ A rule belongs in this skill only when all four hold. Three of the four reject m
 3. **It is judgment rather than a threshold.** A contrast ratio has a number and belongs to the floor. Whether a palette reads cheap has no number and belongs here.
 4. **One line states it, and something could violate that line.** "Use whitespace intentionally" fails, since nothing could break it. "No three consecutive image-and-text splits" passes, since it can be counted.
 
-A rule failing any of the four is recorded as considered and declined rather than argued again, in the reference where it would have gone.
+A rule failing any of the four is recorded as considered and declined rather than argued again, in `references/adopted.md`, under the reference where it would have gone.
 
 ## Must not
 

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

@@ -1,6 +1,8 @@
 ---
 name: design-taste
 description: Carries the layer model that decides which design decision settles first, the rules that keep a surface coherent across sections, and the catalog of defaults a model reaches for when nothing states a direction. Use when drafting or judging an interface, a page, or any rendered surface, when output reads generic or templated, when redesigning something that already exists, or when asked to "make this look designed", "why does this look like AI made it", "give it taste", "what layer is this decision at", or "grey-box this first". Do NOT use for accessibility, forms, or state coverage, which the `ui` governance rules carry, for the shape of the project's design document, which `design.md` governs, to run the candidate loop, which is `draft-and-pick`, or to trace a reference's values, which is `sketch-design`.
+metadata:
+  family: build
 ---
 
 # Design taste
@@ -115,9 +117,11 @@ It states no values. A value belongs to the project's own design document.
 
 ## The rest of the catalog
 
-Read `${CLAUDE_SKILL_DIR}/references/tells.md` before handing over anything a model drafted, and whenever output satisfies every rule here and still reads generic. The ten above are the common cases. It holds the rest, plus the countable composition limits, the first-screen budget, and the record of which external items were adopted, which declined, and why.
+Read `${CLAUDE_SKILL_DIR}/references/tells.md` before handing over anything a model drafted, and whenever output satisfies every rule here and still reads generic. The ten above are the common cases. It holds the rest, plus the countable composition limits and the first-screen budget.
 
-Skip it on a small change to a surface with a settled direction. The catalog is a diagnostic and costs a read on every invocation that does not need one.
+Skip `tells.md` on a small change to a surface with a settled direction. The catalog is a diagnostic and costs a read on every invocation that does not need one.
+
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which external catalog items were adopted, which declined, and why.
 
 ## When it reads almost right
 

package/claude/skills/design-taste/references/adopted.md

@@ -0,0 +1,40 @@
+---
+title: Adopted and declined
+description: Which external design catalogs this skill adopted from, which items it declined, and why, so a later session extends the position instead of re-deriving it
+---
+
+# Adopted and declined
+
+External catalogs were read and filtered rather than imported. This file is the record, and a later session extends it rather than re-deriving it.
+
+## Adopted
+
+**Adopted with no change.** The three equal cards, the centered hero over a wash, enumerated eyebrows, scroll cues, decorative status dots, atmospheric strips, the fake screenshot built from boxes, filler verbs, and placeholder that reads as placeholder. Each names a shape, each carries a replacement, and none depends on a stack.
+
+**Adopted with the stack removed.** Source items naming an icon set, a component library, a font by name, or an animation package were rewritten to state what the rule is about. "Do not use Inter" became one family doing every job, since the defensible claim is about pairing and role separation rather than about one typeface.
+
+## Declined from the catalogs
+
+**Banned fonts by name.** A font ban is a value ban, and a value belongs to the project's own design document rather than to a skill that loads everywhere. A project that wants a typeface ruled out rules it out there.
+
+**Numeric intensity dials.** Every external source carries a 1-to-10 scale for variance, motion and density. A session picks a middle value and reports compliance. That satisfies the rule, decides nothing, and leaves no trace a later reader could check it by. The declared read carries the same information in a sentence somebody can argue with.
+
+**The em dash ban as a design rule.** One source bans the character on a page as a visual tell. The markdown standard already bans it for prose reasons and `canon markdown audit` gates that from package data, so restating it here would put a second copy of an enforced rule behind an unenforced pointer.
+
+**The official-package map.** A table routing a brief to Fluent, Material, Carbon, Polaris, Primer or a government design system. It is real advice and it is a stack decision a project takes once, so it belongs in that project's own records rather than in a skill that loads on every design round.
+
+**Scoping out application UI.** The largest source covers landing pages, portfolios and redesigns, and excludes dashboards, data tables and multi-step product UI. Those exclusions are most of what software projects actually build, so the kinds reference carries application UI as a first-class kind.
+
+## Declined from the systems reference
+
+Each failed the test in `REQUIREMENT.md`. Recorded so they are not argued again.
+
+- **Control sizing and proportion.** An unguided model produces reasonable controls without instruction, so it fails the first question.
+- **Specific ratios for a type scale**, such as a named musical interval. Falsifiable and arbitrary, and a project picking a different ratio is not wrong.
+- **Named palettes or banned hues.** A value ban, which belongs to the project's design document. This is where every external catalog of this kind ends up, and it is why theirs cannot be imported.
+- **A minimum contrast figure.** A threshold with a number, which the accessibility rules own.
+- **Imagery as a system.** There is no scale to establish. What a model gets wrong about images is using fake ones, which `tells.md` already covers, so the layer stays thin on purpose rather than by oversight.
+
+## Carried as a caution
+
+**Greeking.** Placeholder text is correct while judging space and wrong once an arm is judged on content, since real copy length is what breaks a composition. State which of the two a set is doing.

package/claude/skills/design-taste/references/kinds.md

@@ -46,7 +46,7 @@ Documentation, articles, reference pages, learning material. The reader arrived
 ## Kinds this file does not cover
 
 - **Transactional flows** such as checkout, sign-up and settings are read as application UI. Their distinctive rules are state coverage and error recovery, which the `ui` governance rules already carry.
-- **Presentation surfaces** such as slide decks are governed by `${CLAUDE_SKILL_DIR}/../../standards/slides.md` and drafted by `draft-slides`. Take the layer ordering and the floor from the body and the rest from there.
+- **Presentation surfaces** such as slide decks are drafted by `draft-slides`, which carries the deck's own design rules. Take the layer ordering and the floor from the body and the rest from that skill.
 - **Terminal and text-mode surfaces** have no layout engine and their own color rules, stated where the writing surface is decided rather than here.
 
 A read naming any of the three above takes the body's rules and says it has no per-kind guidance, naming the surface that governs it. A read naming a kind this file does not list at all says so rather than borrowing the nearest section.