@erclx/canon 5.72.1 → 5.74.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **app-drive:** draw every decided finding and check the drawing ([#2815](https://github.com/erclx/canon/issues/2815)) ([3f73075](https://github.com/erclx/canon/commit/3f73075fe2be2a2b156877e807563cf8eb3b367c))
+* **hooks:** block a new plan written without a plan-feature invocation ([#2822](https://github.com/erclx/canon/issues/2822)) ([21cca3f](https://github.com/erclx/canon/commit/21cca3f04ced7da7755a33827677df02a1cd97aa))
+* **plan:** bundle shared-file fixes into one row with an H3 per item ([#2819](https://github.com/erclx/canon/issues/2819)) ([041ecac](https://github.com/erclx/canon/commit/041ecac364a52eec56240c6350683ec582bc35c6))
+* **reviewer:** batch the review of small contract-free pull requests ([#2820](https://github.com/erclx/canon/issues/2820)) ([e2422c6](https://github.com/erclx/canon/commit/e2422c6e4b4e268929ade28bc7553c2be23e5e93))
+* **ui-film:** add scratch and harness folders to the film workspace ([#2823](https://github.com/erclx/canon/issues/2823)) ([7698171](https://github.com/erclx/canon/commit/76981718e7021dc02312f652b298d3a69e184ba5))
+
+
+### Bug Fixes
+
+* **debugging:** ask about routing around an external cause before retry ([#2821](https://github.com/erclx/canon/issues/2821)) ([77f36c1](https://github.com/erclx/canon/commit/77f36c1169ffe51f59d14dd2fa08c8f26bd8a3f5))
+* **planner:** invoke plan-feature from the planning tail ([#2816](https://github.com/erclx/canon/issues/2816)) ([15d238b](https://github.com/erclx/canon/commit/15d238bc54b0343377f10068cc7fe733c7e953a7))
+
 ## [5.72.1](https://github.com/erclx/canon/compare/v5.72.0...v5.72.1) (2026-10-27)
 
 

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.72.1",
+  "version": "5.74.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/app-drive/REQUIREMENT.md

@@ -17,7 +17,7 @@ Nothing ties the drive to what the app is for, so a goal goes untried and nobody
 - Every requirements goal is driven per persona, or marked not driven with its reason
 - Every finding names its source and its severity, and carries its evidence inside the intake folder, as does every image the operator pastes during the drive
 - The drive files one intake folder, each finding sorted as a bug, a requirements conflict, or a taste call, and a session staying to plan its rows answers it before any row is promoted
-- `canon intake drive-check` fails a drive that skipped a goal, touched the checkout, or left evidence outside the folder
+- `canon intake drive-check` fails a drive that skipped a goal, touched the checkout, left evidence outside the folder, or decided a visible change without drawing it
 
 ## Must not
 
@@ -31,5 +31,5 @@ Nothing ties the drive to what the app is for, so a goal goes untried and nobody
 - Reading source for roughness, which `ui-audit` owns
 - Driving one pull request's checklist, which `review-ui` owns
 - Measuring paint and layout cost, which `ui-measure` owns
-- Picking between a now frame and a fix frame, which `design-pick` owns
+- Picking between a now frame and a fix frame for an undecided taste finding, which `design-pick` owns
 - Messaging the controller and ending the session, which `role-planner` owns

package/claude/skills/app-drive/SKILL.md

@@ -20,7 +20,7 @@ A drive puts a built app in front of the operator and the session together, and
 
 ## Write scope
 
-- Write inside `.canon/intake/<nn>-<slug>/` and the scratch folder `.canon/tmp/app-drive/<slug>/` at the main worktree root, resolved the way `session-worktree` does
+- Write inside `.canon/intake/<nn>-<slug>/`, the scratch folder `.canon/tmp/app-drive/<slug>/`, and the config's `proposals` folder at the main worktree root, resolved the way `session-worktree` does
 - The one exception is the throwaway worktree outside the repository, which Step 1 adds and the close removes. It is not entered with `EnterWorktree`, and no branch is created.
 - Never write `canon/REQUIREMENTS.md`, a fixture, or any other tracked file, a requirements diff included. Draft that diff as text inside the intake item.
 - Send each intake file out as a heredoc, the main-root route `session-worktree` states
@@ -66,13 +66,30 @@ Append each finding to the drive log as it happens, never batched at the end, si
 - Write an operator's decision under the finding it settles, even when later findings already sit below it, since it is the one edit above the end of the log
 - Write `drive.json` into the intake folder in the shape `drive-record.md` sets, with one entry per goal
 
+### Drawing a decided finding
+
+Draw every finding the operator decides before writing its `Decision (operator)` line, whether it is a bug fix, a new feature, or a taste call. A planner reading one line of text cannot see what the operator saw, and drawing the options settles questions the text hides.
+
+Load `canon:ui-craft` and `canon:design-taste` before the first fix frame of a rendered surface, as `design-pick` does before drafting. The picked frame is what a worker builds against, so it has to cover states such as popover dismissal and focus return.
+
+1. Draw a now frame and one fix frame per option inside the throwaway copy, on a canvas the app offers or a scratch route added to it. Name frames by the log's finding number, per `drive-record.md`.
+2. Screenshot the frames side by side to `evidence/<nn>-options.png` and open it. Put the options to the operator through the structured question surface, shaped as `design-pick`'s Step 4 shapes a pick.
+3. Copy the mock source into `evidence/mocks/<surface>/`, then write `Drawn` citing both paths and record the pick as the decision.
+
+A few cases bend those steps without lifting them.
+
+- When the copy cannot host a mock, lift the frames into standalone HTML in the config's `proposals` folder, and still copy the source into `evidence/mocks/`, since the check reads `evidence/` alone
+- Write `Drawn: skipped, <reason>` only for a change with nothing visible, such as an exit code or a file format
+- Never write a mock into a tracked path, the project's design board, or `canon/design/`. An accepted design reaches the board through `design-pick` or `design-record` once its fix ships.
+- Leave an undecided taste finding undrawn here, since Step 4 hands it to `design-pick`
+
 ## Step 4: sort
 
 Give every finding one kind, and keep the severity it was logged with.
 
 - **Bug.** The app breaks a goal or its own contract. It becomes an item whose fix a worker can build, with the repro and the evidence path. `systematic-debugging` owns finding its cause.
 - **Requirements conflict.** The app does what the record says and the operator wants otherwise, or the record contradicts itself. The item carries the drafted diff as text, and the operator decides.
-- **Taste.** The call is settled by looking. The item carries a now frame and a fix frame for a `design-pick` pass, written to the config's `proposals` folder.
+- **Taste.** The call is settled by looking. An undecided one carries a now frame and a fix frame for a `design-pick` pass in the config's `proposals` folder. A decided one carries what Step 3 drew.
 
 ## Step 5: file
 
@@ -86,7 +103,7 @@ Read `${CLAUDE_SKILL_DIR}/../plan-intake/references/intake.md` before writing a
 
 Close only on the operator's word, while the app stays up for as long as they keep talking.
 
-1. Stop the server and remove the worktree per `isolate.md`.
+1. Confirm every drawn finding's mock source sits under `evidence/mocks/`, then stop the server and remove the worktree per `isolate.md`.
 2. Run `canon intake drive-check <slug> --json`, and on `failed` fix what each finding list names in the folder and re-run.
 3. Report each path under `changed` to the operator and never revert it, since only they know which to keep.
 4. Run `canon records validate intake <slug>` and fix each `structure` entry it names.
@@ -99,7 +116,7 @@ Run this tail only when the operator, staying after the close, asks this session
 1. Answer the intake's `You:` slots with `plan-intake-answer` before any row is promoted from it.
 2. Send the controller the ready list, naming no item whose `You:` slot is still open, and say this session is planning those rows, so it holds a cold planner for each.
 3. Wait for the controller to file the rows and name each back. Plan only a row named to this session, and write no task file.
-4. Plan each named row under `plan-feature`, then link it with `canon tasks plan-link` and announce it per `role-planner` before starting the next.
+4. Invoke `canon:plan-feature` for each named row, since its Step 1 loads the UI skills for a rendered surface. Link it with `canon tasks plan-link` and announce it per `role-planner` before the next.
 
 ## Output
 
@@ -119,5 +136,5 @@ Next: /plan-intake-answer to answer the You: slots from here, then /task-board t
 - The controller messages, the talk clause, and the session's end: `role-planner`
 - The intake folder's shape and its routing test: `plan-intake`
 - The cause of a bug: `systematic-debugging`
-- The pick between a now frame and a fix frame: `design-pick`
+- The pick between a now frame and a fix frame for an undecided taste finding: `design-pick`
 - The voice of every recorded passage: `write-human`

package/claude/skills/app-drive/references/config.md

@@ -21,13 +21,14 @@ proposals = ".canon/picks"
 | `launch`    | The shell command that installs, builds, and serves the app in a worktree |
 | `data`      | A fixture path inside the worktree to load before serving, if any         |
 | `personas`  | Who uses the app, each driven through every goal                          |
-| `proposals` | The folder a taste finding's now frame and fix frame go to                |
+| `proposals` | The folder for an undecided taste finding's frames and a fallback mock    |
 
 Three of the keys carry a reading the table cannot hold.
 
 - `launch` runs from the worktree root and names the port it serves on, so `canon pr local --root` finds it
 - `personas` covers an agent or API caller as well as a person in the UI, when the app has one
 - An absent `data` means the app starts empty, and an absent `proposals` means the frames stay in the intake folder's `evidence/`
+- A fallback mock is the standalone HTML a decided finding's frames are lifted into when the copy cannot host them
 
 ## When the file is absent
 

package/claude/skills/app-drive/references/drive-record.md

@@ -30,10 +30,12 @@ Write the log to `evidence/drive-log.md` inside the intake folder. It opens on a
 - **Saw:** the view stayed put, with 64% of the frame under the panel edge
 - **Cause:** from code, the reveal acts only when the box is wholly outside the view
 - **Evidence:** `evidence/02-partial-no-pan.png`
+- **Drawn:** `evidence/02-options.png`, `evidence/mocks/layers/`
 - **Decision (operator):** center the frame unless it is wholly visible
 ```
 
 - `<nn>` numbers findings in the order they were found, and the frame carries the same number
+- A drive frame is named `frames/<nn>-<name>.png`. A drawn frame is named `<nn>-now`, `<nn>-fix`, or `<nn>-fix-<variant>` by the log's finding number, for a bug fix and a new feature alike.
 - The title names what the persona met, in sentence case with no trailing period
 - The meta line holds the severity, the source, and the persona, in that order. The source is `goal`, `last-drive`, or `operator`, and a finding naming none sorts as taste.
 - A `last-drive` finding adds `fixed`, `still open`, or `changed` to its meta line
@@ -56,6 +58,16 @@ The fields under the meta line carry the drive itself, one fact to a line.
 - A decision settling two findings sits under the first, and the second carries `Decision (operator):` naming that finding's number, such as `see 02`
 - Keep each field to one line. A field that runs long splits into a second field rather than growing.
 
+### Drawn outcomes
+
+The check reads `Drawn` and `Decision (operator)` off the log by those exact labels, so a reworded label turns the check off without failing it.
+
+- Put the options screenshot at `evidence/<nn>-options.png`, showing the now frame beside every fix frame
+- Copy the mock source into `evidence/mocks/<surface>/`, where `<surface>` names the screen or panel drawn on
+- Write `Drawn` above the decision, citing paths under `evidence/` the way `Evidence` does, or `skipped, <reason>` when the change has nothing visible
+- A bare `skipped` with no reason counts as undrawn, since the next reader cannot tell a choice from an omission
+- A decision reading `see <nn>` was drawn under the finding it names and carries no `Drawn` of its own
+
 ### Passed goals
 
 A goal tried and passed takes a heading too, so the next drive can tell a goal checked from one skipped. Its meta line reads `pass` · goal · persona, and it carries `Did` and `Evidence` alone.
@@ -120,4 +132,5 @@ A failed check names each finding by list, and an empty list is a clean axis.
 | `changed`         | a main checkout path that moved since the baseline |
 | `strayEvidence`   | an evidence path outside `evidence/`               |
 | `missingEvidence` | an evidence path holding no file                   |
+| `undrawn`         | a logged decision with no drawn outcome or reason  |
 | `worktreeLeft`    | the `worktree` path still on disk                  |

package/claude/skills/app-drive/references/isolate.md

@@ -37,7 +37,7 @@ A target whose build cannot run outside its repository, such as one linking sibl
 
 ## Close
 
-Close only after every cited frame sits in the intake folder's `evidence/`, since the removal deletes whatever scratch the worktree held.
+Close only after every cited frame sits in the intake folder's `evidence/`, and every drawn finding's mock source in `evidence/mocks/`, since the removal deletes whatever scratch the worktree held.
 
 1. Stop the server this session started.
 2. Run `git worktree remove --force <dir>/app`, then remove `<dir>`.

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-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.
 

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

@@ -11,7 +11,7 @@ metadata:
 
 - If no feature description is provided, stop: `❌ No feature description. Describe what you want to add.`
 - Do not implement anything. Output the plan and stop.
-- When the feature description spans two or more independent concerns, write one plan file per concern. Do not bundle them under a single slug.
+- When the feature description spans two or more independent concerns, write one plan file per concern. Bundle them under one slug only as an agreed bundle row.
 
 ## Write scope
 
@@ -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-feature/references/plan.md

@@ -5,7 +5,7 @@ description: Filename and slug, the required sections, and the suggested-and-ans
 
 # Plan reference
 
-Applies to a feature plan at `.canon/plans/feature-<slug>.md`. One file holds one concern, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
+Applies to a feature plan at `.canon/plans/feature-<slug>.md`. One file holds one concern, except a bundle row, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
 
 The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs a plan deleted before a push, which is why the archive step is a move rather than a cleanup.
 
@@ -50,12 +50,22 @@ A plan failing these is non-conforming even when it satisfies every shape rule b
 ## Filename and slug
 
 - Name the file `feature-<slug>.md`, with `<slug>` two to four kebab-case words naming the concern.
-- Write one concern per file, since a plan bundling two cannot be executed by two sessions or abandoned by half
+- Write one concern per file, except a bundle row below, since a plan bundling two cannot be executed by two sessions or abandoned by half
 - Derive the slug from the concern rather than from a branch, because the plan is written before the branch exists.
 - Give the executing branch the same slug, since a later surface finds the plan from the branch name and finds nothing when the spellings differ
 
 A plan carries no frontmatter. Its filename is the whole of its identity, so a folder of plans is read by name rather than by a generated catalog.
 
+### Bundle rows
+
+A bundle row is the one exception to a concern per file. It is a set of small fixes whose changes share a file, and the operator agreed to bundle them, since one plan drops per-item revert.
+
+- Write one file and one branch for the row, named for the shared surface
+- Give each item its own H3 under `## Files to touch`, holding the usual backticked-path bullets, since the parsers read the bullet and never the heading
+- Give each item its own `## Verification` bullet, so a dropped item is struck on the task file as `- ~~<outcome>~~ <reason>` and the rest ship as one pull request
+- Record the operator's agreement as an answered question in `## Questions`, and never bundle without one
+- Never bundle fixes with no file in common
+
 ### Staged batches
 
 A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `## Files to touch`. One plan filename derives one branch, so batches sharing a file have nothing to open a pull request against once the first merges.

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/plan-intake/references/intake.md

@@ -103,12 +103,12 @@ The index. It points at items and answers nothing itself.
 - The answer contract stated out loud, since it inverts the plan file's
 - A cluster table of file, what it holds, item count, and open count
 - The verdict counts across the folder
-- A ready list, grouped by what shipping one actually costs
+- A ready list with one row per fix, grouped by what shipping one actually costs, and a named bundle row that stands in for the rows of the items whose fixes share a file
 - The open questions, each a labeled markdown link to its owning item's heading anchor
 
 The index carries no answer slot. One question in two answerable places has no rule for which wins, and retrieval walks item headings, so an answer typed into the index is found by nothing and lost silently.
 
-Where an item touches a task already on the board, say so in the index rather than only inside the item. A reader deciding what to promote reads the index first.
+Only a shared file bundles, since separate branches on one file rebase on each other anyway. A small fix with nothing in common stays its own row, and a bundle has no cap on items. Where an item touches a task already on the board, say so in the index rather than only inside the item. A reader deciding what to promote reads the index first.
 
 ## Repro versus groundwork
 
@@ -236,6 +236,7 @@ date: <YYYY-MM-DD>
 ## Ready
 
 - <item, grouped by what shipping it costs>
+- Bundle <name>: <item>, <item>, sharing <file>, standing in for those items' own rows
 
 ## Open questions
 

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