@erclx/canon 5.19.0 → 5.21.0

package/docs/agents/markdown-audit.md

@@ -87,7 +87,7 @@ A hit the closed set could not separate from correct prose was the case with no
 
 ### Where the rules are enforced
 
-Five surfaces apply the ban set and four of them go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, the `Markdown bans` stage in `canon gate run` runs it across the whole corpus before this repository's own push, and the same-named stage in the one verify runner every stack shares, `scripts/verify.ts`, runs it across a scaffolded project's tracked markdown before its own push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
+Four surfaces apply the ban set and all four go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, the `Markdown bans` stage in `canon gate run` runs it across the whole corpus before this repository's own push, and the same-named stage in the one verify runner every stack shares, `scripts/verify.ts`, runs it across a scaffolded project's tracked markdown before its own push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
 
 The seed copy moved onto the verb when the sets became data, since its awk had nothing left to parse. It resolves one runner where the toolkit copy resolves two, looking for no checkout source, and a machine carrying no `canon` gets a report naming the binary to install rather than a silent pass. The Seed independence stage of `bun run check` scopes its walk to markdown and leaves the seed hooks outside it, which its own comment records as deliberate.
 
@@ -95,8 +95,6 @@ The target push stage reads the same exit codes `canon gate run`'s own stage rea
 
 The target push stage excludes `CHANGELOG.md`, unlike every other surface here. A changelog a generator builds from commit subjects carries prose nobody wrote against the ban set, where this repository's own passes only because `release-please` builds it from subjects sessions already wrote to the rule. The stage passes an explicit file list rather than the bare invocation the other surfaces use, so a corpus with no file left once the changelog is set aside reads as a pass rather than falling back to the whole tree.
 
-The fifth surface reads the standards directly and is not a consolidation left half done. `claude/skills/standards-audit/SKILL.md` greps the banned tokens agent-side, which is a session reading prose rather than a process it can shell out to, and it ships to every target. It is the likeliest place for the next drift, since nothing compares it against the verb.
-
 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.
 
 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.

package/docs/agents/rule-citations.md

@@ -24,7 +24,7 @@ Under `--json` the record holds stdout alone and the frame still renders on stde
 
 ## What the drift check cannot see
 
-`bun run check` asserts that an authored rule and its consumed copy agree, and a dead citation passes that assertion because both copies carry it. `governance/rules/canon/661-teach.md` told its reader to open a `references/glossary.md` inside the teach skill that had never existed at that path. The rule shipped, survived a release, and fired during a real teach run before anyone noticed.
+`bun run check` asserts that an authored rule and its consumed copy agree, and a dead citation passes that assertion because both copies carry it. The teach rule told its reader to open a `references/glossary.md` inside the teach skill that had never existed at that path. The rule shipped, survived a release, and fired during a real teach run before anyone noticed.
 
 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.
 
