@erclx/canon 4.97.0 → 4.99.0

package/docs/agents/capture.md

@@ -18,9 +18,9 @@ canon capture https://example.com --selector .window --out preview.png
 
 ## What this repository captures
 
-A capture set here spans two folders. `assets/captures/` holds five sources and the template each is written from, and `assets/evidence/` holds the five images a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the five is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
+A capture set here spans two folders. `assets/captures/` holds three sources and the template each is written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the three sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
 
-Three of the five take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` and `task-board.html` are the two exceptions: the first holds terminal text from a real run and the second holds a hand-frozen snapshot of a gitignored board, each in its template rather than derived from a live catalog at build time.
+Two of the three take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
 
 `assets/captures/` is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source nested a further folder down is skipped by all three with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/captures/` no longer mixes markup in with the images.
 

package/docs/agents/demo.md

@@ -24,13 +24,15 @@ So `canon demo compile` writes a second artifact rather than adding fields to a
 
 The plan is committed, not scratch. Its timing is a starting point tuned by watching a recording, and the draft cannot reproduce a tuned value, so a recompile over an existing plan refuses and names `--force`.
 
+A plan can carry an optional `colorScheme` of `light` or `dark`, which the recording context starts in so a page following the system preference paints that scheme with no click beat of its own. An absent field keeps the engine's default, which is light, and `compile` never seeds it. Any other value makes the plan unreadable. A page keyed on a stored theme rather than the preference ignores the field.
+
 `record-screencast` is the routed way to run both verbs from a draft path: it compiles only when no plan exists yet, then runs, stopping to report any field still unresolved rather than guessing one.
 
 | Option          | Behavior                                                          |
 | --------------- | ----------------------------------------------------------------- |
 | `--out <dir>`   | Directory the plan and its output paths point at, default `demos` |
 | `--slug <slug>` | Plan name, defaulting to the draft filename                       |
-| `--force`       | Overwrite an existing plan, losing any timing tuned by hand       |
+| `--force`       | Overwrite an existing plan, losing any field set by hand          |
 | `--json`        | Add a record on stdout carrying the beats and what is unfilled    |
 
 ## What a run does

package/docs/agents/pr-evidence.md

@@ -46,17 +46,18 @@ image or marks the case new.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
-| Reason               | What it means                                                                 |
-| -------------------- | ----------------------------------------------------------------------------- |
-| `ok`                 | A body was rendered. `commentId` is set when a marked comment already exists. |
-| `no-evidence`        | Nothing in the diff carries an `evidence/` segment. An ordinary silent no-op. |
-| `gh-missing`         | `gh` is not on the path, so no pull request could be resolved.                |
-| `gh-failed`          | `gh` could not answer for this repository or branch, or read its comments.    |
-| `no-branch`          | The pull request carries no head branch name.                                 |
-| `no-object-head`     | The pull request object reported no head commit.                              |
-| `no-base`            | No base resolves against the trunk.                                           |
-| `unreadable-tree`    | git could not read the tree at the base commit.                               |
-| `unreadable-changes` | git could not list what this branch changed.                                  |
+| Reason                 | What it means                                                                 |
+| ---------------------- | ----------------------------------------------------------------------------- |
+| `ok`                   | A body was rendered. `commentId` is set when a marked comment already exists. |
+| `no-evidence`          | Nothing in the diff carries an `evidence/` segment. An ordinary silent no-op. |
+| `unreadable-checklist` | `--checklist` named a path that could not be read, or one holding nothing.    |
+| `gh-missing`           | `gh` is not on the path, so no pull request could be resolved.                |
+| `gh-failed`            | `gh` could not answer for this repository or branch, or read its comments.    |
+| `no-branch`            | The pull request carries no head branch name.                                 |
+| `no-object-head`       | The pull request object reported no head commit.                              |
+| `no-base`              | No base resolves against the trunk.                                           |
+| `unreadable-tree`      | git could not read the tree at the base commit.                               |
+| `unreadable-changes`   | git could not list what this branch changed.                                  |
 
 `no-evidence` is not a refusal a caller reports. A project on a stack that
 carries no evidence path, such as `base` or `python`, hits this reason on
@@ -107,6 +108,28 @@ no evidence in the diff and an address in hand, the body is the address and the
 marker alone, reported as `ok`. `canon docs pr-preview` covers where the
 address comes from.
 
