@erclx/canon 5.24.0 → 5.26.0

package/README.md

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

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

@@ -9,12 +9,12 @@ description: Why the backlog gets a measured verdict per row with a lean toward
 
 Without this skill, the backlog only grows. `task-board` declines or archives one named task, and nothing reads the backlog as a whole, so a row stays until somebody happens to remember it and decides by hand. The orchestrator's backlog re-test only clears a row upward onto the board, so no sweep ever takes one off. A backlog past fifty rows had no surface that could say which of them still mattered.
 
-Three failure modes cost more than the rest. A pass that judges a row by what its task file says rather than by the tree keeps every row, since a task file reads as live the day it was written and every day after. A pass that applies its own verdicts decides rows on silence, which ships a decline nobody approved on a board with no history to restore it from. And a keep that carries no measurement is the default nobody argues with, so a triage without a lean toward decline ends with the same backlog it started with.
+Four failure modes cost more than the rest. A pass that judges a row by what its task file says rather than by the tree keeps every row, since a task file reads as live the day it was written and every day after. A pass that applies its own verdicts decides rows on silence, which ships a decline nobody approved on a board with no history to restore it from. A keep that carries no measurement is the default nobody argues with, so a triage without a lean toward decline ends with the same backlog it started with. And a keep that measures only that the defect still exists keeps nearly everything, since a row filed against the tree almost always still reproduces. One pass suggested keeping 24 of 27 rows that way, where the operator kept 6 and promoted 1.
 
 ## Must
 
 - Measure every row against the tree and the log during the pass, carrying a count, a path, or a commit rather than the task file's own claim
-- Suggest decline for any row this pass cannot argue for, putting the burden of proof on keep and promote
+- Suggest keep or promote only for a row that names a cost, being a wrong result the pass observed or a case someone hit, including a user asking for a feature or working around its absence, or a reach, being a defect on a path the project ships that changes what its users or targets receive, hit or not, and suggest decline for a row whose defect merely still exists
 - Name the commit or pull request per outcome position before suggesting archive
 - File into an ordinary intake folder, so the intake list and answer verbs read and write it unchanged
 - Carry the verdict in the suggestion line and the task stem in the item heading, rather than in new fields

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

@@ -45,18 +45,31 @@ A row whose link resolves to no file gets an item anyway, carrying `decline` and
 
 Measure every claim the task makes against the tree and `git log` during this pass. Grep for the construct its defect names and count the sites, check whether each open outcome's behavior exists, and search the log for a commit or pull request that shipped it under another task. Never carry a figure from the task file forward as current, since the task states what was true when it was filed.
 
+Then gather the evidence Step 5 reads for each row that reproduces. Check whether its origin line or `## Findings` names an issue, a run, or a person it bit. Search the log for a commit or pull request that worked around it rather than fixing it. For a defect in something the project ships, whether a route or a page its users call or a rule, a seed, a scaffold, or a verb other repositories copy or run, name the shipped path it sits on. Record each one that is absent as absent rather than inferring it.
+
 Name the commit the pass measured against in the overview body.
 
 ### Step 5: pick the verdict
 
-Keep and promote carry the burden of proof. A row nobody can argue for from this pass's measurement is declined.
+Keep and promote carry the burden of proof, and a defect that still exists does not meet it. A row filed against the tree nearly always still reproduces, so a test of reproduction alone keeps almost every row.
+
+A row earns keep or promote only by naming one of two things from the evidence Step 4 gathered:
+
+- **A cost**: the defect gives a wrong result that this pass observed, by running the verb that carries it or reading the committed output that shows it, or that the row's evidence shows an issue, a run, or a person hit, a workaround commit included. A hit counts only while the pass does not measure it as fixed or as no longer recurring.
+- **A reach**: the defect sits on a path the project ships, and everyone who reaches that path, whether a user calling it or a target copying or running it, receives the defect as a wrong instruction, a broken, failing, or unbounded behavior, or a wrong output. Reach needs no hit, since the path's users meet the defect whether or not anyone reported it.
+
+A plausible cost names nothing. A row arguing what could go wrong off a shipped path, with no observed output and no hit, is declined however likely the argument sounds. Three things are not a reach: a missing feature on a shipped surface, a defect that changes nothing a user or a target receives, such as dead code on a shipped path, and a defect that shows only in this repository's own config, workflows, scripts, or fixtures.
+
+A missing protection is a defect, not a missing feature. Read a row as a missing protection when the shipped path lacks a bound, a check, or a guard on what it does at run time, such as a limit, a timeout, or input validation, so that the path can fail, run unbounded, or return a wrong output for every user who reaches it. That is a reach. A missing feature leaves the path working as it does today and adds a capability, a document kind, or a sentence of guidance, and it is not a reach.
+
+A missing feature can still earn keep or promote through the cost arm. A user asking for it in an issue or a report, or working around its absence on their side, is a case someone hit, so that row is never declined for being a feature. A feature nobody asked for is declined. A passing mention is not a request, and neither is one the project's own planning records filed with no user behind it.
 
