@erclx/canon 5.12.0 → 5.14.0

package/claude/skills/deprecation-migration/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: deprecation-migration
+description: Carries how a session retires a function, a flag, a field, a file, or a command without stranding whoever still calls it, from deciding whether to deprecate at all through proving no caller remains, migrating callers through an adapter or a strangler, and removing the old surface in its own change after the new one has carried every caller. Use when deleting or replacing code something may still call, when a deprecated path has lingered with no date, when finding dead or unowned code, or when asked "can I delete this", "how do I retire this", "how do I migrate callers off X", or "is anything still using this". Do NOT use to move or rename a file with no caller change, which is `codebase-layout`, to migrate a database schema, which the project's persistence rule governs, or to shape a new field or flag added beside an old one, which is `api-design`.
+---
+
+# Deprecation and migration
+
+A session asked to remove something tends to grep for its name, find nothing it recognizes, and delete it. What it misses calls the thing by a string, a config key, or a copy shipped somewhere the search never looked, and the first anyone hears of it is a break in a place the diff never touched. The reverse failure is as common: a replacement ships, the old path gets a deprecation note, and nobody ever moves the callers, so both live on with no owner. This skill carries the discipline that ends with the old surface gone and every caller working.
+
+Load it before deleting or replacing anything a caller outside the current change could reach. Skip it for code introduced on the same branch that nothing has shipped against yet.
+
+## Decide whether to deprecate at all
+
+Answer four questions before writing a deprecation notice, and keep the surface when the answers do not add up.
+
+- **What does keeping it cost?** Name the concrete cost, such as a duplicate path to test, a dependency that blocks an upgrade, or a behavior that confuses readers. "It is old" is not a cost.
+- **Who calls it?** Count the callers you can see and name the kinds you cannot, by the method in the zero-consumers section below.
+- **What replaces it?** A deprecation with no shipped replacement only tells callers they are on their own. Build the replacement first, or keep the old surface.
+- **Who migrates the callers?** Name an owner. A deprecation nobody owns stalls at the notice.
+
+## Choose advisory or compulsory
+
+- Start advisory: mark the surface deprecated, name the replacement, and leave it working. Callers move when they next touch the code.
+- Move to compulsory only once the replacement has shipped and a removal date is stated where a caller looks, such as the warning text, the changelog, or the docs page for the surface.
+- Make every warning actionable and well timed. Name the replacement and the change a caller makes, and raise it where the caller uses the old surface rather than in a log nobody reads.
+- Never leave an advisory deprecation open with no date and no owner. Either schedule the move to compulsory or withdraw the deprecation.
+
+## Migrate the callers yourself
+
+The owner of a surface moves its callers, the Churn Rule. Announcing a deprecation and waiting for callers to migrate pushes the work onto everyone downstream, and most of them never do it.
+
+- Migrate every caller you can reach in the repository you own, as part of the deprecation work rather than after it.
+- For a caller you cannot edit, such as another team's code or a published consumer, ship a backward-compatible path or migration notes they can apply, and track them as a caller still on the old surface.
+- Never add a feature to the deprecated surface. New behavior goes on the replacement, which gives callers a reason to move.
+
+## Prove zero consumers before removal
+
+A clean search for one spelling of the name proves only that this spelling is absent from the files searched. Check every caller kind before removing anything.
+
+- **Imports and direct calls**, including re-exports and aliases that call it by another name.
+- **String references**, such as a handler looked up by name, a command dispatched from a table, a reflection call, or a test fixture naming it.
+- **Configuration**, including build files, CI workflows, environment defaults, and data files that name the surface.
+- **Documentation and examples**, which callers copy from long after the code moves.
+- **Copies outside the repository**, such as a published package, an installed copy in another project, a shipped binary, a script someone runs from their own machine, or a saved request in an API client.
+
+Say which kinds your search could not reach and why, rather than reporting zero. "No callers in this repository, but a published release still exports it" is a finding a reader can act on, since it names where the remaining risk sits. A bare "no callers" is a guess.
+
+## Bridge with an adapter or a strangler
+
+- **Adapter.** Keep the old interface as a thin layer over the new implementation, so callers keep working while the implementation moves underneath them. The adapter holds no logic of its own and goes once its last caller moves.
+- **Strangler.** Route callers to the new path a group at a time, leaving the old path serving the rest. The old path is done when it serves nothing, and only then is it removed.
+- Prefer the adapter when the interface stays and the implementation changes. Prefer the strangler when callers have to change how they call.
+
+## Expand, migrate, contract as three changes
+
+Never add a replacement and remove the original in one change. Three separate changes keep every step reversible:
+
+1. **Expand.** Add the replacement beside the original. Both work, and nothing calls the new one yet.
+2. **Migrate.** Move callers to the replacement, in one change or several. The original still works for anything missed.
+3. **Contract.** Remove the original once the zero-consumers check passes, in a change of its own.
+
+Reverting any one step leaves a working tree. A change that expands and contracts together leaves no point where a missed caller still works, and reverting it reverts the migration too.
+
+This sits beside the One-Version Rule `api-design` states rather than against it. Two versions live only between the expand and the contract, and the migrate step moves every caller rather than splitting them between the two.
+
+## Treat zombie code as a decision to make
+
+Zombie code is unowned and uncalled yet still built, tested, and shipped. It costs build time and reader attention, and it hides which code is live.
+
+- Run the zero-consumers check on it like anything else, since "nothing calls it" is the claim to prove.
+- When the check comes back clean, remove it. With no replacement there is nothing to expand or migrate, so the removal runs alone as the contract change.
+- When something does still call it, it is not zombie code. Give it an owner, or deprecate it through the steps above.
+
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which external sources were adopted, which declined, and why.
+
+## Excuses and rebuttals
+
+| Excuse                                                   | Rebuttal                                                                                                                         |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| I searched for the name and nothing calls it             | A search finds one spelling in the files it read. A handler looked up by string, a config key, or a published copy stays hidden. |
+| I'll keep the fallback until callers move                | With no date and no owner, the fallback outlives every caller it was kept for. State when it goes and who removes it.            |
+| The callers can migrate when they get to it              | They will not. The owner of the surface moves its callers, or the deprecation never finishes.                                    |
+| It's cleaner to add the new one and drop the old one now | One change that adds and removes leaves no state where a missed caller still works, and a revert undoes the migration too.       |
+| This only matters on one machine                         | One caller is still a caller. Migrate it, or record it as the reason the old path stays.                                         |
+| Nobody owns this, so I can just delete it                | No owner is not no caller. Run the zero-consumers check before deciding, since unowned code is often the code nobody dares move. |
+| I'll mark it deprecated and move on                      | A notice with no shipped replacement and no removal date tells callers nothing they can act on.                                  |
+
+## Red flags
+
+- You are about to delete a surface after one search for its exact name.
+- A deprecation notice names no replacement or no removal date.
+- The diff adds a replacement and deletes the original in the same change.
+- A fallback or compatibility path has no stated condition for its removal.
+- You are adding behavior to the surface being deprecated.
+- Your report says "no callers" without naming the caller kinds the search could not reach.
+- A caller outside the repository was found and the plan still deletes the original.
+
+## Before handing over
+
+Check each line against what the change produced. A line answering no is fixed or reported, never left with a note.
+
+- The surface is deprecated only if it has a stated cost, a shipped replacement, and a named owner.
+- Every compulsory deprecation states its removal date where a caller looks.
+- Every caller reachable in the repository was migrated, or is named with the reason it was not.
+- The zero-consumers check covered every caller kind, and the report names the kinds it could not reach.
+- No change both adds the replacement and removes the original.
+- Every fallback left in place states when it goes and who removes it.
+
+## What this delegates
+
+- Adding a field, flag, or parameter beside an old one, and the One-Version Rule for a surface callers cannot pin: `api-design`
+- Moving or renaming a file with no caller change, and where a replacement file sits: `codebase-layout`
+- Database schema changes and their migrations: the project's persistence rule
+- Sequencing expand, migrate, and contract into committed slices on one branch: `build-in-slices`
+- Listing the consumers a finished change breaks, during review: `review-craft`