@@ -49,7 +49,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`, `standards/<name>.md`, `app/**/route.ts`, `${CLAUDE_SKILL_DIR}/../../standards/<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 `662-session.md` points at `655-tasks.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 generated rule under `governance/rules/standards/` carries no number, so a bare name citing one is not read as a citation, and those rules name each other in prose instead.
 - 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.
 
@@ -59,11 +59,11 @@ The extension test is what carries most of the separation, and it costs one real
 
 Two classes resolve to nothing and are right to. Both are reported by name rather than dropped, so a reader can see what the verdict declined to judge.
 
-**Governed.** A rule spelling a path in its own frontmatter `paths:` is naming an artifact a target holds rather than a file here. `governance/rules/canon/660-diagrams.md` declares `.claude/DIAGRAMS.md` and then tells its reader to convert one an older install left behind, so the file is correctly absent from this tree and correctly named in the rule.
+**Governed.** A rule spelling a path in its own frontmatter `paths:` is naming an artifact a target holds rather than a file here. `governance/rules/standards/diagrams.md` declares `.claude/DIAGRAMS.md` and then tells its reader to convert one an older install left behind, so the file is correctly absent from this tree and correctly named in the rule.
 
 Only an exact declaration exempts, never a glob match against one. A glob declares a shape, so a body path sitting inside it is still a citation and a stale one is still a defect. A rule scoped at `docs/**` citing a `docs/agents/renamed.md` that moved is exactly the class this stage exists to catch, and matching the glob would excuse it.
 
-**Ignored.** A path git ignores is session scratch no clone is expected to hold. `governance/rules/canon/655-tasks.md` cites `.canon/tasks/index.md`, which is real in a live project and absent from a fresh clone and from every linked worktree. Resolving against the filesystem alone would make the verdict depend on which tree the stage ran in, so the unresolved paths go to one batched `git check-ignore` and an ignored one is excused. A read git cannot answer refuses rather than reporting those paths dead.
+**Ignored.** A path git ignores is session scratch no clone is expected to hold. `governance/rules/standards/tasks.md` cites `.canon/tasks/index.md`, which is real in a live project and absent from a fresh clone and from every linked worktree. Resolving against the filesystem alone would make the verdict depend on which tree the stage ran in, so the unresolved paths go to one batched `git check-ignore` and an ignored one is excused. A read git cannot answer refuses rather than reporting those paths dead.
 
 ## Why the glob half reads one corpus
 

package/docs/agents/sandbox.md

@@ -56,13 +56,14 @@ canon sandbox equivalence claude:plan-feature/full --base HEAD
 
 A target is `<category>`, `<category>:<command>`, or `<category>:<command>/<arm>`, defaulting to every category.
 
-| Flag               | Effect                                                                                      |
-| ------------------ | ------------------------------------------------------------------------------------------- |
-| `--base <ref>`     | Ref the baseline is provisioned from, `main` by default                                     |
-| `--include-anchor` | Also run the arms that push to the shared GitHub anchor, one at a time, for an attended run |
-| `--out <dir>`      | Keep the provisioned trees, logs, and per-side manifests in this folder                     |
-| `--no-masks`       | Compare every path, which lists what each mask would hide                                   |
-| `--json`           | Emit the record on stdout                                                                   |
+| Flag               | Effect                                                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------- |
+| `--base <ref>`     | Ref the baseline is provisioned from, `main` by default                                            |
+| `--include-anchor` | Also run the arms that push to the shared GitHub anchor, one at a time, for an attended run        |
+| `--stub-remote`    | Run the anchor arms against a local bare repository and a stub `gh`, writing nothing to the anchor |
+| `--out <dir>`      | Keep the provisioned trees, logs, and per-side manifests in this folder                            |
+| `--no-masks`       | Compare every path, which lists what each mask would hide                                          |
+| `--json`           | Emit the record on stdout                                                                          |
 
 The baseline is a detached worktree with full history, removed on exit including after `SIGINT`. Each arm provisions on the base side, is read into a manifest, is deleted, then provisions on the head side at the same path with the run id pinned. A manifest holds every file's mode and hash, every symlink's target, the exit status, the narration, and for the outer repository and each nested one the commit subjects, the staged index, and the branch.
 

package/docs/agents/slides.md

@@ -0,0 +1,120 @@
+---
+title: Slides
+description: What a folder of HTML slides declares for the whole deck in deck.json, what each slide declares on its own body, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
+---
+
+# Slides
+
+`canon slides render --source <folder>` turns a folder of `.html` slides into an editable PowerPoint deck. Each slide describes its own shapes. What belongs to the whole deck, being the bands, the numbers, and the mark, sits in one file beside them, and the master that carries it takes the project's own colors and face.
+
+```bash
+canon slides render --source slides/q3-review
+```
+
+## The deck file
+
+`deck.json` beside the slides is optional. Without it the deck gets its defaults.
+
+| Field          | Default                        | What it sets                                      |
+| -------------- | ------------------------------ | ------------------------------------------------- |
+| `title`        | the folder name                | the file's title and the default footer text      |
+| `header`       | off                            | a band at the top, with `left`, `center`, `right` |
+| `footer`       | on, with the title on the left | a band at the bottom, with the same three slots   |
+| `slideNumbers` | `true`                         | the number at the right of the footer             |
+| `mark`         | none                           | an image path, relative to the folder, top right  |
+
+```json
+{
+  "title": "Q3 review",
+  "header": { "left": "Acme" },
+  "footer": { "center": "Internal" },
+  "mark": "assets/mark.png"
+}
+```
+
+A band takes `show` and the three slots. A declared band merges over its default, so `"footer": { "center": "Internal" }` keeps the title on the left. Declaring any slot turns a band on unless it also says `"show": false`. Set a slot to `""` to empty it.
+
+Slide numbers belong to the footer and hold its right slot. They show only where the footer does, and `footer.right` needs `slideNumbers` set to `false`.
+
+Prefer a raster mark. An SVG mark lands as a vector, and its fallback for a viewer that cannot draw SVG comes out broken.
+
+## What each slide declares
+
+A slide sets its own place in the deck through attributes on `<body>`.
+
+| Attribute                               | Effect                                        |
+| --------------------------------------- | --------------------------------------------- |
+| `data-section="Results"`                | opens a section the slides after it stay in   |
+| `data-hidden`                           | hides the slide in the show                   |
+| `data-header="off"`                     | drops the header on this slide                |
+| `data-footer="off"`                     | drops the footer and its number on this slide |
+| `data-footer-left`, `-center`, `-right` | replaces that footer slot on this slide alone |
+| `data-header-left`, `-center`, `-right` | replaces that header slot on this slide alone |
+
+Once any slide opens a section, slides ahead of the first one sit in a section named after the deck, since PowerPoint wants every slide in one. A title the deck returns to after another section opens a new section numbered `Intro (2)`, so each section stays one run of slides.
+
+A slide dropping one band keeps the other from the master. A slide replacing a slot draws its band as its own text, so editing that band once in PowerPoint's master view reaches every slide except the ones that replaced it.
+
+## The master
+
+The master takes its colors from the `<html>` element of the first slide as Chromium laid it out with the project's token stylesheet injected, so a theme switched on one slide's `<body>`, such as a dark cover, stays on that slide:
+
+- `--color-background`: the slide ground
+- `--color-text`: the header text
+- `--color-muted`: the footer text
+- `--color-accent`: the slide number
+- the `<body>` font family, first name with a ` Variable` suffix dropped: the theme face
+
+A role the project declares no token for falls back to the slide body's own color and prints one `✗` line naming it. It never falls back to the toolkit's palette.
+
+A slide whose `<body>` background differs from the master's keeps its own. A slide whose `<body>` computes a `--color-text` apart from the master's prints one `✗` line naming it, since its bands keep the master's colors and may not read against its ground.
+
+## Speaker notes
+
+`<aside class="notes">` becomes the slide's notes and is never drawn. Each paragraph or list item becomes its own line, and markup is dropped.
+
+## Charts
+
+A `<figure data-chart="...">` holding a `<table>` becomes a native, editable chart placed where the figure was laid out. The table stays the page's accessible source and is not drawn as well.
+
+```html
+<figure data-chart="bar" data-labels>
+  <figcaption>Revenue by region</figcaption>
+  <table>
+    <tr>
+      <th>Region</th>
+      <th>Q1</th>
+      <th>Q2</th>
+    </tr>
+    <tr>
+      <td>North</td>
+      <td>12</td>
+      <td>16</td>
+    </tr>
+    <tr>
+      <td>South</td>
+      <td></td>
+      <td>11</td>
+    </tr>
+  </table>
+</figure>
+```
+
+- `data-chart` takes `bar`, `line`, `area`, `pie`, or `doughnut`.
+- The header row names the series and the first column names the categories.
+- An empty cell is a gap, not a zero. A comma is a thousands separator only where it groups in threes, as in `12,345.5`, so a comma-decimal `3,5` refuses rather than reading as 35.
+- `data-labels` shows each value. A `<figcaption>` becomes the chart title.
+- Series take the accent first, then every other declared `--color-*` role in sheet order except the background and surface, repeating past the last.
+
+## Refusals
+
+| Case                                   | Report                                         | Exit |
+| -------------------------------------- | ---------------------------------------------- | ---- |
+| `deck.json` field malformed or unknown | `✗` naming the file and the field              | 1    |
+| `mark` path missing                    | `✗` naming the resolved path                   | 1    |
+| chart cell not a number                | `✗` naming the slide, the figure, and the cell | 0    |
+| `data-chart` outside the five types    | `✗` naming the value                           | 0    |
+| token role not declared                | `✗` naming the role                            | 0    |
+| slide body sets its own `--color-text` | `✗` naming the slides                          | 0    |
+
+A refused chart is left out and the rest of the deck is written.

package/docs/agents/tasks-validate.md

@@ -61,7 +61,7 @@ The blocker check re-takes a measurement the board records once and never repeat
 }
 ```
 
-A closed outcome is not the fact the dependency half needs. The ship chain marks outcomes as its first step and opens the pull request several steps later, so a check reading the checkbox reports the row settled while the branch is still in review. A live task therefore settles the row only once it closed every outcome and carries a `Pull request:` line the trunk holds. One that names no pull request, and one whose number no trunk ref could answer for, land in the untested array below rather than being settled or left silent.
+A closed outcome is not the fact the dependency half needs. The ship chain marks outcomes as its first step and opens the pull request several steps later, so a check reading the checkbox reports the row settled while the branch is still in review. A live task therefore settles the row only once it closed every outcome and carries a `Pull request:` line the trunk holds. One that carries a `Pending branch:` line, one that names no pull request, and one whose number no trunk ref could answer for, land in the untested array below rather than being settled or left silent.
 
 The trunk is read as the clone already holds it, `origin/main` first and local `main` behind it, and no run fetches. A validate runs several times a sweep and a fetch per run is a cost this command does not carry, so a clone behind its remote under-reports rather than claiming work landed.
 

package/docs/agents/tasks.md

@@ -84,7 +84,7 @@ canon tasks outcome --plan worktree-scratch-routing --close 2 --json
 
 An outcome already closed comes back under `alreadyClosed` rather than refusing, so a rerun against the same positions changes nothing. A position past the end of the list refuses as `out-of-range`, since a caller counting wrong should hear about it rather than mark a neighbor.
 
-A close that ticks at least one box from a branch other than `main` or `master` names that branch on a `Pending branch:` line, read from `git branch --show-current` in the working directory. The line holds the task against `canon tasks archive --pull-request` until `canon tasks pull-request` records that branch's own number. A detached HEAD, a trunk checkout, or a failed git read writes no line and refuses nothing. The `pending` field lists the branches on the line after the write.
+A close that ticks at least one box from a branch other than `main` or `master` names that branch on a `Pending branch:` line, read from `git branch --show-current` in the working directory. The line holds the task against `canon tasks archive --pull-request` until `canon tasks pull-request` records that branch's own number. A detached HEAD, a trunk checkout, or a failed git read writes no line and refuses nothing. The line is also skipped when `gh pr list --head <branch> --state all` lists a number already on the task's `Pull request:` line, since that branch has recorded itself and a marker would outlive it, as in a review-address pass. A failed, offline, or unreadable `gh` lookup counts as no listing and writes the line. The `pending` field lists the branches on the line after the write.
 
 Positions skip fenced blocks. A checkbox inside a sample a task displays is not an outcome the task claims, and counting one would shift every position after it. `canon tasks archive` reads the list through the same walker, so the two verbs cannot disagree about which checkboxes are outcomes.
 

package/docs/target/migrations.md

@@ -60,7 +60,7 @@ The first line reports the plan and the second applies it, relocating each rule
 
 ## Rename the skill citations, once
 
-Twenty-five plugin skills dropped their `claude-` prefix for two-word names, so `canon:claude-docs` answers as `canon:context-fold` and `canon:claude-tasks` as `canon:task-board`. A project that installed governance or tooling before that release holds files naming the old ones, and the plugin answers to none of them. A later release renamed `docs-fold` to `context-fold`, since the skill folds a session into the context entries and the task board rather than into `docs/`, and the same sweep carries a project across that rename too. <!-- canon-keep-retired -->
+Twenty-five plugin skills dropped their `claude-` prefix for two-word names, so `canon:claude-docs` answers as `canon:context-fold` and `canon:claude-tasks` as `canon:task-board`. A project that installed governance or tooling before that release holds files naming the old ones, and the plugin answers to none of them. A later release renamed `docs-fold` to `context-fold`, since the skill folds a session into the context entries and the task board rather than into `docs/`, and the same sweep carries a project across that rename too. The pointer that answered under the old name no longer ships, so a citation the sweep has not reached names nothing. <!-- canon-keep-retired -->
 
 Two of those files run rather than sit there. `.husky/post-merge` runs the `canon hooks post-merge` verb, so a stale copy of the hook calls a binary that may lack it, and `.claude/hooks/pr-create-log.sh` hands a session a message naming a skill, so a stale copy tells someone to invoke something that no longer exists. A rule under `.claude/rules/canon/core/` names skills too, though a rule is read rather than run.
 

package/docs/workflow/ai-workflow.md

@@ -97,7 +97,7 @@ Review findings split by origin before severity is read. One the branch inherite
 
 Review is skipped when the diff is prose that only informs: every changed file matches `*.md` or `*.txt`, and none sits under a behavior path. Behavior paths cover skills and rules in both the authoring and the installed spelling, so the list matches whether a repository authors those surfaces or consumed them from the toolkit. Standards, `internal/`, and `tooling/` carry the authoring spelling alone, since none of the three reaches a session through a `.claude/` copy, and root `CLAUDE.md` is named as a file because a path prefix reaches nothing sitting in no folder.
 
-Markdown under one states what an agent does, so a branch touching it reaches review while `docs/` and `wiki/` still skip and stay gated by `docs-sync`, `standards-audit`, and pre-push hooks.
+Markdown under one states what an agent does, so a branch touching it reaches review while `docs/` and `wiki/` still skip and stay gated by `docs-sync`, `canon markdown audit`, and pre-push hooks.
 
 An empty changed-file list stops the chain rather than counting as prose-only. The filename test passes vacuously on an empty set, which routed a branch past review instead of through it.
 

package/docs/workflow/operating-model.md

@@ -48,9 +48,9 @@ or a path that no longer resolves is reported rather than repaired, since the
 task file and the board stay the orchestrator's to write.
 
 A worker that halts on a plan question it may not answer, or argues back against
-an instruction the tree contradicts, is working correctly. It never writes
-`.canon/tasks/priority.md` or the backlog beside it, and reports the row it
-needs for the orchestrator to write. `role-worker` carries the reason for each.
+an instruction the tree contradicts, is working correctly. It writes neither
+`.canon/tasks/priority.md`, the backlog, nor a task file for work it turns up,
+and hands the row to the orchestrator. `role-worker` gives the reason for each.
 
 The orchestrator's cell reads every tracked file rather than every feature, and
 it offers no exception for a small one. A correction found while orchestrating
@@ -116,12 +116,12 @@ delta against, and `canon pr checks` reports the runs belonging to that tip, so
 follow-up push cannot be read as green off the predecessor's completed run. See
 [Head-sensitive pull request reads](../agents/pr-reads.md).
 
-Three messages travel from the worker to its controller, and `role-worker`
-states each with its reason: the worker's pull request as it opens, the end of
-each address-review pass with the new CI state, and a block before it becomes an
-interactive prompt. Nothing is sent on progress. An open pull request is what
-starts the controller's review poll, with a dispatch still silent after thirty
-minutes kept as a fallback.
+Three messages travel from the worker to its controller, each stated with its
+reason in `role-worker`: the pull request as it opens, carrying any row the
+build turned up, the end of each address-review pass with the new CI state, and
+a block before it becomes an interactive prompt. Nothing is sent on progress. An
+open pull request is what starts the controller's review poll, with a dispatch
+still silent after thirty minutes kept as a fallback.
 
 What the session channel carries is the handback instruction and the worker's
 reply to it, which is a notification layer over a record that stays on the PR. A

package/docs/workflow/parallel-features.md

@@ -34,7 +34,7 @@ A constraint naming a track in flight carries the same problem past the handoff,
 
 `.canon/plans/`, `.canon/review/`, and `.canon/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. A session inside a worktree reads them directly, since the file-editing tools refuse a main-root path but `Read` resolves normally. It writes a whole file through the shell and makes a change inside an existing file through a `canon` verb, which resolves the main root in-process. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the full rule and the domain-level fan-out guidance.
 
-The plan's shape is fixed by `standards/plan.md`: the section list, the filename, the lifecycle, and the contract its questions keep. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
+The plan's shape is fixed by `standards/plan.md`: the section list, the filename, and the contract its questions keep. Its lifecycle, from the session that writes it to the archive, is `standards/plan-lifecycle.md`. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
 
 An execution that picks other than the suggestion rewrites the `- Suggested:` line as `overridden at execution to <pick>,` followed by the measurement that moved it, and leaves the slot blank. That fixed phrase is how a reader of the archived plan tells an override from a suggestion the execution accepted, since an authored suggestion often carries a number of its own. The same deviation takes one line in the open task's `## Findings`, which is the register that survives the plan being archived. A deviation from a question somebody already answered goes back to whoever answered it instead, since a filled slot is a decision already made.
 

package/docs/workflow/skill-map.md

@@ -53,6 +53,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:search-craft`          | Before searching outside the project, to derive where the field's authorities publish and search there too |
 | `canon:systematic-debugging`  | When a test fails or a bug surfaces, to force root cause first                                             |
 | `canon:design-taste`          | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
+| `canon:video-craft`           | Before composing or judging a video, for sourced captions, zoom, pointer, and audio judgment               |
 | `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
@@ -60,7 +61,6 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | 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                   |
@@ -69,18 +69,17 @@ This page is the corpus the coverage claim is measured against: every name `cano
 
 ## 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                                       |
+| 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-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
 

package/governance/renames.toml

@@ -13,6 +13,10 @@
 # resolves A only while both links 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.
+#
+# A numbered rule replaced by the rule `canon gov regen` generates from its
+# standard is a rename too: the generated rule keeps every glob and bullet, so
+# the pair is one-to-one identity under the standard's name.
 [renamed]
 "005-behavior" = "565-behavior"
 "015-output" = "566-output"
@@ -47,3 +51,23 @@
 "075-dependencies" = "775-dependencies"
 "080-config-comments" = "780-config-comments"
 "090-code-comments" = "790-code-comments"
+"658-plan" = "plan"
+"610-context" = "context"
+"620-wireframes" = "wireframes"
+"630-requirements" = "requirements"
+"640-architecture" = "architecture"
+"650-design" = "design"
+"655-tasks" = "tasks"
+"656-groundwork" = "groundwork"
+"657-intake" = "intake"
+"659-memory" = "memory"
+"660-diagrams" = "diagrams"
+"661-teach" = "teach"
+"662-session" = "session"
+"663-ready" = "ready"
+"570-skill" = "skill"
+"590-rule-authoring" = "rule"
+"801-markdown" = "markdown"
+"802-mermaid" = "mermaid"
+"880-readme" = "readme"
+"891-standard-authoring" = "standard"

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

@@ -1,7 +1,7 @@
 ---
 description: Enforce pytest fixtures, parametrize, and async patterns for Python tests
 paths:
-  - 'tests/**/*.py'
+  - '**/tests/**/*.py'
   - '**/test_*.py'
   - '**/*_test.py'
 ---

