@erclx/canon 4.98.0 → 4.100.0

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.98.0",
+  "version": "4.100.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -15,6 +15,10 @@
 # component half is left out on purpose: it is a scrollbar and a status marker,
 # and a static capture frame renders neither.
 #
+# A frame a README shows in both themes fills once more against the light roles
+# and writes `<name>-light.html` beside the dark one, so each theme is its own
+# capture set with its own stamp.
+#
 # Only the HTML regenerates here. The PNG beside it is a chromium render whose
 # bytes move with the browser version, so asserting it in verify.sh would fail
 # on a machine whose chromium differs rather than on a stale count. Rebuild the
@@ -393,9 +397,38 @@ if (templates.length === 0) {
   process.exit(1)
 }
 
-for (const template of templates) {
+// The frames a README serves in both themes. The emitter already carries a
+// `--color-light-*` role beside each `--color-*` one, so the light frame is the
+// same template with the plain roles pointed at the light ones rather than a
+// second copy of any hex value. The hero is a landing-page frame no README
+// shows, so it stays dark.
+const LIGHT_TEMPLATES = new Set(["catalog.html.tmpl", "install.html.tmpl"])
+
+const lightRoles = [...tokenCss.matchAll(/--color-light-([a-z-]+):/g)].map((match) => match[1])
+if (lightRoles.length === 0) {
+  console.error("regen-hero: token css carries no --color-light-* roles, refusing to write a light frame")
+  process.exit(1)
+}
+const lightTokenCss = [
+  tokenCss,
+  "",
+  "      :root {",
+  ...lightRoles.map((role) => `        --color-${role}: var(--color-light-${role});`),
+  "        --frame-shadow: rgb(0 0 0 / 16%);",
+  "      }",
+].join("\n")
+
+const frames = templates.flatMap((template) => {
+  const base = template.replace(/\.html\.tmpl$/, "")
+  const dark = { template, out: `${base}.html`, tokens: tokenCss }
+  return LIGHT_TEMPLATES.has(template)
+    ? [dark, { template, out: `${base}-light.html`, tokens: lightTokenCss }]
+    : [dark]
+})
+
+for (const { template, out, tokens } of frames) {
   let html = await Bun.file(ASSET_DIR + "/" + template).text()
-  for (const [key, value] of Object.entries(values)) {
+  for (const [key, value] of Object.entries({ ...values, TOKENS: tokens })) {
     html = html.replaceAll(`{{${key}}}`, value)
   }
 
@@ -405,6 +438,6 @@ for (const template of templates) {
     process.exit(1)
   }
 
-  await Bun.write(ASSET_DIR + "/" + template.replace(/\.tmpl$/, ""), html)
+  await Bun.write(ASSET_DIR + "/" + out, html)
 }
 '

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.

package/src/tasks/archive.ts

@@ -7,6 +7,7 @@ import { recordDir, recordDirs } from '@/record-root'
 
 const TASKS = 'tasks'
 const PLANS = 'plans'
+const READY = 'ready'
 const ARCHIVE = 'archive'
 const DECLINED = 'declined'
 const BACKLOG = 'backlog.md'
@@ -75,6 +76,12 @@ export interface PlanMove {
   readonly to: string
 }
 
+/** A ready folder carried into the archive alongside the plan that is its verbatim source. */
+export interface ReadyMove {
+  readonly from: string
+  readonly to: string
+}
+
 export interface ArchiveSuccess {
   readonly ok: true
   readonly stem: string
@@ -84,6 +91,8 @@ export interface ArchiveSuccess {
   readonly indexRegenerated: boolean
   /** Undefined when the task cited no live plan, or when another task still holds it. */
   readonly plan: PlanMove | undefined
+  /** Undefined when the plan stays, or when no ready folder resolves and can move. */
+  readonly ready: ReadyMove | undefined
   readonly closed: number
   readonly cut: number
 }
@@ -280,6 +289,32 @@ export function retargetPlanLine(text: string, target: string): string {
   return text.replace(PLAN_PATTERN, () => planLine(target))
 }
 
+/** The `Ready:` line in either form, matched the way `PLAN_PATTERN` matches `Plan:`. */
+const READY_PATTERN = /^Ready:[ \t]*(?:\[[^\]]*\]\(([^)]+)\)|(\S+))[ \t]*$/m
+
+/** A ready folder path as a plan's constraints write it, the folder name captured. */
+const READY_PATH_PATTERN = /(\.(?:canon|claude)\/ready\/)([^\s/`)]+)(?=\/)/g
+
+export function readReadyTarget(text: string): string | undefined {
+  const match = READY_PATTERN.exec(text)
+  if (!match) return undefined
+  return match[1] ?? match[2]
+}
+
+/**
+ * Builds a `Ready:` line as a link whose target keeps the trailing slash a
+ * folder carries, the label taken from the folder's own name.
+ */
+export function readyLine(target: string): string {
+  const folder = target.replace(/\/+$/, '')
+
+  return `Ready: [${basename(folder)}](${folder}/)`
+}
+
+export function retargetReadyLine(text: string, target: string): string {
+  return text.replace(READY_PATTERN, () => readyLine(target))
+}
+
 /**
  * Builds the `Declined:` line recording why a task was decided against and by
  * whom. Free prose after the colon, since the line names no file to link,
@@ -731,22 +766,41 @@ export async function archiveTask(
   }
 
   const plan = await planToArchive(dir, root, stem, text)
+  const ready = plan && (await readyToArchive(dir, root, text, plan))
   const destination = archiveDir(root)
   const to = join(destination, `${stem}.md`)
 
   // The plan moves first so the line written below describes a file already at
   // its new path. Writing the retarget first and failing the move would leave a
   // pointer at a folder holding nothing, and `.canon/plans/` is gitignored, so
-  // no history recovers the target it named.
+  // no history recovers the target it named. The folder follows the plan and
+  // both precede the task, so a failed rename never leaves the task archived
+  // with its folder live, which the unattended post-merge hook cannot repair.
   if (plan) {
     await mkdir(dirname(plan.to), { recursive: true })
     await rename(plan.from, plan.to)
   }
 
+  if (ready) {
+    await mkdir(dirname(ready.to), { recursive: true })
+    await rename(ready.from, ready.to)
+    await writeFile(
+      plan.to,
+      retargetReadyPaths(await readFile(plan.to, 'utf8'), basename(ready.from)),
+    )
+  }
+
   await mkdir(destination, { recursive: true })
   await rename(from, to)
-  if (plan)
-    await writeFile(to, retargetPlanLine(text, linkTo(destination, plan.to)))
+  if (plan) {
+    const retargeted = retargetPlanLine(text, linkTo(destination, plan.to))
+    await writeFile(
+      to,
+      ready
+        ? retargetReadyLine(retargeted, `${linkTo(destination, ready.to)}/`)
+        : retargeted,
+    )
+  }
 
   const priorityRowRemoved = await clearPriorityRow(dir, stem)
   const regen = await regenOne(dir, { dryRun: false })
@@ -759,6 +813,7 @@ export async function archiveTask(
     priorityRowRemoved,
     indexRegenerated: regen.action === 'written',
     plan,
+    ready: ready || undefined,
     closed: closed.length,
     cut: cut.length,
   }
@@ -797,6 +852,63 @@ async function planToArchive(
   }
 }
 
+/**
+ * The ready folder that travels with the plan, or nothing. It is read from the
+ * task's `Ready:` line, falling back to a folder path in the plan's own text for
+ * a task written before the line was defined. It moves only with its plan,
+ * since the folder is the plan's verbatim source and a plan another task still
+ * cites still needs it, so the caller passes the plan `planToArchive` settled.
+ *
+ * A target naming no folder, one already archived, or a destination taken
+ * yields nothing and refuses nothing, the way a mistyped `Plan:` does.
+ */
+async function readyToArchive(
+  dir: string,
+  root: string,
+  text: string,
+  plan: PlanMove,
+): Promise<ReadyMove | undefined> {
+  const live =
+    readyFolder(dir, root, text) ??
+    readyFolder(dir, root, await readFile(plan.from, 'utf8'))
+  if (!live) return undefined
+
+  const to = join(recordDir(root, READY, ARCHIVE), basename(live))
+  if (existsSync(to)) return undefined
+
+  return { from: live, to }
+}
+
+function readyFolder(
+  dir: string,
+  root: string,
+  text: string,
+): string | undefined {
+  const target = readReadyTarget(text)
+  const named = target ? [resolve(dir, target), resolve(root, target)] : []
+  const constrained = [...text.matchAll(READY_PATH_PATTERN)].map(([, , name]) =>
+    join(recordDir(root, READY), name),
+  )
+  const archives = recordDirs(root, READY, ARCHIVE)
+
+  return [...named, ...constrained].find(
+    (path) =>
+      recordDirs(root, READY).some((base) => dirname(path) === base) &&
+      basename(path) !== ARCHIVE &&
+      !archives.some((base) => isUnder(path, base)) &&
+      existsSync(path),
+  )
+}
+
+/** Points the plan's literal folder paths at `ready/archive/`, since the folder no longer sits where they say. */
+function retargetReadyPaths(text: string, folder: string): string {
+  return text.replace(
+    READY_PATH_PATTERN,
+    (whole: string, prefix: string, name: string) =>
+      name === folder ? `${prefix}${ARCHIVE}/${name}` : whole,
+  )
+}
+
 /**
  * The archived plan as the archived task cites it. Both halves land a folder
  * deeper than the live pair, so the link is measured between the two

package/standards/ready.md

@@ -78,7 +78,7 @@ Below the frontmatter, state in prose what the worker still owns beyond copying
 ## Lifecycle
 
 - Write the ready folder in the same session that writes the files it carries. A folder assembled later from memory is a plan with extra steps, not a handoff.
-- Move the folder to `.canon/ready/archive/<nn>-<slug>/` by hand when the task that shipped it archives. No board verb currently automates this move. `canon tasks archive` moves the task and its plan and leaves the ready folder where it is.
+- Leave the move to `canon tasks archive`, which carries the folder to `.canon/ready/archive/<nn>-<slug>/` with its plan when the task that shipped it archives, and retargets the task's `Ready:` line. A plan another live task still cites keeps its folder.
 - Never delete a ready folder. The archived copy sits beside the merged pull request as the exact text that shipped, the way an archived plan sits beside the reasoning that produced it.
 
 ## Anti-patterns
@@ -86,7 +86,7 @@ Below the frontmatter, state in prose what the worker still owns beyond copying
 - **The folder with an undeclared destination.** A file the plan's `**Files to touch:**` does not list passes the collision check unseen, and a second track can write the same path without either side finding out.
 - **The rewritten copy.** A worker that reads the folder's files as inspiration and writes its own version loses the exact text the handoff exists to carry.
 - **The folder as scratch.** Notes, alternates, or draft passages left in the folder beside the real files leave the worker guessing which is the source.
-- **The folder left live after shipping.** A ready folder nobody moves to the archive reads as unshipped work to the next session that lists the live folder.
+- **The folder left live after shipping.** A ready folder the archive verb did not move reads as unshipped work to the next session that lists the live folder. The verb skips one whose task carries no `Ready:` line and cites no folder path in its plan.
 
 ## Template