package/claude/skills/deprecation-migration/references/adopted.md

@@ -0,0 +1,50 @@
+---
+title: Adopted and declined
+description: Which external sources on deprecation and migration this skill adopted, which it declined, and why, so a later session extends the position instead of re-deriving it
+---
+
+# Adopted and declined
+
+External sources were read and filtered rather than imported. This file is the record. A later session extending the skill adds to it rather than re-arguing an item already settled here.
+
+## Adopted
+
+### From the default shelf
+
+**Deprecation.** [Software Engineering at Google, chapter 15](https://abseil.io/resources/swe-book/html/ch15.html). Adopted from it:
+
+- Advisory and compulsory deprecation as the two types, with compulsory carrying a removal date. The body allows compulsory only once a replacement has shipped, which the chapter implies and the four questions make explicit.
+- Warnings that are actionable and relevant: a warning names what the caller does, and surfaces where the caller uses the old surface.
+- Deprecation as a process with an owner, since the chapter observes that unowned deprecation work makes no progress. Adopted as the fourth decision question and the rule against an advisory deprecation left open with no owner.
+- Finding consumers before removal, which the chapter does with static analysis across one repository. Generalized into the zero-consumers check across caller kinds, since a target project rarely has a whole-company code index and its callers often live outside the repository.
+
+**The Churn Rule.** [Software Engineering at Google, chapter 1](https://abseil.io/resources/swe-book/html/ch01.html), under "Policies That Don't Scale": 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.
+
+### The decision and the bridges
+
+**Deprecation and migration.** 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). Adopted from it:
+
+- The five-question deprecation decision, cut to four. Its unique-value and maintenance-cost questions merge into one question about what keeping the surface costs. Its per-consumer migration-cost question drops, since the Churn Rule puts that cost on the owner rather than weighing it per caller. The owner question from the book takes the freed place.
+- The rule never to deprecate without a replacement, as the third decision question.
+- The strangler and adapter patterns, stated as when each fits rather than as worked code tied to one stack.
+- Expand, migrate, contract, lifted out of its schema section and stated for any surface as three separate changes.
+- Zombie code, narrowed to code that is unowned, uncalled, and still built, and settled by the same zero-consumers check rather than a list of staleness signals.
+- The rationalizations and red flags that carry across stacks, reworded for any surface rather than a service or a column. Two excuse rows come from here:
+  - The row on a search that found nothing, from its red flag against removing code without verifying zero active consumers.
+  - The row on adding the new one and dropping the old one now, generalized from its rationalization about adding a column and dropping the old one in the same migration.
+
+## Declined
+
+**Its database schema section.** The column rename worked example, the tested down path, batched backfills, and concurrent index builds. Declined because a project's persistence rule owns schema changes, and restating them here puts two owners on one rule. Only the expand, migrate, contract shape was lifted, generalized beyond schemas.
+
+**Feature flag migration.** Declined because it is one way to run a strangler, and naming a flag mechanism ties the body to a runtime a target may not have.
+
+**The traffic percentages in its strangler phases.** Declined because they describe a service behind a router, and most surfaces a session retires, such as a function, a flag, or a file, have callers rather than traffic.
+
+**"Default to advisory" as a standing default with no exit.** Kept advisory as the starting state, and declined leaving it open, since an advisory deprecation with no date and no owner is the stalled case the body exists to prevent.
+
+**The thresholds in its zombie signs and rebuttals.** No commits in six months, and comparing costs over two or three years. Declined for the same reason the body states no deprecation window: a number fits one project's cadence and not another's.
+
+**"Code is a liability" and design-time deprecation planning as sections.** Declined as framing a session already accepts by loading the skill. The cost question carries the first, and designing a new surface for removal belongs to the skill shaping that surface.
+
+**The celebration step and the deprecation notice template.** Declined because neither changes what a session does, and the template's example names a package runner and a migration script tied to one stack.

package/claude/skills/git-followup/REQUIREMENT.md

@@ -21,6 +21,7 @@ A fix commit answering a review is the sharpest case of the first paragraph, sin
 - Sync the body when the new commit moves the scope, and the title when the shift makes it inaccurate
 - Reply on the pull request when it carries review comments, and scan that reply for the banned characters and internal phase labels before posting. The hook watches files and never sees a comment body on its way to the remote.
 - Suppress the reply when the caller owns it, and still run the push and the body sync
+- Read `canon pr evidence <number> --check --json` after posting the evidence and mint the preview when it is owed, since a followup that posts the evidence and stops leaves the preview for a relay
 - Force the push under a lease when the tracking branch no longer reaches the head, so a caller's rebase lands and a commit this session never read is not overwritten
 
 ## Must not

package/claude/skills/git-followup/SKILL.md

@@ -33,6 +33,9 @@ A missing tracking ref is no longer a guard. An open pull request proves the bra
    - `no-evidence`: nothing changed under an `evidence/` segment this push. Say nothing and move on.
    - `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post the comment with `gh pr comment <number> --body-file <main-root>/.canon/tmp/pr/evidence/body-<number>.md` when the record carries no `commentId`, or edit the existing one in place with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md` when it does. Clean up the tmp file only after the call reports success.
    - Any other reason is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-changes`, `would-empty`). Report it and continue without stopping the chain.
+
+   After an `ok` post, read what the pull request is still owed with `canon pr evidence <number> --check --json`, branching on `reason` and `owed` rather than the exit. When `owed` lists `preview`, mint it through the preview section of `canon:git-pr`'s `references/evidence.md`, then re-read once. Report anything but `settled` after that re-read and continue, since a refused deploy would otherwise loop. A binary lacking `--check` reports the thread unread rather than settled. A preview already on the comment counts as settled whatever head built it, so a later push does not re-mint one.
+
 6. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
 7. Sync the body and title on every invocation, before the routing below decides on the reply.
    - Run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.

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

@@ -28,6 +28,7 @@ A lookup that resolves by head branch alone carries its own failure. A branch na
 - Label from the paths the branch changed, against a map the project declares, so the label set belongs to the project rather than to the skill
 - Apply labels after the pull request exists, so a label the remote does not carry costs a warning rather than the pull request
 - Report a refused label, since a warning nothing surfaces leaves the run indistinguishable from one that labelled
+- Run the evidence verb on every pull request the skill opens, and let its `no-evidence` answer be the skip, since a session cannot see a regenerated image it did not author and a gate asking it to look lets that image ship with no comment
 - Put a preview address on a pull request that changes a rendered surface when the project's deploy can mint one, since screenshots and a checklist leave a reviewer nothing to click into before merging
 - Bound the wait on that preview and finish the chain without the link on a timeout, since a slow deploy must not hold the ship
 - Put the branch's running local server on the same pull request when this worktree is serving one, and remove it when the pull request closes, since a reviewer on the operator's machine can interact with the branch and a link that outlives it points at whatever runs there next

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

@@ -152,7 +152,7 @@ The last output line carries `head=` so a caller relaying the number holds a bra
 
 ### Post the rendered-surface evidence
 
-Skip this step silently when no UI checklist sits at `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root and the diff changes nothing under an `evidence/` segment, since neither half then has anything to post. Otherwise read `${CLAUDE_SKILL_DIR}/references/evidence.md` for finding the checklist and the local server, posting the evidence comparison, posting the checklist alone, and posting the preview address, each against the `<number>` the final command printed.
+Run this step on every pull request this skill opens or edits. Read `${CLAUDE_SKILL_DIR}/references/evidence.md` for finding the checklist and the local server, posting the evidence comparison, posting the checklist alone, and posting the preview address, each against the `<number>` the final command printed. Never judge from the diff whether an evidence image changed, since the verb answers `no-evidence` for a branch that changed none and a session cannot see an image it did not author.
 
 ### Record the number on the task
 

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

@@ -5,7 +5,7 @@ description: How git-pr finds the UI checklist and the local server, posts the e
 
 # Rendered-surface evidence
 
-The rendered-surface step of `git-pr`, reached after the final command printed the pull request number. The session reads this file when a UI checklist exists or the diff changes a path under an `evidence/` segment.
+The rendered-surface step of `git-pr`, reached after the final command printed the pull request number. The step runs on every pull request, with no test on the diff ahead of it. `no-evidence` is the silent branch, so a pull request that changes no rendered surface posts nothing.
 
 ## Find the UI checklist
 
@@ -92,7 +92,7 @@ Deleting the file is what makes the later re-render safe. `git-followup` re-runs
 
 ## Post the preview address
 
-Run this step only when the evidence step above returned `ok` or a checklist was posted by the fallback. Either one means the pull request changes a rendered surface, and a reviewer holding a checklist with no screenshots needs the live page most. Otherwise skip it silently.
+Run this step when the evidence step above returned `ok`, a checklist was posted by the fallback, or `canon pr evidence <number> --check --json` lists `preview` in `owed`. The first two mean the pull request changes a rendered surface, and a reviewer holding a checklist with no screenshots needs the live page most. The third is how `git-ship` reaches this step alone when an earlier run's deploy timed out, so no evidence step ran in the current one. Otherwise skip it silently.
 
 The evidence comment is already posted, so the reviewer has the screenshots while the deploy runs. Mint the preview against the same `<number>`:
 

package/claude/skills/git-ship/REQUIREMENT.md

@@ -17,10 +17,12 @@ The sequence also reaches the remote on work nothing re-checked. This skill is t
 - Say so and continue when the project names no verify command, since silence there reads as a suite that passed
 - Invoke each step through the Skill tool in the stated order and continue without waiting
 - Stage after the sync skills write, so what they produced reaches a commit
+- Reach the pull request on a branch whose work is already committed and whose sync steps wrote nothing, since `git-stage` stops on an empty index and a session building in slices leaves one
 - Emit no text between steps. The sequence is the unit and prose inside it reopens settled decisions.
 - Name the one point a wrapping caller may act at, so a chain built on this one is not left to pick a gap of its own
 - Name the condition under which the closing block is not emitted, since a caller that closes on its own block leaves two instructions about the last line and nothing deciding between them
 - Watch continuous integration to a terminal state in the background, so the session stays reachable while CI runs, and stop on a failure naming the check
+- Read the evidence thread with `canon pr evidence <number> --check --json` once CI passes, run what it reports owed, and report done only on `settled`, since a chain that never reads the thread ships a regenerated image with no comment and no preview and leaves the controller to repair it
 - Stop memory work at the Propose phase
 
 ## Must not
@@ -35,6 +37,8 @@ The sequence also reaches the remote on work nothing re-checked. This skill is t
 ## Guards
 
 - A failing verify stops the run before the sync skills write, so the tree is left as the user left it
+- A binary lacking `--check` reports the thread unread, never settled, since reading the absence as a pass repeats the failure the read exists to close
+- Re-read the thread once after running what was owed and stop on anything but `settled`, so a refused preview cannot loop the chain
 - A failing check stops the sequence. A stop report and the line announcing the background watch are the two places text is allowed between steps.
 
 ## Out of scope

package/claude/skills/git-ship/SKILL.md

@@ -28,7 +28,7 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 3. Invoke `canon:docs-sync` to sync public docs against changes since main
 4. Run `git add -A` to stage any files the sync skills wrote
 5. Run `canon tasks plan-reach <plan> --json` and report both lists it carries. Name the plan this branch built under, by path or by slug. Read `claimed` first and say who holds each path, since that is the half a reader acts on, then say how many of the changed paths `undeclared` names. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero. This step reports and never stops the sequence.
-6. Invoke `canon:git-stage` to group staged changes and commit by concern
+6. Invoke `canon:git-stage` to group staged changes and commit by concern, only when `git diff --cached --name-only` prints a path. When it prints nothing, the work already reached history in slices, so continue to step 7.
 7. Invoke `canon:git-branch` to rename branch to match conventional format
 8. Invoke `canon:git-pr` to push branch and open pull request
 9. After the PR opens, watch CI in the background, so the session stays reachable while CI runs. Read `### Watching CI` below for the commands and the wake.
@@ -49,7 +49,7 @@ Emit `⏳ Watching CI on #<number> in the background` and end the turn. Print no
 
 On the wake, branch on the final record's fields rather than on the exit:
 
-- `state: passing`: continue to After completion.
+- `state: passing`: read the evidence thread under `### Settling the evidence thread` below, then continue to After completion on `settled`.
 - `state: failing`: stop the sequence and report the failing check with its URL.
 - `conflicted: true`: stop the sequence and report that the branch conflicts with its base, since no run will start for it. A rebase is the repair.
 - A `reason` and no `state`: the read was refused, such as `no-remote-branch` for a branch deleted on the remote. Stop and report that `reason`. A missing `state` is never a pass.
@@ -58,6 +58,17 @@ On the wake, branch on the final record's fields rather than on the exit:
 
 Do not auto-fix any of these. The watch line and a stop report from any branch above are the two exceptions to the no-text-between-steps rule.
 
+### Settling the evidence thread
+
+On a `passing` wake, run `canon pr evidence <number> --check --json` against the number step 8 returned. It reads the pull request's comments and edits none, so the comment a reviewer already ticked stays as it is. Branch on `reason` and `owed` rather than the exit.
+
+- `settled`: nothing is owed, which is also what a branch that changed no rendered surface reads. Continue to After completion.
+- `owed`: run each step the record's `owed` list names, from `canon:git-pr`'s `references/evidence.md`, evidence first and then preview. Re-read once with the same command. Continue to After completion only on `settled`. Any other reading stops the sequence and reports the `reason` with the `owed` list, and the sequence never loops back for a second pass. A preview step that refuses, or a deploy that failed, leaves `preview` owed on the re-read, so that is the stop and not a retry.
+- Any other `reason`, such as `gh-failed`: the thread went unread. Stop and report the `reason`, since an unread thread is not a settled one.
+- No record at all, or an unknown flag error: the installed binary predates `--check`. Report the thread unread rather than settled, and continue to After completion without emitting a claim that it was checked.
+
+The read is a closing step and the draft mark stays the only thing between steps 8 and 9. A caller that closes on its own block, as `auto-ship` does, waits on the same CI wake, so the read lands here and not in that body.
+
 ### Why the reach reads at step 5
 
 The branch is whole there and nowhere earlier. Steps 2 and 3 write past whatever the plan declared, so a reading taken ahead of them misses the chain's own additions, and no pull request exists until step 8 to carry the answer anywhere.

package/claude/skills/review-craft/REQUIREMENT.md

@@ -13,6 +13,8 @@ The miss is measured. On a seeded branch that deleted a dirty-tree guard while t
 
 Rendered output is the larger hole. `git-pr` posts an `## Evidence` comment through `canon pr evidence`, carrying base and head screenshots and a checklist a reviewer ticks. The pull request review named that heading only in its heading set, and no step opened an image. On a seeded pull request whose narrow head screenshot shows the navigation running off the edge while a ticked box claims it collapses, the review filed the finding off the stylesheet diff and said it had not rendered the page. On a styling change with no screenshot at all, on a project whose trunk keeps them, it did not mention the absence.
 
+A dependency upgrade is not a measured miss. On 2026-10-02 a seeded branch bumped one dependency across a major version beside a second, with a lockfile adding a transitive package that carried an install script, and the body without a dependency reference reported it. The run that measured it passed every assertion, including a graded finding naming the upgrade, so the case is a floor and no reference exists for it. An earlier run matched only a loose pattern and left no report to read, so it counts for nothing. The security reference still had no threat-model step and no class for a delete or clean on a derived path, both groundwork lifts with no miss to measure.
+
 The axes also said nothing about a change that passes by lowering the bar it has to clear, such as a test skipped, a threshold moved, or a path excluded from a checker, nothing about performance, and one sentence about design with no procedure behind it. A refactor that only moved complexity read as a design gain, and a removal could call code dead without reading why it was added. The body carried no excuses, red flags, or closing checklist, so a session about to stop at the hunk met no answer first.
 
 ## Must
@@ -27,6 +29,7 @@ The axes also said nothing about a change that passes by lowering the bar it has
 - State a design finding as a concrete cost, so it survives the procedure's filter against subjective suggestions
 - Carry the evidence bar: confirm against the file at the reviewed head, quote a cited rule, name the breaking input, and drop what a gate owns or what rests on unread state
 - Carry security as classes with an exclusion list, in a reference loaded when the diff reaches one
+- Open the security reference with a threat model drawn from the diff, and carry destructive operations on a derived path as a class, so a cleanup deleting an unchecked variable's glob is read for the empty-value collapse
 - Open the evidence images on a rendered change through `git show` at the row's own sha, never through the embedded address, within a stated read budget
 - Test each ticked checklist box against an opened image, and name a ticked box no image covers as untested
 - Flag a rendered change that carries no screenshot, as a finding where the trunk already keeps them and as a question elsewhere

package/claude/skills/review-craft/SKILL.md

@@ -36,7 +36,7 @@ An axis whose condition the diff meets is not optional. When the security or the
 
 Read each of these when the diff reaches what it names.
 
-7. **Security.** Read `${CLAUDE_SKILL_DIR}/references/security.md` when the diff runs a command, writes a file, handles input from outside the process, touches a secret, adds a dependency, or changes a default a consumer installs.
+7. **Security.** Read `${CLAUDE_SKILL_DIR}/references/security.md` when the diff runs a command, writes or deletes a file, handles input from outside the process, touches a secret, adds a dependency, or changes a default a consumer installs.
 8. **Rendered output.** Read `${CLAUDE_SKILL_DIR}/references/ui.md` when the diff touches a file that paints, such as markup, a stylesheet, a component, a template, or a design token, or when the pull request carries an evidence comment. A finding read off a stylesheet diff says what the author changed, and only the screenshot says what a user sees, so the reference opens the images and checks whether any exist.
 9. **Developer experience and operations.** Ports, hooks, scripts, config, and scaffold defaults a consumer installs. A new required step nobody documented, a default that fails on a clean machine, or a hook that slows every commit is a finding even when the code is correct.
 10. **Executable prose.** A skill body, a rule, or a prompt is instructions a model runs. Read it the way you read code: a step that races another, a precondition it never states, a branch with no exit, and two instructions that contradict each other are bugs.

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

@@ -34,6 +34,10 @@ From `addyosmani/agent-skills@2686b620`, `skills/constraint-driven-development/S
 
 From `addyosmani/agent-skills@2686b620`, `skills/code-review-and-quality/SKILL.md` for the axis itself, a call inside a loop and an unbounded fetch, and `skills/performance-optimization/SKILL.md` for keep or revert: measure before and after the same way, and a neutral result argues for removing the added complexity. The repeated-run requirement against noise is stated here so one run on each side reads as an anecdote.
 
+### Security additions
+
+From `addyosmani/agent-skills@2686b620`, `skills/security-and-hardening/SKILL.md`: the threat model first and the derived-path rule. Adopted as the opening step of `references/security.md`, which names who supplies each input and what the code can reach before any class is read, and as the destructive-operations class, which asks for the empty-value collapse, the glob or symlink escape, the missing root check, and no read of what is there before the call. Both stay stack-neutral. No red run measures them, so they ship as lifts rather than as an answer to a miss.
+
 ### Closing sections
 
 The excuses, red flags, and closing checklist follow the practice skill shape every practice skill in this toolkit carries, taken from `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md). Each excuse row rebuts a reason a review stops at the hunk, such as passing tests against a test the diff skipped, rather than an objection nobody raised.
