@erclx/canon 5.35.0 → 5.37.0

package/docs/agents/markdown-audit.md

@@ -55,13 +55,23 @@ A relative link's destination resolves against the filesystem, over the same cor
 
 The placeholder exemption is the one live case the corpus needs. Every current instance is a genuine illustration rather than a literal path, and a marker-based override is available for the day a real one needs an exception instead.
 
+### Colons and heading case
+
+Two advisory measures report beside the bans and never fail a run.
+
+The colon measure reports a colon followed by more text in a prose line, outside the label position. A list item's first colon, a bold or code span label, a line-final colon, a time, a URL, and anything inside a code span or a link are left alone. A heading, a table row, and a fenced line are skipped. Each finding carries the line, the column, the line's text, and the word before the colon as `lead` under `colons` in the `--json` entry.
+
+The heading-case measure reports a heading or a frontmatter `title` with a capitalized word after its first, outside code spans and all-caps tokens, under `headingCase`. A proper noun reports as well and is left as it is.
+
+`CHANGELOG.md` is exempt from both, since the release tool writes its headings.
+
 ### Weight, cadence, and length
 
-Bullet and paragraph weight, run depth, the two cadence numbers, and the document length ceiling are each a judgment a reader settles rather than a fact a scan settles. What each measures, the samples behind its checkpoint, and why none of them gates are in `markdown-audit-weight.md`.
+Bullet and paragraph weight, bullet stacks, run depth, the two cadence numbers, and the document length ceiling are each a judgment a reader settles rather than a fact a scan settles. What each measures, the samples behind its checkpoint, and why none of them gates are in `markdown-audit-weight.md`.
 
 ## Exit codes
 
-Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code. Length reports the same way, since the audit also runs on a plan kept out of version control, and the Document ceiling stage in `canon gate run` owns that verdict instead.
+Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code. A bullet stack, a run of more than 5 plain bullets, reports the same way, and the `bullet-stacks` stage in `canon gate run` owns its verdict. Length reports the same way, since the audit also runs on a plan kept out of version control, and the Document ceiling stage in `canon gate run` owns that verdict instead.
 
 `3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `canon gate run` is right to report it as unmeasured rather than as a pass. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
 
@@ -95,6 +105,8 @@ The target push stage excludes `CHANGELOG.md`, unlike every other surface here.
 
 The hook prefers a checkout's own `src/cli.ts` over a globally installed binary, so it and the push stage read one build. A published binary lags a branch by whatever has not been released, which would put a ban kind added on the branch into the push and not into the edit. It reads its findings out of the `--json` record rather than off the exit code, so an older binary still reports where the fallback applies. It reads `bans.emptySets` out of the same record, so a set the verb shipped empty reaches the author as a check narrowed to what it could measure rather than as a clean pass.
 
+It also relays the two advisory measures from the same record. A heading finding reports for the whole file, and a colon finding reports only where the word before the colon and the colon appear in the text the write carried, so an edit is never asked to answer for a colon it left untouched.
+
 That field replaced `bans.missingStandards`, which answered a standard resolving under none of three roots. The set ships with the package now, so the state it named cannot occur and the narrowed check has one cause left, a defect in the build. The hook keeps reading a field either way, since a reader cannot tell a narrowed check from a clean one without it.
 
 Both hooks answer an absent record as well. A completed run always writes the record and a refusal writes none, so an empty one means the verb declined to measure rather than measured and found nothing. The verb needs a git repository to build its corpus and refuses without one, which is a project the seeded hook can be installed into, and reading the findings alone reported that as a clean file.

package/docs/agents/output-shape.md

@@ -40,7 +40,7 @@ Rules:
 └
 ```
 
-Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to stdout because `--help` is documentation, not runtime UI.
+Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to stdout because `--help` is documentation, not runtime UI. `--help --all` on a command prints each block unframed, one after another, and a help request naming an unknown subcommand, under a group that takes no operand of its own, writes its refusal to stderr and exits 1.
 
 ## JSON and `--names` modes
 

package/docs/agents/overview.md

