@erclx/canon 5.32.0 → 5.33.0

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

@@ -1,6 +1,6 @@
 ---
 name: context-fold
-description: Folds a session into the project's context entries, 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's decisions and its diff into the project's context entries, then audits what it touched. Use when asked to "fold the session into context", "update the context entries", "refresh the context folder", 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 mark a shipped task's outcomes on the board, which is `task-complete`.
 metadata:
   family: ship
 ---
@@ -11,11 +11,11 @@ metadata:
 
 - If neither a `canon/` nor a `.claude/` directory exists, stop: `❌ No canon/ or .claude/ directory found. Run canon claude init to set up the workflow.`
 
-The skip for a session that changed nothing lives at the end of Step 2, because it needs the diff to decide. It drops the doc rewrite alone. The diff-driven refresh in Step 5 still runs.
+The skip for a session that changed nothing lives at the end of Step 2, because it needs the diff to decide.
 
 ## Diff baseline
 
-Steps 2 and 5 share one diff on the usable path. An unusable baseline splits them, per the rule below. Resolve the base ref once and reuse it:
+Steps 2, 3, and 4 share one diff. Resolve the base ref once and reuse it:
 
 ```bash
 git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
@@ -25,18 +25,13 @@ Take the union of `git diff --name-only <base> HEAD`, `git diff --name-only HEAD
 
 Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill goes blind to the work it is meant to read.
 
-The baseline is unusable when no merge base resolves against either ref, or when the base came from local `main` and equals HEAD. On an unusable baseline, read `${CLAUDE_SKILL_DIR}/references/unusable-baseline.md` before Step 2 for what each step reads instead.
+The baseline is unusable when no merge base resolves against either ref, or when the base came from local `main` and equals HEAD. On an unusable baseline, read `${CLAUDE_SKILL_DIR}/references/unusable-baseline.md` before Step 3 for the set that step takes instead.
 
-## Step 1: read current docs
+## Step 1: read the context catalog
 
-Read these in parallel from the current worktree root (`pwd`), not the main worktree root. These are tracked files and edits must commit with the branch. A project the surface move has not reached holds each of them under `.claude/` rather than `canon/`, so read and write each at whichever root already carries it. Skip any that exist at neither:
+Read `canon/context/index.md` from the current worktree root (`pwd`), not the main worktree root, to see which domain entries exist. Entries are tracked files and edits must commit with the branch. A project the surface move has not reached holds the folder under `.claude/` rather than `canon/`, so read and write it at whichever root already carries it.
 
-- `canon/REQUIREMENTS.md`
-- `canon/DESIGN.md`
-
-Read the task board from the main worktree root instead, resolving that root the way `session-worktree` does. It is gitignored scratch and never commits with the branch:
-
-- `.canon/tasks/index.md` first, then the task files this session touched. That narrow read serves the marking step, which is the only step here that opens a task file.
+Read `canon/REQUIREMENTS.md` beside it when it exists, for the direction a session decision is measured against. This skill never writes it.
 
 ## Step 2: identify what changed
 
@@ -46,81 +41,41 @@ Review the session for decisions that diverged from the original plan:
 
 - Requirements added, removed, or changed scope
 - Technical decisions made or revised
-- Design or UX decisions that differ from DESIGN.md
-- Tasks blocked or newly identified
-
-Then resolve the diff baseline and match it against the board. From `.canon/tasks/index.md` at the main worktree root, pick the task files whose title or description relates to the changed paths and read the ones Step 1 skipped.
-
-Path matching only chooses which files to open. Behavior decides each outcome. For each unchecked outcome, decide whether the diff shipped the behavior that outcome names.
-
-Completion is the one judgment here that is a fact about the repository rather than a fact about the conversation, so the diff decides it and the session does not. Requirements, decisions, and design stay session-sourced.
-
-Keep the match conservative:
+- Design or UX decisions that differ from what the context entries state
 
-- Mark only outcomes already written on the board. Never infer a new task from the diff.
-- Match on the behavior an outcome describes, not on filenames or commit subjects. The path match above only narrowed which task files to open.
-- Leave an outcome `[ ]` when the diff is ambiguous. An unmarked shipped outcome costs one manual edit, while a wrongly marked one hides work that never happened.
+Then resolve the diff baseline and keep the changed paths for Step 3.
 
-Skip Step 3 when the session shows no divergence **and** the diff matches no queued outcome, reporting `✅ No doc updates needed. Session matched the original plan.` Both conditions have to hold. Shipping a queued task exactly as planned is the ordinary case and it reads as no divergence, so a session-only skip would drop the marking step with it.
+Stop when the session shows no divergence **and** the diff carries no path a context entry could describe, being a change confined to the task board, scratch, or files outside the repository's source and docs. Report `✅ No context updates needed. Session matched the original plan.` Both conditions have to hold, since a session-only skip would drop the diff-driven refresh for a mechanical change nobody narrated.
 