@@ -46,4 +50,8 @@ The excuses, red flags, and closing checklist follow the practice skill shape ev
 
 **Named structural remedies as a catalog.** A list of refactorings to propose reads as a menu a session fills in. A design finding states the cost, and the remedy is the author's.
 
+**A dependency upgrade reference.** From `addyosmani/agent-skills@2686b620`, `skills/code-review-and-quality/SKILL.md`: read the changelog across the range, one dependency per change, and the lockfile diff. Declined because the seeded upgrade is not a miss. The body without such a reference reported the planted major bump and the install script in the lockfile on the second of two runs, which passed the assertion naming them. Revisit when a run on a changed lockfile misses what a reference would have named.
+
+**STRIDE and abuse-case tests as a procedure.** They belong to a design session rather than a diff read, and the threat-model opening in the security reference takes the one step a diff supports, naming who supplies each input.
+
 **The web and database tables from `performance-optimization`.** They name a stack, and the axis stays stack-neutral until a target asks for a per-stack reference.

package/claude/skills/review-craft/references/security.md

@@ -2,10 +2,15 @@
 
 Read each class against the diff. A class the diff does not reach is skipped, not reported as clean. Name the input that reaches the sink and the path it takes, since a class named with no path is a suspicion rather than a finding.
 
+## Open with the threat model
+
+Before the classes, name from the diff who supplies each input and what the code can reach with it: a file, a process, a network, a credential. Skip a class that model rules out, and say which one and why, so the skip reads as a decision rather than an oversight.
+
 ## Classes to check
 
 - **Shell and command injection.** A value from an argument, an environment variable, a file, or a network response reaching a shell: through `eval`, an unquoted expansion, a string built into a command, or a subprocess call that takes a single command string. Quoting the variable at the call site is the fix to look for.
 - **Path traversal in a file write.** A path built from outside input and written without being resolved and checked against the directory it must stay inside. A `..` segment, an absolute path, and a symlink inside the target each escape a naive join.