@@ -11,7 +11,7 @@ This folder is an index of what an agent can run and how to run it cleanly from
 
 ## Invocation rules
 
-See `CLAUDE.md` design principles. They apply to every command in this folder.
+`output-shape.md` holds the stream and exit contract. It applies to every command in this folder.
 
 ## Where to start
 
@@ -21,6 +21,6 @@ See `CLAUDE.md` design principles. They apply to every command in this folder.
 
 ## Related
 
-- `CLAUDE.md`: project behaviors and design principles
+- `CLAUDE.md`: project behaviors
 - `.claude/skills/internal-*`: domain-scoped guidance for editing work, in the toolkit checkout only
 - `docs/index.md`: full docs directory

package/docs/agents/pr-frames.md

@@ -8,7 +8,7 @@ description: How canon pr frames pushes a UI review frame to a never-merged bran
 `canon pr frames` gives a review comment an image it can embed. `review-ui`
 drives a pull request's checklist and captures a frame per box, and a frame
 on the reviewer's disk resolves for nobody else. The verb pushes one frame to
-the `canon-frames` branch and returns a link to its path there.
+the `canon/frames` branch and returns a link to its path there.
 
 ```bash
 canon pr frames 1341 --add frames/3.png --box 3 --head <sha> --pass 20261002T154450Z --json
@@ -19,7 +19,7 @@ canon pr frames --prune 30 --json
 
 ## What it writes
 
-The verb writes `refs/heads/canon-frames` and no other ref. Every call goes
+An add writes `refs/heads/canon/frames` and no other ref. Every call goes
 through the GitHub git data API, being blobs, trees, commits, and that one ref,
 so nothing is checked out, no worktree is entered, and neither `main` nor any
 branch a pull request holds is touched. The branch never merges.
@@ -36,7 +36,7 @@ box therefore writes a new file rather than replacing the image an earlier
 comment shows, which matters when a preview is minted again at one head.
 
 `link` uses the same `blob/<ref>/<path>?raw=true` form as the evidence comment,
-naming the `canon-frames` branch rather than a commit. Every drop rewrites the
+naming the `canon/frames` branch rather than a commit. Every drop rewrites the
 branch, and a link pinned to a commit would stop resolving for every other pull
 request's frames once GitHub collects the commit it names. A path link lives
 exactly as long as its file, so it survives every rewrite that drops another
@@ -97,6 +97,20 @@ than that many days ago, in a single rewrite. It keeps one still open, one
 reopened after closing, one closed exactly the given days ago, and one whose
 state could not be read, listing that last kind under `unread`.
 
+## The legacy branch
+
+Frames lived on `canon-frames` before the rename to `canon/frames`. An add
+never writes it. `--drop` and `--prune` also run against it after the
+current branch, remove only, and delete it once empty. `--prune` drains it
+as its pull requests expire, and `--drop` clears one pull request at once.
+The record carries `legacy: true` when that
+pass changed the ref, and its `removed` list folds both branches in, naming
+a pull request once. A missing or unreadable legacy ref never fails a run
+the current branch finished.
+
+A link minted before the rename points at `blob/canon-frames/...` and keeps
+resolving until its pull request has been closed 30 days or `--drop` runs.
+
 This repository runs `--prune 30` daily from
 `.github/workflows/pr-frames-cleanup.yml`. A frame's file stays on the branch
 until its own pull request has been closed for 30 days, so a link in a review

package/docs/agents/rule-citations.md

@@ -1,6 +1,6 @@
 ---
 title: Rule citations
-description: Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the two forms a citation is written in, the shapes that look like citations and are not, the two classes where an absent path is correct, why the glob half reads one corpus, and why this one gates
+description: Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the one form a citation is written in, the shapes that look like citations and are not, the two classes where an absent path is correct, why the glob half reads one corpus, and why this one gates
 ---
 
 # Rule citations
@@ -28,14 +28,9 @@ Under `--json` the record holds stdout alone and the frame still renders on stde
 
 Two files agreeing is what a drift check measures. Whether either one is right about the tree is a different question, and this is the stage that asks it.
 
-## The two forms
+## The one form
 
-A citation reaches a reader in one of two shapes, and each resolves against a different root.
-
-| Form      | Shape                    | Resolves against                   |
-| --------- | ------------------------ | ---------------------------------- |
-| `path`    | a backticked path        | the root                           |
-| `sibling` | a bare `<nnn>-<slug>.md` | the folder the citing rule sits in |
+A citation reaches a reader as a backticked path, reported under the form `path`, and it resolves against the root. A bare filename is never a citation, since with no folder around it nothing tells a rule from a convention such as `index.md`. A rule pointing at another rule writes its repository path.
 
 A call to the retired standards verb is no form here. A rule holding one fails the shipped-references stage of `canon gate run`, which reads every shipped file for it.
 
@@ -46,7 +41,7 @@ A `path` is anchored on the whole backticked span rather than on a trailing patt
 A rule body is full of backticked spans carrying a slash, and almost none of them names a file in this tree. The stage declines four shapes outright.
 
 - A placeholder or glob segment describes a shape rather than naming a file: `canon/context/<domain>.md`, `app/**/route.ts`, `${CLAUDE_SKILL_DIR}/../references/<name>.md`.
-- A bare filename names a convention: `route.ts`, `manifest.toml`, `components.json`, `playwright.config.ts`. A bare name is read as a citation only when it matches a rule filename, which is how one authored rule would point at a sibling such as `605-worktrees.md`.
+- A bare filename names a convention: `route.ts`, `manifest.toml`, `components.json`, `playwright.config.ts`.
 - A span carrying no file extension is a folder or a module specifier: `src/pages/`, `next/font`, `try/except`, `react-hooks/set-state-in-effect`, `oven-sh/setup-bun@v2`, `@/lib/utils`.
 - A fenced block displays a path rather than pointing at one.
 
@@ -70,7 +65,7 @@ A rule under `governance/rules/` installs into a target, and its `paths:` entrie
 
 `internal/rules/` ships nowhere. The tree it governs is the tree present, which makes the question answerable, and all 14 of its globs across 7 rules match at the commit this shipped on.
 
-What that leaves unreached is a glob that matches real files and still reaches none of the work it was scoped at. `governance/rules/lib/305-e2e-reliability.md` scoped itself at `e2e/*.ts` and `e2e/**/*.ts` and now reads `**/e2e/**/*.ts`. No probe in this repository is written under `e2e/`, so the rule asking a session to watch a new guard fail never fired for the session writing guards. Resolution is mechanical and reach is a judgment about where the work happens, so only the first is here.
+What that leaves unreached is a glob that matches real files and still reaches none of the work it was scoped at. `governance/rules/lib/e2e-reliability.md` scoped itself at `e2e/*.ts` and `e2e/**/*.ts` and now reads `**/e2e/**/*.ts`. No probe in this repository is written under `e2e/`, so the rule asking a session to watch a new guard fail never fired for the session writing guards. Resolution is mechanical and reach is a judgment about where the work happens, so only the first is here.
 
 ## The exemption marker
 

package/docs/agents/scripting.md

@@ -79,7 +79,7 @@ CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
 CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --write
 
 # Install a governance stack (the stack argument is required headlessly)
-CANON_NON_INTERACTIVE=1 canon gov install node --add 210-astro,260-shadcn /path/to/project
+CANON_NON_INTERACTIVE=1 canon gov install node --add astro,shadcn /path/to/project
 
 # Update installed governance rules, dropping a retired .claude/GOV.md
 CANON_NON_INTERACTIVE=1 canon gov sync /path/to/project

package/docs/agents/sessions-transfer.md

@@ -67,12 +67,14 @@ The transcript and side folder land under `projects/<encoding>/`, where the enco
 
 Exit codes: `0` the session was placed, `1` refused. The refusal carries one of these reasons:
 
-- `not-a-bundle`: the file is no gzip tarball, carries no manifest at format `1`, or names a path outside its own session, such as one climbing out with `..` or an absolute one
-- `other-repository`: the local `origin` differs from the one the bundle recorded
-- `exists`: the target transcript or side folder is already there, or any other project folder already holds a transcript for the id, which `--resume <id>` could reach first
-- `live-here`: the id is live in the local roster, so a second copy would fork it
-- `write-failed`: a write failed partway for a reason other than a copy appearing, such as a bundle carrying a file where it also needs a folder
-- `no-archive`: the running Bun predates `Bun.Archive`
+| Reason             | Meaning                                                                                                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `not-a-bundle`     | the file is no gzip tarball, carries no manifest at format `1`, or names a path outside its own session, such as one climbing out with `..` or an absolute one    |
+| `other-repository` | the local `origin` differs from the one the bundle recorded                                                                                                       |
+| `exists`           | the target transcript or side folder is already there, or any other project folder already holds a transcript for the id, which `--resume <id>` could reach first |
+| `live-here`        | the id is live in the local roster, so a second copy would fork it                                                                                                |
+| `write-failed`     | a write failed partway for a reason other than a copy appearing, such as a bundle carrying a file where it also needs a folder                                    |
+| `no-archive`       | the running Bun predates `Bun.Archive`                                                                                                                            |
 
 A write that fails partway removes every file this run placed and every folder it created before refusing, so a retry of the same bundle does not refuse on its own leftovers. Any path it could not remove is named in the message. A copy that appears between the existence check and the write refuses as `exists` on the same terms.
 

package/docs/agents/skills-audit.md

@@ -28,14 +28,22 @@ The audit reads the directory it is pointed at, defaulting to the cwd. `canon cl
 
 Each check traces to a line in the standard.
 