-Then run Steps 4 through 8. Step 3 is the only one this skips, because it is the only one driven by the session rather than by the diff or the board. A project with an empty task board making a mechanical change satisfies both conditions above, and stopping here would put an uncovered surface out of reach in every such project.
+## Step 3: refresh context entries
 
-This changes which steps the skill reaches and never widens what any of them reads. Step 5 still takes the same scoped set the Diff baseline section defines.
+Skip this step silently when `canon/context/` does not exist or its catalog lists no entries.
 
-## Step 3: update
-
-For each doc with relevant changes, apply updates following these rules. Read a standard this skill names, here or in a later step, from `${CLAUDE_SKILL_DIR}/../../standards/` when the project does not have it.
-
-**`.canon/tasks/`**
-
-- Mark completed outcomes `[x]` in the task's own file through `canon tasks outcome <stem> --close <n> --json`, repeating `--close` for each. Positions count every outcome checkbox in file order from 1, which the read above already gives. Do not move or archive the file.
-- Write a newly identified task as its own file, following `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` for the filename and frontmatter.
-- Do not touch task files this session did not change.
-- Never hand-edit `.canon/tasks/index.md`. A hook regenerates it.
-
-The verb resolves the board at the main worktree root in-process, which is the route `session-worktree` states for an edit inside an existing main-root file.
-
-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.
+Otherwise read `${CLAUDE_SKILL_DIR}/references/context-refresh.md` for the diff it reads, the widening a removed capability takes, when a new entry is created, and the output lines.
 
-**DESIGN.md**
+Write a session decision into the entry for the domain it constrains, under that entry's `## Decisions`, whatever other domains its reasoning touches. Every write follows these rules:
 
 - 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`.
+- Update only the sections affected by session decisions or the diff, and leave unrelated sections alone.
+- 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}/references/context.md`.
 - Follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/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`, whatever other domains its reasoning touches.
 
 Write each updated file immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 
-## Step 4: flag CLAUDE.md drift
+## Step 4: audit what the fold touched
 
-If this session established or changed a cross-cutting behavior rule that belongs in root `CLAUDE.md` (a new always-on convention, a revised workflow rule), surface a one-line warning:
+Run the structural audit, then the content classifier, and answer both before the report.
 
-`⚠ CLAUDE.md may need a rule from this session. Review and edit by hand.`
-
-Do not edit `CLAUDE.md` inline. Every `CLAUDE.md` change goes through the show-diff-and-approve gate, so this step only flags. Skip silently when the session made no cross-cutting behavior decision.
-
-## Step 5: refresh context entries
-
-Read `canon/context/index.md` at `pwd` to see which domain entries exist. Skip this step silently if the directory does not exist or has no entries.
-
-Otherwise read `${CLAUDE_SKILL_DIR}/references/context-refresh.md` for the diff it reads, the widening a removed capability takes, when a new entry is created, and the output lines.
-
-## Step 6: fold promoted pages
-
-Skip this step silently when no teach promotion handoff exists at `.canon/tmp/handoff/teach-promotion/<slug>.md` at the main worktree root, deriving `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md` with the `latest` fallback. Otherwise read `${CLAUDE_SKILL_DIR}/references/promoted-pages.md` for how each block lands, the handoff delete, and the output lines.
-
-## Step 7: sweep consumed receipts
-
-Read `${CLAUDE_SKILL_DIR}/references/receipt-sweep.md` for which review receipts this session sweeps, which it keeps, and the output lines. Skip this step silently when nothing qualifies.
+```bash
+canon context audit --json
+```
 
-## Step 8: classify the fold's diff baseline
+The verb takes a project root rather than a file list, so it reports the whole folder. Report only the findings whose `rel` names a file Step 3 wrote this run or a file the diff carries, one line each as `⚠ Audit: <rel>, <finding>`, and leave the rest unreported, since a finding in an entry this run never touched belongs to whoever next edits it. Repair a finding in a file Step 3 wrote this run when the fix is inside what it already rewrote, such as a bare reference or a missing section it dropped. Report a missing subcommand or a refusal as `⚠ Audit: <message>` and continue.
 
-Skip this step silently only when the Diff baseline section could not resolve a base ref at all, reporting `⚠ No diff to scope against. Skipped the classify check.` The verb needs a resolvable ref to run against, which is the one condition it cannot answer for itself.
+Then classify. Skip the classifier only when the Diff baseline section could not resolve a base ref at all, reporting `⚠ No diff to scope against. Skipped the classify check.` The verb needs a resolvable ref to run against, which is the one condition it cannot answer for itself.
 
-Otherwise read `${CLAUDE_SKILL_DIR}/references/classify.md` for the invocation, its scope, the record fields, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape. `${CLAUDE_SKILL_DIR}` names this skill's own directory, resolved once when the skill loaded, several steps before this one. Read the reference by that resolved path rather than guessing a `.claude/skills/context-fold/references/classify.md` path from the toolkit's install-time layout, which is a different root than the one this skill's own files live under. The invocation is `canon context classify diff --base <base> --json`, and it runs whether or not that reference resolves. Findings never stop the fold.
+Otherwise read `${CLAUDE_SKILL_DIR}/references/classify.md` for the invocation, its scope, the record fields, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape. `${CLAUDE_SKILL_DIR}` names this skill's own directory, resolved once when the skill loaded. Read the reference by that resolved path rather than guessing a `.claude/skills/context-fold/references/classify.md` path from the toolkit's install-time layout, which is a different root than the one this skill's own files live under. The invocation is `canon context classify diff --base <base> --json`, and it runs whether or not that reference resolves. Findings never stop the fold.
 
 ## After completion
 
-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 8 add, and when the closing line is suppressed.
+Read `${CLAUDE_SKILL_DIR}/references/completion-report.md` before printing anything, for the line each outcome prints, the lines Step 2 and Step 4 add, and when the closing line is suppressed.

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

@@ -5,7 +5,7 @@ description: The classify diff invocation, the record fields to read, applying a
 
 # Classify the fold's diff baseline
 
-Mechanics for Step 8 of `context-fold`. The body owns the skip condition and the shared baseline, and this file owns the invocation, what the record carries, and what applying a finding does.
+Mechanics for the classify half of Step 4 of `context-fold`. The body owns the skip condition and the shared baseline, and this file owns the invocation, what the record carries, and what applying a finding does.
 
 ## Invocation
 
@@ -30,14 +30,14 @@ Each finding carries `file`, a `verdict` of `KEEP`, `REPLACE`, `HISTORY`, or `MO
 
 ## Scope
 