+- **Destructive operation on a derived path.** A delete, overwrite, move, or clean whose path is built from a variable, a config value, or a listing. Look for the empty or unset value that collapses it to a root, a glob or a symlink that carries it outside the folder it was meant for, no check that the resolved path sits at least one level below an expected root, and no read of what is there, owned by this tool or not, before the call. The fix to look for is resolve, require the root, then act. A write escaping its folder is path traversal. When a finding fits both, name the class whose fix applies.
 - **Secrets and personal data leaving the process.** A token, a key, a password, or personal data reaching a log line, an error message, a session transcript, a published page, a pull request comment, or a sync to a remote. Check what a debug line prints and what a verbose flag adds.
 - **Supply chain.** One-shot package execution of an unpinned version, which runs whatever the registry serves that day. A new dependency, and what its install scripts run. A lockfile that changes without a manifest change.
 - **Time of check to time of use on a file write.** An existence or permission check followed by a write to the same path in a later step, and a predictable name in a shared temporary directory. Another process can swap the path in between.

package/claude/skills/review-ui/REQUIREMENT.md

@@ -18,11 +18,14 @@ A verdict also goes stale without saying so. A push after the pass changes what
 - Drive every checklist box in the running app and give each exactly one verdict: pass or fail read off the page with the value quoted, pass or fail against a frame with what it shows, needs eyes for a box marked as taste, or not driven with the reason
 - Drive a box written before the drivable format all the same, naming the route or width it guessed, so no box is skipped silently
 - Read the checklist and the address from the evidence record rather than from the diff, the plan, or the author's description