-- **keep**: the defect or gap reproduces this pass, stated with a count or a path.
-- **promote**: it reproduces, and the thing it was waiting on has cleared, naming what cleared it.
+- **keep**: the defect reproduces this pass, stated with a count or a path, and the row names a cost or a reach, stated with the observation, the hit, or the shipped path.
+- **promote**: it qualifies for keep, and the thing it was waiting on has cleared, naming what cleared it.
 - **archive**: every open outcome is measured shipped, naming the commit or pull request per outcome position.
-- **decline**: anything else, including a defect the tree no longer holds, work superseded by another task, and a row whose argument rests only on its original filing.
+- **decline**: anything else, including a defect that reproduces but names no cost and no reach, a defect the tree no longer holds, work superseded by another task, and a row whose argument rests only on its original filing.
 
-Age is evidence in neither direction. A row untouched for months is not more declinable than one filed yesterday, and a row filed yesterday is not more worth keeping.
+Age is evidence in neither direction. A row untouched for months is not more declinable than one filed yesterday, and a row filed yesterday is not more worth keeping. An old hit is read the same way as a new one, by whether the pass measures it as still able to recur.
 
 ### Step 6: write the items
 
@@ -64,7 +77,7 @@ Write one item per row in the intake item format, one cluster file per domain th
 
 - `Problem:` states what this pass measured, with the count, path, or commit behind it
 - `Fix:` states what applying the verdict does to the board
-- `Worth it:` carries the verdict's reason in one clause
+- `Worth it:` names the cost or the reach the verdict rests on in one clause, or says the row names neither. A `yes` or a `later` carries no verdict on its own, so a decline can follow either word
 - `Open:` reads `decline, archive, keep, or promote?` on every item
 - `Suggested:` opens with exactly one of the four verdict tokens, then the reason. An archive suggestion lists every outcome position it closes, as `archive 1, 3: shipped in #NNN`
 - `Overlaps:` names a live board task that already carries the work, where one does

package/claude/skills/canvas/REQUIREMENT.md