-Answer every non-`KEEP` finding the verb returns, not only the files Step 3 or Step 5 wrote this run. A branch carrying earlier commits from a prior session has doc edits the fold is equally responsible for, and the verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none, so there is no narrower check to add here.
+Answer every non-`KEEP` finding the verb returns, not only the files Step 3 wrote this run. A branch carrying earlier commits from a prior session has doc edits the fold is equally responsible for, and the verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none, so there is no narrower check to add here.
 
 ## Applying a finding
 
 Locate the finding by its `quote` in the file's current content. The quote is often a narrow fragment rather than the whole clause it sits in, since the regex layer's own match is a short pattern hit, so the edit below targets the sentence or bullet the quote sits in rather than the literal substring alone.
 
 - **Found exactly once.** Apply the verdict:
-  - `REPLACE`: rewrite the sentence or bullet carrying the quote in place with the fact that now stands, per Step 3 and Step 5's rewrite-in-place rule. State what is current and drop what the quote restated, in the one edit.
+  - `REPLACE`: rewrite the sentence or bullet carrying the quote in place with the fact that now stands, per Step 3's rewrite-in-place rule. State what is current and drop what the quote restated, in the one edit.
   - `HISTORY`: rewrite the sentence or bullet carrying the quote to drop the narration and keep any current fact the same clause states. The quote narrates how the fact arrived rather than stating the fact, which a canonical doc excludes regardless of what wrote it, and a literal cut of the fragment alone would leave the rest of the clause grammatically stranded.
   - `MOVE`: do not cut. The verdict means correct content sitting on the wrong surface, such as a rule written into a context entry that belongs in a path-scoped rule, and only the model layer returns it. Cutting would delete content a fold with no model configured would never have flagged at all. Report the finding instead, naming the surface the `reason` names as where the content belongs, and leave the file unedited.
 - **Found more than once, or not found at all.** Report that the finding could not be located rather than guessing which occurrence or rewriting nothing silently. A model verdict paraphrasing the quote it read is the ordinary way this happens.

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

@@ -1,6 +1,6 @@
 ---
 title: Completion report
-description: The lines context-fold prints once every step has run, being one per file updated, the direction-change note, Step 8's own lines, and the closing line with when it is suppressed
+description: The lines context-fold prints once every step has run, being one per file updated, the direction-change note, Step 4's audit and classify lines, and the closing line with when it is suppressed
 ---
 
 # Completion report
@@ -13,10 +13,10 @@ Output one line per file updated:
 
 When Step 2 noted a requirements change: `↪ Direction changed this session: run document-health on canon/REQUIREMENTS.md`
 
-Step 8 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.
+Step 4 adds one `⚠ Audit:` line per audit finding it reported, in the shape the body gives. Its classify half 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:
+If no files were updated and Step 4 reported nothing, 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.
+Suppress that line when Step 2 already reported no context updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.

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

@@ -1,11 +1,11 @@
 ---
 title: Refresh context entries
-description: How context-fold Step 5 folds diff-scoped rewrites into canon/context entries, when it creates an entry, and the lines it reports
+description: How context-fold Step 3 folds diff-scoped rewrites into canon/context entries, when it creates an entry, and the lines it reports
 ---
 
 # Refresh context entries
 