-- `REQUIREMENT.md` present in every skill folder
+### Folder and frontmatter
+
 - Frontmatter `name` matching the folder name
 - Frontmatter `description` present
 - `description` under 1024 characters
 - No `README.md` inside a skill folder
 - Folder name in kebab-case
+
+### Requirement and content
+
+- `REQUIREMENT.md` present in every skill folder
 - Each `REQUIREMENT.md` declaring `Gap` and `Must`, matched at any heading level
 - No ISO date in `SKILL.md` or any file under `references/`, reported as `datedProvenance` in the JSON record's `findings`
+
+### Practice, references, and family
+
 - Each listed practice skill closing with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, and each skill on the wider ledger list carrying `references/adopted.md`, reported together as `practiceShape`
 - Each file under `references/` running over 100 lines opening with a `## Contents` H2, reported as `referenceContents`
 - Each skill under `claude/skills/` declaring a `metadata.family` that names a key in `checkpoints.families`, reported as `family`

package/docs/target/projects.md

@@ -72,7 +72,7 @@ Keep the `## Scripts` table in `canon/context/development.md` current as scripts
 Scaffold installs tooling and seeds. It does not fill the planning docs or the design system. Complete those before the first feature session:
 
 1. Fill `canon/REQUIREMENTS.md`. The seed asks for the problem in one line, then goals and non-goals, and the scope is yours to write. The seed states its own cap of 600 words, and `canon context audit` gates on it. Edit the number in the record to loosen it. A decision about how the project is built goes in the `canon/context/` entry of the domain it constrains.