@@ -0,0 +1,49 @@
+---
+name: canvas
+description: Scope boundary for driving the local design canvas, and the line between a drafted frame and the design it feeds
+---
+
+# Canvas requirement
+
+## Gap
+
+Without this skill, a session asked to draw on the canvas writes frames into a folder nothing is serving, so the operator sees nothing and the session reports the frames as drawn. When the server is running, the session trusts a passing capture as proof the canvas works. Captures go through the frame route, so a shell that answers its address with an empty page passes every capture while the operator looks at a blank tab.
+
+It reads "this one" from the conversation rather than from the operator's selection, and when it does read the selection it acts on an element index recorded against an earlier version of the file, which lands the edit on a different element. It restyles through a class while the operator's inspector edit sits on the element as inline style, so the change never shows and the session reports it as made.
+
+It writes frames from a linked worktree with the file tools, which refuse the main-root path and offer a worktree copy the canvas never serves. It captures after every edit, filling session scratch with images of drafts nobody picked.
+
+When the operator picks a frame, the session leaves the decision on the canvas and cites the frame as the design, so the project's design document never learns it and a gitignored file becomes the only record.
+
+## Must
+
+- Start the canvas when it is not serving, before writing any frame
+- Confirm the live shell loads at the address the server reported, rather than trusting a capture
+- Read the address off the server's record rather than composing one
+- Make pages and frames through the verbs, so a box and the operator's drags share one locked writer
+- Name the main-root write route for a frame written from a linked worktree
+- Read the operator's selection when they point at something, and treat a stale element pick as unknown
+- Read a frame's inline styles before restyling it, and say which operator edits were kept and which dropped
+- Capture once per finished frame or page rather than after every edit
+- Carry a picked direction into the project's design document or wireframes
+
+## Must not
+
+- Present the canvas as the project's source of truth for design
+- Promise the canvas survives a lost checkout
+- Name any third-party design tool, or the canvas's predecessor surface
+- Be invoked only by the author typing its name. A request to draw, select, or capture on the canvas should reach it by description, and a run where it never fires on such a request is a defect in the description
+
+## Guards
+
+- No `canon` on PATH, or an installed CLI with no canvas command, stop rather than writing files nothing serves
+- A server that refuses to start, or a shell that answers blank, stop and report it rather than drawing into it
+
+## Out of scope
+
+- What the canvas verbs do internally, which is the CLI's own contract
+- The content format a frame and a layout take, which the canvas standard fixes
+- Drafting candidates for a taste decision and taking the pick, which `draft-and-pick` runs on its own render path
+- Tracing reference images into design values, which is `sketch-design`
+- Writing the design document itself, which is `design-extract`
+- Backing up the canvas folder off one disk

package/claude/skills/canvas/SKILL.md