+- Drive only a build of the head the verdict names, and stop with nothing posted when the hosted preview was built from an older one
 - Take the hosted preview, then the local preview, then an address the launch names, and refuse when none exists
 - Report an address that does not answer as not driven rather than as a fail, and leave the review closed on a box no commit on the branch can settle, so an absent preview never holds the draft mark at every head
 - Sweep console errors, sideways overflow at each named width, and the focus and details probes over the states reached, and nothing beyond them
 - Post its own comment as a pull request review under `## UI review` while anything is owed and `## UI review closed` once nothing is, ending on a marker naming the head it drove
-- Describe each frame in words in the evidence and cite no path, since a path under `.canon/` fails the label scan the review-event run applies to the posted body
+- Embed a frame only for a state the worker's evidence record lacks, pushed through `canon pr frames` to a branch that never merges and linked by its path there under this pass's own stamp, so the image lasts until its own pull request is dropped and no later pass replaces it, and cite the evidence stem for a state the record already shows, so the review adds no image the worker's evidence already carries
+- Push only a frame of the address the pass drove, since the branch is as public as the repository
+- Describe a frame in words when the push refuses, naming the reason, and cite no local path, since a path under `.canon/` fails the label scan the review-event run applies to the posted body
 - Read the review-event checks for the head after the post, bounded, and report a failure in the result line, or the checks as unread when they never settle
 - Report the heading it posted by reading the posted file's first line, so the result line and the body come from one source
 - Name the renderer the browser reported, and render on the GPU only when the launch names a config for it