-2. For a UI project, write `canon/DESIGN.md` from the seed template, or work the direction out with `canon:canvas-board` and carry the pick in. Skip for non-UI projects.
+2. For a UI project, write `canon/DESIGN.md` from the seed template and name the project's stylesheet in its lead, or work the direction out with `canon:canvas-board` and carry the pick in. Skip for non-UI projects.
 3. Optionally invoke `canon:draft-figure` naming an architecture view, such as system context or components, and the document it belongs in. It draws the view from the context index, the folder layout, and the requirements and renders it to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
 4. Start the feature loop. See [AI workflow](../workflow/ai-workflow.md) for the per-feature sequence.
 
@@ -88,7 +88,7 @@ Escalate for a project writing code. The `target-setup` skill reads `package.jso
 
 In a monorepo the skill reads each folder holding a `package.json`, `pyproject.toml`, `go.mod`, `composer.json`, or `Cargo.toml` to depth two, skipping what git ignores. Each of those folders gets its own tooling stack and a `canon tooling sync <stack> <folder> --skip base` in the preview. Governance still installs once at the root, since a rule's `paths:` globs reach every subfolder, so a subfolder's language rules join the root install through `--add`.
 
-The server-side security and persistence rules belong to no stack. `canon gov detect` proposes both from a server framework or database client in the manifest, which you confirm in the preview, or add them by hand with `--add 360-security-server,370-database`.
+The server-side security and persistence rules belong to no stack. `canon gov detect` proposes both from a server framework or database client in the manifest, which you confirm in the preview, or add them by hand with `--add security-server,database`.
 
 Markdown-heavy projects, CLI tools, docs sites, research notebooks, and scripting repos stay on `base`. Escalation is a ceiling move, not a default.
 

package/docs/target/scenarios.md

@@ -26,7 +26,7 @@ bun create vite my-app && cd my-app
 claude
 ```
 