@@ -0,0 +1,106 @@
+---
+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`.
+---
+
+# Canvas
+
+Drive the canvas the operator is looking at. A page is a folder of HTML frames and a frame is one file, so a session draws by writing files and the operator sees each write land in the browser. The content format is fixed by `${CLAUDE_SKILL_DIR}/../../standards/canvas.md`. Read it before writing a frame.
+
+Every verb below is `canon canvas`. Run `canon docs canvas` for the full verb reference, its records, and its refusals.
+
+## Guards
+
+- If `canon` is not on PATH, stop: `❌ canon CLI not found.`
+- If `canon canvas --help` reports no such command, stop: `❌ The installed canon carries no canvas command. Update the CLI and re-run.`
+- Write no frame before the canvas is serving and the shell has loaded. A frame nobody can see is a draft reported as delivered.
+- Never present a frame as the project's design. The canvas is a drafting surface and the project's design document or wireframes hold what was decided.
+- Never promise the canvas survives a lost checkout. Its folder is gitignored and nothing backs it up.
+
+## Step 1: start the canvas and confirm the shell
+
+Read the pages first, which also proves the verb resolves:
+
+```bash
+canon canvas list --json
+```
+
+The record carries `content`, the folder every page lives in. It sits at the main worktree root whichever worktree the session runs in, so write through that path rather than one composed from the current directory.
+
+Start the server in the background unless the operator named an address that already answers, since it runs until interrupted. No verb reports a running server, and a second one is harmless, since it walks to the next free port and serves the same folder:
+
+```bash
+canon canvas serve --json
+```
+
+Read `url` off the record rather than composing one, since the server walks past a port already in use. Report the refusal and its `reason` when `ok` is false, and stop there.
+
+Then fetch the printed address and check the shell itself, not a capture:
+
+- The body is non-empty and carries a `<script` tag. An empty `200` means the shell failed to build, usually a dependency missing from the canvas tool's install, and every capture still passes because captures go through the frame route alone. Report it as a blank shell and stop.
+- `<url>/api/pages` answers with JSON listing the pages.
+
+Hand the operator the address as a markdown link carrying the URL as its text and its target.
+
+## Step 2: make pages and frames
+
+- Add a page for each decision being drafted: `canon canvas page add <page> --json`.
+- Add each frame through the verb, which writes the starting file and its box in one locked step: `canon canvas frame add <page> <frame> --width <px> --height <px> --json`. Give the width the frame should render at, since a capture and the canvas both render at it.
+- Lay frames out with `canon canvas frame move <page> <frame> --x <px> --y <px> --json` rather than writing `layout.json` by hand, since the operator's drags write the same file under a lock.
+- Name pages and frames for what they hold, such as `pricing` and `pricing-dense`, so the operator can say which one by name.
+
+## Step 3: edit a frame through its file
+
+Write the frame's whole document to the `path` the add verb reported. The open canvas reloads the frame when its file changes.
+
+- From a linked worktree, `Edit` and `Write` refuse a main-root path. Write the whole file through one plain `Bash` heredoc instead, the route `session-worktree` states for a main-root write, and never take the redirect to a worktree copy.
+- 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.
+
+## Step 4: read what the operator pointed at
+
+Read the selection when the operator says "this one", "the selected frame", or "that button":
+
+```bash
+canon canvas selection --json
+```
+
+- `selection: null` means nothing is selected or the selected frame is gone. Ask which one rather than guessing.
+- An `element` carrying `stale: true` was picked against an earlier version of the file, so its `index` may now land on a different element. Treat the pick as unknown and ask the operator to pick again, rather than acting on the index or matching its `tag` and `text` by eye.
+- A fresh `element` gives the `index` that `canvas edit` takes.
+
+## Step 5: respect the operator's inspector edits
+
+The operator restyles elements from the inspector, and each edit lands as inline `style` on the element. Inline style beats a class, so a class change made afterwards does not show.
+
+- Read the frame's inline `style` attributes before restyling anything in it.
+- Keep an inline property the operator set unless the change replaces it, and drop it, through `canvas edit` with an empty value or by rewriting the file, when it does.
+- Say which operator edits were kept and which were dropped.
+
+## Step 6: capture finished work
+
+- Capture a frame once it is finished: `canon canvas capture <page>/<frame> --json`. Each PNG is the frame's whole document, so its height follows the content rather than the box.
+- 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 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
+
+When the operator picks a frame, the decision leaves the canvas.
+
+- Carry visual values, being color, type, spacing, and radius, into the project's design document, through the skill that owns it. Carry structure and layout into the project's wireframes.
+- Name the frame the decision came from in the reply, and leave the frame on the canvas until the operator clears it.
+- Never cite a frame path from a tracked file. The folder is gitignored, so the citation resolves on this machine alone.
+
+## Output
+
+```plaintext
+✅ Canvas: <url the serve verb reported>
+Page:     <page>, <n> frames
+Selected: <page>/<frame>, element <index>, or none, or stale
+Capture:  <path of each capture written>
+Carried:  <the design document or wireframe the pick went to, or not yet>
+```
+
+Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the carried line when no direction was picked. Emit every path from the project root.

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,6 @@
 ---
 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`.
 ---
 
 # Context fold
@@ -82,13 +82,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 +109,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.
 
