@erclx/canon 4.123.0 → 4.124.0

package/docs/workflow/skill-map.md

@@ -0,0 +1,148 @@
+---
+title: Skill map
+description: When to reach for each plugin skill, grouped by the moment a project meets it
+category: Workflow
+---
+
+# Skill map
+
+Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target-projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
+
+This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing.
+
+## Set up a project
+
+| Skill                  | When to use                                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| `canon:target-setup`   | On a fresh scaffold, to detect the stack and run the install chain, or to reach one phase of it alone  |
+| `canon:canon-operator` | On a project that already exists, to read what it carries before an install is picked                  |
+| `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs   |
+| `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                |
+| `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                   |
+| `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README |
+
+## Decide what to build
+
+| Skill                      | When to use                                                                       |
+| -------------------------- | --------------------------------------------------------------------------------- |
+| `canon:plan-intake`        | When the input is a pile of findings rather than one feature                      |
+| `canon:plan-intake-answer` | When an intake folder holds unread slots waiting on your decision                 |
+| `canon:backlog-triage`     | When the backlog needs pruning, to file a verdict per row and apply approved ones |
+| `canon:plan-groundwork`    | When the state is unmeasured and more than one approach is live                   |
+| `canon:decision-escalate`  | When open decisions turn on your preference and want batching into one set        |
+| `canon:draft-and-pick`     | When the call is taste and wants several candidates rendered side by side         |
+| `canon:task-board`         | When a decided item needs a file on the board, or a shipped one needs archiving   |
+| `canon:plan-feature`       | When the approach is settled and the next step is a plan                          |
+| `canon:codebase-layout`    | When a plan or change adds a file and you need to decide which folder holds it    |
+
+## Build the feature
+
+| Skill                        | When to use                                                                                                |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `canon:session-worktree`     | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
+| `canon:auto-ship`            | After plan approval, to chain implement, verify, review, draft PR                                          |
+| `canon:project-commands`     | When the project's own command needs running                                                               |
+| `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor                            |
+| `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
+| `canon:review-craft`         | When reviewing a change, for what to look for and how much evidence a finding needs                        |
+| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
+| `canon:ui-checklist`         | After a UI change, to write what to look at and name what ships untested                                   |
+
+## Check the work before it leaves the branch
+
+| Skill                    | When to use                                                                             |
+| ------------------------ | --------------------------------------------------------------------------------------- |
+| `canon:review-branch`    | On the local branch diff, before anything is pushed                                     |
+| `canon:standards-audit`  | When changed markdown has to answer to the authoring standards                          |
+| `canon:document-health`  | When the documents themselves have to answer for length, placement, and staleness       |
+| `canon:markdown-propose` | When a markdown claim needs rewriting and the change should wait for an answer per file |
+| `canon:ux-audit`         | To read UI source for missing states, edge cases, and inconsistencies                   |
+| `canon:ux-measure`       | To start the interface and measure paint, processor, and layout cost                    |
+| `canon:ux-walkthrough`   | To run a multi-finding inspection pass over a running app with the operator             |
+
+## Ship it
+
+| Skill                  | When to use                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| `canon:git-ship`       | To run the whole post-feature chain from the verify gate through open PR                          |
+| `canon:memory-capture` | First skill in that chain, to route what the session learned to the surface owning it             |
+| `canon:context-fold`   | When decisions diverged from the plan, or a shipped task needs its outcomes marked                |
+| `canon:docs-fold`      | Never on purpose. A pointer at the old name that names `context-fold` <!-- canon-keep-retired --> |
+| `canon:docs-sync`      | When a change since main left `README.md` or `docs/` stale                                        |
+| `canon:git-stage`      | When the staged set spans several concerns and wants one commit each                              |
+| `canon:git-commit`     | When the staged set is one concern, or was staged hunk by hand                                    |
+| `canon:git-branch`     | When a branch name needs generating or renaming to conventional form                              |
+| `canon:git-pr`         | When a pull request needs a title and body written from the diff                                  |
+| `canon:memory-review`  | When the pen has grown, to propose where each entry belongs                                       |
+
+## After the pull request opens
+
+| Skill                  | When to use                                                          |
+| ---------------------- | -------------------------------------------------------------------- |
+| `canon:review-pr`      | From an independent session, to post findings on the PR itself       |
+| `canon:review-address` | On the worker's side, to fix posted findings and push a follow-up    |
+| `canon:git-followup`   | For a small self-review edit on a branch whose PR is already open    |
+| `canon:git-split`      | When a branch turns out to carry unrelated commits                   |
+| `canon:git-issue`      | When something surfaced that belongs on the tracker rather than here |
+| `canon:git-worktree`   | After a PR merges, to list worktrees and reclaim the slot            |
+
+## Run several tracks at once
+
+| Skill                     | When to use                                                                                                 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR                              |
+| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass        |
+| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                             |
+| `canon:session-relay`     | When this session owes another session a message, with or without a role                                    |
+| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                              |
+| `canon:session-compact`   | Before a compaction or a move to another machine, to write a plain session's handoff note outside the board |
+| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                                   |
+
+## Keep the project current with the toolkit
+
+| Skill                         | When to use                                                                            |
+| ----------------------------- | -------------------------------------------------------------------------------------- |
+| `canon:target-check`          | In a target project, to report per domain what it holds against what the toolkit ships |
+| `canon:seed-sync`             | After a toolkit update, to reconcile installed seeds without losing customizations     |
+| `canon:canon-feedback`        | When something in the toolkit is broken, missing, or off, to open an issue on it       |
+| `canon:canon-feedback-triage` | In the toolkit repo, to work through the open feedback issues                          |
+| `canon:canon-rollout`         | In the toolkit repo, to take one change out to every consuming project at once         |
+
+## Generate an artifact on demand
+
+| Skill                     | When to use                                                                                                       |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                  |
+| `canon:create-skill`      | For a new `SKILL.md`                                                                                              |
+| `canon:create-snippet`    | For a reusable prompt                                                                                             |
+| `canon:create-standard`   | For a new authoring convention                                                                                    |
+| `canon:draft-docs`        | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                                             |
+| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task         |
+| `canon:draft-context`     | For a brand-new `canon/context/<domain>.md` entry, drafted against `standards/context.md`                         |
+| `canon:draft-wireframes`  | For a brand-new `canon/wireframes/<surface>.md` file, drafted against `standards/wireframes.md`                   |
+| `canon:draft-wiki`        | For a brand-new wiki reference page on a subject owned outside the project, drafted against `standards/wiki.md`   |
+| `canon:draft-figure`      | For a hand-drawn figure inside an existing doc, drafted against `standards/figures.md` in Mermaid or freehand SVG |
+| `canon:draft-readme`      | For a project's `README.md`, drafted against `standards/readme.md`                                                |
+| `canon:bash-script`       | For an interactive, human-facing shell tool                                                                       |
+| `canon:bash-cli-script`   | For a non-interactive automation, CI, or pipeline script                                                          |
+| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                |
+| `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                             |
+| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                     |
+| `canon:record-screencast` | For compiling and running a screencast draft into a recording and a still                                         |
+| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                       |
+
+## Answer a question at any point
+
+| Skill                       | When to use                                                                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
+| `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
+| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
+| `canon:read-frames`         | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
+| `canon:teach-workspace`     | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
+| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
+| `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |
+
+Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
+
+A learning workspace produces two halves and only one of them leaves. A lesson is worked through once and stays in the workspace, and a reference page or a glossary carries no learner, so it belongs wherever the project already keeps prose on that subject. Asking `canon:teach-workspace` to promote sorts each durable page by who owns its subject, sending an Anthropic-owned subject to the wiki, an internal one to the matching context entry, and everything else, subject-neutral material included, to the public docs. It proposes and waits, because a promoted page is public prose that needs a line naming who owns the subject, and it writes nothing to a destination: each page the operator confirms goes to a handoff file that `canon:context-fold` folds in from a branch. A project with no wiki folder gets a refusal naming `canon wiki init` rather than a folder it never asked for.

package/governance/renames.toml

@@ -11,3 +11,37 @@
 # stay. A key must name no live rule and every chain must end on one, which
 # `src/gov/renames.test.ts` checks against this file.
 [renamed]
+"005-behavior" = "565-behavior"
+"015-output" = "566-output"
+"070-planning" = "567-planning"
+"025-indexes" = "601-indexes"
+"035-tasks" = "602-tasks"
+"045-memory" = "603-memory"
+"055-scratch" = "604-scratch"
+"085-worktrees" = "605-worktrees"
+"087-git" = "606-git"
+"510-context" = "610-context"
+"511-indexes" = "611-indexes"
+"520-wireframes" = "620-wireframes"
+"530-requirements" = "630-requirements"
+"540-architecture" = "640-architecture"
+"545-decisions" = "645-decisions"
+"550-design" = "650-design"
+"555-tasks" = "655-tasks"
+"556-groundwork" = "656-groundwork"
+"557-intake" = "657-intake"
+"558-plan" = "658-plan"
+"559-memory" = "659-memory"
+"560-diagrams" = "660-diagrams"
+"561-teach" = "661-teach"
+"562-session" = "662-session"
+"563-ready" = "663-ready"
+"500-prose" = "800-prose"
+"501-markdown" = "801-markdown"
+"502-mermaid" = "802-mermaid"
+"580-readme" = "880-readme"
+"591-standard-authoring" = "891-standard-authoring"
+"065-spelling" = "765-spelling"
+"075-dependencies" = "775-dependencies"
+"080-config-comments" = "780-config-comments"
+"090-code-comments" = "790-code-comments"

package/governance/rules/{claude/560-diagrams.md → canon/660-diagrams.md}

@@ -10,7 +10,7 @@ paths:
 ## Authority
 
 - Follow the diagrams standard for which question an entry answers, the entry kinds and their source signals, the frontmatter, and the explanation prose beneath the fence. It is the single source. Read it with `canon standards diagrams`.
-- Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. `502-mermaid` routes them to `mermaid.md`.
+- Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. `802-mermaid` routes them to `mermaid.md`.
 - A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
 
 ## Scope

package/governance/rules/{claude/562-session.md → canon/662-session.md}

@@ -8,7 +8,7 @@ paths:
 
 ## What a handoff carries
 
-- Follow this rule rather than `555-tasks.md` for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.
+- Follow this rule rather than `655-tasks.md` for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.
 
 ## Authority
 

package/governance/rules/code/000-code.md

@@ -0,0 +1,21 @@
+---
+description: Code placement, dependency, error, and naming choices a model does not make by default
+---
+
+# Code standards
+
+## Placement
+
+- Load the `canon:codebase-layout` skill before placing a new file, and report it rather than proceeding silently when it does not resolve.
+- Prioritize native platform capabilities over third-party libraries.
+- Ensure data and configuration reside in designated Single Source of Truth locations.
+
+## Errors
+
+- Return structured error types for recoverable failures.
+- Never expose internal implementation details in error messages.
+
+## Naming
+
+- Prefix booleans with `is`, `has`, `should`, or `can`: `isLoading`, `hasAccess`.
+- Prefix event handlers with `handle`: `handleClick`, `handleSubmit`.

package/governance/rules/lib/300-testing-ts.md

@@ -9,10 +9,6 @@ paths:
 
 # TypeScript/JavaScript testing tooling
 
-## Layer
-
-- Load the `canon:test-craft` skill to pick the layer a test belongs at before choosing the tooling below, and report it rather than proceeding silently when the skill does not resolve.
-
 ## Unit and integration
 
 - Use Vitest for unit and integration tests.

package/governance/rules/lib/330-testing-py.md

@@ -8,10 +8,6 @@ paths:
 
 # Python testing tooling
 
-## Layer
-
-- Load the `canon:test-craft` skill to pick the layer a test belongs at before choosing the tooling below, and report it rather than proceeding silently when the skill does not resolve.
-
 ## Framework
 
 - Use `pytest` for all tests. Do not use `unittest.TestCase`.

package/governance/rules/{claude/500-prose.md → writing/800-prose.md}

@@ -12,4 +12,4 @@ paths:
 - Load it before drafting a passage, not after revising one.
 - Report it rather than proceeding silently when the skill does not resolve.
 - Do not work these rules from memory.
-- Punctuation, formatting, and file references are a separate topic. `501-markdown` routes them.
+- Punctuation, formatting, and file references are a separate topic. `801-markdown` routes them.

package/governance/rules/{claude/501-markdown.md → writing/801-markdown.md}

@@ -11,4 +11,4 @@ paths:
 - Follow the markdown standard for headings, paragraph and list structure, code spans, punctuation, emphasis, file references, and the wording of a `title` or `description`. It is the single source. Read it with `canon standards markdown`.
 - Read it before a substantial markdown edit. Do not work the banned characters from memory.
 - Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
-- Voice, rhythm, and sentence construction are a separate topic. `500-prose` routes them.
+- Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.

package/governance/rules/{claude/502-mermaid.md → writing/802-mermaid.md}

@@ -11,4 +11,4 @@ paths:
 - Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.
 - Follow the mermaid standard for direction and layout, node and edge budgets, the accessibility fields, punctuation inside labels, and how a render is verified. It is the single source. Read it with `canon standards mermaid`.
 - Read it before drafting the fence. Do not work the layout or the budgets from memory.
-- Which diagram a document carries and what question it answers is a separate topic. `560-diagrams` routes it.
+- Which diagram a document carries and what question it answers is a separate topic. `660-diagrams` routes it.

package/governance/stacks/base.toml

@@ -1,8 +1,9 @@
 extends = ""
-# All four folders whole. Every rule authored under them ships to a base
+# Four audience groups whole. Every rule authored under them ships to a base
 # consumer, so adding one is a single edit rather than a file and a name here.
-# `snippets` carries the `@`-reference convention rule, which lost its only
-# other delivery path when `canon snippets install` retired. `ci` carries the
-# workflow rule, whose glob is the only inbound route to the `ci-workflow`
-# skill.
-rules = ["core", "claude", "snippets", "ci", "120-bash"]
+# `canon` carries the toolkit workflow and canonical-doc rules, `claude` the
+# session conduct and `.claude/` authoring rules, `tooling` the dev setup and
+# CI workflow rules, and `writing` the prose and document-shape rules. The
+# `code` group is left to the stacks that write code, so a docs or writing
+# project loads no rule it can never apply.
+rules = ["canon", "claude", "tooling", "writing", "120-bash"]

package/governance/stacks/node.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["100-typescript"]
+rules = ["code", "100-typescript"]

package/governance/stacks/python.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["110-python", "340-pydantic", "330-testing-py", "360-security-server", "370-database"]
+rules = ["code", "110-python", "340-pydantic", "330-testing-py", "360-security-server", "370-database"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.123.0",
+  "version": "4.124.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/install-check.sh

@@ -91,13 +91,11 @@ log_step "Assert scaffold"
 # Standards and snippets name no path because neither corpus installs into a
 # target. A scaffold reads a standard through `canon standards <name>` and a
 # snippet through the plugin's live `claude/snippets` symlink, both resolving
-# against the toolkit rather than a copy this gate could assert on. The
-# `@`-reference convention rule is the one snippets-domain file that still
-# installs, since `base` carries `governance/rules/snippets/` as a
-# folder-whole entry the same way it does `core` and `claude`.
+# against the toolkit rather than a copy this gate could assert on. The two
+# rule paths stand for the `claude` and `canon` groups `base` takes whole.
 for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" "canon/wireframes/index.md" ".canon/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
-  ".claude/rules/canon/core/000-constitution.md" ".claude/rules/canon/snippets/600-at-references.md"; do
+  ".claude/rules/canon/claude/565-behavior.md" ".claude/rules/canon/canon/604-scratch.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then
     log_error "Missing after canon init: $path"
   fi

package/src/claude/routing.ts

@@ -196,7 +196,7 @@ function frontmatter(text: string): string {
  *
  * A glob opening `**` reaches every folder in the tree, so it answers that a
  * file type is governed and never that a named path is. Counting one would
- * report every markdown path covered by `501-markdown` and leave the column
+ * report every markdown path covered by `801-markdown` and leave the column
  * saying nothing a reader could act on.
  */
 function isAnchored(glob: string): boolean {

package/src/commands/gov.ts

@@ -234,7 +234,7 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Measures the rule in .claude/rules/canon/core/070-planning.md that asks for',
+        'Measures the rule in .claude/rules/canon/claude/567-planning.md that asks for',
         'the test before the code. It reports and never gates, because pairing',
         'a test to an implementation is a judgment.',
         '',

package/src/gate/measures.ts

@@ -101,12 +101,7 @@ const output = (text: string): Emission => ({ kind: 'output', text })
 /**
  * Rules no stack reaches, sorted the way `canon gov list` emits them.
  * `260-shadcn` and `320-tanstack-query` are opt-in libraries a project may not
- * want. `600-at-references` used to sit here too, shipping with no stack on
- * purpose since a rule under `claude/` would reach every base consumer through
- * the folder-whole entry there. Its own install channel, `canon snippets
- * install`, retired with nothing left to deliver it, so `base` now carries
- * `snippets` as a folder-whole entry of its own and the rule reaches every base
- * consumer through that instead.
+ * want.
  *
  * `130-go`, `140-php`, `335-testing-go`, and `336-testing-php` are opt-in by
  * `--add` until a Go or PHP stack ships, which `target-setup` reaches by

package/src/gov/citations.ts

@@ -266,7 +266,7 @@ export function collectCitations(text: string): RawCitation[] {
  *
  * A rule spelling a whole path there is declaring that exact artifact, and a
  * body line naming it again is naming what the rule governs rather than
- * pointing a reader somewhere. `governance/rules/claude/560-diagrams.md` tells
+ * pointing a reader somewhere. `governance/rules/canon/660-diagrams.md` tells
  * its reader to convert a `.claude/DIAGRAMS.md` left by an older install, which
  * is correctly absent from this tree and correctly named in the rule.
  */

package/src/gov/list.ts

@@ -31,7 +31,7 @@ export interface GovCatalog {
 /**
  * Reports each stack's own entries expanded, so a folder entry reaches a
  * consumer as the rules it stands for. the `setup` skill dedupes `--add` extras
- * against this list, and a stack answering `core` there would re-add every
+ * against this list, and a stack answering `canon` there would re-add every
  * rule that folder already carries.
  *
  * The `extends` chain is deliberately not resolved, which is what the bash

package/src/gov/restated.ts

@@ -698,8 +698,8 @@ export function readRestated(root: string): RestatedReport {
 
   // Every candidate's rare set is invariant across the subject loop, so it is
   // built once here rather than per pair. The corpora multiply out to hundreds
-  // of thousands of pairings, and rebuilding a set inside that is the shape
-  // `.claude/rules/canon/core/040-performance.md` names.
+  // of thousands of pairings, and rebuilding a set inside that would dominate
+  // the run.
   const rareCandidates = candidates.map((candidate) => ({
     ...candidate,
     rare: distinctive(candidate.analysis),

package/src/init/steps.ts

@@ -5,7 +5,7 @@ import type { DomainStep } from '@/init/run'
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
 
 /**
- * States the same fact as `docs/target-projects.md`'s backup section in its
+ * States the same fact as `docs/target-migrations.md`'s backup section in its
  * own words. Keep the two in step by hand; nothing compares them.
  */
 const RECORDS_SETUP_NOTICE =

package/src/labels/spelling.ts

@@ -8,7 +8,7 @@ import { execa } from 'execa'
  *
  * `no-binary` is the binary being absent anywhere from the root upward.
  * `cspell` is a devDependency of this repository alone, per
- * `075-dependencies.md`'s ban on importing a transitive-only package, so a
+ * `775-dependencies.md`'s ban on importing a transitive-only package, so a
  * target project that never adopted it gets no coverage from this check
  * rather than a network fetch or a forced new dependency.
  *

package/src/records/prune.ts

@@ -35,7 +35,7 @@ const LEGACY_MOVES: ReadonlyMap<string, string> = new Map([
  * Scratch-root names a different migration moves out of scratch for good,
  * derived from that migration's own table rather than duplicated in a second
  * hand-kept list. `RECORD_LAYOUT_MOVES` names `memory-archive`, the
- * retired-entry archive `045-memory` says never to delete, and `PROMOTED_FOLDERS`
+ * retired-entry archive `603-memory` says never to delete, and `PROMOTED_FOLDERS`
  * names an evidence folder a durable record cites by name. A project that has
  * not run either migration still carries these at the scratch root, where an
  * ordinary slug's own age test would eventually offer them.

package/src/shipped/references.ts

@@ -212,7 +212,7 @@ const PHASE_LABEL = /\bv\d+\.\d+(?!\.\d)\b/g
  * number, such as `create-rule`, `memory-review`, and `target-setup` already
  * write correctly, from matching. The segment group between `rules/` and the
  * numbered file admits both a governance-namespace path
- * (`canon/core/055-scratch.md`) and a project-namespace one
+ * (`canon/canon/604-scratch.md`) and a project-namespace one
  * (`project/<subdir>/<n>-<slug>.md`) without distinguishing them, since
  * either shape is the same broken citation.
  */

package/standards/rule.md

@@ -32,7 +32,7 @@ Write both when both apply. A rule stating the directive and a skill stating how
 ## Location
 
 - A toolkit-shipped rule lives at `.claude/rules/canon/<subdirectory>/<n>-<slug>.md`. The wrapper marks the file as toolkit-owned and replaced on sync, so a reader unfamiliar with the numbering convention still knows not to edit it.
-- Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`, `snippets/`, `ci/`
+- Subdirectories group by domain or audience: `code/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`, `canon/`, `tooling/`, `writing/`
 - `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
 - 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.
@@ -40,11 +40,9 @@ Write both when both apply. A rule stating the directive and a skill stating how
 
 ## Reserved numbers
 
-`000-899` is reserved for a rule set that ships to targets. `000-599` is what the first six subdirectories above already divide, at 100 per subdirectory. `ci/` was the first to draw from the headroom past that, taking `700-799`.
+`000-899` is reserved for a rule set that ships to targets, and the nine subdirectories above divide it at 100 per subdirectory, in the order listed. No band is left over, so a subdirectory a shipped set adds later joins an existing band or takes one a retired subdirectory freed.
 
-`snippets/` holds one rule rather than a subdirectory's worth of them, and draws a single number, `600`, from the nearer overflow band rather than claiming a hundred for one file. The rest of `600-699`, along with `800-899`, is what remains for a subdirectory a shipped set has not added yet.
-
-A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met `claude/561-teach.md` on its next install, and now reads two numbers differently from everywhere else.
+A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met the shipped teach rule, then numbered 561, on its next install, and now reads two numbers differently from everywhere else.
 
 The cost is that a project-authored rule's leading digit stops naming its domain. Its subdirectory names it instead, and install preserves that either way. What a shared band costs is worse: a session that loads two rules reading as one number, with nothing in the folder to say which is which.
 
@@ -54,7 +52,7 @@ The cost is that a project-authored rule's leading digit stops naming its domain
 
 The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source, a rule set held back from targets and installed only where it was authored, needs its own division too. This repository is the one place all three sources exist at once, and it divides the third pair two ways at once rather than one: `canon/` and `internal/` separate a shipped rule from an internal one by location, the same way `project/` separates a project-authored one, and within each subdirectory the numbering still divides by source as well, one source taking the top of the band and the other the gaps between the tens.
 
-The numbering half stays because location alone does not carry to a reader who only sees the number, such as one comparing `core/070-planning.md` against a citation written before the rules moved into `canon/`.
+The numbering half stays because location alone does not carry to a reader who only sees the number, such as one comparing `claude/567-planning.md` against a citation written before the rules moved into `canon/`.
 
 The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it. Separating `canon/` from `internal/` by folder removes the filename-collision case specifically, since the two no longer install to the same directory, but the number still carries the source signal for a reader who has only the number in view.
 

package/tooling/base/reference.md

@@ -4,7 +4,7 @@
 
 The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and one maintenance script. Every other stack extends it, so a decision made here is one every stack inherits.
 
-A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs target-projects` carries the recipe.
+A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs target-scenarios` carries the recipe.
 
 ## What ships as golden configs
 

package/tooling/claude/seeds/.claude/hooks/path-form.sh

@@ -9,7 +9,7 @@
 # to infer on every response and hands the answer back instead.
 #
 # The entrypoint branch (bare vs. `file://` link) stays prose in