-Invoke `canon:target-setup`. The skill reads `package.json` and the Vite config, resolves tooling to `vite-react` and governance to `node`, proposes `200-react` and the other rules its manifest matches as extras, and runs `canon init` with the resolved flags.
+Invoke `canon:target-setup`. The skill reads `package.json` and the Vite config, resolves tooling to `vite-react` and governance to `node`, proposes `react` and the other rules its manifest matches as extras, and runs `canon init` with the resolved flags.
 
 Ongoing maintenance:
 
@@ -34,22 +34,22 @@ Ongoing maintenance:
 - Seed drift: merge by hand against the toolkit copy
 - Catch-all sync: `canon sync .`
 - Governance rule refresh only: `canon gov sync .`
-- Layer a new rule on top, for example `260-shadcn` after adopting shadcn: `canon gov install node --add 260-shadcn .`
+- Layer a new rule on top, for example `shadcn` after adopting shadcn: `canon gov install node --add shadcn .`
 
 ## Monorepo with multiple language roots
 
 The repo root owns the shared `base` layer, and each language lives in its own subfolder.
 
 ```bash
-canon init --stack node --add 200-react .
+canon init --stack node --add react .
 canon tooling sync vite-react ./frontend --skip base --write
 canon tooling sync python ./backend --skip base --write
 ```
 
-`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, commitlint, and CI stay single at the repo root. The one exception is base's verify runner, `scripts/verify.sh`, `scripts/verify.ts`, and `scripts/verify.json`, which every subtree still receives so it can verify on its own. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite), and its own stack reference reads through `canon tooling reference <stack>`.
+`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, commitlint, and CI stay single at the repo root. The one exception is base's verify runner, `scripts/verify.ts` and `scripts/verify.json`, which every subtree still receives so it can verify on its own. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite), and its own stack reference reads through `canon tooling reference <stack>`.
 
 A sync whose target sits below the git root knows it is writing into a subfolder:
 
 - It withholds `.github/`, since GitHub reads workflows only at the repository root, and names each withheld file. Run the subtree from a job in the root workflow instead, with `working-directory` set to the subtree path the sync prints, such as `working-directory: frontend`.
 - It installs no dependencies and adds no scripts to a subtree without a `package.json`. It names what it skipped and ends on `run 'bun init' in <path>, then sync again`.
-- The subtree carries no `check` script, since that lives in the root's base layer, so run `./scripts/verify.sh` there. It skips the format and shell phases a subtree does not declare, since the root runs them, and still fails on a missing lint, typecheck, or test script, the phases its stack's `scripts/verify.json` requires.
+- The subtree carries no `check` script, since that lives in the root's base layer, so run `bun scripts/verify.ts` there. It skips the format phase a subtree does not declare, since the root runs them, and still fails on a missing lint, typecheck, or test script, the phases its stack's `scripts/verify.json` requires.

package/docs/target/standards-moved.md

@@ -10,23 +10,25 @@ category: Agent surface
 
 Each standard now lives at `references/<name>.md` in the skill that owns it. Load that skill and read the reference it names:
 
