@erclx/canon 5.74.0 → 5.75.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [5.75.0](https://github.com/erclx/canon/compare/v5.74.0...v5.75.0) (2026-10-29)
+
+
+### Features
+
+* **claude:** audit proposal-critique against its ledger ([#2845](https://github.com/erclx/canon/issues/2845)) ([397699b](https://github.com/erclx/canon/commit/397699bdeb7da47a39fb210d2850e8502d503a1f))
+* **claude:** seed the plan guard and wire installed projects ([#2851](https://github.com/erclx/canon/issues/2851)) ([e312aab](https://github.com/erclx/canon/commit/e312aabaa69941ce01f656a635b98ef9e01680f1))
+* **gov:** check a project's ledgers under canon/ledger/ ([#2848](https://github.com/erclx/canon/issues/2848)) ([65fb0e6](https://github.com/erclx/canon/commit/65fb0e6e60ef22c16a7743964865fc62d6b55ed8))
+* **governance:** route a rule edit to create-rule ([#2847](https://github.com/erclx/canon/issues/2847)) ([010b639](https://github.com/erclx/canon/commit/010b63970a874905ec9ee3db520b7cb5f96db778))
+* **take:** refuse a take past --max-seconds as over-cap ([#2855](https://github.com/erclx/canon/issues/2855)) ([d9d6424](https://github.com/erclx/canon/commit/d9d642434d082f9f7d4b1508723576044e55f6a4))
+
+
+### Bug Fixes
+
+* **take:** cut a screencast clip at the stage clock ([#2853](https://github.com/erclx/canon/issues/2853)) ([3588832](https://github.com/erclx/canon/commit/3588832a8263079ff8340b2cf7af3c492bf4cc66))
+* **take:** hold canon take steady on a page whose frames run slow ([#2852](https://github.com/erclx/canon/issues/2852)) ([f2b55f9](https://github.com/erclx/canon/commit/f2b55f9a2f948c46fb4c84720da7596df31107a5))
+* **take:** scroll a target taller than the window ([#2854](https://github.com/erclx/canon/issues/2854)) ([976b85d](https://github.com/erclx/canon/commit/976b85d27391106d2cb7e03072451de5a128d2fd))
+
 ## [5.74.0](https://github.com/erclx/canon/compare/v5.73.0...v5.74.0) (2026-10-28)
 
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.74.0",
+  "version": "5.75.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -86,6 +86,10 @@ Read `${CLAUDE_SKILL_DIR}/references/checklist.md` and run every bullet of the w
 
 ## After writing
 
-Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session. When a bullet claims outside practice, tell them to cite its source in the commit that adds the rule.
+Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session. When a bullet claims outside practice, tell them to cite its source, in a ledger or in the commit that adds the rule.
 
 Show the new rule as a diff in chat and commit nothing until the operator says OK.
+
+### When a bullet cites outside practice
+
+Offer to record each source in a ledger at `canon/ledger/rules/<subdir>/<slug>.md`, which `canon gov audit` checks row for bullet. Read `${CLAUDE_SKILL_DIR}/references/ledger.md` for the layout and the row shape before writing one.

package/claude/skills/create-rule/references/ledger.md

@@ -0,0 +1,73 @@
+---
+title: Project ledger reference
+description: Where a project's rule and skill ledgers live under canon/ledger/, and the row shape both audits check, one table per H2 and one row per bullet
+---
+
+# Project ledger reference
+
+## Contents
+
+- [Overview](#overview)
+- [Where it lives](#where-it-lives)
+- [Shape](#shape)
+- [Rows](#rows)
+- [Example](#example)
+
+## Overview
+
+A ledger names what stands behind each bullet of a rule or a skill file, kept beside the file rather than inside it, so the reasoning costs no load. A bullet claiming outside practice names its source, and a bullet recording a project decision names what it prevents.
+
+A project writes a ledger where it wants one and owes none. `canon gov audit` and `canon claude skills audit` check each ledger that exists against its file and report a ledger whose file is gone.
+
+## Where it lives
+
+Every ledger sits under `canon/ledger/`, which Claude Code never loads. A ledger under `.claude/rules/` would load as a rule on every matching read.
+
+- A rule at `.claude/rules/project/<subdir>/<slug>.md` takes `canon/ledger/rules/<subdir>/<slug>.md`
+- A skill body at `.claude/skills/<skill>/SKILL.md` takes `canon/ledger/skills/<skill>/SKILL.md`
+- A skill reference at `.claude/skills/<skill>/references/<file>.md` takes `canon/ledger/skills/<skill>/<file>.md`, dropping the `references/` segment
+- Move or delete a ledger in the change that moves or deletes its file, since the audits report one left behind
+
+## Shape
+
+The audits match rows to bullets by count under a heading of the same name, so the shape is fixed and whether a row supports its bullet is a review judgment.
+
+- Write one `## <heading>` per H2 in the file, spelled as the file spells it
+- Put one table under each heading, with one row per bullet in the file's order
+- Give a file with no H2 one table under the title
+- Write no other table in the ledger, since every table row under a heading counts. A sample table inside a code fence is not counted.
+
+A skill file counts a few lines differently from a rule.
+
+- Give each top-level ordered step a row, the way a bullet takes one
+- Give `## Contents` no table, since it repeats the headings
+- Stop a `SKILL.md` ledger's tables at the body's first closing section, such as `## Excuses and rebuttals` or `## What this delegates`, since a table under one reads as rows with no bullets
+
+## Rows
+
+Each row names the bullet and the one thing behind it.
+
+- **Sourced:** a link to the primary source, with the line it says, such as the framework's own docs or the language spec
+- **House choice:** a cell opening `House choice:` and naming the bug class the bullet prevents, when no outside source takes a side
+- **Decision:** a house choice naming what the bullet prevents and the option it beat, with the date it was decided
+- Cut a bullet that has neither a source nor a bug class behind it, rather than writing a row that says so
+
+## Example
+
+A project React rule in the `framework/` subdir, with two bullets under `## Component patterns`, takes this ledger at `canon/ledger/rules/framework/react.md`:
+
+```markdown
+---
+title: React rule ledger
+description: Sources for the project React rule, one row per bullet
+---
+
+# React rule ledger
+
+## Component patterns
+
+| Bullet                       | Source                                                                                        |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| Stable keys over array index | [Rendering lists](https://react.dev/learn/rendering-lists): index keys cause subtle bugs      |
+| Named exports                | House choice: a default export renamed at import drifts from the component's name in a search |
+```

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

@@ -101,7 +101,7 @@ A bullet claiming outside practice, such as a language idiom or a library's corr
 
 - Cite the source in the commit that adds the rule, naming a primary page or the bug class the bullet prevents
 - Cut a bullet that has neither a source nor a bug class behind it
-- The toolkit holds its outside-practice rules to a source ledger kept outside the installed tree, so the citation costs no load
+- A project can hold its rules to a source ledger kept outside the installed tree, so the citation costs no load, laid out in `${CLAUDE_SKILL_DIR}/references/ledger.md`
 - A bullet resting on how Claude Code behaves ends with a `Revisit when` sentence, per `### Phrasing`
 
 ## Location

package/claude/skills/create-skill/references/skill-practice.md

@@ -73,4 +73,4 @@ The audit counts a few lines in a ledgered file apart from a rule's.
 - It keeps a wider ledger list beside it, adding the skills that teach a craft drawn from outside sources without a practice's closing shape
 - A skill on the wider list alone owes the ledger and none of the three sections
 - Never mark a skill as a practice skill in its own frontmatter, since a self-declared kind lets a skill exempt itself.
-- Both lists name this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.
+- Both lists name this toolkit's shipped skills alone. A project's own skill owes no ledger, and one it writes is checked per `${CLAUDE_SKILL_DIR}/../create-rule/references/ledger.md`.

package/claude/skills/pr-evidence/references/reel.md

@@ -62,23 +62,23 @@ Write one plan entry for each beat chosen, then skip when none was.
 
 The negative test is a judgment over the box's text. A misread box costs a weaker reel and never a wrong pass, since the still check below guards the footage and the UI reviewer drives every box regardless.
 
-Keep the whole reel at or under 12 seconds. Each beat opens and closes on a 0.6 s hold, so give each action's `wait` only what its result needs to settle.
+Keep the whole reel at or under 12 seconds, which the take below enforces. Each beat opens and closes on a 0.6 s hold, so give each action's `wait` only what its result needs to settle.
 
 ## Film the reel
 
 ```bash
-canon take <url> .canon/tmp/pr/reel/<number>/plan.json --out .canon/tmp/pr/reel/<number>/takes --reel .canon/tmp/pr/reel/<number>/reel.webp --json
+canon take <url> .canon/tmp/pr/reel/<number>/plan.json --out .canon/tmp/pr/reel/<number>/takes --reel .canon/tmp/pr/reel/<number>/reel.webp --max-seconds 12 --json
 ```
 
 Branch on the record's `reason`, never on the exit code.
 
-| Record          | Route                                                              |
-| --------------- | ------------------------------------------------------------------ |
-| No `reason`     | Sum the beats' `seconds` and continue to the stills                |
-| `reel-failed`   | Skip as `reel-failed` with the record's `message`                  |
-| Any other value | Skip under that `reason`, such as `target-missing` with its `beat` |
-
-When the beats sum past 12 seconds, drop the last beat from the plan and film once more. A second run past the cap skips as `over-cap`.
+| Record             | Route                                                                                                                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| No `reason`        | Continue to the stills                                                                                                                                                                                                                                             |
+| `reel-failed`      | Skip as `reel-failed` with the record's `message`                                                                                                                                                                                                                  |
+| `target-offscreen` | Add a setup step that brings the target into the window, being a scroll over an element already inside it, such as a fixed header, with `dy` covering the distance, or a click on a link to it, and film once more. Skip as `target-offscreen` on a second refusal |
+| `over-cap`         | Drop `beat` and each beat after it, then film once more. Skip as `over-cap` if `beat` is first or it refuses again                                                                                                                                                 |
+| Any other value    | Skip under that `reason`, such as `target-missing` with its `beat`                                                                                                                                                                                                 |
 
 ## Check each still
 

package/claude/skills/proposal-critique/references/adopted.md

@@ -0,0 +1,44 @@
+---
+title: Adopted and declined
+description: Which designs this skill considered and dropped, and what would revive each, so a later session extends the position instead of re-deriving it
+---
+
+# Adopted and declined
+
+The skill came out of a groundwork track that measured two shipped fixes against the questions a critique would have asked. This file records the options the track dropped. A later session extending the skill adds to it rather than re-arguing an item settled here.
+
+A bullet's source is linked in its row of the toolkit's per-bullet ledger at `governance/ledger/skills/proposal-critique/`, outside the plugin, and this file links no source a row cites.
+
+## Declined
+
+Each item names the design that stays out, the reason, and what would bring it back.
+
+### A default call from every planning skill
+
+An authoring session questioning its own plan is the weak form Kahneman, Lovallo, and Sibony warn against when they ask for reviewers independent of the team that made the recommendation. The planning skills name the critique in one line for a one-way change or a fix with an unverified cause, and never call it.
+
+Revisit when a replay finds a case where the on-demand form would not have been invoked in time.
+
+### Folding it into `decision-escalate`
+
+That skill batches preference questions. Most critique questions are answered from evidence, and only the remainder goes to the operator.
+
+Revisit when critique passes show every question turning out to be preference.
+
+### Running it as a forked subagent
+
+A fork reads cold, which is the independence Kahneman, Lovallo, and Sibony ask for. It also loses the conversation, and a background fork loses the tools the operator questions need.
+
+Revisit when a critique keeps agreeing with the session that wrote the proposal.
+
+### A written critique section in the plan
+
+A plan already carries `## Risks` and `## Questions`, and its validator owns the sections. The verdict goes to chat, and the operator decides what moves into a record.
+
+Revisit when critiques are lost to compaction before anyone acts on them.
+
+## Revisit the whole design when
+
+- Replaying the chain that shipped two fixes and two or three past plans finds the on-demand form would not have been invoked in time
+- One body cannot hold questions that differ so much per record, whether plan, fix, or triage
+- A replayed case shows a cheap, reversible change still doing real harm

package/claude/skills/ui-film/SKILL.md

@@ -70,13 +70,14 @@ canon take <url> .canon/video/<slug>/plan.json --out .canon/video/<slug>/takes -
 
 Branch on the record's `reason`, never on the exit code, which a shell function wrapping `canon` can flatten to zero.
 
-| Record                           | Route                                                                                                              |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| No `reason`                      | Continue to the stills                                                                                             |
-| `target-missing` with `fallback` | Check the access before the selector, per the note below the table                                                 |
-| `target-missing`                 | Open the record's `still`, find the target the record's `beat` names on the page, fix the plan, and film once more |
-| `server-unreachable`             | Restart the server from Step 1 and film once more                                                                  |
-| Any other `reason`               | Report the `reason` and `message` to the operator and stop, since each is a setup step                             |
+| Record                           | Route                                                                                                                                                                                                              |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| No `reason`                      | Continue to the stills                                                                                                                                                                                             |
+| `target-missing` with `fallback` | Check the access before the selector, per the note below the table                                                                                                                                                 |
+| `target-missing`                 | Open the record's `still`, find the target the record's `beat` names on the page, fix the plan, and film once more                                                                                                 |
+| `target-offscreen`               | Add a setup step that brings the target into the window, being a scroll over an element already inside it, such as a fixed header, with `dy` covering the distance, or a click on a link to it, and film once more |
+| `server-unreachable`             | Restart the server from Step 1 and film once more                                                                                                                                                                  |
+| Any other `reason`               | Report the `reason` and `message` to the operator and stop, since each is a setup step                                                                                                                             |
 
 A refusal carrying `fallback` means the screencast opened the address a second time, so a single-use link was spent before the step ran. Read `${CLAUDE_SKILL_DIR}/references/config.md` for the access the take opens with, and fix that before touching the target.
 

package/docs/agents/audits.md

@@ -63,30 +63,30 @@ An audit that finds no corpus reports `absent`, which moves neither the verdict
 
 `canon audits list` reports the first 18 rows. The rows marked `outside` run by hand or from a skill and sit beside the aggregate.
 
-| Id                   | Verb                                | Measures                                                                           | Finding        |
-| -------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- | -------------- |
-| `context`            | `canon context audit`               | Context folder structure, citations, and the requirements record's word cap        | Gates          |
-| `markdown`           | `canon markdown audit`              | Bans, dead links, density, and reference shape                                     | Gates          |
-| `skills`             | `canon claude skills audit`         | Both skill corpora against the skill standards                                     | Gates          |
-| `skills-reach`       | `canon claude skills reach`         | Skill bodies citing a path no target receives                                      | Reports        |
-| `skills-rank`        | `canon claude skills rank`          | Whether skill descriptions separate against a routing case corpus                  | Reports        |
-| `tasks`              | `canon tasks validate`              | Board rows nothing resolves                                                        | Reports        |
-| `records-plans`      | `canon records validate plans`      | Plan records against their shape                                                   | Reports        |
-| `records-groundwork` | `canon records validate groundwork` | Groundwork folders against their shape                                             | Reports        |
-| `records-intake`     | `canon records validate intake`     | Intake folders against their shape                                                 | Reports        |
-| `comments`           | `canon comments scan`               | Comment density by language and kind, and `TODO`, `FIXME`, `HACK`, `XXX`           | Reports        |
-| `test-order`         | `canon gov test-order`              | Implementations that reached branch history before their test                      | Reports        |
-| `secrets`            | `canon secrets scan`                | Credential-shaped values in the shipped tree                                       | Gates          |
-| `labels`             | `canon labels audit`                | Changed paths no row of the label map reaches                                      | Reports        |
-| `restated`           | `canon gov restated`                | Instructions `CLAUDE.md` states that a second surface states too                   | Reports        |
-| `rules`              | `canon gov audit`                   | Rules past a shape limit, and here rules short of a ledger or out of step with one | Reports        |
-| `counts`             | `canon gov counts`                  | Sentences stating a closed catalog's size that disagree with the tree              | Reports        |
-| `census`             | `canon census`                      | File count, extension breakdown, and line total                                    | Reports        |
-| `deps`               | `canon deps audit`                  | Advisories against the resolved dependencies                                       | Reports        |
-| `outside`            | `canon gov citations`               | Rule citations and internal frontmatter globs reaching nothing                     | Gates in check |
-| `outside`            | `canon gov superseded <old> <new>`  | Where the tree still asserts a value a changed convention no longer produces       | Reports        |
-| `outside`            | `canon claude skills drift <ref>`   | Shipped skill bodies rewritten since a ref                                         | Reports        |
-| `outside`            | `canon claude routing`              | Per `CLAUDE.md` section, how many bullets name a path and whether a rule covers it | Reports        |
+| Id                   | Verb                                | Measures                                                                                    | Finding        |
+| -------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------- | -------------- |
+| `context`            | `canon context audit`               | Context folder structure, citations, and the requirements record's word cap                 | Gates          |
+| `markdown`           | `canon markdown audit`              | Bans, dead links, density, and reference shape                                              | Gates          |
+| `skills`             | `canon claude skills audit`         | Both skill corpora against the skill standards, and any ledger under `canon/ledger/skills/` | Gates          |
+| `skills-reach`       | `canon claude skills reach`         | Skill bodies citing a path no target receives                                               | Reports        |
+| `skills-rank`        | `canon claude skills rank`          | Whether skill descriptions separate against a routing case corpus                           | Reports        |
+| `tasks`              | `canon tasks validate`              | Board rows nothing resolves                                                                 | Reports        |
+| `records-plans`      | `canon records validate plans`      | Plan records against their shape                                                            | Reports        |
+| `records-groundwork` | `canon records validate groundwork` | Groundwork folders against their shape                                                      | Reports        |
+| `records-intake`     | `canon records validate intake`     | Intake folders against their shape                                                          | Reports        |
+| `comments`           | `canon comments scan`               | Comment density by language and kind, and `TODO`, `FIXME`, `HACK`, `XXX`                    | Reports        |
+| `test-order`         | `canon gov test-order`              | Implementations that reached branch history before their test                               | Reports        |
+| `secrets`            | `canon secrets scan`                | Credential-shaped values in the shipped tree                                                | Gates          |
+| `labels`             | `canon labels audit`                | Changed paths no row of the label map reaches                                               | Reports        |
+| `restated`           | `canon gov restated`                | Instructions `CLAUDE.md` states that a second surface states too                            | Reports        |
+| `rules`              | `canon gov audit`                   | Rules past a shape limit or out of step with a ledger, and here rules short of one          | Reports        |
+| `counts`             | `canon gov counts`                  | Sentences stating a closed catalog's size that disagree with the tree                       | Reports        |
+| `census`             | `canon census`                      | File count, extension breakdown, and line total                                             | Reports        |
+| `deps`               | `canon deps audit`                  | Advisories against the resolved dependencies                                                | Reports        |
+| `outside`            | `canon gov citations`               | Rule citations and internal frontmatter globs reaching nothing                              | Gates in check |
+| `outside`            | `canon gov superseded <old> <new>`  | Where the tree still asserts a value a changed convention no longer produces                | Reports        |
+| `outside`            | `canon claude skills drift <ref>`   | Shipped skill bodies rewritten since a ref                                                  | Reports        |
+| `outside`            | `canon claude routing`              | Per `CLAUDE.md` section, how many bullets name a path and whether a rule covers it          | Reports        |
 
 A deliberate secret takes a `canon-allow-secret: <reason>` marker. A deliberate citation takes `canon-allow-citation: <reason>` and a deliberate superseded value takes `canon-allow-superseded: <reason>`, each on its own line or the one above. Run any verb with `--help` for its flags and refusal reasons.
 

package/docs/agents/migrate.md

@@ -21,7 +21,7 @@ kind: reference
 | `record-layout`    | Review receipts, memory archives, feedback, renders, picks, evidence, and the design board into their current folders |
 | `session-defaults` | The seeded session defaults into an existing `.claude/settings.json`, listed below the table                          |
 
-`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies `Agent`, `Task`, and both merge commands, and turns auto memory off. The bullets below add detail per verb.
+`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies `Agent`, `Task`, and both merge commands, turns auto memory off, and wires an installed `plan-guard.sh` into the PreToolUse hooks. The bullets below add detail per verb.
 
 - `skill-names` takes no `--scope`, and skips the changelog, eval transcripts, replay fixtures, and the pointer each renamed `draft-` skill leaves at its old name
 - `surface-roots` moves `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the stamp folder, and leaves `rules/`, `skills/`, `hooks/`, and `settings.json` in place
@@ -56,15 +56,15 @@ Three markers keep an old spelling on a line. Each also covers the nearest non-b
 
 ## Refusals
 
-| Verb               | Refuses when                                                                          |
-| ------------------ | ------------------------------------------------------------------------------------- |
-| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.        |
-| `records`          | A record folder already exists at the destination                                     |
-| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan                |
-| `scratch-evidence` | A destination is occupied                                                             |
-| `record-layout`    | A destination already exists, each move refused on its own                            |
-| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply.   |
-| `session-defaults` | The settings file is not valid JSON, or `permissions` or its `deny` has another shape |
+| Verb               | Refuses when                                                                                              |
+| ------------------ | --------------------------------------------------------------------------------------------------------- |
+| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.                            |
+| `records`          | A record folder already exists at the destination                                                         |
+| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan                                    |
+| `scratch-evidence` | A destination is occupied                                                                                 |
+| `record-layout`    | A destination already exists, each move refused on its own                                                |
+| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply.                       |
+| `session-defaults` | The settings file is not valid JSON, or `permissions`, `deny`, `hooks`, or `PreToolUse` has another shape |
 
 A `rule-layout` destination holding the same bytes marks a duplicate, which `--write` deletes.
 

package/docs/migrations/by-verb.md

@@ -108,6 +108,8 @@ It moves each surface with `git mv` and repoints every tracked citation. No othe
 
 The seeded `.claude/settings.json` now denies the `Agent` and `Task` tools and both merge commands, and sets `autoMemoryEnabled` to `false`. `canon claude sync` never rewrites a settings file you hold, so it warns while the file holds no default or lacks a merge entry. Removing `Agent` and `Task` later draws no warning.
 
+The plan guard takes two steps. `canon claude init` adds the absent `.claude/hooks/plan-guard.sh`, and the verb below then wires it into `hooks.PreToolUse` for `Bash` and `Write|Edit`. It skips a tool whose matcher already runs the guard, and wires nothing while the script is absent.
+
 ```bash
 canon migrate session-defaults --json
 canon migrate session-defaults --write --json

package/governance/detect.toml

@@ -20,6 +20,10 @@
 deps = []
 files = [".claude/skills", "claude/skills"]
 
+["rule"]
+deps = []
+files = [".claude/rules/project"]
+
 ["ci-workflow"]
 deps = []
 files = [".github/workflows"]

package/governance/ledger/claude/rule.md

@@ -0,0 +1,16 @@
+---
+title: Rule rule ledger
+description: Decisions behind governance/rules/claude/rule.md, one row per bullet
+---
+
+# Rule rule ledger
+
+The rule is a core rule, so every row is a house choice rather than a citation. Each names what goes wrong without its bullet and the option the bullet beat, with the date it was decided.
+
+## Rule files
+
+| Bullet                          | Source                                                                                                                                                                                          | Read       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load create-rule before an edit | House choice: a session hand-editing rules without the skill shipped defects `canon gov audit` passed (issue 2842). It beat relying on the audit alone                                          | 2026-10-29 |
+| Report an unresolved skill      | House choice: a project that installed governance without the plugin has no `create-rule`, and a silent skip hides that. It beat omitting the line                                              | 2026-10-29 |
+| Audit each touched rule         | House choice: the audit catches the shape and ledger defects the skill's checklist names, so running it before the commit closes the loop. It beat leaving the audit to the pre-push gate alone | 2026-10-29 |

package/governance/rules/claude/rule.md

@@ -0,0 +1,13 @@
+---
+description: Route edits to a rule file to the create-rule skill for its shape and checklist
+paths:
+  - '.claude/rules/project/**/*.md'
+---
+
+# Rule standards
+
+## Rule files
+
+- Load the `canon:create-rule` skill before a hand edit to a rule, since it carries the frontmatter, the shape limits, and the bullet checklist.
+- Report it rather than proceeding silently when `canon:create-rule` does not resolve, as in a project that installed governance without the plugin.
+- Run `canon gov audit` over each rule the edit touched before committing it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.74.0",
+  "version": "5.75.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/ci/refresh-frames-pr.sh

@@ -1,29 +1,29 @@
 #!/usr/bin/env bash
-# Commits the regenerated capture frames onto the refresh branch and opens or
+# Commits the recaptured home baseline onto the refresh branch and opens or
 # updates its pull request, called by refresh-capture-frames.yml after the
-# capture steps. The step holds GH_TOKEN and HUSKY, since the token scope is
+# capture step. The step holds GH_TOKEN and HUSKY, since the token scope is
 # read off the workflow.
 #
 # Hooks stay off, since pre-push runs a check whose format step needs shfmt,
 # which the runner lacks. verify.yml checks the pull request.
 #
-# The frames commit where they rendered, then only the files that commit wrote
+# The baseline commits where they rendered, then only the files that commit wrote
 # or dropped carry onto main fetched now, so a merge landing mid-run neither
-# leaves the branch on an older base nor loses a frame it moved. The pull
+# leaves the branch on an older base nor loses a baseline frame it moved. The pull
 # request resolves by number, since every merged refresh leaves a closed one on
 # the same head.
 set -e
 
 branch=chore/refresh-capture-frames
-title="chore(web): refresh capture frames"
+title="chore(web): refresh home baseline"
 
-if [ -z "$(git status --porcelain assets/captures assets/frames assets/evidence)" ]; then
-  echo "Frames are current, nothing to refresh."
+if [ -z "$(git status --porcelain assets/evidence)" ]; then
+  echo "The home baseline is current, nothing to refresh."
   exit 0
 fi
 git config user.name "github-actions[bot]"
 git config user.email "41898282+github-actions[bot]@users.noreply.github.com" # canon-allow-reference: the bot account id, not a commit
-git add assets/captures assets/frames assets/evidence
+git add assets/evidence
 git commit -m "$title"
 rendered=$(git rev-parse HEAD)
 written=$(git diff --name-only --no-renames --diff-filter=d HEAD~1 HEAD)
@@ -36,8 +36,8 @@ fi
 if [ -n "$dropped" ]; then
   printf '%s\n' "$dropped" | xargs -d '\n' git rm -q --ignore-unmatch --
 fi
-if git diff --cached --quiet -- assets/captures assets/frames assets/evidence; then
-  echo "Main already carries these frames, nothing to refresh."
+if git diff --cached --quiet -- assets/evidence; then
+  echo "Main already carries this baseline, nothing to refresh."
   exit 0
 fi
 git commit -m "$title"
@@ -50,11 +50,10 @@ if [ -z "$number" ]; then
     --title "$title" \
     --body "## Summary
 
-- Refreshes the capture frames from main so their counts and tokens stay current.
+- Refreshes the home page baseline from main so canon pr evidence compares against a current render.
 
 ## Key changes
 
-- Regenerates the count and token bearing frames, their images, and their stamps from main.
 - Recaptures the home page baseline under assets/evidence/home.
 - Merges itself by squash once its required check passes."
   number=$(gh pr list --head "$branch" --state open --json number --jq '.[0].number')

package/src/audits/catalog.ts

@@ -379,7 +379,8 @@ function restatedCounts(record: unknown): Record<string, number> | undefined {
  * a short one are fixed by different passes.
  */
 function ruleCounts(record: unknown): Record<string, number> | undefined {
-  const rules = asObject(record)?.rules
+  const root = asObject(record)
+  const rules = root?.rules
   if (!Array.isArray(rules)) return undefined
 
   let shapeRules = 0
@@ -397,7 +398,11 @@ function ruleCounts(record: unknown): Record<string, number> | undefined {
     if ((lengthOf(ledger.mismatches) ?? 0) > 0) ledgerMismatches += 1
   }
 
-  return { shapeRules, missingLedgers, ledgerMismatches }
+  // A target ledger with no rule sits beside `rules` rather than in it. A
+  // binary predating it carries no `orphans` key, which reads as none.
+  const orphanLedgers = lengthOf(root?.orphans) ?? 0
+
+  return { shapeRules, missingLedgers, ledgerMismatches, orphanLedgers }
 }
 
 function findingsOnly(record: unknown): Record<string, number> | undefined {

package/src/capture/stamp.ts

@@ -6,13 +6,11 @@ const STAMP_EXTENSION = '.stamp'
 
 /**
  * Provenance for one rendered PNG: the markup it came from and a digest over
- * each side of the pair. `assertStampField` in `src/gate/measures.ts` reads both
- * digests back off the first whitespace-separated token, so the field names, the
- * colon, and the space after it are a contract between the writer and the gate
- * rather than formatting.
+ * each side of the pair. Nothing reads the digests back today, so no check
+ * fails when either side moves.
  *
  * Both sides are recorded because either can move alone. The markup digest
- * catches an edit committed with no capture, and the image digest catches a PNG
+ * would show an edit committed with no capture, and the image digest a PNG
  * replaced under markup that never changed.
  */
 export interface CaptureStamp {

package/src/claude/skills-audit.ts

@@ -82,6 +82,7 @@ export const LEDGER_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'write-human'),
   join(SHIPPED_CORPUS, 'test-first'),
   join(SHIPPED_CORPUS, 'ui-craft'),
+  join(SHIPPED_CORPUS, 'proposal-critique'),
 ]
 
 function references(...names: string[]): string[] {
@@ -125,6 +126,7 @@ export const BULLET_LEDGER_SKILLS: Readonly<Record<string, BulletLedgerScope>> =
     [join(SHIPPED_CORPUS, 'write-human')]: { exempt: [], body: true },
     [join(SHIPPED_CORPUS, 'systematic-debugging')]: { exempt: [], body: true },
     [join(SHIPPED_CORPUS, 'build-in-slices')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'proposal-critique')]: { exempt: [], body: true },
   }
 
 /** Where a per-bullet ledger lives, as `<skill>/<file>.md` below it. */
@@ -139,6 +141,15 @@ export function skillLedgerPath(folder: string, file: string): string {
   return join(SKILL_LEDGERS, folder, inside.startsWith('..') ? file : inside)
 }
 
+/**
+ * Where a target keeps the ledgers behind its own skills, as `<skill>/<file>.md`
+ * below it. A tree holding `governance/rules/` is the toolkit, which keeps its
+ * ledgers at `SKILL_LEDGERS`, so this folder is never read there.
+ */
+export const PROJECT_SKILL_LEDGERS = join('canon', 'ledger', 'skills')
+
+const TOOLKIT_MARKER = join('governance', 'rules')
+
 /** The closing H2s a practice skill carries, matched exactly outside fences. */
 export const PRACTICE_SECTIONS: readonly string[] = [
   'Excuses and rebuttals',
@@ -312,6 +323,9 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
     present.map((corpus) => readCorpus(root, corpus.rel, corpus.dir)),
   )
   const sources = perCorpus.flat()
+  const projectLedgers = existsSync(join(root, TOOLKIT_MARKER))
+    ? []
+    : await readProjectLedgers(root, sources)
 
   return {
     corpora: present.map((corpus, index) => ({
@@ -344,6 +358,7 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
         sources,
       ),
       ...sources.flatMap(practiceFindings),
+      ...projectLedgers,
     ],
     referenceContents: sources.flatMap((source) =>
       source.bodies.flatMap(contentsFindings),
@@ -483,6 +498,56 @@ async function readReferenceLedgers(
   )
 }
 
+/**
+ * Pairs each file a target wrote under `PROJECT_SKILL_LEDGERS` with the skill
+ * file of that name, `SKILL.md` with the body and any other with the reference
+ * at `references/<file>`. Nothing is owed, since a project has no list to owe a
+ * ledger against, so only a ledger that exists is read, and one naming a skill
+ * or a file that is gone is reported rather than skipped.
+ */
+async function readProjectLedgers(
+  root: string,
+  sources: readonly SkillSource[],
+): Promise<SkillFinding[]> {
+  const dir = join(root, PROJECT_SKILL_LEDGERS)
+  if (!existsSync(dir)) return []
+  const paths = [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: dir, onlyFiles: true }),
+  ].sort()
+
+  const perLedger = await Promise.all(
+    paths.map(async (path): Promise<SkillFinding[]> => {
+      const ledgerRel = join(PROJECT_SKILL_LEDGERS, path)
+      const [folder, ...rest] = path.split('/')
+      const owners = sources.filter((source) => source.folder === folder)
+      if (rest.length === 0 || owners.length === 0) {
+        return [{ rel: ledgerRel, detail: `missing skill: ${folder}` }]
+      }
+      const file = rest.join('/')
+      const target = file === 'SKILL.md' ? file : join('references', file)
+      const rows = countLedgerRows(await Bun.file(join(dir, path)).text())
+
+      return owners.flatMap((owner) => {
+        const rel = join(owner.rel, target)
+        const body = owner.bodies.find((entry) => entry.rel === rel)
+        if (body === undefined) {
+          return [{ rel: ledgerRel, detail: `missing file: ${rel}` }]
+        }
+        return referenceLedgerFindings({
+          rel,
+          ledgerRel,
+          mismatches: compareLedger(
+            ledgerGroups(body.text, target === 'SKILL.md'),
+            rows,
+          ),
+          sources: [],
+        })
+      })
+    }),
+  )
+  return perLedger.flat()
+}
+
 /**
  * Directives per H2, `null` for any above the first. A contents list repeats
  * the headings rather than stating a rule, so `## Contents` takes no rows. A