@@ -54,4 +57,5 @@ A verdict also goes stale without saying so. A push after the pass changes what
 - Writing the checklist and its drivable format, which `ui-checklist` owns
 - Dispatching the pass, polling its verdict, and lifting the draft mark, which `role-orchestrator` owns
 - A subagent inside the code reviewer, dropped because its cost stays invisible until it returns
-- Hosting frames where a reader on another machine can open them, since the reviewer holds no upload route and writes no tracked file
+- Writing a tracked file or checking anything out to host a frame. The push goes through the GitHub API onto the frames branch alone, so the reviewer still enters no worktree and touches no branch a pull request holds.
+- Dropping a closed pull request's frames, which a scheduled workflow runs, and purging a dropped frame GitHub still serves by commit, which needs a platform request

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

@@ -21,11 +21,12 @@ rather than inside it, so the two passes finish on their own clocks.
 - No address resolves under Step 3: stop and post nothing, `❌ No address to drive. PR #<number> carries no preview and no local preview, and the launch named none.`
 - The wrapper refuses to open the browser because its revision is absent: stop and post nothing, passing its install command to whoever launched the pass. Never install mid-pass.
 - The newest UI verdict is `## UI review closed` at the current head: stop, `The UI review already covers <short-sha>.` An open verdict at the head stops the same way only when nothing has arrived since it: drive again when a `## Review response` or `## Post-review findings` comment is newer than the verdict, or the launch names an address.
+- The hosted preview was not built from the head: stop and post nothing, naming `built`, `tip`, and `canon pr preview <number> --json` for the dispatcher. A verdict posted against an older build carries a marker naming a head nobody drove.
 - Post and stop. Never merge, never tick a box on the evidence comment, and never lift the draft mark.
 
 ## Step 1: resolve the pull request
 
-Resolve the number with `gh pr view --json number,headRefName,headRefOid`, or take the one the launch names. Take `<head>` off `canon pr head <number> --json`, reading its `tip`, and fall back to `headRefOid` when no record comes back. The first seven characters are `<short-sha>`.
+Resolve the number with `gh pr view --json number,headRefName,headRefOid`, or take the one the launch names. Take `<head>` off `canon pr head <number> --json`, reading its `tip`, and fall back to `headRefOid` when no record comes back. The first seven characters are `<short-sha>`. Record `<pass>` once, as the instant this pass starts, with `date -u +%Y%m%dT%H%M%SZ`. Every frame Step 5 pushes files under it, so a later pass at the same head never replaces an image this one's comment shows.
 
 Read the newest UI verdict for the head guard:
 
@@ -43,7 +44,7 @@ Read nothing else about the change. The diff, the plan, the task, and the descri
 canon pr evidence <number> --json
 ```
 
-Take three fields off the record, each present only when the posted evidence comment holds it: `checklist`, `preview`, and `local`. They come from the comment already on the thread, so `reason` reading `ok` or `no-evidence` makes no difference here, and the rendered `body` is not this pass's to read. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero. Only `ok` and `no-evidence` read the thread. Every other `reason` is a refusal that never reached the comment, so report it verbatim and stop rather than reading the missing fields as an absent checklist.
+Take three fields off the record, each present only when the posted evidence comment holds it: `checklist`, `preview`, and `local`. They come from the comment already on the thread, so `reason` reading `ok` or `no-evidence` makes no difference here, and the rendered `body` is not this pass's to read. Keep `states` as well when `reason` reads `ok`, being each evidence state's name and the stems under it, which Step 5 matches a frame against. A record carrying no `states`, on `no-evidence` or from an older binary, covers no state, so every frame is pushed. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero. Only `ok` and `no-evidence` read the thread. Every other `reason` is a refusal that never reached the comment, so report it verbatim and stop rather than reading the missing fields as an absent checklist.
 
 A binary older than 5.4.0 reports none of the three fields whatever the thread holds, so a record carrying none is ambiguous. Read `canon --version` before taking the no-checklist stop, and on an older release report the release this pass needs and stop rather than parsing the comment by hand.
 
@@ -55,6 +56,16 @@ Take the first rung that answers, testing each with `curl -s -o /dev/null -w '%{
 2. The `local` address off the record.
 3. An address the launch names.
 
+When the hosted rung answers, check that it was built from the head before driving it:
+
+```bash
+canon pr preview <number> --check --json
+```
+
+Branch on the record's `reason`. Only `fresh` continues. Any other stops with nothing posted, naming `built`, `tip`, and the next act: `stale` and `no-build` ask the dispatcher to run `canon pr preview <number> --json`, and `building` asks it to wait, since a mint is already running for the tip. This pass never mints. A `canon` that rejects `--check` predates the verb. Report that this pass needs a `canon` whose `pr preview` takes `--check`, naming the installed `canon --version`, and stop rather than reading the missing flag as `fresh`, the way Step 2 does for its own older binaries. A `reason` of `no-deploy`, `unfenced`, or `no-alias` means the project has no fenced deploy to read, so the hosted build cannot be verified. Stop on the hosted address then too, and say so.
+
+The check covers the hosted address only. The local rung and an address the launch names have no deploy run to read, so say in the comment that they were driven unverified rather than implying the same coverage.
+
 An address that exists and does not answer is a different outcome from no address at all. When every rung that exists fails to answer, skip the drive, record each box as not driven with the addresses tried and what each returned, and go to Step 7. A local address on another machine is the usual cause, and it says nothing about the change.
 
 ## Step 4: open the browser