@@ -153,6 +153,8 @@ When Step 3 met the architecture record's cap, add one line naming what it did t
 
 `↪ 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:

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/design-extract/REQUIREMENT.md

@@ -39,4 +39,4 @@ The greenfield case is the one that fails quietly. A project with no UI code sti
 - Mutating an existing design system, which is a direct edit of the file rather than a skill
 - Producing the HTML and CSS preview, which `canon design render` owns
 - Auditing the implemented UI against the tokens, which `ux-audit` owns
-- Architecture and flow diagrams, which `draft-diagram` owns
+- Architecture and flow diagrams, which `draft-figure` owns

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

@@ -115,9 +115,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.

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

@@ -40,10 +40,4 @@ The layer a model is worst at, and the layer where rules are hardest to make fal
 
 ## Considered and declined
 
-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.
+The items considered for this reference and declined sit in `adopted.md` beside this file, recorded so they are not argued again.

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

@@ -1,6 +1,6 @@
 ---
 title: Machine tells in design
-description: The visual defaults a model reaches for when nothing states a direction, each with what to do instead, plus the record of which external items were adopted, which were declined, and why
+description: The visual defaults a model reaches for when nothing states a direction, each with what to do instead, plus the countable composition limits and the first-screen budget
 ---
 
 # Machine tells in design
@@ -76,26 +76,4 @@ These are the rules with numbers, so they are checked by counting rather than by
 
 ## Adopted, declined, and why
 
-External catalogs were read and filtered rather than imported. This section 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
-
-**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.
-
-### 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.
+The record of which external catalog items were adopted, which declined, and why sits in `adopted.md` beside this file.

package/claude/skills/docs-sync/REQUIREMENT.md

@@ -35,7 +35,8 @@ The quiet one is the baseline. A diff resolved against a bare local ref equals H
 
 ## Out of scope
 
-- The context entries, requirements, architecture, wireframes, and task board: `context-fold`, which runs immediately before this skill in the ship chain and resolves the same baseline. The split is by audience, so a file's location decides which skill owns it rather than its subject.
+- The context entries, architecture, wireframes, and task board: `context-fold`, which runs immediately before this skill in the ship chain and resolves the same baseline. The split is by audience, so a file's location decides which skill owns it rather than its subject.
+- The requirements record: `document-health` reads it when asked, and `markdown-propose` rewrites it from the answers
 - `CLAUDE.md` and the installed seed docs: `seed-sync`, which reconciles them per section against the toolkit source
 - Changelog entries, which release tooling generates from commit messages
 - Whether the prose conforms to its standards. `canon markdown audit` reports violations and fixes none, and this skill writes prose it does not audit.

package/claude/skills/document-health/REQUIREMENT.md

@@ -23,6 +23,7 @@ The third is silence on an unread axis. Both measured verbs resolve their folder
 - Say which layer answered the classifier sweep, since its model layer being off narrows the read without refusing it
 - Take every checkpoint from the record the verb returns rather than from a number written into the skill
 - Run standalone, and stay callable from the structural check rather than reachable only through it
+- Read the requirements and architecture records for identity drift when the scope reaches them, and print one reminder line per doc from `canon records stale canonical`, since the fold no longer writes the first and only writes the second for a planned slot decision, so nothing else reads either whole
 
 ## Must not
 
@@ -30,6 +31,7 @@ The third is silence on an unread axis. Both measured verbs resolve their folder
 - Emit a verdict across the three axes, or a score across the documents. Two axes answer from verbs and one answers from a reading, so any roll-up is a figure that lies about the third.
 - Report a finding against a file nobody hand-authors. A generated index, a gitignored file, and a copied reference each name a file an author cannot fix.
 - Answer an axis by file inspection where a verb answers it. The verb is the surface under test and a hand-rolled read of the same files is not.
+- Trigger itself, or ask a hook, a gate stage, or CI to trigger the canonical review. The operator settled that it runs only when asked.
 - Read a document's modification time as its staleness. A file untouched beside code untouched is current, and the timestamp answers a different question.
 
 ## Guards

package/claude/skills/document-health/SKILL.md

@@ -59,6 +59,18 @@ No verb answers whether a document still describes the tree it was written about
 
 Mark every staleness finding as a reading. It is this session's judgment rather than a measurement, and a report that sets it beside two verb-backed axes without marking it implies evidence the axis does not carry.
 
+### The requirements and architecture records
+
+When the scope reaches `canon/REQUIREMENTS.md` or `canon/ARCHITECTURE.md`, read each for identity drift as well as for stale paths, and take the review point from the verb:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon records stale canonical --json
+```
+
+Each doc in the record carries `reviewed` and `releasesSince`. `${CLAUDE_SKILL_DIR}/references/axes.md` holds the identity claim shapes to test and how the record reads. Skip both the read and the verb when the scope excludes the two docs.
+
+Nothing triggers this review but a request. A finished review routes to `markdown-propose` for the rewrite, and its last edit sets `reviewed:` in the doc's frontmatter to the day the operator's answers landed. This run writes neither.
+
 ## Step 4: report per document
 
 Give each document its three axes, and give each axis three things: the state, the evidence class, and the command or skill that repairs it. Naming the repair is not running it.