-Step 5 of `context-fold`, reached in order once `canon/context/index.md` lists at least one entry.
+Step 3 of `context-fold`, reached in order once `canon/context/index.md` lists at least one entry.
 
 The diff carries what the repository changed, and this step rewrites against it.
 
@@ -15,8 +15,8 @@ Reuse the diff from the baseline above, names and content both. For each domain
 
 - Map the entry's section headings, whether they sit in one flat file or spread across a nested domain's sibling files, to the changed files. An entry is relevant when its prose references files, modules, or decisions touched by the diff.
 - For each relevant entry, rewrite only the sections affected by the diff. Same pattern as `docs-sync`. Do not touch unrelated sections. Never rewrite a split domain's own `index.md` directly, since a regen overwrites it the same way it overwrites the top-level catalog. Rewrite the sibling file the affected section actually lives in instead.
-- Rewrite a restated or superseded statement in place rather than appending beside it, the same rule Step 3 applies to the other canonical doc types.
-- Write a reference to another entry as the path that entry sits at, rather than as its bare filename. `${CLAUDE_SKILL_DIR}/../../standards/context.md` states the form, and a bare name strands the reference once a domain splits into subfolders.
+- Rewrite a restated or superseded statement in place rather than appending beside it, the same rule the body states for a session decision.
+- Write a reference to another entry as the path that entry sits at, rather than as its bare filename. `${CLAUDE_SKILL_DIR}/references/context.md` states the form, and a bare name strands the reference once a domain splits into subfolders.
 
 ## When the diff removes a capability
 
@@ -29,7 +29,7 @@ Grep the tree for the name that went, rather than for the paths the diff carries
 
 Report each hit as an ordinary rewrite.
 
-Create a new entry only for a domain `canon/context/index.md` already lists but carries no file for, following `${CLAUDE_SKILL_DIR}/../../standards/context.md` for its shape. Before treating a domain as carrying no file, confirm it holds no entry under either spelling, `canon/context/<domain>.md` or `canon/context/<domain>/index.md`, since a domain already split into a folder still passes a check that only looked for the flat file. A row in the catalog is the deliberate decision, taken by whoever added it. This step only fills in what that decision left open, and only until the next `canon indexes regen` pass, which rebuilds the catalog from each entry's own frontmatter plus every sibling's and drops a row whose file still does not exist. Create the file before that regen runs, or the row this bar exists to fill in is gone. A domain the catalog does not list at all is a different case: report it and stop, rather than creating an entry or a catalog row for it.
+Create a new entry only for a domain `canon/context/index.md` already lists but carries no file for, following `${CLAUDE_SKILL_DIR}/references/context.md` for its shape. Before treating a domain as carrying no file, confirm it holds no entry under either spelling, `canon/context/<domain>.md` or `canon/context/<domain>/index.md`, since a domain already split into a folder still passes a check that only looked for the flat file. A row in the catalog is the deliberate decision, taken by whoever added it. This step only fills in what that decision left open, and only until the next `canon indexes regen` pass, which rebuilds the catalog from each entry's own frontmatter plus every sibling's and drops a row whose file still does not exist. Create the file before that regen runs, or the row this bar exists to fill in is gone. A domain the catalog does not list at all is a different case: report it and stop, rather than creating an entry or a catalog row for it.
 
 Write each updated entry immediately. Output one line per file, naming the path this run actually wrote rather than always the flat template:
 

package/{standards → claude/skills/context-fold/references}/context.md

@@ -1,17 +1,28 @@
 ---
 title: Context entry reference
 description: Shape and content rules for canon/context/<domain>.md entries