-- `task-board`: `board`, `tasks`, `tasks-decline`
-- `context-fold`: `context`
-- `canvas-board`: `canvas`, `design`
-- `docs-sync`: `docs`, `readme`
-- `draft-figure`: `figures`, `mermaid`
-- `create-rule`: `rule`
-- `create-skill`: `skill`, `skill-paths`, `skill-practice`, `skill-requirement`
-- `git-branch`: `branch`, `slug`
-- `git-commit`: `commit`, `versioning`
-- `git-pr`: `pr`, `publish`
-- `markdown-craft`: `markdown`
-- `teach-workspace`: `glossary`, `teach`
-- `plan-groundwork`: `groundwork`, `groundwork-spikes`
-- `plan-intake`: `intake`
-- `plan-feature`: `plan`, `plan-lifecycle`
-- `draft-ready`: `ready`
-- `draft-doc`: `requirements`, `wiki`
-- `session-map`: `session`
+| Skill             | Standards                                                     |
+| ----------------- | ------------------------------------------------------------- |
+| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
+| `context-fold`    | `context`                                                     |
+| `canvas-board`    | `canvas`, `design`                                            |
+| `docs-sync`       | `docs`, `readme`                                              |
+| `draft-figure`    | `figures`, `mermaid`                                          |
+| `create-rule`     | `rule`                                                        |
+| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
+| `git-branch`      | `branch`, `slug`                                              |
+| `git-commit`      | `commit`, `versioning`                                        |
+| `git-pr`          | `pr`, `publish`                                               |
+| `markdown-craft`  | `markdown`                                                    |
+| `teach-workspace` | `glossary`, `teach`                                           |
+| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
+| `plan-intake`     | `intake`                                                      |
+| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
+| `draft-ready`     | `ready`                                                       |
+| `draft-doc`       | `requirements`, `wiki`                                        |
+| `session-map`     | `session`                                                     |
 
 One name moved under a new filename. `standard`, the shape of a standard itself, became `skill-reference.md` in `create-skill`, since the toolkit no longer ships a standards folder to hold one.

package/docs/workflow/ai-workflow.md

@@ -17,7 +17,7 @@ Project docs split across three roots at the project root. What the project auth
 ```plaintext
 canon/
 ├── REQUIREMENTS.md  ← problem, goals, non-goals
-├── DESIGN.md        ← visual intent and token decisions (UI projects)
+├── DESIGN.md        ← visual intent, pointing at the stylesheet (UI projects)
 └── context/         ← per-domain narrative loaded on demand via index.md
 
 .claude/
@@ -52,6 +52,9 @@ Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full fi
 - When the input is a pile of findings rather than one feature, invoke `canon:plan-intake` first. It files the dump into `.canon/intake/<nn>-<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled.
 - When the backlog has grown past what anyone rereads, invoke `canon:backlog-triage`. It files one item per backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, and once `canon:plan-intake-answer` has taken your answers, a second run applies the approved verdicts through the task verbs.
 - When the current state is unmeasured and more than one approach is live, invoke `canon:plan-groundwork` first. It opens a track folder under `.canon/groundwork/<nn>-<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled.
+
+Then plan and build:
+
 - Invoke `canon:plan-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
 - Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
 - For UI changes, invoke `canon:ui-checklist` to write what a reviewer has to look at and name any behavior shipping without a test

package/docs/workflow/visual-design-workflow.md

@@ -14,19 +14,19 @@ The tier framework sits alongside [Claude Design](../../wiki/claude/design.md),
 
 ## Tier 0: prose only
 
-The default. `canon/DESIGN.md` holds visual intent as token tables for color, typography, spacing, and borders, with one Personality paragraph and at most three one-line rules a section, motion and iconography included.
+The default. `canon/DESIGN.md` holds visual intent, being one Overview paragraph, at most three one-line rules a section, and a table naming what each color and shape role is for. Its lead names the stylesheet the values live in, since a hand-typed copy of them drifts from the CSS.
 
 Claude Code reads it and writes the implementation. Works for CLI tools, internal dashboards, admin panels, and backend-focused projects.
 
 ### Seed shape
 