package/governance/rules/lib/336-testing-php.md

@@ -1,7 +1,7 @@
 ---
 description: Enforce PHPUnit test classes, attributes, and strict assertions for PHP tests
 paths:
-  - 'tests/**/*.php'
+  - '**/tests/**/*.php'
   - '**/*Test.php'
 ---
 

package/governance/rules/{canon/640-architecture.md → standards/architecture.md}

@@ -1,5 +1,6 @@
 ---
-description: Route canon/ARCHITECTURE.md edits to the architecture standard for system decisions and risks
+# Generated by `canon gov regen` from standards/architecture.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/ARCHITECTURE.md
 paths:
   - 'canon/ARCHITECTURE.md'
   - '.claude/ARCHITECTURE.md'
@@ -9,5 +10,5 @@ paths:
 
 ## Authority
 
-- Follow the architecture standard for the overview, named decision entries, and risks. It is the single source. Read it with `canon standards architecture`.
+- Follow the architecture standard for shape and content rules for canon/ARCHITECTURE.md. It is the single source. Read it with `canon standards architecture`.
 - Add a decision here only when it fills one of the standard's slots, and write any other decision into the context entry for the domain it constrains. At the record's stated cap, merge or retire an entry before adding one.

package/governance/rules/standards/context.md

@@ -0,0 +1,15 @@
+---
+# Generated by `canon gov regen` from standards/context.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/context/<domain>.md entries
+paths:
+  - 'canon/context/**'
+  - '.claude/context/**'
+---
+
+# Context entry standards
+
+## Authority
+
+- Follow the context standard for shape and content rules for canon/context/<domain>.md entries. It is the single source. Read it with `canon standards context`.
+- 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.