@@ -75,6 +86,14 @@ Give every box exactly one verdict, in checklist order. A box the pass could not
 
 Never judge a box ending in `(taste)`. Drive to the state, capture the frame, and mark it needs eyes. Drive a ticked box the same as an unchecked one, since a tick is the author's claim and this pass exists to check it.
 
+A frame the verdict rests on is published only when the worker's evidence lacks it. Compare the box's route, width, and theme against the `states` Step 2 kept, and when a state and stem show the same thing, cite that stem and push nothing. The match is this pass's judgment over the box's wording, so the verb never makes it. Otherwise push the frame and keep the `link` the record returns:
+
+```bash
+canon pr frames <number> --add frames/<box-number>.png --box <box-number> --head <head> --pass <pass> --json
+```
+
+Push only a frame of the address this pass drove, since the branch is as public as the repository. Branch on `reason` rather than on the exit code. Every reason but `ok` is a refusal, `read-only` among them on a fork's token, so describe that frame in words and name the reason in its evidence rather than failing the pass.
+
 ## Step 6: sweep
 
 Run three checks over every route the boxes reached, and nothing beyond them:
@@ -89,7 +108,7 @@ Close the browser with `${CLAUDE_SKILL_DIR}/scripts/pw.sh -s=<project>-<number>
 
 ## Step 7: post
 
-Read `${CLAUDE_SKILL_DIR}/references/post.md` for the heading rule, the body shape, the marker every body ends on, and the post command.
+Read `${CLAUDE_SKILL_DIR}/references/post.md` for the heading rule, the body shape, the marker every body ends on, and the post command. Each Evidence cell embeds the `link` its Step 5 push returned, as given, or names the evidence stem it matched.
 
 ## Step 8: read the review-event checks
 
@@ -119,4 +138,4 @@ Add `S sweep finding(s).` when the sweep raised any. Report no merge recommendat
 - Drive the checklist and the sweep, and nothing else. Open exploration has no end a dispatcher can predict.
 - Never check out, build, or serve the head. An address is handed to this pass or the pass refuses.
 - Never read a value off the snapshot file whole. Search it for the ref a box needs, and read text, styles, and geometry with `eval`.
-- Write only under `.canon/tmp/pr/review-ui/`, at the main worktree root.
+- Write only under `.canon/tmp/pr/review-ui/`, at the main worktree root, and to the frames branch through `canon pr frames`, which goes through the API and checks nothing out.

package/claude/skills/review-ui/references/driving.md

@@ -41,10 +41,12 @@ Each box takes exactly one.
 | Verdict             | When                                                    | Evidence it carries                                                                                                          |
 | ------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | pass or fail, read  | The result is a fact the page reports                   | The value read, quoted, such as `scrollWidth 436 against clientWidth 320`                                                    |
-| pass or fail, frame | The result has a stated criterion only an image settles | What the opened frame shows, in words, with no path                                                                          |
-| needs eyes          | The box ends in `(taste)`                               | What the frame showed, in words, and nothing about whether it looks right                                                    |
+| pass or fail, frame | The result has a stated criterion only an image settles | The pushed frame's link or the matching evidence stem, and what the frame shows, in words                                    |
+| needs eyes          | The box ends in `(taste)`                               | The pushed frame's link or the matching evidence stem, and what the frame showed, with nothing about whether it looks right  |
 | not driven          | The state could not be reached                          | The reason, such as an unreachable address, a `(local only)` box on a hosted preview, or a target the snapshot does not hold |
 
-A frame cannot be attached to a review comment and the reviewer writes no tracked file, so a frame verdict describes the value or region it judged in words and cites no path. A path under `.canon/` is a board identifier the label scan rejects, and it resolves only on this machine. The description carries what the frame held, such as the element, its position, and the colors or text read, so the person merging can check it without the image.
+A frame verdict carries one image at most, and never one the worker's evidence already shows. When a state and stem in the evidence record match the box's route, width, and theme, the evidence names that stem and nothing is pushed. Otherwise the frame goes up through `canon pr frames` and the evidence carries the `link` the record returned, which names the frame's path on the frames branch. Either way the words stay, describing the value or region judged, such as the element, its position, and the colors or text read, so a reader whose image fails to load can still check it.
+
+A push that refuses leaves the words alone, with the reason named. Never cite the local frame path. A path under `.canon/` is a board identifier the label scan rejects, and it resolves only on this machine.
 
 A fail names what was expected beside what was read. A not driven never reads as a fail, since it says the pass could not look rather than that the page is wrong. Its reason says whether the cause sits on the page or off it, since only a cause on the page opens the heading Step 7 picks.

package/claude/skills/review-ui/references/post.md

@@ -28,7 +28,8 @@ P passed, F failed, E need eyes, N not driven. Drove <address> at <short-sha>, r
 | Box                                | Verdict    | Evidence                                      |
 | ---------------------------------- | ---------- | --------------------------------------------- |
 | 1. <the box as written, shortened> | fail       | <the value read against what the box expects> |
-| 2. <box>                           | needs eyes | <what the frame showed, in words, no path>    |
+| 2. <box>                           | needs eyes | ![](link) <what the frame showed, in words>   |
+| 3. <box>                           | pass       | Evidence `<stem>` <what it showed, in words>  |
 
 **Sweep**
 
@@ -43,7 +44,7 @@ P passed, F failed, E need eyes, N not driven. Drove <address> at <short-sha>, r
 <!-- review-ui: head=<head> -->
 ```
 
-A frame cannot be attached and a path under `.canon/` is a board identifier the label scan rejects, so the Evidence cell describes what the frame showed in words and cites no path. Say plainly that the frame is not published where a reader could open it.
+An Evidence cell resting on a frame takes one of three forms. A frame Step 5 pushed embeds as `![](<link>)`, with the link exactly as `canon pr frames` returned it. It names the frame's path on the frames branch, which stays put while other pull requests' frames are dropped and carries this pass's stamp, so a later pass never changes the image. A state the worker's evidence already shows names the evidence stem in backticks and embeds nothing, since the evidence comment carries that image. A push that refused leaves the words alone and names the reason. Never cite the local frame path, since a path under `.canon/` is a board identifier the label scan rejects.
 
 A pass where every box needs eyes and nothing else is owed takes the closed heading:
 