-The toolkit seed in `tooling/claude/seeds/canon/DESIGN.md` ships a token-table template with a starting set of roles, and `claude/skills/canvas-board/references/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the renderer parses, so they stay verbatim in either, while the rows and values are the project's own.
+The toolkit seed in `tooling/claude/seeds/canon/DESIGN.md` ships an intent template with a starting set of roles, each naming its custom property, and `claude/skills/canvas-board/references/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the parser reads, so they stay verbatim in either, while the rows are the project's own. The seed's lead asks for the project's own stylesheet, such as `src/styles/tokens.css` or a Tailwind `@theme` block, and falls back to `.claude/design/project/` only when the project has none.
 
 `canon design render` writes an HTML plus CSS preview to `.canon/tmp/render/design/` for eyeballing the current system without leaving Claude Code. See `canon/context/design/index.md`.
 
 A project wanting a neutral starting point to override runs `canon design install`, which copies one stylesheet to `.claude/design/base.css` carrying an achromatic token set as custom properties and two components built on them. Greys run from near-black to near-white and the accent is monochrome, so the only palette the project renders is one it writes itself. That file is toolkit-owned and `canon design sync` refreshes it, so a project overrides a value in `.claude/design/project/` instead, which sync never touches. Nothing arrives without that install, and the two channels are independent: a record the project wrote is its own, and the installed stylesheet is the toolkit's.
 
-A cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
+A record generated from a token source carries the values in tables instead, which is the shape this toolkit's own record takes. There a cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
 
 ### Tools
 
@@ -35,9 +35,14 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 
 ### Skills
 