package/governance/rules/standards/design.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/design.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/DESIGN.md
+paths:
+  - 'canon/DESIGN.md'
+  - '.claude/DESIGN.md'
+---
+
+# Design standards
+
+## Authority
+
+- Follow the design standard for shape and content rules for canon/DESIGN.md. It is the single source. Read it with `canon standards design`.

package/governance/rules/standards/diagrams.md

@@ -0,0 +1,17 @@
+---
+# Generated by `canon gov regen` from standards/diagrams.md. Edit that frontmatter, not this file.
+description: Shape and content rules for .canon/diagrams/<kind>.md files
+paths:
+  - '.canon/diagrams/**'
+  - '.claude/DIAGRAMS.md'
+---
+
+# Diagram standards
+
+## Authority
+
+- Follow the diagrams standard for shape and content rules for .canon/diagrams/<kind>.md files. 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. The mermaid standard routes them.
+- A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
+- Write a new diagram to `.canon/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
+- Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it

package/governance/rules/standards/groundwork.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/groundwork.md. Edit that frontmatter, not this file.
+description: Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
+paths:
+  - '.canon/groundwork/**'
+---
+
+# Groundwork standards
+
+## Authority
+
+- Follow the groundwork standard for folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track. It is the single source. Read it with `canon standards groundwork`.
+- Follow the groundwork spikes standard for `08-spikes.md` and the folders holding what a spike produced. Read it with `canon standards groundwork-spikes`.

package/governance/rules/standards/intake.md

@@ -0,0 +1,12 @@
+---
+# Generated by `canon gov regen` from standards/intake.md. Edit that frontmatter, not this file.
+description: Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
+paths:
+  - '.canon/intake/**'
+---
+
+# Intake standards
+
+## Authority
+
+- Follow the intake standard for folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval. It is the single source. Read it with `canon standards intake`.

package/governance/rules/standards/markdown.md

@@ -0,0 +1,15 @@
+---
+# Generated by `canon gov regen` from standards/markdown.md. Edit that frontmatter, not this file.
+description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
+paths:
+  - '**/*.md'
+---
+
+# Markdown standards
+
+## Authority
+
+- Follow the markdown standard for headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording. 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. `800-prose` routes them.

package/governance/rules/standards/memory.md

@@ -0,0 +1,12 @@
+---
+# Generated by `canon gov regen` from standards/memory.md. Edit that frontmatter, not this file.
+description: Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
+paths:
+  - '.canon/memory/**'
+---
+
+# Memory standards
+
+## Authority
+
+- Follow the memory standard for filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire. It is the single source. Read it with `canon standards memory`.

package/governance/rules/standards/mermaid.md

@@ -0,0 +1,15 @@
+---
+# Generated by `canon gov regen` from standards/mermaid.md. Edit that frontmatter, not this file.
+description: Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
+paths:
+  - '**/*.md'
+---
+
+# Mermaid standards
+
+## Authority
+
+- Follow the mermaid standard for direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram. It is the single source. Read it with `canon standards mermaid`.
+- Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.
+- 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. The diagrams standard routes it.

package/governance/rules/{canon/658-plan.md → standards/plan.md}

@@ -1,22 +1,18 @@
 ---
-description: Route .canon/plans/ edits to the plan standard for sections, the answer contract, and the archive move
+# Generated by `canon gov regen` from standards/plan.md. Edit that frontmatter, not this file.
+description: Filename and slug, the required sections, and the suggested-and-answer contract for a feature plan
 paths:
   - '.canon/plans/**'
 ---
 
 # Plan standards
 
-## The answer contract
+## Authority
 
+- Follow the plan standard for filename and slug, the required sections, and the suggested-and-answer contract for a feature plan. It is the single source. Read it with `canon standards plan`.
 - Never fill an `- Answer:` slot on behalf of the person who owns it. A blank slot accepts the suggestion at execution time.
 - Never ship a question without a `- Suggested:` line. Write `- Suggested: needs your call, <why>` where the answer turns on preference.
 - Rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when execution deviates from an unanswered question, leaving the slot blank. Put the same deviation in one line under the open task's `## Findings`.