-paths:
-  - 'canon/context/**'
-rule:
-  - 'Before non-trivial work in a domain, read its `canon/context/<domain>.md` entry. Use `canon/context/index.md` to find it.'
-  - 'Leave the entry conforming when work in its domain changes what it describes.'
 ---
 
 # Context entry reference
 
 Applies to per-domain narrative entries under `canon/context/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
 
+## Contents
+
+- [Scope](#scope)
+- [Organizing principle](#organizing-principle)
+- [What a working entry looks like](#what-a-working-entry-looks-like)
+- [Frontmatter](#frontmatter)
+- [Required sections](#required-sections)
+- [Expected sections](#expected-sections)
+- [Optional sections](#optional-sections)
+- [Ordering](#ordering)
+- [The development entry](#the-development-entry)
+- [What goes in](#what-goes-in)
+- [What does not go in](#what-does-not-go-in)
+- [Length](#length)
+- [Examples](#examples)
+
 ## Scope
 
 Governs per-domain narrative entries under `canon/context/`: their structure, the decisions and gotchas they carry, and what they leave to the code.

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

@@ -1,6 +1,6 @@
 ---
 title: An unusable diff baseline
-description: When context-fold's diff baseline is unusable, what Step 2 reads to recover the committed half, and why Step 5 keeps the scoped set rather than the whole tree
+description: When context-fold's diff baseline is unusable, why Step 3 keeps the scoped set rather than the whole tree
 ---
 
 # An unusable diff baseline
@@ -14,10 +14,8 @@ The baseline is unusable in two cases:
 
 An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty by definition once the base equals HEAD, while `git diff HEAD` and `git ls-files --others --exclude-standard` still report uncommitted and untracked work at correct scope.
 
-**Step 2 recovers the committed half.** Read `git log -p -1`, widening to `git log -p -<n>` when the session spans several commits, and read the candidate task files against the working tree. That yields names and content both, which is what lets Step 2 decide on behavior rather than on filenames. A fresh `git init` on `main` with no remote is the ordinary shape of a scaffolded project, so this path carries the evidence rather than covering an edge case.
+**Step 3 keeps the scoped set.** Run it on the working tree and untracked files alone, and skip only when that set comes out empty, reporting the warning its own reference names.
 
-**Step 5 keeps the scoped set.** Run it on the working tree and untracked files alone, and skip only when that set comes out empty, reporting the warning its own step names.
-
-Never substitute the whole tree for a missing baseline, and do not reuse Step 2's commit read in Step 5 for consistency. On a fresh `git init` project the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route. Step 2 tolerates that because it only reads, and it matches conservatively against outcomes already on the board. Step 5 writes, so the same set rewrites every context entry that tree touches.
+Never substitute the whole tree for a missing baseline, and do not widen to `git log -p -1` for coverage. On a fresh `git init` project the last commit is the scaffold commit, so that read is the whole tree by another route, and Step 3 writes, so the same set rewrites every context entry that tree touches. `task-complete` takes the widened read for its marking step, which only reads and matches conservatively against outcomes already on the board.
 
 Widening what a step reads is safe. Widening what a step writes is not.

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

@@ -45,7 +45,7 @@ A project-authored rule numbers in `900-999`, the band reserved for one. `000-89
 
 ## Step 4: write the rule
 
-Read `${CLAUDE_SKILL_DIR}/../../standards/rule.md` for frontmatter, body shape, and voice before writing the body. Do not work the shape from memory.
+Read `${CLAUDE_SKILL_DIR}/references/rule.md` for frontmatter, body shape, and voice before writing the body. Do not work the shape from memory.
 
 Write `.claude/rules/project/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, subdir, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
 
@@ -66,7 +66,7 @@ paths:
 - <imperative rule>
 ```
 
-Title casing is sentence case, with proper nouns keeping their own casing (`# TypeScript standards`). `${CLAUDE_SKILL_DIR}/../../standards/rule.md` owns the rest of the body shape.
+Title casing is sentence case, with proper nouns keeping their own casing (`# TypeScript standards`). `${CLAUDE_SKILL_DIR}/references/rule.md` owns the rest of the body shape.
 
 ## After writing
 

package/{standards → claude/skills/create-rule/references}/rule.md

@@ -1,14 +1,22 @@
 ---
 title: Governance rule reference
 description: Rule frontmatter, body shape, and voice for .claude/rules files
-paths:
-  - '.claude/rules/**/*.md'
-rule:
-  - 'Read it before writing or editing a rule. Do not work the shape from memory.'
 ---
 
 # Governance rule reference
 