+#### Reviewing and measuring
+
 - `canon:ui-checklist` for what a reviewer has to look at after UI changes, and what ships without a test
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
+
+#### Drafting
+
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates as frames on the canvas and taking your pick
 - `canon:canvas-board` for a direction worked out over several turns, drawn as HTML frames you drag, select, and restyle in the browser while the session reads your changes back. Only the pick moves into `canon/DESIGN.md`, since the canvas folder is gitignored
 - `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop. On an Astro project holding the card route scaffold, the card lands as a route the project keeps and is captured through a running server, so it reads the project's real stylesheet rather than typed copies of every color. Everywhere else it ships as a PNG and the run says so.

package/governance/detect.toml

@@ -21,67 +21,67 @@
 deps = []
 files = [".claude/skills", "claude/skills"]
 
-["700-ci-workflow"]
+["ci-workflow"]
 deps = []
 files = [".github/workflows"]
 
-["775-dependencies"]
+["dependencies"]
 deps = []
 files = ["**/package.json", "**/pyproject.toml", "**/go.mod", "**/composer.json"]
 
-["780-config-comments"]
+["config-comments"]
 deps = []
 files = [".editorconfig", "**/Dockerfile*", "**/*.config.*", "**/.env.example"]
 
-["790-code-comments"]
+["code-comments"]
 deps = []
 files = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.sh", "**/*.py"]
 
-["130-go"]
+["go"]
 deps = []
 files = ["**/go.mod"]
 
-["140-php"]
+["php"]
 deps = []
 files = ["**/composer.json"]
 
-["200-react"]
+["react"]
 deps = ["react"]
 files = []
 
-["210-astro"]
+["astro"]
 deps = ["astro"]
 files = ["**/astro.config.*"]
 
-["220-fastapi"]
+["fastapi"]
 deps = ["fastapi"]
 files = []
 
-["230-nextjs"]
+["nextjs"]
 deps = ["next"]
 files = ["**/next.config.*"]
 
-["250-tailwind"]
+["tailwind"]
 deps = ["tailwindcss", "@tailwindcss/vite", "@tailwindcss/postcss"]
 files = ["**/tailwind.config.*"]
 
-["260-shadcn"]
+["shadcn"]
 deps = []
 files = ["**/components.json"]
 
-["305-e2e-reliability"]
+["e2e-reliability"]
 deps = ["@playwright/test", "playwright", "cypress"]
 files = ["**/e2e"]
 
-["306-test-scope"]
+["test-scope"]
 deps = ["@playwright/test", "playwright", "cypress"]
 files = ["**/e2e"]
 
-["310-zod"]
+["zod"]
 deps = ["zod"]
 files = []
 
-["320-tanstack-query"]
+["tanstack-query"]
 deps = [
   "@tanstack/react-query",
   "@tanstack/vue-query",
@@ -91,23 +91,23 @@ deps = [
 ]
 files = []
 
-["335-testing-go"]
+["testing-go"]
 deps = []
 files = ["**/go.mod"]
 
-["336-testing-php"]
+["testing-php"]
 deps = ["phpunit/phpunit", "pestphp/pest"]
 files = ["**/phpunit.xml", "**/phpunit.xml.dist"]
 
-["340-pydantic"]
+["pydantic"]
 deps = ["pydantic"]
 files = []
 
-["350-security-web"]
+["security-web"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["360-security-server"]
+["security-server"]
 deps = [
   "express",
   "fastify",
@@ -129,7 +129,7 @@ deps = [
 ]
 files = []
 
-["370-database"]
+["database"]
 deps = [
   "prisma",
   "@prisma/client",
@@ -156,42 +156,42 @@ deps = [
 ]
 files = ["**/migrations", "**/schema.prisma", "**/*.sql"]
 
-["400-ui"]
+["copy"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["410-a11y"]
+["a11y"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["420-forms"]
+["forms"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["430-ux-completeness"]
+["ux-completeness"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["440-surface-capture"]
+["surface-capture"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["450-link-behavior"]
+["link-behavior"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["460-design-taste"]
+["design-taste"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["canon/DESIGN.md", "index.html", "*/index.html"]
 
-["465-interface-casing"]
+["interface-casing"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["470-motion"]
+["motion"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
-["480-canvas"]
+["canvas"]
 deps = []
 files = [".canon/canvas"]

package/governance/renames.toml

@@ -32,3 +32,47 @@
 "655-tasks" = "tasks"
 "570-skill" = "skill"
 "801-markdown" = "markdown"
+"602-tasks" = "task-scope"
+"604-scratch" = "scratch"
+"605-worktrees" = "worktrees"
+"606-git" = "git"
+"611-indexes" = "indexes"
+"566-output" = "output"
+"000-code" = "routing"
+"010-testing" = "testing"
+"200-react" = "react"
+"210-astro" = "astro"
+"220-fastapi" = "fastapi"
+"230-nextjs" = "nextjs"
+"250-tailwind" = "tailwind"
+"260-shadcn" = "shadcn"
+"100-typescript" = "typescript"
+"110-python" = "python"
+"130-go" = "go"
+"140-php" = "php"
+"300-testing-ts" = "testing-ts"
+"305-e2e-reliability" = "e2e-reliability"
+"306-test-scope" = "test-scope"
+"310-zod" = "zod"
+"320-tanstack-query" = "tanstack-query"
+"330-testing-py" = "testing-py"
+"335-testing-go" = "testing-go"
+"336-testing-php" = "testing-php"
+"340-pydantic" = "pydantic"
+"350-security-web" = "security-web"
+"360-security-server" = "security-server"
+"370-database" = "database"
+"700-ci-workflow" = "ci-workflow"
+"775-dependencies" = "dependencies"
+"780-config-comments" = "config-comments"
+"790-code-comments" = "code-comments"
+"400-ui" = "copy"
+"410-a11y" = "a11y"
+"420-forms" = "forms"
+"430-ux-completeness" = "ux-completeness"
+"440-surface-capture" = "surface-capture"
+"450-link-behavior" = "link-behavior"
+"460-design-taste" = "design-taste"
+"465-interface-casing" = "interface-casing"
+"470-motion" = "motion"
+"480-canvas" = "canvas"

package/governance/rules/lib/{305-e2e-reliability.md → e2e-reliability.md}

@@ -32,4 +32,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/rules/canon/lib/300-testing-ts.md` for framework choice, file placement, and test naming.
+- Follow `.claude/rules/canon/lib/testing-ts.md` for framework choice, file placement, and test naming.