-
-## Archiving
-
 - Move a shipped plan to `.canon/plans/archive/`. Never delete one.
 - Amend a plan in place when a decision changes. Do not append a second passage narrating the change.
-
-## Authority
-
-- Follow the plan standard for the filename and slug, the required sections, the suggested-and-answer contract, and the lifecycle. It is the single source. Read it with `canon standards plan`.
+- Follow the plan lifecycle standard for when a plan is written, how it is amended, and its move to the archive. Read it with `canon standards plan-lifecycle`.

package/governance/rules/standards/readme.md

@@ -0,0 +1,12 @@
+---
+# Generated by `canon gov regen` from standards/readme.md. Edit that frontmatter, not this file.
+description: Readme voice, structure, and content conventions
+paths:
+  - '**/README.md'
+---
+
+# Readme standards
+
+## Authority
+
+- Follow the readme standard for readme voice, structure, and content conventions. It is the single source. Read it with `canon standards readme`.

package/governance/rules/standards/ready.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/ready.md. Edit that frontmatter, not this file.
+description: Folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff
+paths:
+  - '.canon/ready/**'
+---
+
+# Ready standards
+
+## Authority
+
+- Follow the ready standard for folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff. It is the single source. Read it with `canon standards ready`.
+- Load the `canon:draft-ready` skill to write a ready folder, its overview, the thin plan, and the task row. It owns the procedure. Report it rather than proceeding silently when it does not resolve, since it ships with the plugin and this rule ships with the CLI.