+## The checklist line
+
+`--checklist <path>` closes the body with a visual checklist, below the
+comparison it annotates, so one comment carries the preview address, the
+screenshots, and what a reviewer has to look at. The file is what
+`canon:ui-checklist` writes to `.canon/tmp/handoff/ui-checklist/<slug>.md`, and
+`git-pr` passes it here rather than posting it as a second comment.
+
+A run without the option carries forward whatever checklist the marked comment
+already holds, the same way the preview address is carried. That is what keeps
+`git-followup`'s re-render after a push from wiping boxes a reviewer has
+already ticked, since `git-pr` deletes the handoff once the first post reports
+success and no later call has a file to pass.
+
+The option does not decide `no-evidence`. A branch with a checklist and no
+changed evidence image still reports `no-evidence`, and the caller posts the
+checklist on its own, which is what it did before this option existed. A path
+that cannot be read, or one holding nothing, refuses as
+`unreadable-checklist` rather than rendering without it: the caller deletes the
+handoff once a post succeeds, so a silently dropped checklist is the only copy
+gone.
+
 ## What a collapsed comment still leaves to GitHub
 
 GitHub already draws its own before-and-after comparison on the Files Changed

package/docs/agents/pr-preview.md

@@ -81,13 +81,14 @@ going, so the preview may still land after the verb has given up on it.
 
 `canon pr evidence --preview <url>` puts `**Preview:** <url>` on the first line
 of the evidence body. With no evidence image in the diff, the body is that line
-and the trailing marker alone, so a pull request with a checklist and no
-screenshots still gets one comment a later call can find and edit.
+and the trailing marker alone, so a pull request whose screenshots did not
+change still gets one comment a later call can find and edit.
 
 A later `canon pr evidence` run without `--preview` reads the address off the
 marked comment and carries it into the new body. `git-followup` re-renders the
 comment after every push, and without that carry the first push would delete
-the link.
+the link. A visual checklist folded in through `--checklist` carries the same
+way, which is what keeps that push from wiping boxes a reviewer already ticked.
 
 ## Removing a preview
 

package/docs/agents/tasks.md

@@ -54,7 +54,9 @@ An outcome whose body is struck reads as cut rather than open or closed, whateve
 
 The task carries its plan with it. When the closing task is the last live one whose `Plan:` line resolves onto that file, the plan moves to `.canon/plans/archive/` under its own name and the archived task's line is rewritten as `Plan: [feature-<slug>](../../plans/archive/feature-<slug>.md)`, a folder deeper than the live task wrote it. The `plan` field on the success record carries that `from` and `to`, and is `null` when nothing moved.
 
-A plan several tasks share stays where it is, and the task archives anyway. Moving it on the first task to close strands every sibling's pointer at a path that has gone, and `.canon/plans/` is gitignored so no history recovers the target. A `Plan:` line resolving to no file leaves the plan alone too, since a pointer somebody typed wrong is not a plan to move and holding the whole archive over it would park the board behind a repair the merge cannot make.
+The ready folder the task's `Ready:` line names moves with the plan to `.canon/ready/archive/`, falling back to a `.canon/ready/<nn>-<slug>/` path in the plan when the line is absent. The `Ready:` line and the plan's literal path to the folder are retargeted, and the `ready` field on the success record carries `from` and `to`, or `null` when nothing moved. A folder that resolves to nothing, sits already archived, or meets a taken destination moves nothing and refuses nothing.
+
+A plan several tasks share stays where it is, and its ready folder with it, and the task archives anyway. Moving it on the first task to close strands every sibling's pointer at a path that has gone, and `.canon/plans/` is gitignored so no history recovers the target. A `Plan:` line resolving to no file leaves the plan alone too, since a pointer somebody typed wrong is not a plan to move and holding the whole archive over it would park the board behind a repair the merge cannot make.
 
 The merge is what settles a plan. `.husky/post-merge` reads the pull request number off the squash subject and calls this verb, so both halves close in one act with nobody naming a file. That is why the move sits inside this verb rather than in a second call the hook would make after it, which could leave the task archived and the plan live.
 

package/docs/workflow/ai-workflow.md

@@ -58,7 +58,7 @@ Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full fi
 - When the current state is unmeasured and more than one approach is live, invoke `canon:plan-groundwork` first. It opens a track folder under `.canon/groundwork/<nn>-<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled.
 - Invoke `canon:plan-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
 - Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