@@ -85,4 +97,13 @@ Document health: `<scope>`, <n> documents read.
 Length and placement are measured. Staleness is a reading.
 ```
 
+When Step 3 read the canonical records, add one reminder line per doc the verb returned, under the evidence line:
+
+```markdown
+`canon/REQUIREMENTS.md`: reviewed <date>, <n> releases since.
+`canon/ARCHITECTURE.md`: never reviewed.
+```
+
+Write `reviewed value is not a date: <value>` for a doc carrying `invalidReviewed`, and `no release tags to count` in place of the count when `tagged` is false. Name the unread cause instead when the verb refused or the binary carries no `canonical` kind.
+
 Keep the evidence line under the table on every run. A table read without it flattens a judgment into a measurement, which is the one shape the three classes exist to prevent.

package/claude/skills/document-health/references/axes.md

@@ -67,6 +67,18 @@ Read each document against the surfaces it names. Four claim shapes are testable
 
 A claim resting on none of the four is unverifiable from here. Report it as unread rather than as passing, which is the same rule the measured axes take when a verb refuses.
 
+### Identity drift in the requirements and architecture records
+
+These two records state what the project is and why it is built the way it is, so they go stale by the project changing direction as well as by the tree moving. Test these claim shapes beside the four above:
+
+- A goal nobody pursues, read against the task board and the recent history
+- A non-goal the project has since shipped
+- A constraint the tree contradicts
+- A decision whose revisit sentence has fired
+- A risk or open question already fixed
+
+Each is a `read`. The review point beside them is `measured`: `canon records stale canonical --json` returns per doc the `reviewed` date from its frontmatter and `releasesSince`, the release tags merged into HEAD after that day. A null `releasesSince` means the doc was never reviewed, and `tagged: false` means no release tag exists to count, so a zero there measured nothing. The count is a reminder of how far the project has moved since someone last read the record whole, never a threshold.
+
 **Routes to:** the skill that rewrites a stale claim against an answer, rather than a direct edit from here. A document health run reports and never repairs.
 
 **Caveat:** a reading is the weakest evidence in the report and the most consequential finding in it, which is the tension this axis ships with. Marking the class is what keeps the two facts together in the reader's hands.

package/claude/skills/draft-and-pick/SKILL.md

@@ -35,7 +35,7 @@ Write every arm side by side on one self-contained HTML page at `<dest>/candidat
 - Hand over the per-arm file addresses beside the combined page where the declared layer is composition, layout or space, and say that an arm is judged at a width by opening its own file in the browser's device toolbar. The combined page cannot answer that question at all: every arm sits in a column there while the media queries answer to the whole window, so each one renders its widest layout in a narrow space no matter how the window is sized. Build no width control of your own, since the browser already has one.
 - Take the live-app branch instead when the surface under decision is a running app: lift the rendered markup and link a copy of the built stylesheet rather than inlining, per `${CLAUDE_SKILL_DIR}/references/live-arms.md`.
 - On the default path, inline every style, script, and asset the page needs. The render reads the file off disk, so a page reaching for a build step or a network font renders without it and the arms differ by something nobody chose.
-- On the default path, declare a font stack the machine resolves, such as `system-ui` behind a generic fallback. The render refuses a page that would rewrap against a substitute rather than shipping a false comparison, so a page naming no font at all is refused on whatever the default resolves to.
+- On the default path, name a real font first in the stack, one the machine has or the page embeds, such as the project's own family from its design tokens. A generic keyword such as `system-ui` or `sans-serif` is refused, since it resolves to a different font on each machine. The render refuses a page that would rewrap against a substitute rather than shipping a false comparison, so a page naming no font at all is refused on whatever the default resolves to.
 
 ### What varies
 

package/claude/skills/draft-doc/REQUIREMENT.md

@@ -42,5 +42,5 @@ The same procedure ran as five skills, one per kind, each restating the read, th
 - Rewriting or syncing an existing `docs/` page or an authored README against a diff: `docs-sync`
 - Refreshing an existing context entry or wireframe, or stubbing a surface a diff touched: `context-fold`
 - Drafting a standard or a governance rule: `create-standard`, `create-rule`
-- Drawing a figure or a diagram for a document: `draft-figure`, `draft-diagram`
+- Drawing a figure or a diagram for a document: `draft-figure`
 - Voice, rhythm, punctuation, and formatting in the drafted document: the `write-human` skill and the markdown standard