-# governance/rules/core/015-output.md. CLAUDE_CODE_ENTRYPOINT is not among
+# governance/rules/claude/566-output.md. CLAUDE_CODE_ENTRYPOINT is not among
 # the environment variables Claude Code documents as passed to a hook
 # subprocess, unlike CLAUDE_PROJECT_DIR, so a hook cannot read it reliably.
 #

package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh

@@ -57,5 +57,5 @@ marker="$marker_dir/$key"
 mkdir -p "$marker_dir"
 : >"$marker"
 
-msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, or .claude/.tmp/<slug>/ where the project carries no .canon/ root, not system temp. See the Scratch rule (055-scratch, under core/ in your installed governance rules).'
+msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, or .claude/.tmp/<slug>/ where the project carries no .canon/ root, not system temp. See the Scratch rule (604-scratch, under canon/ in your installed governance rules).'
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

package/tooling/web/reference.md

@@ -16,7 +16,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 - `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
 - `scripts/lib/preview-server.sh`: sourced, never executed. Builds, serves on `PREVIEW_PORT`, blocks until the port answers, and traps the whole process group on exit, including the detached grandchild `lsof` finds. Both capture scripts source it so the startup lives once.
 - `scripts/readme-screenshot.sh`: captures one case under `SCREENSHOT_FILTER` and copies its light and dark frames to `assets/evidence/readme/`. `README_FILTER` ships empty with `header/1280` as its example, and the script exits 1 until a project fills it, since a shipped default would capture the wrong part of the page in every project but one. Its copy reads from `screenshots/<hostname>/`, which is where the harness writes.
-- `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/ci/700-ci-workflow.md` states the test.
+- `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/tooling/700-ci-workflow.md` states the test.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order. Its last stage runs `scripts/check-card-exclusion.sh` whenever that file is installed, which puts the social card route's build exclusion on the default path rather than behind a flag nobody passes. The stage tests for the script rather than for a framework, so this layer owns when the check runs and the stack shipping a card route owns what it reads. The astro reference carries the route itself.

package/governance/rules/core/000-constitution.md

@@ -1,30 +0,0 @@
----
-description: Define senior architect persona and core philosophy
----
-
-# Role persona
-
-You are a Senior Principal Architect.
-Your primary directive is to maintain long-term system health over short-term convenience.
-
-## Readability and simplicity
-
-- Optimize for readability. Code is read far more than it is written.
-- Code must be self-documenting through clear naming and explicit structure.
-- Comments are permitted ONLY to explain intent, never logic.
-- Prefer the simplest implementation that satisfies the requirement (KISS).
-
-## Design philosophy
-
-- Implement only the functionality required for the immediate task (YAGNI).
-- Extract shared logic into single-purpose utilities. Never duplicate behavior across modules (DRY).
-- Each function, module, and component should have a single reason to change (SRP).
-- Apply SRP to directories: once a folder mixes distinct roles and grows past a handful of files, split it into subfolders by role. Load the `canon:codebase-layout` skill before placing a new file, and report it rather than proceeding silently when it does not resolve.
-- Favor composition over inheritance.
-- Prioritize native platform capabilities over third-party libraries.
-
-## Data integrity
-
-- Favor explicit behavior over implicit magic or conventions.
-- Ensure data and configuration reside in designated Single Source of Truth locations.
-- Treat data as immutable unless mutation is explicitly required.

package/governance/rules/core/020-concurrency.md

@@ -1,22 +0,0 @@
----
-description: Enforce safe concurrency and async operation patterns
----
-
-# Concurrency standards
-
-## Async lifecycle
-
-- Make async operations cancellable. Clean up on scope exit or caller cancellation.
-- Coordinate dependent async operations explicitly. Document execution order.
-- Set explicit timeouts on all external async operations.
-- Do not fire-and-forget async operations without cleanup handlers.
-- Batch independent async operations. Do not run them sequentially when parallelizable.
-
-## Race conditions
-
-- Do not ignore race conditions in concurrent flows.
-- Protect shared mutable state with locks, queues, or single-writer patterns.
-
-## Failure handling
-
-- Handle partial failures in batched operations independently. Do not fail the entire batch for a single error.