-- For UI changes, invoke `canon:ui-test` to route each change to its test layer and run the tests it writes, with Playwright kept for journeys
+- For UI changes, invoke `canon:ui-checklist` to write what a reviewer has to look at and name any behavior shipping without a test
   End the session once the feature works and tests pass. Invoke `canon:docs-fold` to capture any decisions made during implementation before closing.
 
 The routing test is whether the repository can answer an item today. A session grepping handles the yes, and a groundwork track handles the no.
@@ -81,7 +81,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 
 - Create a worktree per feature, then start a Claude Code session in each
 - Invoke `canon:plan-feature` in each session. Plans land at the main worktree root as `.canon/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
-- Implement, verify, and review each feature independently. `review-branch` writes a per-branch report at the main worktree root (`review/branch-<slug>.md`), and `ui-test` writes a per-branch checklist handoff there too (`tmp/handoff/ui-checklist/<slug>.md`) that `git-pr` posts to the pull request and removes, so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
+- Implement, verify, and review each feature independently. `review-branch` writes a per-branch report at the main worktree root (`review/branch-<slug>.md`), and `ui-checklist` writes a per-branch checklist handoff there too (`tmp/handoff/ui-checklist/<slug>.md`) that `git-pr` posts to the pull request and removes, so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
 - Ship each worktree separately with `canon:git-ship`
 - For full autonomy per worktree, invoke `canon:auto-ship` instead of the manual chain. Approve the plan, walk away, come back to a pull request the chain marked as a draft and then read the flag back on. The mark says the work has had no review yet, and it holds no window, since readying a pull request to merge lifts it directly, an act reserved to the operator or to the controlling session that closed the review.
 
@@ -174,7 +174,7 @@ The receipt is collected once every item on it has been decided, and it survives
 
 ### UI polish
 
-Verify the change manually in the browser. Invoke `canon:ui-test` if you need tests at the right layer and a visual verification checklist for the session. For the fix itself, describe the change in Claude Code directly.
+Verify the change manually in the browser. Invoke `canon:ui-checklist` if you need a written list of what to look at. For the fix itself, describe the change in Claude Code directly.
 
 ### Quick fix
 
@@ -235,7 +235,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `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:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                  |
-| `canon:ui-test`              | After a UI change, to generate layered tests and a visual checklist             |
+| `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/docs/workflow/visual-design-workflow.md

@@ -31,13 +31,13 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 ### Tools
 
 - None beyond Claude Code itself
-- Playwright CLI optional for verifying journeys across routes and browser-only behavior. See [`ui-test`](../../claude/skills/ui-test/SKILL.md).
+- Playwright CLI optional for verifying journeys across routes and browser-only behavior. See [`test-craft`](../../claude/skills/test-craft/SKILL.md) for which layer a journey belongs at.
 
 ### Skills
 
 - `canon:sketch-design` to trace a design direction from reference images or URLs, before `design-extract`'s greenfield path proposes from a personality paragraph alone
 - `canon:design-extract` to draft `canon/DESIGN.md`, from existing project signals or from requirements alone on day one
-- `canon:ui-test` for layered test generation after UI changes
+- `canon:ui-checklist` for what a reviewer has to look at after UI changes, and what ships without a test
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.97.0",
+  "version": "4.99.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -77,8 +77,11 @@ GOV_JSON="$(catalog gov list)"
 STANDARDS_JSON="$(catalog standards list)"
 SNIPPETS_JSON="$(catalog snippets list)"
 TOOLING_JSON="$(catalog tooling list)"
+# The catalog ledger names three commands, and the registered set is only
+# readable from the root help, which lists one per line under `Commands:`.
+COMMANDS_HELP="$(cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts --help 2>/dev/null)"
 
-for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
+for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON" "$COMMANDS_HELP"; do
   if [ -z "$payload" ]; then
     echo "regen-hero: a catalog returned nothing, refusing to write a zeroed hero" >&2
     exit 1
@@ -98,6 +101,7 @@ printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
 printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
 printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
 printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
+printf '%s' "$COMMANDS_HELP" >"$PAYLOAD_DIR/commands-help.txt"
 printf '%s' "$TOKEN_CSS" >"$PAYLOAD_DIR/tokens.css"
 
 export PAYLOAD_DIR
@@ -326,8 +330,36 @@ for (const [label, rows] of [
   }
 }
 
+// The ledger names a few real entries per domain. Chosen by hand for the same
+// reason FEATURED_SKILLS is, and asserted against the catalog so a rename fails
+// the run rather than leaving a name the repository no longer ships.
+const commandNames = readFileSync(PAYLOAD_DIR + "/commands-help.txt", "utf8")
+  .split("\n")
+  .map((line) => line.match(/^[│\s]{2,}(?<name>[a-z][a-z-]*)\s/)?.groups?.name)
+  .filter(Boolean)
+const LEDGER = [
+  ["skills", skills.length, ["plan-feature", "role-orchestrator", "review-pr"], skills],
+  ["rules", rules.length, ["behavior", "memory", "testing"], rules],
+  ["standards", standards.length, ["markdown", "plan", "teach"], standards],
+  ["commands", commandCount, ["gov", "tasks", "design"], commandNames],
+  ["stacks", toolingStacks.length, ["astro", "python", "web"], toolingStacks.map((stack) => stack.name)],
+]
+for (const [domain, , chosen, names] of LEDGER) {
+  const known = new Set(names)
+  const missing = chosen.filter((name) => !known.has(name))
+  if (missing.length > 0) {
+    console.error(`regen-hero: ledger ${domain} names missing from the catalog: ${missing.join(", ")}`)
+    process.exit(1)
+  }
+}
+const ledgerRows = LEDGER.map(
+  ([domain, count, chosen]) =>
+    `      <div class="row"><span class="count">${count}</span><span class="domain">${domain}</span><span class="names">${escape(chosen.join(", "))}</span></div>`,
+).join("\n")
+
 const values = {
   TOKENS: tokenCss,
+  LEDGER_ROWS: ledgerRows,
   GOV_STACK_ROWS: govStackRows,
   GOV_RULE_ROWS: govRuleRows,
   STANDARD_ROWS: standardRows,

package/src/claude/cases/workflow.ts

@@ -126,8 +126,9 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
     expect: 'teach-workspace',
   },
   {
-    prompt: 'Generate the Playwright tests I need after this UI change.',
-    expect: 'ui-test',
+    prompt:
+      'The restyle is finished. Write down what a reviewer has to look at by eye, and which behaviors have no test.',
+    expect: 'ui-checklist',
   },
   {
     prompt:

package/src/commands/demo.ts

@@ -187,9 +187,10 @@ function runCompile(draftPath: string, opts: CompileOptions): number {
   if (existsSync(target) && !opts.force) {
     logStep('Plan')
     logError(`${display(target)} already exists`)
-    // Stated rather than implied, because the value at risk is timing the
-    // operator tuned by watching a recording and the draft cannot reproduce it.
-    logWarn('Pass --force to overwrite it, losing any timing tuned by hand.')
+    // Stated rather than implied, because the value at risk is whatever the
+    // operator set by hand, such as timing tuned by watching a recording or a
+    // color scheme, and the draft can reproduce neither.
+    logWarn('Pass --force to overwrite it, losing any field set by hand.')
     outro()
     emit(opts.json, { plan: target, reason: 'plan-exists' })
     return 1

package/src/commands/pr.ts

@@ -22,6 +22,7 @@ import {
 } from '@/pr/bijection'
 import { type CheckRunListing, collapseChecks } from '@/pr/checks'
 import {
+  findEvidenceChecklist,
   findEvidenceCommentId,
   findEvidencePreview,
   groupEvidence,
@@ -70,6 +71,7 @@ interface ReadOptions {
 
 interface EvidenceOptions extends ReadOptions {
   readonly preview?: string
+  readonly checklist?: string
 }
 
 interface PreviewOptions extends ReadOptions {
@@ -137,10 +139,13 @@ type EvidenceRefusal =
   | 'no-base'
   | 'unreadable-tree'
   | 'unreadable-changes'
+  | 'unreadable-checklist'
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
   'gh-failed':
     'gh could not answer for this repository. Name the pull request number.',
+  'unreadable-checklist':
+    'The file named by --checklist could not be read, or holds nothing. Rendering without it would drop the only copy, since the caller deletes the handoff once a post reports success.',
   'no-base': 'No base resolves against the trunk. Fetch origin and re-run.',
   'unreadable-tree':
     'git could not read the tree at the base commit, so no path could be judged added or changed.',
@@ -369,6 +374,10 @@ export function register(program: Command): void {
       '--preview <url>',
       'Open the body with this preview address, from canon pr preview',
     )
+    .option(
+      '--checklist <path>',
+      'Close the body with this visual checklist file, from canon:ui-checklist',
+    )
     .addHelpText(
       'after',
       [
@@ -393,6 +402,14 @@ export function register(program: Command): void {
         'Without --preview, an address the marked comment already opens with',
         'is carried into the new body, so a re-render after a push keeps it.',
         '',
+        '--checklist closes the body with a visual checklist, below the',
+        'comparison it annotates. A checklist the marked comment already',
+        'carries is read back and carried forward the same way the preview',
+        'address is, which keeps a re-render from wiping ticked boxes. It does',
+        'not decide no-evidence: a branch with a checklist and no evidence',
+        'image still reports no-evidence, and the caller posts the checklist',
+        'on its own.',
+        '',
         'Exit codes:',
         '  0  read, whether it produced a body or reported no-evidence',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -401,6 +418,7 @@ export function register(program: Command): void {
         '  canon pr evidence --json',
         '  canon pr evidence 1341 --json',
         '  canon pr evidence 1341 --preview https://feat-x.site.pages.dev --json',
+        '  canon pr evidence 1341 --checklist .canon/tmp/handoff/ui-checklist/x.md --json',
         '',
       ].join('\n'),
     )
@@ -1214,6 +1232,23 @@ async function runEvidence(
 
   intro('canon pr evidence')
 
+  // Read ahead of anything else, so a bad path refuses before a `gh` round
+  // trip rather than after one.
+  let suppliedChecklist: string | undefined
+  if (opts.checklist !== undefined) {
+    suppliedChecklist = await readFile(resolve(root, opts.checklist), 'utf8')
+      .then((text) => text.trim() || undefined)
+      .catch(() => undefined)
+    if (suppliedChecklist === undefined) {
+      return refuseWith(
+        'unreadable-checklist',
+        EVIDENCE_REFUSALS['unreadable-checklist'],
+        emitJson,
+        root,
+      )
+    }
+  }
+
   const read = await readIdentity(root, number)
   if (read.kind === 'refused') {
     return refuseWith(read.reason, PULL_REFUSALS[read.reason], emitJson, root)
@@ -1294,6 +1329,7 @@ async function runEvidence(
 
   let commentId: number | undefined
   let carriedPreview: string | undefined
+  let carriedChecklist: string | undefined
   if (identity.number !== undefined) {
     const commentsRow = await gh(root, [
       'pr',
@@ -1327,11 +1363,20 @@ async function runEvidence(
     }
     commentId = findEvidenceCommentId(comments)
     carriedPreview = findEvidencePreview(comments)
+    carriedChecklist = findEvidenceChecklist(comments)
   }
 
   const preview = opts.preview ?? carriedPreview
+  const checklist = suppliedChecklist ?? carriedChecklist
   const states = grouped.kind === 'read' ? grouped.states : []
-  const body = renderEvidenceBody(states, repo, base, identity.head, preview)
+  const body = renderEvidenceBody(
+    states,
+    repo,
+    base,
+    identity.head,
+    preview,
+    checklist,
+  )
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
 
@@ -1340,6 +1385,13 @@ async function runEvidence(
     `${plural(caseCount, 'case')} across ${plural(states.length, 'state')}`,
   )
   if (preview !== undefined) logInfo(`preview ${preview}`)
+  if (checklist !== undefined) {
+    logInfo(
+      suppliedChecklist === undefined
+        ? 'checklist carried forward from the marked comment'
+        : 'checklist folded in below the comparison',
+    )
+  }
 
   outro()
 

package/src/commands/tasks.ts

@@ -146,6 +146,11 @@ export function register(program: Command): void {
         'plan, and the archived task keeps a working Plan: pointer at the new',
         'path. A plan several tasks share stays where it is.',
         '',
+        'The ready folder the task names moves to .canon/ready/archive/ with its',
+        'plan, and the Ready: line and the plan path to it are retargeted. A',
+        'folder that does not resolve, or a destination already taken, moves',
+        'nothing and refuses nothing.',
+        '',
         'Exit codes:',
         '  0  the task was archived',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -1310,6 +1315,11 @@ function report(
     logAdd(relative(root, outcome.plan.to))
     logInfo('retargeted the Plan: line')
   }
+  if (outcome.ready) {
+    logRemove(relative(root, outcome.ready.from))
+    logAdd(relative(root, outcome.ready.to))
+    logInfo('retargeted the Ready: line')
+  }
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   if (outcome.cut > 0) logInfo(`${outcome.cut} outcome(s) cut`)
@@ -1344,6 +1354,12 @@ function recordFor(
           to: relative(root, outcome.plan.to),
         }
       : null,
+    ready: outcome.ready
+      ? {
+          from: relative(root, outcome.ready.from),
+          to: relative(root, outcome.ready.to),
+        }
+      : null,
     closed: outcome.closed,
     cut: outcome.cut,
   }

package/src/demo/compile.ts

@@ -107,11 +107,14 @@ export interface DemoStep {
   readonly note?: string
 }
 
+export type ColorScheme = 'light' | 'dark'
+
 export interface DemoPlan {
   readonly slug: string
   readonly title: string
   readonly url: string
   readonly viewport: { readonly width: number; readonly height: number }
+  readonly colorScheme?: ColorScheme
   readonly output: { readonly video: string; readonly still: string }
   readonly pointer: { readonly travelMs: number; readonly typeDelayMs: number }
   readonly annotations: typeof ANNOTATIONS
@@ -229,6 +232,9 @@ export function parsePlan(text: string): PlanParse {
     steps.push(step.step)
   }
 
+  const colorScheme = parseColorScheme(raw.colorScheme)
+  if (colorScheme.status === 'failed') return colorScheme
+
   const slug = asText(raw.slug)
   const output = isRecord(raw.output) ? raw.output : {}
   const pointer = isRecord(raw.pointer) ? raw.pointer : {}
@@ -244,6 +250,7 @@ export function parsePlan(text: string): PlanParse {
         width: asNumber(viewport.width, VIEWPORT.width),
         height: asNumber(viewport.height, VIEWPORT.height),
       },
+      ...(colorScheme.value && { colorScheme: colorScheme.value }),
       output: {
         video: asText(output.video) || `demos/${slug || 'demo'}.webm`,
         still: asText(output.still) || `demos/${slug || 'demo'}.png`,
@@ -258,6 +265,19 @@ export function parsePlan(text: string): PlanParse {
   }
 }
 
+function parseColorScheme(
+  value: unknown,
+):
+  | { status: 'ok'; value?: ColorScheme }
+  | { status: 'failed'; reason: string } {
+  if (value === undefined) return { status: 'ok' }
+  if (value === 'light' || value === 'dark') return { status: 'ok', value }
+  return {
+    status: 'failed',
+    reason: `colorScheme is ${JSON.stringify(value)}, which is not light or dark`,
+  }
+}
+
 function parseStep(
   entry: unknown,
   index: number,

package/src/demo/drive.ts

@@ -118,6 +118,7 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
 
     context = await browser.value.newContext({
       viewport: plan.viewport,
+      ...(plan.colorScheme && { colorScheme: plan.colorScheme }),
       // Pointed the opposite way from a test. A recording wants the motion the
       // interface was designed with, where a test wants it suppressed.
       reducedMotion: 'no-preference',

package/src/migrate/skill-names.ts

@@ -21,6 +21,13 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
  * reading in sequence with `draft-screencast` as one three-step pipeline with
  * no prefix forcing that reading.
  *
+ * One row renames a skill rather than retiring a prefix. `ui-test` became
+ * `ui-checklist` when the skill stopped writing tests and shrank to the
+ * checklist a reviewer reads, so the old name described a job it no longer
+ * does. `claude-ui-test` is retargeted onto the same destination rather than
+ * left pointing at the retired name, which lands a target on the oldest
+ * spelling in one pass instead of two.
+ *
  * Every name takes two words. Ten of these would have landed as a bare single
  * word under a plain strip, and a bare word such as `review` or `docs` is a
  * substring of ordinary prose with no token left for a later sweep to find.
@@ -56,7 +63,8 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'claude-standards-audit': 'standards-audit',
   'claude-tasks': 'task-board',
   'claude-teach': 'teach-workspace',
-  'claude-ui-test': 'ui-test',
+  'claude-ui-test': 'ui-checklist',
+  'ui-test': 'ui-checklist',
   'claude-ux-audit': 'ux-audit',
   'claude-ux-measure': 'ux-measure',
   'claude-worker': 'role-worker',
@@ -72,11 +80,11 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
  *
  * It protects nothing. The `aitk` sweep had to guard a sibling repository
  * whose name contained the token, and no string here contains a skill name
- * while meaning something else: the one overlap in the map is
- * `claude-intake` inside `claude-intake-answer`, which the longest-first
- * ordering settles rather than a protected form. Reading that off the output
- * would report a pass either way, since both rows land on a name opening with
- * `plan-intake`, so the ordering is asserted directly.
+ * while meaning something else. Two rows overlap another row: `claude-intake`
+ * inside `claude-intake-answer`, and `ui-test` inside `claude-ui-test`. The
+ * longest-first ordering settles both rather than a protected form. Reading
+ * either off the output would report a pass anyway, since each pair lands on
+ * one destination, so the ordering is asserted directly.
  *
  * It matches whole tokens. A skill name is a complete name rather than a word
  * stem, and the corpus holds one word that opens with a name and means

package/src/pr/evidence.ts

@@ -7,6 +7,13 @@ const MARKER_PREFIX = '<!-- pr-evidence:'
 /** How the first line of a body names the branch's preview deployment. */
 const PREVIEW_PREFIX = '**Preview:**'
 
+/** The heading the checklist sits under, printed outside the delimiters so a carried checklist never doubles it. */
+const CHECKLIST_HEADING = '## What to look at'
+
+/** Delimiters around the checklist, so a re-render can read back what a reviewer has already ticked. */
+const CHECKLIST_START = '<!-- pr-checklist:start -->'
+const CHECKLIST_END = '<!-- pr-checklist:end -->'
+
 /** A `#issuecomment-<id>` suffix, which is the REST comment id `gh pr view` never returns directly. */
 const ISSUE_COMMENT_ID = /#issuecomment-(\d+)$/
 