package/claude/skills/role-worker/REQUIREMENT.md

@@ -52,5 +52,6 @@ The draft mark fails from both ends. On 2026-08-31 four sessions re-drafted a pu
 
 - Entering the worktree, which `session-worktree` owns
 - The chain from implement through pull request, which `auto-ship` owns
+- How the build moves through the plan, slice by slice with a commit each, which `build-in-slices` owns
 - Answering a posted review, which `review-address` owns
 - The controlling session's half of the channel, the review poll, and the watch beside it, which `role-orchestrator` and its runbooks hold

package/claude/skills/role-worker/SKILL.md

@@ -20,6 +20,10 @@ from the skill that owns it and invoke none of the three from here. The ordinary
 path arrives through `auto-ship` Step 0, which means that chain is already
 running and re-invoking it would restart the build.
 
+This body holds what the session may write. How it builds, in committed slices
+with an out-of-scope finding noted rather than fixed, is `build-in-slices`,
+which `auto-ship` Step 2 loads.
+
 ## Where the session stands
 
 - Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, `.canon/memory/`, and `.canon/ready/` at the main worktree root, never against the linked worktree this session builds in. Those folders are gitignored, so `git worktree add` never creates them and the copy beside the build is absent rather than empty.

package/claude/skills/test-first/REQUIREMENT.md

@@ -14,6 +14,7 @@ Without this skill, a session implementing a planned change writes the test afte
 - Write or extend the test before the implementation it covers, for any behavior whose shape is already known
 - Run the test before implementing and confirm it fails for the missing behavior, not for an unrelated mistake in the test itself
 - Implement the minimum the current test demands, and start a new test before extending past it
+- Load `canon:code-craft` before writing the implementation when its shape is still open and the session has not loaded the skill, so the shape of the code is settled before the body rather than during refactor
 - Re-run the test after implementing and confirm the pass is the one the test was written to prove
 - Refactor the implementation and the test once the suite is green, re-running it after each change, since the smallest change that passes leaves duplication and shortcuts the loop exists to remove before they reach history
 
@@ -33,4 +34,6 @@ Without this skill, a session implementing a planned change writes the test afte
 - Choosing the layer a test belongs at and judging whether it is a good test: `canon:test-craft`, loaded at step 1 rather than restated here
 - Finding the cause of an unexplained failure: `canon:systematic-debugging`
 - Confirming visual output after a change lands: `567-planning.md` states the order and `ui-checklist` writes the list to confirm against
+- Shaping the function, class, or module the implementation writes: `canon:code-craft`, loaded at step 4 rather than restated here
+- Committing the behavior as a slice and ordering the slices of a larger build: `canon:build-in-slices`
 - The mechanical audit of whether an implementation reached history ahead of its test: `canon gov test-order`, invoked from `auto-ship`

package/claude/skills/test-first/SKILL.md

@@ -10,7 +10,7 @@ description: Write the failing test for a behavior before writing the code that
 1. Load `canon:test-craft` and pick the layer the test belongs at before writing it. Then find or write the test at that layer before touching the code it covers. Follow the pairing convention the project already uses, which is commonly a test sitting beside its subject under one name, so that `foo.ts` takes `foo.test.ts` beside it. Report it rather than proceeding silently when `canon:test-craft` does not resolve, and write the test at the smallest layer that can observe the behavior.
 2. Write the test against the behavior as it should exist once the change lands, naming the case for what it proves rather than for the function it calls.
 3. Run only that test and read the failure. Confirm it fails because the behavior is missing, not because of a typo, a missing import, or a signature the test itself got wrong. A test failing for the wrong reason still reads green the moment any code exists to satisfy that wrong reason, so treat any other failure as a defect in the test and fix the test before moving on.
-4. Implement the smallest change that turns the failure into a pass. Do not add behavior the test does not ask for. A second behavior wants its own test written first, not a shortcut folded into the change already open.
+4. Load `canon:code-craft` and settle the shape of the code before writing it, unless the shape is already fixed or this session already loaded the skill. Report it rather than proceeding silently when `canon:code-craft` does not resolve, and write the plainest code the test asks for. Then implement the smallest change that turns the failure into a pass. Do not add behavior the test does not ask for. A second behavior wants its own test written first, not a shortcut folded into the change already open.
 5. Run the test again and confirm it passes for the reason it was written for, not by accident. Then run the surrounding suite so a change made to satisfy this test has not broken another.
 6. Refactor with the suite green. Remove the duplication and the shortcuts step 4 left, in the implementation and in the test, without changing what either does. Run the suite after each change, and undo a change that turns anything red rather than fixing forward.
 
@@ -23,4 +23,5 @@ description: Write the failing test for a behavior before writing the code that
 
 - Which layer a test belongs at and what makes it a good one. `canon:test-craft` owns that judgment, and step 1 loads it.
 - A failure with no known cause. Route through `canon:systematic-debugging` first, whose own fix phase already writes the reproducing test as part of finding the cause. This skill starts once the shape of the fix or the feature is already decided.
+- Committing the green, refactored behavior as one slice of a larger build. `canon:build-in-slices` owns the commit and the order slices land in.
 - Confirming a change looks right once it has landed, which is a separate concern from whether the test passed and runs after implementation rather than before it.

package/docs/agents/commands.md

@@ -103,7 +103,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `worktrees`, in `worktrees.md`: `list`, `reclaim`
 - `hooks`, in `hooks.md`: `post-merge`
 - `autoship`, in `review-classification.md`: `classify`
-- `pr`, in `pr-reads.md`: `key-changes`, `head`, `checks`, `review-state`, `evidence`, `preview`, `local`
+- `pr`, in `pr-reads.md`: `key-changes`, `head`, `checks`, `review-state`, `evidence`, `preview`, `local`, `frames`
 - `audits`, in `audits.md`: `run`, `list`
 - `gate`, in `gate.md`: `run`
 - `secrets`, in `state-scoped-risk.md`: `scan`