+## Contents
+
+- [Overview](#overview)
+- [Scope](#scope)
+- [Whether a skill belongs behind the rule](#whether-a-skill-belongs-behind-the-rule)
+- [Location](#location)
+- [Reserved numbers](#reserved-numbers)
+- [Two sources numbering into one folder](#two-sources-numbering-into-one-folder)
+- [Frontmatter](#frontmatter)
+- [Body](#body)
+- [Examples](#examples)
+
 ## Overview
 
 Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start.
@@ -41,7 +49,6 @@ Write both when both apply. A rule stating the directive and a skill stating how
 - A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, a sibling of `canon/` rather than nested inside it, keeping the same subdirectory names
 - This repository's own toolkit-only rules, which never ship to a target, live at `.claude/rules/internal/<subdirectory>/<n>-<slug>.md`, a second sibling of `canon/`. See "Two sources numbering into one folder" below.
 - Give every authored rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
-- A rule that only routes a path to a standard is generated, not authored. It lives at `governance/rules/standards/<standard>.md` under the standard's name, carries no number, and installs to `.claude/rules/canon/standards/`. Never hand-edit one. Change its globs and bullets in the standard's `paths` and `rule` frontmatter, and `canon gov regen` rewrites it. The generator refuses a standard named like a band folder, which keeps the bare-word name reachable.
 
 ## Reserved numbers
 

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

@@ -9,7 +9,7 @@ metadata:
 
 Read these files in parallel:
 
-- `${CLAUDE_SKILL_DIR}/../../standards/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
+- `${CLAUDE_SKILL_DIR}/references/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
 - `${CLAUDE_SKILL_DIR}/references/skill-requirement.md`: what `REQUIREMENT.md` must answer, its sections, and its template
 - `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites a standard
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for skill body text
@@ -18,7 +18,7 @@ Read these files in parallel:
 
 ## Guards
 
-- If `${CLAUDE_SKILL_DIR}/../../standards/skill.md` is not present, stop: `❌ skill.md standard not found. Reinstall the canon plugin.`
+- If `${CLAUDE_SKILL_DIR}/references/skill.md` is not present, stop: `❌ skill.md standard not found. Reinstall the canon plugin.`
 
 ## Steps
 

package/{standards → claude/skills/create-skill/references}/skill.md

@@ -1,22 +1,25 @@
 ---
 title: Claude skill reference
 description: Skill structure and authoring rules for Claude Code
-paths:
-  - '.claude/skills/**/SKILL.md'
-  - 'claude/skills/**/SKILL.md'
-  - '.claude/skills/**/REQUIREMENT.md'
-  - 'claude/skills/**/REQUIREMENT.md'
-rule:
-  - "Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `canon:create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate."
-  - 'Report it rather than proceeding silently when `canon:create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.'
-  - 'Re-read a skill body this session edited before invoking that skill again in the same session'
-  - 'Do not read a resolved file path in a held body as evidence the body is current'
-  - 'Follow the skill requirement standard for the shape a `REQUIREMENT.md` states. Read it with `canon standards skill-requirement`.'
-  - 'Follow the skill path standard for which root a path in a body resolves against and how a body cites a standard. Read it with `canon standards skill-paths`.'
 ---
 
 # Claude skill reference
 
+## Contents
+
+- [Overview](#overview)
+- [Scope](#scope)
+- [Changing a skill](#changing-a-skill)
+- [Whether a rule belongs beside the skill](#whether-a-rule-belongs-beside-the-skill)
+- [Skill types](#skill-types)
+- [Structure](#structure)
+- [Frontmatter](#frontmatter)
+- [Description](#description)
+- [Body](#body)
+- [Scripts](#scripts)
+- [Invocation](#invocation)
+- [Examples](#examples)
+
 ## Overview
 
 Skills give Claude Code domain-specific constraints and rules inline, so it can act immediately without reading all docs.
@@ -34,7 +37,7 @@ Does not govern:
 - Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
 - Punctuation, formatting, and word choice in a skill body: `markdown.md`
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
-- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the creation-time bullet in this standard's own `rule` frontmatter
+- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the creation-time bullet in the `skill` governance rule
 
 ## Changing a skill
 
@@ -133,7 +136,7 @@ allowed-tools: <tools required>
 - Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
 - Open a file under `references/` running over 100 lines with a `## Contents` H2 of anchor links after its H1 and intro, so a session that reads only the top of the file still sees everything it holds.
 - Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
-- Never point one skill at a sibling skill's folder for a reference both read. Each skill carries its own copy under `references/`, generated rather than hand-copied by the rule in `## Path resolution`.
+- Point one skill at a sibling skill's reference by the form `skill-paths.md` states, `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`, and name the owner rather than copying the file.
 
 ### Reading and running commands
 

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

@@ -15,7 +15,7 @@ The instruction against that already existed. `draft-and-pick` Step 1 says to na
 
 The second half is the output itself. A model with no stated direction draws the population average of its training data, which produces interfaces that satisfy every craft rule and still read templated.
 
-Prose is already governed in two halves and design is governed in neither. The character bans ship as data a command reads, and the shapes no closed word set can match needed a skill of their own, because each is a pattern rather than a token. `standards/design.md` governs the shape of a project's design document and is silent on whether its values are any good.
+Prose is already governed in two halves and design is governed in neither. The character bans ship as data a command reads, and the shapes no closed word set can match needed a skill of their own, because each is a pattern rather than a token. `claude/skills/canvas-board/references/design.md` governs the shape of a project's design document and is silent on whether its values are any good.
 
 Importing an external catalog wholesale fails on what those catalogs turn out to carry. The largest is 1,206 lines in one file, pinned to one framework, one styling library and one animation package, and it scopes itself out of dashboards, data tables and multi-step product UI. A second bans default fonts by name and prescribes a component library.
 
@@ -56,7 +56,7 @@ A rule failing any of the four is recorded as considered and declined rather tha
 - Express intensity as a numeric scale. A session picks a middle value and reports compliance, which satisfies the rule and decides nothing.
 - Claim the reported failure is closed. Nothing measures whether a round follows these rules, so this skill states them and the measurement is owed separately.
 - Duplicate a rule a surface already states for itself, such as slide layout or terminal color, where pointing at that surface is the whole of the correct answer
-- Be reached only by an author typing its name. `standards/skill.md` makes this a review criterion rather than a check, since nothing answers it before the skill has run. The intended non-author caller is the declared read in `draft-and-pick`'s output. A round producing no read, with this skill never loaded, is the evidence that the description's triggers are too weak.
+- Be reached only by an author typing its name. `claude/skills/create-skill/references/skill.md` makes this a review criterion rather than a check, since nothing answers it before the skill has run. The intended non-author caller is the declared read in `draft-and-pick`'s output. A round producing no read, with this skill never loaded, is the evidence that the description's triggers are too weak.
 
 ## Guards
 
@@ -71,6 +71,6 @@ A rule failing any of the four is recorded as considered and declined rather tha
 - Validation timing, error placement and save blocking, which `420-forms` owns
 - Rendered copy casing, button labels and error wording, which `400-ui` owns
 - The candidate loop, the arm set, the render and the pick, which `draft-and-pick` owns and which this skill is loaded alongside rather than inside
-- The shape of the project's design document, its sections and its token tables, which `standards/design.md` governs
+- The shape of the project's design document, its sections and its token tables, which `claude/skills/canvas-board/references/design.md` governs
 - Prose on the surface being designed, which `write-human` and `markdown.md` govern between them
 - Measuring whether finished output followed these rules, which needs a check this skill does not carry and which no command reaches while a render is an image rather than a parse

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

@@ -145,6 +145,6 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 - States, empty and loading coverage, destructive confirmation, truncation: the same rules
 - Rendered copy casing, button labels, error message shape: the same rules
 - The candidate loop, the arm set, the render, and the pick: `draft-and-pick`
-- The shape of the project's design document and its token tables: `${CLAUDE_SKILL_DIR}/../../standards/design.md`
+- The shape of the project's design document and its token tables: `${CLAUDE_SKILL_DIR}/../canvas-board/references/design.md`
 - Reading source for roughness: `ux-audit`. Measuring what a running interface costs to paint: `ux-measure`
 - Prose on the surface being designed: the `write-human` skill

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

@@ -35,7 +35,7 @@ The quiet one is the baseline. A diff resolved against a bare local ref equals H
 
 ## Out of scope
 
-- The context entries 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: `context-fold`, which runs ahead of this skill in the ship chain and resolves the same baseline. The task board: `task-complete`, which runs between the two. 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
 - `CLAUDE.md` and the installed seed docs, which an operator reconciles by hand against the toolkit source
 - Changelog entries, which release tooling generates from commit messages

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

@@ -1,6 +1,6 @@
 ---
 name: docs-sync
-description: Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync the public docs", "update the docs in docs/", or "update the README". Do NOT use for the context entries, planning records, or task board, which `context-fold` owns, or for changelog and `CLAUDE.md` updates.
+description: Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync the public docs", "update the docs in docs/", or "update the README". Do NOT use for the context entries, which `context-fold` owns, the task board, which `task-complete` owns, or for changelog and `CLAUDE.md` updates.
 metadata:
   family: ship
 ---
@@ -11,8 +11,8 @@ Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for all generated text
 - The `write-human` skill: voice, rhythm, and sentence construction for all generated text
-- `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: README structure, required sections, and content rules
-- `${CLAUDE_SKILL_DIR}/../../standards/docs.md`: the reader a page under `docs/` serves, its frontmatter, structure, and what it links out rather than carrying
+- `${CLAUDE_SKILL_DIR}/references/readme.md`: README structure, required sections, and content rules
+- `${CLAUDE_SKILL_DIR}/references/docs.md`: the reader a page under `docs/` serves, its frontmatter, structure, and what it links out rather than carrying
 
 ## Diff baseline
 

package/{standards → claude/skills/docs-sync/references}/docs.md

@@ -7,6 +7,17 @@ description: Reader and jurisdiction, frontmatter, page structure, what a page l
 
 Applies to each authored reference page under `docs/`. Skip for `index.md` at any depth, which is generated rather than authored.
 
+## Contents
+
+- [Scope](#scope)
+- [What a working docs page looks like](#what-a-working-docs-page-looks-like)
+- [Frontmatter](#frontmatter)
+- [Structure](#structure)
+- [Content](#content)
+- [Diagrams](#diagrams)
+- [Splitting the folder](#splitting-the-folder)
+- [Template](#template)
+
 ## Scope
 
 Governs each authored reference page under `docs/`, whose reader is an operator running what the project ships rather than developing it, and an agent reading the page cold from a project that consumes it: the frontmatter a page carries, its structure, what it links out to rather than restating, whether it holds a diagram, and when a category earns a subfolder of its own.

package/{standards → claude/skills/docs-sync/references}/readme.md

@@ -1,8 +1,6 @@
 ---
 title: Readme reference
 description: Readme voice, structure, and content conventions
-paths:
-  - '**/README.md'
 ---
 
 # Readme reference
@@ -11,6 +9,15 @@ Applies to every `README.md`. The `## Voice` section states the voice for a repo
 
 The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
 
+## Contents
+
+- [Scope](#scope)
+- [Voice](#voice)
+- [Structure](#structure)
+- [Sections](#sections)
+- [Content](#content)
+- [Examples](#examples)
+
 ## Scope
 
 Governs every `README.md`: voice, heading structure, required and optional sections, the header block, badge selection, and what the page links out to instead of carrying.

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

@@ -9,7 +9,7 @@ metadata:
 
 Some decisions are settled by looking rather than by reasoning, and no draft is wrong until one is picked. Every step here puts several candidates in front of the operator and keeps the real surface untouched until they have chosen.
 
-The candidates live on the local design canvas, the surface `canon:canvas` drives. Every verb below is `canon canvas`, and `canon standards canvas` fixes the content format a frame takes. Read that standard before writing the first frame.
+The candidates live on the local design canvas, the surface `canon:canvas-board` drives. Every verb below is `canon canvas`, and `canon standards canvas` fixes the content format a frame takes. Read that standard before writing the first frame.
 
 ## Guards
 
@@ -30,10 +30,10 @@ The candidates live on the local design canvas, the surface `canon:canvas` drive
 
 Every arm of a round sits as one frame on one canvas page, side by side. The comparison the operator judges is that page, never a set of separate images handed over to compare from memory.
 
-1. Start the canvas the way `canon:canvas` Step 1 states, unless this run already has: read `canon canvas list --json`, start `canon canvas serve --json` in the background unless the operator named an address that already answers, and fetch the `url` the record carries to check the shell's body holds a `<script` tag. Note whether this run started the server, since Step 6 stops only a server this run started. A refused serve or a blank shell stops the run, reported with its `reason`. A run with no canvas cannot draft, and no file stands in for one.
+1. Start the canvas the way `canon:canvas-board` Step 1 states, unless this run already has: read `canon canvas list --json`, start `canon canvas serve --json` in the background unless the operator named an address that already answers, and fetch the `url` the record carries to check the shell's body holds a `<script` tag. Note whether this run started the server, since Step 6 stops only a server this run started. A refused serve or a blank shell stops the run, reported with its `reason`. A run with no canvas cannot draft, and no file stands in for one.
 2. Add the round's page with `canon canvas page add <page> --json` and record its name on the run's own list of pages it added. A name `canvas list` already shows belongs to somebody else, so take the next free suffix rather than writing into it.
 3. Add each arm as a frame with `canon canvas frame add <page> arm-<id> --width <px> --height <px> --json`. Name every frame `arm-<id>`, since Step 6's archive keeps those names and its readers key on them. Set the width the arm is judged at. A frame renders at its own layout width on the canvas and in a capture alike, so a decision about layout reads off the frame itself and needs no device toolbar.
-4. Write each arm's whole document to the `path` the add verb reported. From a linked worktree, take the heredoc route `canon:canvas` Step 3 gives for a main-root write.
+4. Write each arm's whole document to the `path` the add verb reported. From a linked worktree, take the heredoc route `canon:canvas-board` Step 3 gives for a main-root write.
 5. Lay the frames out in one row, in arm order, with `canon canvas frame move <page> arm-<id> --x <px> --y <px> --json`.
 
 ### What every frame carries
@@ -62,7 +62,7 @@ canon canvas capture <page> --composite --json
 - Point `--out` at `evidence/<slug>/renders/<page>.png` inside a live track, and leave it at its session-scratch default everywhere else. A pick taken from an image the track does not hold is a judgment nobody but this session can check, and the archive in Step 6 covers the picked round alone.
 - Read the PNG's `path` off the record. The composite shows every frame in its default theme, so look at the other theme on the live canvas where the arms carry two.
 - `canon canvas capture` needs a browser binary the toolkit does not install. When it refuses for that reason, report the refusal and name `bunx playwright install chromium` as the repair, stop the canvas server if this run started it, then stop rather than describing an arm nobody has seen.
-- A capture refusing on a font names the family it read off the frame's text. Take the repair `canon:canvas` Step 6 gives and capture again.
+- A capture refusing on a font names the family it read off the frame's text. Take the repair `canon:canvas-board` Step 6 gives and capture again.
 - Hand over the address rather than a description. Emit the canvas link first on its own line, naming the page, then the PNG path on its own line. A still answers how a thing looks and answers none of a hover response, a scroll-linked position, or a pace, which the live frame does.
 - Never report a visual result you have not looked at. A claim about appearance with no render behind it is a guess.
 - Look to judge rather than to confirm. Reading the image back to check it rendered satisfies the rule above and still hands over weak work, so name the weakest thing on the page in a sentence. Where that sentence would embarrass the work, fix it and hand over the second version. Say the remaining weakness out loud either way, so the operator is not hunting for what you already know.
@@ -120,4 +120,4 @@ Cite these rather than restating them. A step reimplemented here rots against th
 - `write-human` carries the voice for any copy an arm puts in front of a reader
 - `git-stage`, `git-pr`, and `git-followup` carry the commits and the pull request
 - `review-pr` and `review-address` run the review pass
-- `canon:canvas` carries the canvas start-and-check sequence, the main-root write route for a frame, and the selection and capture refusals
+- `canon:canvas-board` carries the canvas start-and-check sequence, the main-root write route for a frame, and the selection and capture refusals