@@ -116,6 +123,9 @@ export function evidenceMarker(head: string): string {
  * A preview address opens the body, and with no states it is the whole body
  * apart from the marker, so a pull request whose screenshots did not change
  * still gets one comment a later call can find and edit in place.
+ *
+ * A checklist closes the body, below the comparison it annotates, so one
+ * comment carries the preview address, the screenshots, and what to look at.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -123,11 +133,16 @@ export function renderEvidenceBody(
   base: string,
   head: string,
   preview?: string,
+  checklist?: string,
 ): string {
   const opening =
     preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`, '']
+  const closing =
+    checklist === undefined
+      ? []
+      : [CHECKLIST_HEADING, '', CHECKLIST_START, checklist, CHECKLIST_END, '']
   if (states.length === 0) {
-    return [...opening, evidenceMarker(head)].join('\n')
+    return [...opening, ...closing, evidenceMarker(head)].join('\n')
   }
 
   const sections = states.map((entry) => {
@@ -157,6 +172,7 @@ export function renderEvidenceBody(
     '',
     ...sections,
     '',
+    ...closing,
     evidenceMarker(head),
   ].join('\n')
 }
@@ -204,3 +220,22 @@ export function findEvidencePreview(
   if (!first.startsWith(PREVIEW_PREFIX)) return undefined
   return first.slice(PREVIEW_PREFIX.length).trim() || undefined
 }
+
+/**
+ * The checklist the marked comment already carries, read back out of its
+ * delimiters. The handoff file is deleted once posted, so every later render
+ * passes no checklist of its own, and carrying this one forward is what keeps
+ * a re-render after a push from wiping the boxes a reviewer has ticked.
+ */
+export function findEvidenceChecklist(
+  comments: readonly EvidenceComment[],
+): string | undefined {
+  const marked = comments.find((comment) => hasEvidenceMarker(comment.body))
+  if (marked === undefined) return undefined
+  const start = marked.body.indexOf(CHECKLIST_START)
+  const end = marked.body.indexOf(CHECKLIST_END, start)
+  if (start === -1 || end === -1) return undefined
+  return (
+    marked.body.slice(start + CHECKLIST_START.length, end).trim() || undefined
+  )
+}

package/src/sandbox/expect.ts

@@ -178,7 +178,8 @@ function contentArray(value: unknown): ContentAssertion[] {
     // A bare key written below a `[[content]]` header belongs to that table in
     // TOML, not to the document, so a declaration listing `manual` or
     // `max_turns` after its content blocks parses clean and silently asserts
-    // neither. The `claude/ui-test` arm shipped that way: a turn ceiling that
+    // neither. The arm then named `claude/ui-test`, now
+    // `claude/ui-checklist`, shipped that way: a turn ceiling that
     // never ran and five manual entries that never reached the unchecked count,
     // while `canon sandbox coverage` counted the arm as armed. Nothing at the
     // top level can see the difference, so the check belongs here.