@erclx/canon 5.73.0 → 5.75.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # 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)
+
+
+### Features
+
+* **claude:** fail a source linked in both adopted.md and a ledger ([#2831](https://github.com/erclx/canon/issues/2831)) ([f5bd7bc](https://github.com/erclx/canon/commit/f5bd7bc7a42c628d9725d8559678556821b2d4ef))
+* **gate:** run only related tests on a scoped push ([#2838](https://github.com/erclx/canon/issues/2838)) ([0918616](https://github.com/erclx/canon/commit/0918616ec6b0dcf9dea5c09da2761ca8bf0a0188))
+* **hooks:** log each plan-guard decision to a file ([#2829](https://github.com/erclx/canon/issues/2829)) ([87da825](https://github.com/erclx/canon/commit/87da825f23163c3dca64d17f959489fba41544f8))
+* **pr:** gate lift and merge on the base's required checks ([#2840](https://github.com/erclx/canon/issues/2840)) ([7758c02](https://github.com/erclx/canon/commit/7758c02389a0ace567ac753c59bb9baaf1c9e51d))
+* **pr:** show why a local link or reel is missing on evidence ([#2836](https://github.com/erclx/canon/issues/2836)) ([370f0de](https://github.com/erclx/canon/commit/370f0de3dd5f2bf2c79a0b91d4173bc0ed5c1a7a))
+* **skills:** add proposal-critique to question a proposal before build ([#2824](https://github.com/erclx/canon/issues/2824)) ([dd6e28d](https://github.com/erclx/canon/commit/dd6e28d4accde639ac5c1d7653069c44f71176ad))
+* **skills:** audit search-craft bullets against a source ledger ([#2832](https://github.com/erclx/canon/issues/2832)) ([acd3cea](https://github.com/erclx/canon/commit/acd3ceaacf5747e2f5e78963e4cf3267ee56cb9b))
+* **skills:** audit write-human bullets against a source ledger ([#2833](https://github.com/erclx/canon/issues/2833)) ([e78d299](https://github.com/erclx/canon/commit/e78d299f01ea470b26c61cb3ddb3246ab882502b))
+* **skills:** check outside tools and add a canon-media bundle ([#2837](https://github.com/erclx/canon/issues/2837)) ([f32e7c3](https://github.com/erclx/canon/commit/f32e7c3ea636d6b8e84debc70d6afe1f40430536))
+* **skills:** ledger every systematic-debugging step against a source ([#2835](https://github.com/erclx/canon/issues/2835)) ([e225b98](https://github.com/erclx/canon/commit/e225b9810d830e49276b9049d1c26f05feaac1f0))
+* **skills:** source each build-in-slices bullet in a ledger ([#2841](https://github.com/erclx/canon/issues/2841)) ([8651b8e](https://github.com/erclx/canon/commit/8651b8ef1e2a0517c7dad0792090dab5cafbfe91))
+* **skills:** source test-first bullets in a per-bullet ledger ([#2830](https://github.com/erclx/canon/issues/2830)) ([8d61a40](https://github.com/erclx/canon/commit/8d61a40d9e0a5faf70c3e9c753b965cea1f245d0))
+
+
+### Bug Fixes
+
+* **hooks:** track plan-guard.sh as executable and test hook modes ([#2826](https://github.com/erclx/canon/issues/2826)) ([d1ac3f5](https://github.com/erclx/canon/commit/d1ac3f543c7b1cad038871f5acaa71cb9889085c))
+
 ## [5.73.0](https://github.com/erclx/canon/compare/v5.72.1...v5.73.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.73.0",
+  "version": "5.75.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/api-design/references/adopted.md

@@ -7,21 +7,23 @@ description: Which external API design sources this skill adopted, which it decl
 
 External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
+A source a bullet rests on is linked once, in that bullet's row of the toolkit's per-bullet ledger at `governance/ledger/skills/api-design/`, which ships outside the plugin. This file names those sources without the link and keeps the catalog-level adopted and declined record, linking only a source no row cites.
+
 ## Adopted from the default shelf
 
 ### Observable behavior
 
-[Software Engineering at Google, ch. 1](https://abseil.io/resources/swe-book/html/ch01.html) states Hyrum's Law, that with enough users, every observable behavior of a system is depended on by somebody, whatever the contract promises.
+Software Engineering at Google, ch. 1 states Hyrum's Law, that with enough users, every observable behavior of a system is depended on by somebody, whatever the contract promises.
 
 Adopted as the opening group, stated as design rules rather than as an observation, so a session decides what is observable before a caller decides it for them. Ordering and timing are named because the chapter's own examples are hash iteration order and timing.
 
 ### One version per dependency
 
-[Software Engineering at Google, ch. 16](https://abseil.io/resources/swe-book/html/ch16.html) states the One-Version Rule, keeping one version of each dependency in a repository, so a change to it migrates every caller rather than leaving two versions live. Adopted under additive change for a caller that cannot pin, which is any module imported from inside one repository.
+Software Engineering at Google, ch. 16 states the One-Version Rule, keeping one version of each dependency in a repository, so a change to it migrates every caller rather than leaving two versions live. Adopted under additive change for a caller that cannot pin, which is any module imported from inside one repository.
 
 ## Adopted from one external skill
 
-From `addyosmani/agent-skills@2686b620`, [`skills/api-and-interface-design/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/api-and-interface-design/SKILL.md).
+From `addyosmani/agent-skills@2686b620`, `skills/api-and-interface-design/SKILL.md`.
 
 ### Contract and errors
 

package/claude/skills/build-in-slices/references/adopted.md

@@ -7,17 +7,19 @@ description: Which external sources on incremental building this skill adopted,
 
 External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
+A source a bullet rests on is linked once, in that bullet's row of the toolkit's per-bullet ledger at `governance/ledger/skills/build-in-slices/`, which ships outside the plugin. This file names those sources without the link and keeps the catalog-level adopted and declined record, linking only a source no row cites.
+
 ## Adopted from the default shelf
 
 ### Small changes
 
-[Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html), from Google's engineering practices, keeps a change self-contained and about one thing, puts a refactor in a change apart from the feature needing it, and puts a test in the same change as its code.
+Small CLs, from Google's engineering practices, keeps a change self-contained and about one thing, puts a refactor in a change apart from the feature needing it, and puts a test in the same change as its code.
 
 Adopted as the rule that each commit carries one logical change, the refactor excuse row, and the rule that a slice's test never lands after its code.
 
 ## Adopted for the increment cycle
 
-Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, [`skills/incremental-implementation/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md), supplies the cycle and most of the rules.
+Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, `skills/incremental-implementation/SKILL.md`, supplies the cycle and most of the rules.
 
 ### The cycle and its rules
 

package/claude/skills/code-craft/references/adopted.md

@@ -7,11 +7,13 @@ description: Which external software design sources this skill adopted, which it
 
 External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
+A source a bullet rests on is linked once, in that bullet's row of the toolkit's per-bullet ledger at `governance/ledger/skills/code-craft/`, which ships outside the plugin. This file names those sources without the link and keeps the catalog-level adopted and declined record, linking only a source no row cites.
+
 ## Adopted from the default shelf
 
 ### What to look for in a code review
 
-[Google's engineering practices](https://google.github.io/eng-practices/review/reviewer/looking-for.html) say to solve the problem known to need solving now rather than one speculated about, and to read "too complex" as "cannot be understood quickly by a reader".
+Google's engineering practices say to solve the problem known to need solving now rather than one speculated about, and to read "too complex" as "cannot be understood quickly by a reader".
 
 Adopted as the writing-time half of the same judgment, behind the change test and the ban on building for an unnamed case. The review procedure itself stays with `review-craft`.
 
@@ -29,25 +31,25 @@ Adopted as the opening of the depth group and the pass-through flag. `api-design
 
 ### The design book exchange
 
-In [John Ousterhout and Robert Martin's discussion](https://github.com/johnousterhout/aposd-vs-clean-code), Martin argues for very small methods and Ousterhout for fewer, deeper ones a reader need not stitch together.
+In John Ousterhout and Robert Martin's discussion, Martin argues for very small methods and Ousterhout for fewer, deeper ones a reader need not stitch together.
 
 Adopted as the third tension, stated as when each side wins rather than as a verdict, plus the depth bullet preferring one function a reader follows top to bottom.
 
 ### Reducing coupling
 
-Martin Fowler, [Reducing Coupling](https://martinfowler.com/ieeeSoftware/coupling.pdf), IEEE Software, 2001, holds that a change in one module should not ripple into others. Adopted behind the rule that a decision stays in one unit and the red flag on a third file opened to adjust one rule.
+Martin Fowler, Reducing Coupling, IEEE Software, 2001, holds that a change in one module should not ripple into others. Adopted behind the rule that a decision stays in one unit and the red flag on a third file opened to adjust one rule.
 
 ## Adopted for the tensions
 
 ### DRY as knowledge
 
-Andy Hunt and Dave Thomas, [Orthogonality and the DRY Principle](https://www.artima.com/articles/orthogonality-and-the-dry-principle), give every piece of knowledge one authoritative representation, which is broader than and different from avoiding repeated text.
+Andy Hunt and Dave Thomas, Orthogonality and the DRY Principle, give every piece of knowledge one authoritative representation, which is broader than and different from avoiding repeated text.
 
 Adopted as the first tension, with its other side stated. Two blocks that only look alike and change for different reasons stay apart.
 
 ### Yagni and its carve-out
 
-Ron Jeffries, [You're NOT Gonna Need It](https://ronjeffries.com/xprog/articles/practices/pracnotneed/), and Martin Fowler, [Yagni](https://martinfowler.com/bliki/Yagni.html), build no capability for a presumptive feature, though Yagni "does not apply to effort to make the software easier to modify".
+Ron Jeffries, [You're NOT Gonna Need It](https://ronjeffries.com/xprog/articles/practices/pracnotneed/), and Martin Fowler, Yagni, build no capability for a presumptive feature, though Yagni "does not apply to effort to make the software easier to modify".
 
 Adopted as the second tension, with Fowler's carve-out as the side that wins for a refactor, a test, or a parameter serving the asked-for code.
 
@@ -63,11 +65,11 @@ Martin Fowler, [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRule
 
 ### Injection
 
-Martin Fowler, [Inversion of Control Containers and the Dependency Injection pattern](https://martinfowler.com/articles/injection.html), hands a component what it depends on rather than letting it find it. Adopted as the hidden-inputs rule for the clock, the environment, randomness, and globals, without any container.
+Martin Fowler, Inversion of Control Containers and the Dependency Injection pattern, hands a component what it depends on rather than letting it find it. Adopted as the hidden-inputs rule for the clock, the environment, randomness, and globals, without any container.
 
 ## Adopted for agent failure modes
 
-Birgitta Böckeler, [The role of developer skills in agentic coding](https://martinfowler.com/articles/exploring-gen-ai/13-role-of-developer-skills.html), 2025, and [How far can we push AI autonomy in code generation?](https://martinfowler.com/articles/pushing-ai-autonomy.html), 2025.
+Birgitta Böckeler, The role of developer skills in agentic coding, 2025, and How far can we push AI autonomy in code generation?, 2025.
 
 - Together they record a lack of reuse and modularity, overeagerness that builds unrequested features, assumptions filled in for silent requirements, and brute-force fixes
 - Adopted as the closing concern group, worded as checks on the session's own diff

package/claude/skills/codebase-layout/references/adopted.md

@@ -7,39 +7,41 @@ description: Which external layout patterns this skill adopted, which it decline
 
 External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
+A source a bullet rests on is linked once, in that bullet's row of the toolkit's per-bullet ledger at `governance/ledger/skills/codebase-layout/`, which ships outside the plugin. This file names those sources without the link and keeps the catalog-level adopted and declined record, linking only a source no row cites.
+
 ## Adopted for placing files
 
 ### Group what changes together
 
-Robert Martin's restatement of the single responsibility principle reads "Gather together the things that change for the same reasons. Separate those things that change for different reasons" ([The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html)).
+Robert Martin's restatement of the single responsibility principle reads "Gather together the things that change for the same reasons. Separate those things that change for different reasons" (The Single Responsibility Principle).
 
 It gives "split by role" a test a planner can apply to a folder, which is whether these files would change together.
 
 ### Name folders for the domain rather than the framework
 
-Martin's [Screaming Architecture](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html) argues the top level should tell readers "about the system, not about the frameworks you used in your system". It is the root of naming a folder for what it holds rather than its technical kind.
+Martin's Screaming Architecture argues the top level should tell readers "about the system, not about the frameworks you used in your system". It is the root of naming a folder for what it holds rather than its technical kind.
 
 ### Feature folders, no cross-feature imports, one-way flow
 
-bulletproof-react puts most code under per-feature folders holding only the subfolders each needs, forbids one feature importing another, and enforces a shared, then features, then app direction with an import-path lint rule ([project structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)).
+bulletproof-react puts most code under per-feature folders holding only the subfolders each needs, forbids one feature importing another, and enforces a shared, then features, then app direction with an import-path lint rule (project structure).
 
 Adopted as the direction rule in the body and the feature-folder guidance in `frontend.md`, without the mandate.
 
 ### Grow in levels and promote on the second consumer
 
-Robin Wieruch grows a project from one file to feature folders, each level triggered by a named event rather than a count, and moves a helper to the shared layer once two or more features need it ([React folder structure](https://www.robinwieruch.de/react-folder-structure/)).
+Robin Wieruch grows a project from one file to feature folders, each level triggered by a named event rather than a count, and moves a helper to the shared layer once two or more features need it (React folder structure).
 
 Adopted as the promotion rule in the body and the levels in `frontend.md`.
 
 ### Consistency over any one strategy
 
-The Next.js docs call the framework unopinionated about organization, list three strategies, and ask a project to "choose a strategy that works for you and your team and be consistent across the project" ([project structure](https://nextjs.org/docs/app/getting-started/project-structure)).
+The Next.js docs call the framework unopinionated about organization, list three strategies, and ask a project to "choose a strategy that works for you and your team and be consistent across the project" (project structure).
 
 Adopted as the body's first section, reading and keeping the project's own strategy.
 
 ### Fixtures in modules, page objects on their own
 
-Playwright defines fixtures in dedicated modules that extend the base test, merges them into one module the specs import, and keeps page objects as their own modules ([fixtures](https://playwright.dev/docs/test-fixtures)). Adopted in `tests.md` as the split between specs and support.
+Playwright defines fixtures in dedicated modules that extend the base test, merges them into one module the specs import, and keeps page objects as their own modules (fixtures). Adopted in `tests.md` as the split between specs and support.
 
 ## Adopted for closing the body
 

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

@@ -55,7 +55,12 @@ A skill whose files list outside-practice directives one per bullet takes a ledg
 - Exempt by name a checklist restating rules a ledgered file sources, which would cite each source twice, and a glossary, whose definitions direct nothing
 - Mark the skill's `SKILL.md` for a ledger too when the body carries directives of its own
 - Keep the rows outside the plugin, so a target pays nothing for them
+
+Two copies of one source drift, and the audit holds the move.
+
 - Move a source out of `adopted.md` once its row lands in a ledger, since two copies drift on the first edit. `adopted.md` keeps the catalog-level record and the sources behind any unledgered file.
+- Expect the audit to fail a link in both `adopted.md` and one of the skill's ledgers. It reads an anchor or a trailing slash as the same page and two commit pins as two pages.
+- Name the ledger folder in `adopted.md` once every link has moved out, since a record with no link and no `House choice` row otherwise reads as citing nothing
 
 The audit counts a few lines in a ledgered file apart from a rule's.
 
@@ -68,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/deprecation-migration/references/adopted.md

@@ -7,11 +7,13 @@ description: Which external sources on deprecation and migration this skill adop
 
 External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
+A source a bullet rests on is linked once, in that bullet's row of the toolkit's per-bullet ledger at `governance/ledger/skills/deprecation-migration/`, which ships outside the plugin. This file names those sources without the link and keeps the catalog-level adopted and declined record, linking only a source no row cites.
+
 ## Adopted from the default shelf
 
 ### Deprecation
 
-[Software Engineering at Google, chapter 15](https://abseil.io/resources/swe-book/html/ch15.html) supplies four positions the body states.
+Software Engineering at Google, chapter 15 supplies four positions the body states.
 
 - **Two types.** Advisory and compulsory, the second carrying a removal date. The body allows compulsory only once a replacement ships, which the chapter implies and the four questions make explicit.
 - **Actionable, relevant warnings.** A warning names what the caller does, and surfaces where the caller uses the old surface.
@@ -20,13 +22,13 @@ External sources were read and filtered rather than imported. This file is the r
 
 ### Migrating callers yourself
 
-[Software Engineering at Google, chapter 1](https://abseil.io/resources/swe-book/html/ch01.html), under "Policies That Don't Scale", has infrastructure teams move their internal users to new versions themselves, or update in place in a backward-compatible way.
+Software Engineering at Google, chapter 1, under "Policies That Don't Scale", has infrastructure teams move their internal users to new versions themselves, or update in place in a backward-compatible way.
 
 Adopted as the group on migrating callers yourself, with the backward-compatible path kept for callers the owner cannot edit.
 
 ## Adopted for the decision and the bridges
 
-Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, [`skills/deprecation-and-migration/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md), supplies the decision and the bridge patterns.
+Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, `skills/deprecation-and-migration/SKILL.md`, supplies the decision and the bridge patterns.
 
 ### The decision
 

package/claude/skills/design-pick/references/board.md

@@ -13,8 +13,8 @@ Resolve `<board>` and `<project>` from the `board` and `project` keys of `canon/
 Resolve `<board>` against the main worktree root, the way `session-worktree` resolves it, since a linked worktree holds no copy of the gitignored folder.
 
 - Pass `--root <board> --project <project> --json` to every verb unless the step says otherwise, so no verb relies on the only-project default
-- Where `frameboard` is not on PATH, run every verb as `bunx -y frameboard@0.6 <verb>`. Say so once and keep that form for the run.
-- The pin holds the minor, since record shapes move across a pre-1.0 minor
+- Where `frameboard` is not on PATH, run every verb as `bunx -y frameboard <verb>`. Say so once and keep that form for the run.
+- The fallback takes the latest release unpinned, since the verbs and record shapes come from `frameboard docs --json` each run and a renamed verb surfaces as a refusal
 
 Run `frameboard docs --json` before writing the first frame. Its `contentFormat` fixes what a frame may hold and link, and its `exitCodes` name every refusal a verb can return.
 

package/claude/skills/plan-feature/SKILL.md

@@ -77,7 +77,8 @@ What this skill adds on top of the standard:
 - Record each command Step 2 ran and what it showed, or the not-run reason, under `## Current behavior`, and omit the section when nothing ran
 - Reframe a vague ask as success criteria before `## Files to touch`, each an observable result and its check, which becomes one `## Verification` bullet. "Make it faster" names none.
 - Confirm a concrete project or use case drives the feature, and lift patterns from it where precedent exists. A feature with no named user is a guess.
-- Prefer one layout that serves both a new and a grown project over a dual-mode toggle or a migration shim. Two modes double what every later change has to hold.
+- Prefer one layout that serves both a new and a grown project over a dual-mode toggle or a migration shim. Two modes double what every later change holds.
+- Name `proposal-critique` for a one-way change or an unverified cause
 
 ### Suggestions and sections
 

package/claude/skills/plan-groundwork/SKILL.md

@@ -134,6 +134,8 @@ The standard sets the open question format inside a topic file and in `00-scope.
 
 Aside from an experiment fixture, Steps 4 and 5 are the only ways close mode reaches outside the folder. Do not close while an open question quietly fails an outcome. Resolve it, or record it in `06-decision.md` as knowingly accepted.
 
+Name `proposal-critique` in the close report when the decision is a one-way change or a fix whose cause is unverified, and never invoke it from here.
+
 ## Check the folder
 
 Run `canon records validate groundwork <nn>-<slug>` on the folder this run wrote, in every mode, before reporting. Fix each entry its `structure` array names, against `### Structure` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.

package/claude/skills/pr-evidence/REQUIREMENT.md

@@ -32,3 +32,4 @@ A session judging from the diff whether an evidence image changed cannot see a r
 - The title, body, labels, and pre-publish scan, which `git-pr` owns
 - Writing the checklist, which `ui-checklist` owns, leaving this skill to consume the handoff file and remove it after posting
 - Driving the checklist in the running app, which `review-ui` owns
+- The filming rules the reel follows, which `ui-film` owns

package/claude/skills/pr-evidence/SKILL.md

@@ -48,6 +48,8 @@ Collect only the lines below whose condition holds, and nothing when none does.
 | The reel step skipped with a reason                       | `🎞️ No reel: <reason>: <message>`                                  |
 | A git refusal or a preview refusal the reference reports  | `⚠️ <reason>: <message>`                                           |
 
+The no-local-preview and no-reel lines also land on the evidence comment, through the evidence call's `--local-skip` and `--reel-skip`, so the pull request shows why a link or a reel is missing after the session's report scrolls away.
+
 ### The uncaptured line
 
 Collect `📸 <N> painted paths changed with no evidence capture. Recapture and push.` when the evidence record lists `uncaptured` paths, with `<N>` its count. The line never stops the run, since no step here can take a capture, and the review raises the same paths as a finding until a recapture lands.

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

@@ -36,7 +36,7 @@ canon pr local --json
 The verb reports the lowest port serving an HTML page whose process runs inside this worktree, never one in another worktree or the main checkout, which shows a different branch. `canon pr local --help` states the contract. Read `reason` on the record rather than the exit code.
 
 - `ok`: hold the record's `url` for the evidence step below.
-- `no-server`, `no-listener-reader`, `unhealthy`, or `invalid-config`: hold the reason and the record's `message` for the closing report, and pass no link.
+- `no-server`, `no-listener-reader`, `unhealthy`, or `invalid-config`: hold the reason and the record's `message` for the closing report and for the evidence step's `--local-skip`, and pass no link.
 - `unhealthy` means a page answered but a health path declared in `canon/config/local.toml` failed. `invalid-config` means that file cannot be read, so nothing was checked.
 - Never start a server here, since the ship chain cannot own one. A worker starts one under `role-worker`.
 - Anything else, including no record or an older binary's unknown-subcommand error: move on silently, as a skip rather than a stop.
@@ -63,12 +63,14 @@ canon pr evidence <number> --check --json
 - Skip filming when the record's `reel.head` is a prefix of the `tip` that `canon pr head <number> --json` reports, since the posted reel already shows this head
 - With no checklist from either source, skip silently, since nothing names an interaction to film
 
-Invoke `canon:ui-film` in pull request mode, passing the number, the local `url`, and the checklist. It films, checks each beat's closing still, pushes the reel to `canon/frames`, and hands back a `link` or a skip reason.
+Read `${CLAUDE_SKILL_DIR}/references/reel.md` and run it with the number, the local `url`, and the checklist. It films, checks each beat's closing still, pushes the reel to `canon/frames`, and hands back a `link` or a skip reason.
 
-Report it rather than proceeding silently when `canon:ui-film` does not resolve, and post the evidence without a reel.
+It reads the filming rules in `ui-film`. Report it rather than proceeding silently when the `ui-film` skill does not resolve, and post the evidence without a reel.
 
 - Hold a `link` for the evidence step, which embeds it under the addresses
-- Hold a skip's reason and message for the closing report. A skip never stops the chain, and a reel already on the comment carries forward under the older head it names.
+- Hold a skip's reason and message for the closing report and for the evidence step's `--reel-skip`
+- A skip never stops the chain, and a reel already on the comment carries forward under the older head it names
+- A silent skip holds no reason, so it passes no `--reel-skip`
 
 ## Post the evidence comparison
 
@@ -78,6 +80,11 @@ Run the verb once against the pull request number. Pass `--checklist` when the c
 canon pr evidence <number> --checklist <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md --local <url> --reel <link> --json
 ```
 
+Pass `--local-skip '<reason>: <message>'` in place of `--local` when the local step held a refusal, and `--reel-skip '<reason>: <message>'` in place of `--reel` when the reel step held a skip. Each puts the line the closing report prints onto the comment as well, so a reader of the pull request sees why the link or the reel is missing.
+
+- Pass the same text the closing report carries, so the comment and the report agree
+- A later run that posts the link or films the reel drops the line, and one passing neither flag carries it forward
+
 One call answers both questions because a checklist decides `no-evidence`. A diff carrying a checklist and no evidence image renders `ok` with the checklist in a marked body, so the checklist lands in the one comment a later call finds and edits.
 
 - Pass `--checklist` only for a file that exists

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

@@ -0,0 +1,108 @@
+---
+title: Reel
+description: The reel pr-evidence films for an evidence comment with no operator present, covering the beat choice from the checklist, the length cap, the still check that stands in for approval, the reel flag, and the push to the frames branch
+---
+
+# Reel
+
+Read by the reel step of `evidence.md`, passing the pull request number, the `url` its `canon pr local` read returned, and the checklist text.
+
+This file films a short reel of what the checklist asks a reviewer to try, hosts it on `canon/frames`, and hands back the link or the reason it skipped. The filming rules are `ui-film`'s, in `${CLAUDE_SKILL_DIR}/../ui-film/references/take-craft.md`, and so is the config's `access` value, in `${CLAUDE_SKILL_DIR}/../ui-film/references/config.md`.
+
+## Contents
+
+- [How the reel runs](#how-the-reel-runs)
+- [Choose the beats](#choose-the-beats)
+- [Film the reel](#film-the-reel)
+- [Check each still](#check-each-still)
+- [Push the reel](#push-the-reel)
+- [What goes back to the reel step](#what-goes-back-to-the-reel-step)
+
+## How the reel runs
+
+No operator is present, so the run is unattended end to end.
+
+- Film the address the caller passed, joined to the config's `access` value, and start no server
+- Approve nothing. The beats come from a checklist a reviewer already reads, and the still check below is the guard against posting a wrong take.
+- Compose nothing, since the reel is the product
+- Write inside `.canon/tmp/pr/reel/<number>/` at the current worktree's root, since a reel is thrown away once posted
+- Ask nothing at any step. Every stop below is a skip with a reason, since the ship chain runs this with nobody to answer.
+
+## Choose the beats
+
+Film where motion is the claim. Filter the boxes first, then spend the three beats so each feature area shows its change once before any area shows two.
+
+### Filter the boxes
+
+A box is filmable when it asks the reviewer to click, fill, or scroll something and its result is a visible change.
+
+- Skip a box ending in `(taste)`, since no driver judges it
+- Skip a box that asks only to look at a state the page opens on, since a screenshot already shows it
+- Skip a negative box, one asserting that something does not happen, such as "no drop line draws", since footage of nothing shows nothing
+
+Read the box's text for the negative. A box asserting an unchanged result, such as "the board goes to all projects as before", is not negative, since the action still produces a visible change. Rank it behind a box in the same group that names new behavior.
+
+### Order the beats
+
+A group is the bold feature-area label above at most five boxes, as `ui-checklist` defines it.
+
+1. Take one beat per group in checklist order, from the highest-ranked filmable box of each group, up to three beats.
+2. When beats remain after every group has one, take a second pass in checklist order over the boxes left, highest-ranked first within each group, up to three beats in all.
+
+A checklist with one group gives up to three beats from it. A checklist with four groups gives three beats, one from each of the first three.
+
+### Plan the beats
+
+Write one plan entry for each beat chosen, then skip when none was.
+
+- Name each beat after its box's text, cut to the action
+- Write the plan per `${CLAUDE_SKILL_DIR}/../ui-film/references/take-craft.md`, finding each target on the served page rather than guessing it
+- With no interactive box, skip as `no-interactive-box` and film nothing
+- With interactive boxes that the filter removed, whether negative, static, or marked `(taste)`, skip as `no-visible-change` and film nothing
+
+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, 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 --max-seconds 12 --json
+```
+
+Branch on the record's `reason`, never on the exit code.
+
+| 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
+
+Open each beat's `still.jpg`, the closing frame the record names in its `still` field, and confirm it shows the state the beat's box describes. This check replaces the operator's approval, so it runs on every reel.
+
+- A still showing the wrong state skips the reel as `wrong-state`, naming the beat and what the still shows
+- A record whose beats carry no `still` field comes from a `canon` predating the still, so skip as `no-still` rather than posting a reel nothing checked
+- Read `fallback` on each beat. A beat filmed by screencast still joins the reel, since the reel shrinks every beat to one width.
+
+## Push the reel
+
+Stamp the pass in compact UTC and push the file:
+
+```bash
+canon pr frames <number> --reel .canon/tmp/pr/reel/<number>/reel.webp --pass "$(date -u +%Y%m%dT%H%M%SZ)" --json
+```
+
+- `ok`: hold the record's `link`
+- `reel-too-large`: skip as `reel-too-large`, since GitHub would not render it
+- Any other `reason`: skip under it with the record's `message`
+
+## What goes back to the reel step
+
+Hand the reel step one of two things and print nothing of your own:
+
+- The `link` from the push, which the evidence step passes to `canon pr evidence --reel`
+- A skip, as the reason and a one-line message, which the closing report names

package/claude/skills/proposal-critique/REQUIREMENT.md

@@ -0,0 +1,34 @@
+---
+name: proposal-critique
+description: Scope boundary for questioning a proposal before it is built, the two directions it checks, and the one verdict it ends on
+---
+
+# Proposal critique requirement
+
+## Gap
+
+Without this skill, a session builds a proposal as stated. A fix for an upstream failure ships before anyone checks whether the cause is ours. A proposal that holds back too far, such as a gate serializing work it never needed to hold, passes too, since an improvised critique asks only whether a change does too much.
+
+When a session does question a proposal, it asks the same long list of a one-line revertible edit and of a published release, so it either stalls small work or waves through large work. It ends on a list of concerns with no call, and it answers from its own reading of the conversation without saying the proposal was its own.
+
+## Must
+
+- Ask whether the proposal does too much and whether it is too cautious
+- Scale the question count by reversibility and reach, two questions for a two-way local change and every group for a one-way or shipped change or an unverified cause
+- Answer each question from evidence in the tree, the history, or the record, and put a preference question through the question surface
+- End on exactly one verdict of go, probe first, absorb, or stop, naming the questions that decided it
+- Say where the proposal was read from, and say when this session wrote it
+
+## Must not
+
+- Write a section into the plan, task, or intake item it critiques, since the operator decides what moves into a record
+- Run on its own initiative or from another skill by default
+- Stay in the catalog if the operator and the planning skills' pointers never reach it at the costly moment, which is the review criterion for whether it earns its place
+- Give a conditional verdict, which is a probe stated as a go
+
+## Out of scope
+
+- Batching decisions that turn on the operator's preference, which `decision-escalate` owns
+- Investigating a failing test or a bug in hand, which `systematic-debugging` owns
+- Judging a finished change, which `review-pr` owns
+- Writing the plan a go lets through, which `plan-feature` owns