@erclx/canon 5.12.0 → 5.14.0

package/docs/agents/index.md

@@ -36,6 +36,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
+- [The pull request frame store](pr-frames.md): How canon pr frames pushes a UI review frame to a never-merged branch through the GitHub API and returns a branch-path link, which ref it writes, the pass segment that keeps an earlier image fixed, the refusal reasons it names, and how --drop and --prune rewrite the branch so a dropped frame leaves history
 - [The pull request local preview](pr-local.md): How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow removes the link with --remove
 - [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs

package/docs/agents/markdown-audit.md

@@ -89,7 +89,7 @@ A hit the closed set could not separate from correct prose was the case with no
 
 Five surfaces apply the ban set and four of them go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, the `Markdown bans` stage in `canon gate run` runs it across the whole corpus before this repository's own push, and the same-named stage in the one verify runner every stack shares, `scripts/verify.ts`, runs it across a scaffolded project's tracked markdown before its own push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
 
-The seed copy moved onto the verb when the sets became data, since its awk had nothing left to parse. It resolves one runner where the toolkit copy resolves two, looking for no checkout source, and a machine carrying no `canon` gets a report naming the binary to install rather than a silent pass. `scripts/core/check-seed-independence.sh` scopes its walk to markdown and leaves the seed hooks outside it, which its own comment records as deliberate.
+The seed copy moved onto the verb when the sets became data, since its awk had nothing left to parse. It resolves one runner where the toolkit copy resolves two, looking for no checkout source, and a machine carrying no `canon` gets a report naming the binary to install rather than a silent pass. The Seed independence stage of `bun run check` scopes its walk to markdown and leaves the seed hooks outside it, which its own comment records as deliberate.
 
 The target push stage reads the same exit codes `canon gate run`'s own stage reads: 0 passes, 1 is a refusal logged as a skip, 2 is a finding, and 3 is a shipped-empty ban set. It skips and logs rather than failing when no `canon` binary is on the machine's PATH, since a scaffolded project is not guaranteed the toolkit is installed, and its skip line names the install command.
 

package/docs/agents/pr-evidence.md

@@ -83,6 +83,11 @@ them means the thread is read before the `no-evidence` answer too, so an
 unreadable thread refuses as `gh-failed` on both reasons rather than
 reporting the fields absent.
 
+`ok` also carries `states`, the comparison the body renders as data: each
+state's name and its items, each with its `path`, `stem`, and whether it was
+`added`. `review-ui` matches a frame against it so it publishes no image the
+worker's evidence already shows. `canon docs pr-frames` covers that store.
+
 ## What `[number]` selects, and what it does not
 
 Naming a number picks the pull request the whole record describes: its head

package/docs/agents/pr-frames.md

@@ -0,0 +1,112 @@
+---
+title: The pull request frame store
+description: How canon pr frames pushes a UI review frame to a never-merged branch through the GitHub API and returns a branch-path link, which ref it writes, the pass segment that keeps an earlier image fixed, the refusal reasons it names, and how --drop and --prune rewrite the branch so a dropped frame leaves history
+---
+
+# The pull request frame store
+
+`canon pr frames` gives a review comment an image it can embed. `review-ui`
+drives a pull request's checklist and captures a frame per box, and a frame
+on the reviewer's disk resolves for nobody else. The verb pushes one frame to
+the `canon-frames` branch and returns a link to its path there.
+
+```bash
+canon pr frames 1341 --add frames/3.png --box 3 --head <sha> --pass 20261002T154450Z --json
+canon pr frames 1341 --drop --json
+canon pr frames --prune 30 --json
+```
+
+## What it writes
+
+The verb writes `refs/heads/canon-frames` and no other ref. Every call goes
+through the GitHub git data API, being blobs, trees, commits, and that one ref,
+so nothing is checked out, no worktree is entered, and neither `main` nor any
+branch a pull request holds is touched. The branch never merges.
+
+A frame lands at `pr-<number>/<short-head>/<pass>/box-<n>.png`. `--head` names
+the commit the pass drove, 7 to 40 lowercase hex characters, and defaults to
+the head the pull request object reports. `--pass` is the instant the pass
+started, in compact UTC as `date -u +%Y%m%dT%H%M%SZ` prints it, which
+`review-ui` records once at its first step. A second pass at the same head and
+box therefore writes a new file rather than replacing the image an earlier
+comment shows, which matters when a preview is minted again at one head.
+
+`link` uses the same `blob/<ref>/<path>?raw=true` form as the evidence comment,
+naming the `canon-frames` branch rather than a commit. Every drop rewrites the
+branch, and a link pinned to a commit would stop resolving for every other pull
+request's frames once GitHub collects the commit it names. A path link lives
+exactly as long as its file, so it survives every rewrite that drops another
+pull request and ends only when its own is dropped.
+
+The first `--add` creates the branch with a root commit holding the
+frame, so a project needs no setup. An add only fast-forwards the ref. When
+another writer moved it between the read and the move, the add rebuilds on the
+new tip, up to three times, before refusing as `ref-conflict`.
+
+Only a frame of the address the pass drove belongs here. The branch is as
+public as the repository, so a frame of a private or pre-release state would
+be published with it.
+
+## What the record carries
+
+`reason` on the record is what a caller branches on, not the exit code:
+
+| Reason             | What it means                                                                    |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `ok`               | An add pushed, or a drop or prune finished, including one that removed nothing.  |
+| `bad-mode`         | Not exactly one of `--add`, `--drop`, `--prune`, or a number with `--prune`.     |
+| `no-number`        | `--add` or `--drop` named no pull request.                                       |
+| `bad-box`          | `--add` carried no positive `--box`.                                             |
+| `bad-head`         | `--head`, or the head the pull request reported, is not a 7 to 40 character sha. |
+| `bad-pass`         | `--add` carried no `--pass` stamp in compact UTC.                                |
+| `bad-days`         | `--prune` carried no positive number of days.                                    |
+| `unreadable-frame` | The `--add` file is missing, empty, or not a PNG. Nothing is called.             |
+| `read-only`        | GitHub refused a write with 403 or 404, which is what a fork's token gets.       |
+| `unreadable-tip`   | The branch exists and could not be read.                                         |
+| `push-failed`      | A write failed partway and the ref did not move.                                 |
+| `ref-conflict`     | Another writer kept moving the ref through every attempt.                        |
+| `no-object-head`   | No `--head` and the pull request reported none.                                  |
+| `gh-missing`       | `gh` is not on the path.                                                         |
+| `gh-failed`        | `gh` could not name the repository or read the pull request.                     |
+
+An add's `ok` record carries `link`, `commit`, `path`, `box`, `head`, `pass`,
+and `created`, which is true when the add made the branch. A drop's carries
+`removed`, the pull requests whose folders went, plus `commit` for the rewrite
+or `deleted` when it emptied the branch. A prune adds `kept` and `unread`.
+
+`review-ui` reads every reason but `ok` as a cue to describe the frame in words
+and name the reason, so a refused push never fails the pass.
+
+## Dropping frames
+
+A plain delete commit would keep every image reachable through history, so
+`--drop` and `--prune` write one root commit holding everything else and
+force-move the ref to it. A rewrite that leaves the branch empty deletes it,
+and the next add recreates it. Dropping a pull request with no frames, or on a
+missing branch, reports `ok` with nothing removed, so a scheduled run never
+fails on an empty branch.
+
+`--prune <days>` reads every `pr-<n>/` folder, asks GitHub for each pull
+request's state, and drops every one reading closed with a close date more
+than that many days ago, in a single rewrite. It keeps one still open, one
+reopened after closing, one closed exactly the given days ago, and one whose
+state could not be read, listing that last kind under `unread`.
+
+This repository runs `--prune 30` daily from
+`.github/workflows/pr-frames-cleanup.yml`. A frame's file stays on the branch
+until its own pull request has been closed for 30 days, so a link in a review
+comment keeps resolving for about a month after its pull request closes,
+whatever other pull requests the branch drops in between. A target project
+carries no such workflow yet and keeps its frames until someone runs `--drop`.
+
+## What a rewrite does not do
+
+A force-move leaves the old commits unreachable without purging them. GitHub
+serves an unreachable commit by sha until it collects it, so a dropped frame
+stays reachable to anyone holding a sha from an earlier record, and a frame
+holding sensitive content needs a purge request to GitHub. Its path link stops
+resolving at the drop, since the branch no longer carries the file.
+
+A drop racing an add can lose the add's frame, since GitHub's ref update has no
+compare-and-swap for a force-move. The drop builds from the tip it reads, and
+the window is the length of one rewrite.

package/docs/agents/pr-preview.md

@@ -14,6 +14,7 @@ rather than screenshots and a checklist alone.
 ```bash
 canon pr preview --json
 canon pr preview 1341 --json --timeout 20
+canon pr preview 1341 --check --json
 ```
 
 ## Which workflow it dispatches
@@ -61,22 +62,49 @@ keeps the match independent of the local clock.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
-| Reason        | What it means                                                              |
-| ------------- | -------------------------------------------------------------------------- |
-| `ok`          | The preview was published. `url` carries the address and `runId` the run.  |
-| `no-deploy`   | No dispatchable workflow runs `pages deploy`.                              |
-| `unfenced`    | The deploy passes no `--branch`, so nothing was dispatched.                |
-| `no-alias`    | The workflow prints no alias line, or the finished run's log carried none. |
-| `run-failed`  | The deploy run finished without succeeding. `runId` names it.              |
-| `timeout`     | The run did not finish inside `--timeout` minutes, 15 by default.          |
-| `bad-timeout` | `--timeout` was not a positive number.                                     |
-| `gh-missing`  | `gh` is not on the path.                                                   |
-| `gh-failed`   | `gh` could not read the pull request, or list or dispatch the workflow.    |
-| `no-branch`   | The pull request carries no head branch name.                              |
+| Reason          | What it means                                                              |
+| --------------- | -------------------------------------------------------------------------- |
+| `ok`            | The preview was published. `url` carries the address and `runId` the run.  |
+| `no-deploy`     | No dispatchable workflow runs `pages deploy`.                              |
+| `unfenced`      | The deploy passes no `--branch`, so nothing was dispatched.                |
+| `no-alias`      | The workflow prints no alias line, or the finished run's log carried none. |
+| `run-failed`    | The deploy run finished without succeeding. `runId` names it.              |
+| `timeout`       | The run did not finish inside `--timeout` minutes, 15 by default.          |
+| `bad-timeout`   | `--timeout` was not a positive number.                                     |
+| `gh-missing`    | `gh` is not on the path.                                                   |
+| `gh-failed`     | `gh` could not read the pull request, or list or dispatch the workflow.    |
+| `no-branch`     | The pull request carries no head branch name.                              |
+| `check-timeout` | `--check` was combined with `--timeout`.                                   |
 
 The exit is 0 on `ok` and 1 on every refusal. A `timeout` leaves the run
 going, so the preview may still land after the verb has given up on it.
 
+## Checking which head a preview was built from
+
+`--check` dispatches nothing and waits on nothing. It lists the branch's
+`workflow_dispatch` runs, takes the newest successful one by creation time, and
+compares the head it ran at with the branch tip read from the remote. The tip
+comes from the remote rather than the pull request object's `headRefOid`, which
+lags a push. `--check` takes no `--timeout` and refuses one as `check-timeout`.
+
+The alias serves the newest successful deployment for the branch and names no
+sha, so the run listing is the only record of the built head. The
+`workflow_dispatch` filter also drops the cleanup run a closed pull request
+fires, which concludes `success` with its deploy skipped. A project that deploys
+on `push` to a feature branch would need that filter widened.
+
+| Reason     | What it means                                                         |
+| ---------- | --------------------------------------------------------------------- |
+| `fresh`    | The newest successful deploy built the tip. Exit 0.                   |
+| `stale`    | It built an earlier head. `built` and `tip` name both. Mint again.    |
+| `building` | A deploy of the tip is still running. Wait rather than minting again. |
+| `no-build` | No deploy of the branch has succeeded.                                |
+
+The record also carries `runId` for the deploy it read. The check covers the
+hosted address only, so a local address has no run to read and stays unverified.
+`review-ui` runs it before driving a hosted preview and posts nothing on any
+reason but `fresh`.
+
 ## How the address reaches the pull request
 
 `canon pr evidence --preview <url>` puts `**Preview:** <url>` on the first line

package/docs/workflow/skill-map.md

@@ -38,18 +38,21 @@ This page is the corpus the coverage claim is measured against: every name `cano
 
 ## Build the feature
 
-| Skill                        | When to use                                                                                                |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `canon:session-worktree`     | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
-| `canon:auto-ship`            | After plan approval, to chain implement, verify, review, draft PR                                          |
-| `canon:project-commands`     | When the project's own command needs running                                                               |
-| `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor                            |
-| `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
-| `canon:api-design`           | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
-| `canon:review-craft`         | When reviewing a change, for what to look for and how much evidence a finding needs                        |
-| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
-| `canon:design-taste`         | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
-| `canon:ui-checklist`         | After a UI change, to write what to look at and name what ships untested                                   |
+| Skill                         | When to use                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `canon:session-worktree`      | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
+| `canon:auto-ship`             | After plan approval, to chain implement, verify, review, draft PR                                          |
+| `canon:project-commands`      | When the project's own command needs running                                                               |
+| `canon:test-first`            | Before implementing a planned change, to run its test red, green, then refactor                            |
+| `canon:test-craft`            | When writing or changing any test, to pick its layer and filter what it asserts                            |
+| `canon:build-in-slices`       | While building a plan, to commit each tested slice and note out-of-scope defects rather than fix them      |
+| `canon:api-design`            | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
+| `canon:deprecation-migration` | When deleting or replacing code something may still call, to migrate its callers and prove none remain     |
+| `canon:code-craft`            | Before writing a function, class, or module, to pick the shape the next change needs                       |
+| `canon:review-craft`          | When reviewing a change, for what to look for and how much evidence a finding needs                        |
+| `canon:systematic-debugging`  | When a test fails or a bug surfaces, to force root cause first                                             |
+| `canon:design-taste`          | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
+| `canon:ui-checklist`          | After a UI change, to write what to look at and name what ships untested                                   |
 
 ## Check the work before it leaves the branch
 

package/governance/rules/code/000-code.md

@@ -1,5 +1,5 @@
 ---
-description: Code placement, dependency, error, and naming choices a model does not make by default
+description: Code placement, shape, dependency, error, and naming choices a model does not make by default
 ---
 
 # Code standards
@@ -10,6 +10,10 @@ description: Code placement, dependency, error, and naming choices a model does
 - Prioritize native platform capabilities over third-party libraries.
 - Ensure data and configuration reside in designated Single Source of Truth locations.
 
+## Shape
+
+- Load the `canon:code-craft` skill before deciding the shape of a new function, class, or module, and report it rather than proceeding silently when it does not resolve.
+
 ## Errors
 
 - Return structured error types for recoverable failures.

package/package.json

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

package/src/claude/cases/misc.ts

@@ -74,6 +74,21 @@ export const MISC_CASES: readonly SkillCase[] = [
       "I'm adding a field to the JSON this command prints and renaming one flag, anything to watch?",
     expect: 'api-design',
   },
+  {
+    prompt:
+      'The same discount rule sits in two files and I need a third variant. Should I extract it, or add a strategy class for the two cases?',
+    expect: 'code-craft',
+  },
+  {
+    prompt:
+      "I've got the plan approved and it touches the parser, the command, and the docs. How should I build it so I don't end up with one giant diff?",
+    expect: 'build-in-slices',
+  },
+  {
+    prompt:
+      'The old parseDate helper was replaced months ago. Can I just delete it, or could a few files still be calling it?',
+    expect: 'deprecation-migration',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',

package/src/claude/skills-audit.ts

@@ -37,6 +37,9 @@ export const PRACTICE_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'review-craft'),
   join(SHIPPED_CORPUS, 'systematic-debugging'),
   join(SHIPPED_CORPUS, 'api-design'),
+  join(SHIPPED_CORPUS, 'code-craft'),
+  join(SHIPPED_CORPUS, 'build-in-slices'),
+  join(SHIPPED_CORPUS, 'deprecation-migration'),
 ]
 
 /** The closing H2s a practice skill carries, matched exactly outside fences. */