@erclx/canon 4.97.0 → 4.99.0

package/README.md

@@ -1,3 +1,7 @@
+<div align="center">
+
+<img src="assets/brand/mark-accent.svg" alt="canon" width="56" height="56">
+
 # canon
 
 [![npm version](https://img.shields.io/npm/v/@erclx/canon)](https://www.npmjs.com/package/@erclx/canon)
@@ -6,17 +10,13 @@
 
 canon is a CLI and Claude Code plugin that stops your AI conventions drifting apart across repositories. It keeps one authoritative copy and installs it into each project on demand.
 
-![The canon catalog, listing skills, governance rules, and standards with the count each ships, the workflow skills named, and a sample of the rule and standard names](assets/evidence/hero.png)
-
-The counts above are read from the catalogs when the image is built, so they're what the repo actually ships today. See it live at [canon.erclx.dev](https://canon.erclx.dev).
-
-## It runs on itself
+**[See it run at canon.erclx.dev](https://canon.erclx.dev)**
 
-The workflow this toolkit ships is the workflow that built it. Several Claude Code sessions run at once, each in its own git worktree on its own branch, and each opens its own pull request.
+</div>
 
-![The canon landing page's session list, with the orchestrator pinned above bands of working and completed sessions, workers and planners in both, each naming what it is doing and the pull request it opened, and one row moving from Working into Completed](demos/agent-view.gif)
+![The first screen of the canon landing page, a project before and after one canon init, with the file counts each step lays down](assets/evidence/arrival.png)
 
-That is the landing page's own agent view, recorded from a local build by `canon demo run`. The session rows behind it are a real `canon sessions list --json` read. The activity text and the pull request number are transcribed, because no verb here reports either.
+The page is one real session the toolkit ran on itself, and every count on it is read from the repo when the page builds.
 
 ## Why
 
@@ -53,35 +53,37 @@ bun install --global @erclx/canon
 
 ## What is inside
 
-Each domain has a canonical source in this repo and a thin install or sync CLI on your side.
+Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The domains split on one line: some are copied into your project and become yours to edit, and some are never copied at all.
 
-- Claude Code plugin: skills that plan a feature, review a diff, sync the planning docs, and run the ship chain from branch through pull request
-- Governance rules: coding and authoring rules that load into a Claude session when a matching path is edited, installed per project and refreshed by sync
-- Standards: authoring conventions for commits, branches, plans, tasks, and markdown, read by name with `canon standards <name>` rather than copied into your project
-- Snippets: reusable prompts fired by `@` reference in a Claude Code session, resolved live from the plugin with no install step
-- Tooling stacks: golden configs, seeds, and a reference per framework, laid down by `canon init` and reconciled by `canon tooling sync`
-- Design system: a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command
-- Slides: a `SLIDES.md` source format with a layout catalog, rendered to PowerPoint by `canon slides render`
-- Transcripts: `canon transcripts` pulls a YouTube transcript with metadata frontmatter into any repo
-- Sandbox: scenario-based scaffolds that provision an isolated project state for verifying each domain flow
+| Domain         | What it is                                                                                                               | How it reaches you                                              |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain                                | Loaded live from the plugin, never copied                       |
+| Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                                | Installed per project by `canon gov install`, refreshed by sync |
+| Standards      | Authoring conventions for commits, branches, plans, tasks, and markdown                                                  | Opened by name, read by name with `canon standards <name>`      |
+| Snippets       | Reusable prompts fired by `@` reference                                                                                  | Resolved live from the plugin                                   |
+| Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
+| Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
+| Slides         | A `SLIDES.md` source format with a layout catalog                                                                        | `canon slides render` writes PowerPoint                         |
+| Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
+| Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                               | `canon sandbox`                                                 |
 
-Those domains split on one line: some are copied into your project and become yours to edit, and some are never copied at all.
+![The canon catalog as a ledger of five rows, with the count each ships and a few real names: skills, rules, standards, commands, and stacks](assets/evidence/catalog.png)
 
-![canon tooling list and canon standards list side by side, the first showing five stacks with their dependency and script counts, the second showing standards against the artifact each governs](assets/evidence/install-surface.png)
+Every count in that image is read from the catalogs when it is built, so they're what the repo ships today. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one. Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
 
-A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one.
+Two of the outputs are documents you open rather than files you run. A `SLIDES.md` renders to a deck, and a learning workspace renders to a small site.
 
-Governance is the third shape, and it is worth seeing rather than reading about, because the glob beside each rule is what decides whether it reaches a session at all.
+![A slide from the showcase deck rendered by canon slides render, a bulleted list under a heading on a dark warm background](examples/slides/evidence/showcase-dark-04.png)
 
-![canon gov list, showing seven stacks with the rules each carries and a sample of rules beside the path glob that loads each one](assets/evidence/governance.png)
+![The learning workspace listing rendered by canon teach, three workspaces with their lesson and term counts, one still a stub](examples/teach/evidence/root-listing.png)
 
-Stacks compose, so a react project inherits node and node inherits base. A rule with a glob loads only when a matching path is edited, and a rule with none loads every session. Both counts and every row above are read from the catalogs when the image is built.
+## It runs on itself
 
-The toolkit tracks its own work the same way, in a task board no catalog can read back.
+The workflow this toolkit ships is the workflow that built it. Several Claude Code sessions run at once, each in its own git worktree on its own branch, and each opens its own pull request.
 
-![the task board's Run now table, one row per task in flight, each naming the files it touches and the plan it runs under](assets/evidence/task-board.png)
+![The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened](demos/agent-view.gif)
 
-`.canon/tasks/` is gitignored session scratch, so unlike the two frames above, this one is a hand-taken snapshot rather than something the build reads live, and it goes stale the moment the board moves.
+That recording is the landing page's own `dispatch` and `workers` sections, driven by `canon demo run` against a local build. The branch graph beside the pull request numbers is authored rather than read, because nothing on a build machine records which files four sessions held.
 
 ## Documentation
 

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.97.0",
+  "version": "4.99.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -117,13 +117,15 @@ The verb reads git history rather than the working tree, so a branch with nothin
 
 The verb ships with the CLI and this body ships with the plugin, matching Step 6's own fallback for the classify verb. Report that the check did not run rather than reading a missing subcommand as clean, and continue to Step 5.
 
-## Step 5: UI test (conditional)
+## Step 5: UI checklist (conditional)
 
-If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:ui-test`.
+If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:ui-checklist`.
 
-If `ui-test` produces a manual checklist, stop: `❌ UI requires visual verification. Checklist at .canon/tmp/handoff/ui-checklist/<slug>.md, which reaches the pull request once /git-ship runs. Verify manually, then run /git-ship.`
+If `ui-checklist` produces a checklist, stop: `❌ UI requires visual verification. Checklist at .canon/tmp/handoff/ui-checklist/<slug>.md, which reaches the pull request once /git-ship runs. Verify manually, then run /git-ship.`
 
-If all UI changes are covered by tests, continue.
+The stop is unchanged by that skill's shrink. The checklist is now the step's whole output rather than the visual remainder beside the tests it wrote, so the stop is the only thing that makes the operator look before `git-ship`.
+
+If there is nothing to verify visually and nothing shipping untested, continue.
 
 ## Step 6: review
 

package/claude/skills/draft-and-pick/REQUIREMENT.md

@@ -28,6 +28,7 @@ Without this skill, a session facing a decision nobody can settle from a diff:
 - Names no layer at all, since the instruction to name one carries no catalog to name from and nothing reports the omission. Four consecutive rounds against one page each varied a property at the top layer while the defect sat two below it, and three of the four changed nothing the operator could see.
 - Judges a lower layer through a finished higher one, so an operator asked about composition looks at the palette instead and answers about that.
 - Hands over the combined page alone for a decision about layout, where every arm sits in a column while the media queries answer to the whole window, so no arm is ever seen at its own viewport and a fault that appears only narrower survives the pick.
+- Rebuilds a navigation harness by hand on a run with several rounds, since each round writes its own folder and nothing reaches all of them from one address. Two design tracks hand-wrote the same page picker and theme toggle.
 - Sets the theme on an arm that persists its own and reads it back on load, so the control reports one theme while the arm renders the other and the set is compared across two.
 
 ## Must
@@ -38,6 +39,7 @@ Without this skill, a session facing a decision nobody can settle from a diff:
 - Grey-box the set when the declared layer sits below typography, and say the set is grey-boxed when handing it over, so the operator reads a flat page as the question rather than as unfinished work.
 - Render every arm in one theme at a time, with a control that sets the whole set, so the comparison holds still while the operator reads it, and set the theme in a way that survives an arm reading its own stored preference back on load.
 - Hand over the per-arm file addresses beside the combined page where the declared layer is composition, layout or space, since only a whole-page file at a real viewport answers how an arm behaves at a width, and the browser's own device toolbar is the control.
+- Write a frame from `references/frame.html` where the run has several rounds, so a picker reaches every round from one address. The frame carries no width control of its own.
 - Judge each render against a stated bar before handing it over, name the weakest thing on the page, and fix it where that sentence would embarrass the work.
 - Write each iteration to its own folder rather than narrowing the previous one in place, so every earlier round stays openable.
 - Write the run's renders inside the record that cites them wherever one exists, and reserve the scratch path for inputs that are re-runnable and cited by nothing.
@@ -66,7 +68,7 @@ The refusal strings sit in the body, since the runtime loads that file and ignor
 - `plan-feature` plans the work once the answer is settled, and declares the pull request boundary its plan carries. This produces the answer to pick from and stops before the plan.
 - `ux-audit` reads source to find roughness and reports it. This takes its input from the operator and changes nothing until they pick.
 - `ux-measure` measures what a running interface costs to paint. This measures whatever a visual claim depends on, which is usually geometry or contrast rather than cost.
-- `ui-test` writes tests for a change already made. This runs before there is a change to test.
+- `ui-checklist` writes what to look at on a change already made. This runs before there is a change to look at.
 - `draft-screencast` scripts a recording of something already built. This has nothing built yet.
 - `canon capture`, `canon serve`, and `canon drive` own the render, the address, and the probes, and are invoked rather than reimplemented.
 

package/claude/skills/draft-and-pick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: draft-and-pick
-description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write tests for a change already made, which is `ui-test`, to script a recording, which is `draft-screencast`, or to inspect a running app across many findings, which is `ux-walkthrough`.
+description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write what to look at on a change already made, which is `ui-checklist`, to script a recording, which is `draft-screencast`, or to inspect a running app across many findings, which is `ux-walkthrough`.
 ---
 
 # Draft and pick
@@ -31,6 +31,7 @@ Write every arm side by side on one self-contained HTML page at `<dest>/candidat
 - Label each arm on the page with its id and its cost, so the render carries what the question will ask about.
 - Give the combined page one control that sets every arm's theme at once, beside whatever per-arm control the arms carry. A set spanning both themes cannot be compared, since the operator has to toggle each arm and hold the earlier ones in memory, which is the failure the single-page rule exists to prevent.
 - Set that theme so it survives the arm reading its own preference back. An arm that stores a theme and applies it on load will overwrite whatever the control set, which shows the control in one state and the arm in the other, and it passes a fresh browser profile because the stored value is not there yet.
+- Write `<dest>/frame.html` from `${CLAUDE_SKILL_DIR}/references/frame.html` where the run has more than one round, and hand over its address beside the combined page. Replace the template's one data token with the JSON object its comment describes, listing the combined page and every per-arm file of this round and each earlier one, with each `src` relative to the frame and `themeKey` set to the key the arms read their theme from. The frame is the route to every round from one address, with a page picker and the global theme toggle. Earlier rounds are sibling folders, so serve the parent folder with `canon serve <parent> --entry <dest-name>/frame.html` rather than `<dest>`, and keep the per-arm files as the fallback where nothing is served.
 - Hand over the per-arm file addresses beside the combined page where the declared layer is composition, layout or space, and say that an arm is judged at a width by opening its own file in the browser's device toolbar. The combined page cannot answer that question at all: every arm sits in a column there while the media queries answer to the whole window, so each one renders its widest layout in a narrow space no matter how the window is sized. Build no width control of your own, since the browser already has one.
 - Take the live-app branch instead when the surface under decision is a running app: lift the rendered markup and link a copy of the built stylesheet rather than inlining, per `${CLAUDE_SKILL_DIR}/references/live-arms.md`.
 - On the default path, inline every style, script, and asset the page needs. The render reads the file off disk, so a page reaching for a build step or a network font renders without it and the arms differ by something nobody chose.
@@ -70,7 +71,7 @@ Put the choice to the operator through the structured question surface, since a
 ## Step 5: loop on the pick
 
 1. Write each iteration to its own `<dest>` rather than narrowing the previous one in place, suffixing the slug so the folders sort. An iteration overwritten is one a later pass cannot open, and the losing round is what stops a correction re-proposing something already rejected.
-2. Write fresh arms off the pick and return to Step 2 where the correction opens a new question. Revise the one arm where it does not.
+2. Write fresh arms off the pick and return to Step 2 where the correction opens a new question. Revise the one arm where it does not. Each pass through Step 2 rewrites the frame with every earlier round's arms, since the list is baked in when the frame is written.
 3. Re-render, hand off again, and take the next answer.
 4. Repeat until the operator says it is right. The loop stops on their word and on nothing else, so a run stopping because the arms stopped differing has stopped early.
 5. Hold the real surface untouched across every iteration. Nothing outside the run's own folders changes until the pick is final.

package/claude/skills/draft-and-pick/references/frame.html

@@ -0,0 +1,118 @@
+<!doctype html>
+<html lang="en" data-theme="light">
+  <head>
+    <meta charset="utf-8" />
+    <title>Draft and pick frame</title>
+    <style>
+      :root {
+        --bg: #f4f4f5;
+        --fg: #18181b;
+        --bar: #ffffff;
+        --line: #d4d4d8;
+      }
+      :root[data-theme='dark'] {
+        --bg: #18181b;
+        --fg: #f4f4f5;
+        --bar: #27272a;
+        --line: #3f3f46;
+      }
+      * {
+        box-sizing: border-box;
+      }
+      body {
+        margin: 0;
+        height: 100vh;
+        display: flex;
+        flex-direction: column;
+        background: var(--bg);
+        color: var(--fg);
+        font-family: system-ui, sans-serif;
+        font-size: 14px;
+      }
+      header {
+        display: flex;
+        gap: 12px;
+        align-items: center;
+        padding: 8px 12px;
+        background: var(--bar);
+        border-bottom: 1px solid var(--line);
+      }
+      select,
+      button {
+        font: inherit;
+        color: inherit;
+        background: var(--bg);
+        border: 1px solid var(--line);
+        border-radius: 4px;
+        padding: 4px 8px;
+      }
+      main {
+        flex: 1;
+        overflow: auto;
+        display: flex;
+        justify-content: center;
+        padding: 12px;
+      }
+      iframe {
+        width: 100%;
+        height: 100%;
+        border: 1px solid var(--line);
+        background: #fff;
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <label
+        >Page
+        <select id="picker"></select
+      ></label>
+      <button id="theme" type="button">Theme: light</button>
+      <span>F12 device toolbar to resize</span>
+    </header>
+    <main><iframe id="page" title="Candidate page"></iframe></main>
+    <!-- The skill replaces the token below with one JSON object: {"themeKey": "<key the arms read>", "rounds": [{"label": "...", "pages": [{"label": "...", "src": "<path relative to this file>"}]}]} -->
+    <script type="application/json" id="frame-data">
+      __FRAME_DATA__
+    </script>
+    <script>
+      const data = JSON.parse(document.getElementById('frame-data').textContent)
+      const picker = document.getElementById('picker')
+      const themeButton = document.getElementById('theme')
+      const frame = document.getElementById('page')
+      let theme = 'light'
+
+      for (const round of data.rounds) {
+        for (const page of round.pages) {
+          const option = document.createElement('option')
+          option.value = page.src
+          option.textContent = round.label + ' · ' + page.label
+          picker.append(option)
+        }
+      }
+
+      // A page that stores its own theme and reads it back on load overwrites the
+      // attribute alone, so write the stored key as well as the attribute.
+      function applyTheme() {
+        document.documentElement.dataset.theme = theme
+        themeButton.textContent = 'Theme: ' + theme
+        try {
+          const win = frame.contentWindow
+          win.document.documentElement.setAttribute('data-theme', theme)
+          win.localStorage.setItem(data.themeKey, theme)
+        } catch {}
+      }
+
+      picker.addEventListener('change', () => {
+        frame.src = picker.value
+      })
+      themeButton.addEventListener('click', () => {
+        theme = theme === 'light' ? 'dark' : 'light'
+        applyTheme()
+      })
+      frame.addEventListener('load', applyTheme)
+
+      if (picker.options.length > 0) frame.src = picker.value
+    </script>
+  </body>
+</html>

package/claude/skills/draft-ready/SKILL.md

@@ -73,7 +73,7 @@ Write `<main-root>/.canon/tasks/<label>-<slug>.md` by heredoc, from the label St
 canon tasks plan-link <task-stem> .canon/plans/feature-<slug>.md --json
 ```
 
-Branch on the record rather than on the exit. `Ready:` is defined nowhere yet, so the line orients a worker reading the task and no check reads it.
+Branch on the record rather than on the exit. The `Ready:` line orients a worker reading the task, and `canon tasks archive` reads it to move the folder on ship.
 
 A task file with no row is a dropped task, so place the row in the same pass. The plan exists, so the row takes `## Run now` when `canon tasks plan-reach` reports nothing claimed and `## Up next` otherwise, with the held path in its `Waiting on` cell, per the tests in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`. Check the roster the way `canon:task-board` Step 4 does, reading `canon sessions list --self --json` for this session and `canon sessions list --json` for a row from the same repository, under another `sessionId`, whose `name` starts with `orchestrator-`. Treat a refused read as a roster read that failed.
 
@@ -106,10 +106,10 @@ Fix what the records name in the files this run wrote and re-run once. Report a
    Plan: .canon/plans/feature-<slug>.md
    Task: .canon/tasks/<label>-<slug>.md
    Row: <label> <title>, <written under ## Run now | reported to <orchestrator name> | left for the operator to place>, <reason>
-   Archive on ship: move the folder to .canon/ready/archive/<nn>-<slug>/ by hand, then retarget the task's Ready: line
+   Archive on ship: canon tasks archive moves the folder to .canon/ready/archive/<nn>-<slug>/
 ```
 
-Name the archive move every time. `canon tasks archive` moves the task and its plan and leaves the folder live, so the move is the one step this run leaves for whoever ships.
+Name the archive move every time, so whoever ships knows the verb carries the folder and needs no step of their own.
 
 ## Rules
 

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

@@ -152,54 +152,72 @@ rm -rf .canon/tmp/pr/body
 printf 'number=%s\nurl=%s\n' "$pr_number" "$pr_url"
 ```
 
-### Post the UI checklist
+### Find the UI checklist
 
-`ui-test` writes a manual checklist to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This step is the file's sole consumer. Resolve the main root the way `session-worktree` does (`git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`) and check for the file there. A missing file means no checklist was produced, and there is nothing to post.
+`ui-checklist` writes a visual checklist to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill is the file's sole consumer. Resolve the main root the way `session-worktree` does (`git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`) and check for the file there. A missing file means no checklist was produced, and the two steps below each skip their checklist half.
 
-When it exists, scan it against `${CLAUDE_SKILL_DIR}/../../standards/publish.md` before posting, the same as the pull request body above. Post it as its own comment on `<number>`, the number the final command above resolved, rather than folding it into the body, since a later push editing the body would overwrite checkboxes a reviewer already ticked:
+When it exists, scan it against `${CLAUDE_SKILL_DIR}/../../standards/publish.md` before either step posts it, the same as the pull request body above.
+
+Where it lands is decided by the evidence step below rather than here, since a checklist reads next to the screenshots it annotates and posting it on its own is the fallback for a branch that changed no screenshot.
+
+### Post the evidence comparison
+
+Run the verb once against the number the pull request step above resolved, passing `--checklist` when the step above found a file and leaving it off when it did not:
 
 ```bash
-gh pr comment <number> --body-file <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
+canon pr evidence <number> --checklist <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md --json
 ```
 
-Run the cleanup below only once that call reports success. On a failure, stop and leave the file in place: a retry needs the checklist to still be there, and deleting it on a failed post loses the only copy with nothing landed on the pull request.
+One call answers both questions because a checklist does not decide `no-evidence`. The verb reports `no-evidence` on a diff carrying no evidence image whether or not a checklist came with it, so the branch below reads the same `reason` it would have read without the flag, and the checklist is folded in only on the path that has a comparison to fold it into.
 
-From a linked worktree the file-editing tools refuse a main-root path, so the cleanup goes out through `Bash` as two plain commands, the file and then the folder, rather than joined by `&&`, which is refused as compound:
+Pass `--checklist` only for a file that exists. The verb refuses as `unreadable-checklist` on a path it cannot read or one holding nothing, which is a caller bug rather than a transient failure, so stop and repair the path rather than posting a body with the checklist silently dropped.
+
+Read `reason` on the record rather than the exit code.
+
+- `no-evidence`: nothing changed under an `evidence/` segment, so there is no comparison to post and no body was rendered. Say nothing about the evidence and fall through to the checklist step below.
+- `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post or update the comment:
 
 ```bash
-rm <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
+gh pr comment <number> --body-file <main-root>/.canon/tmp/pr/evidence/body-<number>.md
 ```
 
+When the record carries a `commentId`, edit that comment in place instead of posting a second one, reading the body field from the tmp file with `@`:
+
 ```bash
-rmdir <main-root>/.canon/tmp/handoff/ui-checklist 2>/dev/null || true
+gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md
 ```
 
-The `rmdir` is a no-op when another branch's pending checklist still sits in the folder, which keeps this step from deleting a handoff that is not its own.
+Delete the handoff file once that call reports success, per the cleanup below, since the checklist now lives on the pull request. Clean up the tmp body file the same way.
 
-### Post the evidence comparison
+Any other `reason` is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-tree`, `unreadable-changes`). Report it and move on without stopping the chain: a branch that carries no evidence images most of the time should not fail here on a transient git or `gh` read. Fall through to the checklist step, which posts the checklist alone rather than losing it to a transient read.
 
-Run `canon pr evidence <number> --json` against the number the pull request step above resolved. Read `reason` on the record rather than the exit code.
+### Post the UI checklist alone
 
-- `no-evidence`: nothing changed under an `evidence/` segment. 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 or update the comment:
+Run this step only when the evidence step above did not carry the checklist, meaning it reported `no-evidence` or one of the git refusals, and a checklist file exists. Post it as its own comment on `<number>`:
 
 ```bash
-gh pr comment <number> --body-file <main-root>/.canon/tmp/pr/evidence/body-<number>.md
+gh pr comment <number> --body-file <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
 ```
 
-When the record carries a `commentId`, edit that comment in place instead of posting a second one, reading the body field from the tmp file with `@`:
+Run the cleanup below only once the call that carried the checklist reports success, whichever of the two steps that was. On a failure, stop and leave the file in place: a retry needs the checklist to still be there, and deleting it on a failed post loses the only copy with nothing landed on the pull request.
+
+From a linked worktree the file-editing tools refuse a main-root path, so the cleanup goes out through `Bash` as two plain commands, the file and then the folder, rather than joined by `&&`, which is refused as compound:
 
 ```bash
-gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md
+rm <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
 ```
 
-Clean up the tmp file the way the UI-checklist step does, only after the call reports success.
+```bash
+rmdir <main-root>/.canon/tmp/handoff/ui-checklist 2>/dev/null || true
+```
 
-Any other `reason` is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-tree`, `unreadable-changes`). Report it and move on without stopping the chain: a branch that carries no evidence images most of the time should not fail here on a transient git or `gh` read.
+The `rmdir` is a no-op when another branch's pending checklist still sits in the folder, which keeps this step from deleting a handoff that is not its own.
+
+Deleting the file is what makes the later re-render safe. `git-followup` re-runs `canon pr evidence` with no `--checklist`, and the verb carries the checklist forward out of the comment it is editing, so the boxes a reviewer already ticked survive the push.
 
 ### Post the preview address
 
-Run this step only when the evidence step above returned `ok` or the UI checklist step posted a comment. 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 only when the evidence step above returned `ok` or a checklist was posted, by either step. 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.
 
 The evidence comment is already posted, so the reviewer has the screenshots while the deploy runs. Mint the preview against the same `<number>`:
 
@@ -250,9 +268,11 @@ Add a further line only when the labelling command printed its warning, quoting
 
 `⚠️ Labels not applied: <what gh reported>`
 
-Add a line when the UI checklist step posted a comment, naming the pull request it landed on:
+Add a line when a checklist was posted, naming the pull request it landed on and which comment carries it:
+
+`📋 Posted the UI checklist to <number>, in the evidence comment.`
 
-`📋 Posted the UI checklist to <number>.`
+`📋 Posted the UI checklist to <number>, on its own.`
 
 Add a line when the preview step returned an address:
 

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

@@ -49,7 +49,7 @@ Moving the guidance into a path-scoped rule does not reach the session that need
 - Structure floors for every test: the core testing rule
 - Runner choice, file suffix, placement, and query conventions: the TypeScript and Python testing rules
 - Settle, guard, and run-scope rules inside an end to end file: the end to end reliability and test scope rules
-- Writing a UI change's tests and its visual checklist after implementation: `ui-test`
+- Writing a UI change's visual checklist, and naming the behaviors it ships untested for this skill to place: `ui-checklist`
 - Grading the tests a pull request adds: `review-pr`
 - Whether the guidance moves where a session puts a test, which needs a measured with-and-without run rather than a rule here
 

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

@@ -32,5 +32,5 @@ 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: `070-planning.md` states the order and `ui-test` covers it
+- Confirming visual output after a change lands: `070-planning.md` states the order and `ui-checklist` writes the list to confirm against
 - The mechanical audit of whether an implementation reached history ahead of its test: `canon gov test-order`, invoked from `auto-ship`

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

@@ -0,0 +1,49 @@
+---
+name: ui-checklist
+description: Why the visual half of a UI change needs a written record a reviewer can open, why that record travels with the screenshots it annotates, and why writing the tests belongs elsewhere now
+---
+
+# UI checklist requirement
+
+## Gap
+
+Without this skill, UI work ships on the confidence of the session that wrote it. Nobody states which part of the change an eye has to judge, so a reviewer opens the diff and reads the automatable half, which the tests already cover, and never looks at the half that only rendering shows.
+
+The visual half is where the record is lost. A checklist printed into chat scrolls away before anyone verifies it, so the ship step has nothing to gate on and the work reads as verified because a list was produced. Written from a linked worktree against `pwd`, the file lands where the caller does not look.
+
+Writing the checklist correctly to disk does not close the gap either. The file sits under a gitignored folder on the machine that authored it, so a pull request reviewer, on that machine or another, never sees it. A record that only the author can open reads as verified for the same reason a record that never existed does.
+
+Posting it as a comment of its own is the next failure. The screenshots the checklist annotates sit in a second comment, so a reviewer reads "the hero settles without a jump" with no picture of the hero beside it and scrolls looking for one. Two comments describing one change also drift: a later push re-renders the screenshots and leaves the checklist claiming what an older head showed.
+
+The automatable half has its own gap, and it is no longer this skill's to close by writing the tests. `test-first` writes a behavior's test while the code is written, and `test-craft` owns which layer it belongs at. A skill writing tests after implementation duplicates both, and what it produces is the test the session already skipped rather than the test the behavior needed. What stays open is that nobody names the behaviors shipping untested, which is a list rather than a test.
+
+## Must
+
+- Split every change into visual-only and automatable before writing anything
+- Write the checklist for the visual-only half, each item an action and the result a person is looking for
+- Name every automatable change shipping with no test, with the layer `test-craft` would place it at, as a section of the same file
+- Write the file to the `.canon/tmp/handoff/ui-checklist/<slug>.md` handoff at the main worktree root, overwriting
+- Report that there is nothing to verify rather than manufacturing a checklist to show work
+
+## Must not
+
+- Write a test at any layer, which is `test-first` while the code is written and `test-craft` for where it goes
+- Read a project's test config or runner in order to write against it
+- Try to assert a visual property programmatically
+- Repeat the full checklist in chat, which is what made it evaporate
+- Stage or commit the checklist, which is gitignored scratch
+- Talk to GitHub directly. Posting the checklist belongs to `git-pr`, the sole consumer of the handoff file
+- Move the handoff path to match this skill's name, which strands a checklist an older binary wrote
+
+## Guards
+
+- No implementation context in the session: stop, since there is nothing to split
+- Nothing visual and nothing untested: skip the file write and report the coverage
+
+## Out of scope
+
+- Judging whether the UI is any good, which `ux-audit` owns
+- The rules for choosing a layer, which `test-craft` owns
+- Writing the test itself, which is `test-first`
+- Deciding whether an outstanding checklist blocks the ship, which the calling pipeline gates on
+- Performing the visual verification, which needs a person

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

@@ -0,0 +1,71 @@
+---
+name: ui-checklist
+description: Writes the visual checklist a reviewer reads beside the evidence screenshots, and names each changed behavior shipping with no test so `test-craft` can place one. Use after implementing UI changes, or when asked "what should I look at", "what do I verify", or "give me a visual checklist". Do NOT use in empty sessions with no implementation context, and do NOT use to write the tests themselves.
+---
+
+# UI checklist
+
+## Guards
+
+- If no implementation context exists in the session, stop: `❌ No implementation context. Describe what you built first.`
+- This skill writes no test. When a behavior needs one, name it and let `canon:test-craft` place it.
+
+## Analysis
+
+Review the session to identify what was built or changed. Split each change two ways:
+
+- **Visual-only:** spacing, alignment, color, typography, layout proportions, animation timing. These are what the checklist exists for, since nothing asserts them programmatically.
+- **Automatable:** interactions, state transitions, form submissions, keyboard handling, conditional rendering, loading, empty, and error states, plus journeys across routes and behavior only a real browser renders.
+
+An automatable change already covered by a test written during implementation is done. What is left is the missing-test list below.
+
+## The checklist
+
+Group visual items by feature area. Use `- [ ]` checkbox syntax, and write each item as the action and the result a person is looking for, so a reviewer who did not build the change can run it.
+
+```markdown
+**What to verify visually:**
+
+**<Feature area>**
+
+- [ ] <action> → <expected visual result>
+```
+
+## The missing-test list
+
+Name every automatable change this branch ships with no test, one per line, with the layer `test-craft` would place it at. Do not write the test and do not read the project's test config to write one against.
+
+Route each through the `test-craft` layer table: a journey or a browser-only behavior to end to end, a rendered state to a component test, and logic that renders nothing to a unit test. When the project has no runner at that layer, say so on the line rather than moving the item to a layer that does.
+
+This list ships inside the checklist file, below the visual items, so a reviewer reads what is untested next to what to look at:
+
+```markdown
+**Shipping without a test:**
+
+- <behavior> → <layer> (<runner, or the runner that is missing>)
+```
+
+Omit the heading when every automatable change is covered.
+
+## Persist the checklist
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
+
+When a checklist is produced, write it directly to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist. Always overwrite. This is a handoff file rather than a deliverable: `git-pr` renders it into the evidence comment once a pull request opens, then removes it, and nothing here talks to `gh` directly.
+
+The path names the artifact rather than this skill, so it does not move when the skill is renamed. A checklist written by an older binary still lands where the consumer looks.
+
+From a linked worktree the file-editing tools refuse that path, so the checklist goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+
+Skip the file write when there is nothing to verify visually and nothing shipping untested.
+
+The `.canon/tmp/` directory is gitignored. Do not stage or commit the file.
+
+## Output order
+
+1. If a checklist was produced, write it to file, then output only the file path in chat:
+   `📝 Wrote .canon/tmp/handoff/ui-checklist/<slug>.md`
+2. Name the count of visual items and the count of behaviors shipping without a test, on one line each
+3. If nothing was produced: `✅ Nothing to verify visually and nothing shipping untested.`
+
+Do not repeat the full checklist in chat.

package/claude/skills/ux-audit/REQUIREMENT.md

@@ -35,6 +35,6 @@ The pass slides into fixing what it finds, and then the audit and the change lan
 
 - Fixing what it found, which is a separate change with its own review
 - Feature planning, which `plan-feature` owns
-- Verifying one specific change, which `ui-test` owns
+- Verifying one specific change, which `ui-checklist` owns
 - Defining the intent it audits against, which `design-extract` and the wireframes own
 - Measuring what a running interface costs to paint, block, or shift, which `ux-measure` owns. Contrast stays here rather than going with it, being computable from two color values this skill already reads off the token table.

package/claude/skills/ux-measure/REQUIREMENT.md

@@ -44,5 +44,5 @@ A session that does start one picks a runner on the spot. The reading then comes
 - Judging the interface against stated intent, which `ux-audit` owns
 - Contrast, which is computable from two color values in the token table `ux-audit` already reads. A contrast failure from a color computed at runtime stays invisible to that reader, and the cost is accepted rather than overlooked.
 - Network waterfall, bundle size, and accessibility, which no version of this measures
-- Writing behavioral tests against the interface, which `ui-test` owns
+- Writing behavioral tests against the interface, which `test-first` and `test-craft` own
 - Fixing what the reading found