@erclx/canon 5.68.0 → 5.70.0

package/src/tasks/launch-wait.ts

@@ -0,0 +1,160 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import {
+  type AnswerRefusal,
+  type OpenQuestion,
+  planAnswers,
+} from '@/tasks/answers'
+import {
+  describeUnmatchedStem,
+  listTaskStems,
+  readPlanTargets,
+  tasksDir,
+} from '@/tasks/archive'
+
+export const DEFAULT_LAUNCH_WAIT_SECONDS = 1800
+export const LAUNCH_POLL_MS = 30_000
+
+export type LaunchRefusal =
+  | AnswerRefusal
+  | 'no-board'
+  | 'no-match'
+  | 'ambiguous'
+  | 'several-plans'
+
+export interface LaunchRefused {
+  readonly ok: false
+  readonly reason: LaunchRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+/**
+ * One reading of a row. `reason` is `unlinked` while the task carries no
+ * `Plan:` line, `open` while its plan holds a question for the operator, and
+ * `launchable` once it holds none. `plan` and `open` keep the names
+ * `plan-answers` gives them, so the dispatch reads one concept by one name.
+ */
+export interface LaunchReading {
+  readonly ok: true
+  readonly task: string
+  readonly plan?: string
+  readonly reason: 'unlinked' | 'open' | 'launchable'
+  readonly launchable: boolean
+  readonly open: readonly OpenQuestion[]
+}
+
+export type LaunchOutcome = LaunchReading | LaunchRefused
+
+/**
+ * The record a wait ends on. A reading ends `launchable` or, at the deadline,
+ * `timeout` carrying the last reading, so the caller still sees which question
+ * holds the row. A refusal ends the wait at once, since nothing a planner
+ * writes next turns an archived plan or an unknown task launchable.
+ */
+export type LaunchWait =
+  | (Omit<LaunchReading, 'reason'> & {
+      readonly reason: 'launchable' | 'timeout'
+      readonly waitedSeconds: number
+    })
+  | (LaunchRefused & { readonly waitedSeconds: number })
+
+export interface LaunchClock {
+  now(): number
+  sleep(ms: number): Promise<void>
+}
+
+export interface LaunchWaitOptions {
+  readonly waitSeconds: number
+  readonly clock: LaunchClock
+  readonly pollMs?: number
+}
+
+/**
+ * Reads a row by its task stem: resolves the task's `Plan:` line, then runs the
+ * `plan-answers` gate on the plan it names. Keying on the line rather than on
+ * the plan file is what keeps a plan still being written from reading as
+ * landed, since a planner links it only after it validates.
+ *
+ * It reports and never writes, and answers planning alone. The branch and
+ * claim checks stay with the dispatch runbook, which owns them.
+ */
+export async function readLaunchable(
+  root: string,
+  task: string,
+): Promise<LaunchOutcome> {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) {
+    return refuse('no-board', `No task board at ${relative(root, dir)}.`)
+  }
+
+  const stems = await listTaskStems(dir)
+  if (!stems.includes(task)) {
+    const { reason, message, detail } = describeUnmatchedStem(stems, task)
+    return refuse(reason, message, detail)
+  }
+
+  const targets = readPlanTargets(
+    await readFile(join(dir, `${task}.md`), 'utf8'),
+  )
+  const [target] = targets
+  if (target === undefined) {
+    return { ok: true, task, reason: 'unlinked', launchable: false, open: [] }
+  }
+  if (targets.length > 1) {
+    return refuse(
+      'several-plans',
+      `${task} links ${targets.length} plans, so no single plan is the one to dispatch.`,
+      targets,
+    )
+  }
+
+  const answers = await planAnswers(root, target)
+  if (!answers.ok) return answers
+
+  return {
+    ok: true,
+    task,
+    plan: answers.plan,
+    reason: answers.launchable ? 'launchable' : 'open',
+    launchable: answers.launchable,
+    open: answers.open,
+  }
+}
+
+/**
+ * Re-reads the row every `pollMs` until it is launchable, a read refuses, or
+ * the next reading would land past the deadline.
+ */
+export async function waitForLaunchable(
+  root: string,
+  task: string,
+  opts: LaunchWaitOptions,
+): Promise<LaunchWait> {
+  const { clock } = opts
+  const pollMs = opts.pollMs ?? LAUNCH_POLL_MS
+  const started = clock.now()
+  const deadline = started + opts.waitSeconds * 1000
+  const waited = () => Math.round((clock.now() - started) / 1000)
+
+  for (;;) {
+    const reading = await readLaunchable(root, task)
+    if (!reading.ok) return { ...reading, waitedSeconds: waited() }
+    if (reading.launchable) {
+      return { ...reading, reason: 'launchable', waitedSeconds: waited() }
+    }
+    if (clock.now() + pollMs > deadline) {
+      return { ...reading, reason: 'timeout', waitedSeconds: waited() }
+    }
+    await clock.sleep(pollMs)
+  }
+}
+
+function refuse(
+  reason: LaunchRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): LaunchRefused {
+  return { ok: false, reason, message, detail }
+}

package/tooling/claude/reference.md

@@ -16,7 +16,7 @@ The claude stack installs the Claude Code workflow into a project through `canon
 
 - `.canon/tasks/` holds one file per task plus a generated `index.md`, local scratch only, with `archive/` holding the tasks that shipped
 - `.canon/plans/` holds execution detail for multi-step tasks, and `canon tasks archive` moves a `feature-*.md` plan into `archive/` when the `post-merge` hook archives its task
-- `.canon/review/` holds the reports a review or measurement skill writes, such as `ux-measure-<slug>.md`
+- `.canon/review/` holds the reports a review or measurement skill writes, such as `ui-measure-<slug>.md`
 - `.canon/tmp/` is ephemeral scratch, safe to delete without loss
 - `.claude/worktrees/` is where `EnterWorktree` creates a linked worktree, which is why it stays under `.claude/`
 

package/claude/skills/canon-feedback-triage/REQUIREMENT.md

@@ -1,34 +0,0 @@
----
-name: canon-feedback-triage
-description: Why the feedback queue is read from GitHub rather than local scratch, and why triage files measured items instead of routing or implementing
----
-
-# Canon feedback triage requirement
-
-## Gap
-
-Without this skill, the feedback queue fills and nothing drains it. A local folder looks like the place to read and is the wrong one, since that scratch is per-machine and any cleanup removes it.
-
-Triage then fails three ways. An issue routes to a fix from a paragraph, which skips the scope argument. A self-contradicting report gets a guess instead of a question. The same issue gets filed twice because two passes cannot see the board carries it.
-
-## Must
-
-- Read the durable queue through the `gh` CLI rather than local session scratch, and stop when it is absent or unauthenticated
-- File one measured item per open issue into an intake folder, headed so an answer finds its issue, and name each skipped issue with its carrier
-- Measure each claim against the tree rather than carrying the issue's figures forward
-- Claim the folder through the CLI rather than picking an ordinal by hand
-- Report an empty queue as nothing open rather than widening the label to find work
-
-## Must not
-
-- Post to the remote, whether a comment, a close, or a label
-- Implement a fix or write a plan
-- Fill an answer slot, or read an empty one as agreement
-- Write outside the folder it claimed
-
-## Out of scope
-
-- Filing new feedback, which `canon-feedback` owns
-- Answering the filed items, which `plan-intake-answer` owns
-- Writing the plan a plan-worthy item needs, which `plan-feature` owns
-- Issues carrying any other label, which no skill here owns

package/claude/skills/canon-feedback-triage/SKILL.md

@@ -1,98 +0,0 @@
----
-name: canon-feedback-triage
-description: Files every open GitHub issue labeled `feedback` on the toolkit repo into an intake folder as one measured item each, skipping any issue the board already carries. Use when asked to "triage toolkit feedback", "work through the feedback issues", "process feedback issues", or "what feedback is open". Do NOT use to file new feedback (that is `canon-feedback`), to answer the filed items (that is `plan-intake-answer`), or for general GitHub issue triage unrelated to toolkit feedback.
-metadata:
-  family: upkeep
----
-
-# Canon feedback triage
-
-Consume the feedback queue that `canon feedback` fills. Each open `feedback` issue is measured against the tree and filed as one item for the operator, who answers it before anything is built.
-
-The record is an ordinary intake folder at `.canon/intake/<nn>-feedback-triage/`. Read `${CLAUDE_SKILL_DIR}/../plan-intake/references/intake.md` before writing any file in it, since it holds the item format, the frontmatter, the index shape, and the answer contract this skill is bound by.
-
-- Run from the toolkit repo root
-- Read GitHub issues and write only inside the claimed folder, posting no comment, close, or label to GitHub
-
-## Guards
-
-- Resolve `.canon/tasks/` and `.canon/intake/` at the main worktree root, from `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside git
-- If `gh` is not on PATH, stop: `❌ gh CLI not found. Install it to read feedback issues.`
-- If `gh auth status` fails, stop: `❌ gh is not authenticated. Run gh auth login.`
-- If no open `feedback` issues exist, stop: `✅ No open feedback issues.`
-
-### Slots and records
-
-Two more guards hold through every step.
-
-- Never fill a `You:` slot, and never read an empty one as agreement. Answering runs through `plan-intake-answer` or the operator's own edit.
-- Branch on each `canon` record's `ok` and `reason` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
-
-## Step 1: list the queue
-
-```bash
-gh issue list --label feedback --state open --limit 1000 --json number,title,body,labels
-```
-
-Take every issue. An issue without the `feedback` label does not surface here by design.
-
-## Step 2: drop what the board already carries
-
-An issue is carried when its number appears in a live or archived task's `Issue:` line under `.canon/tasks/`, or in an item heading of an existing `.canon/intake/` folder, written `(#NNN)`. Search both at the main root.
-
-Set each carried issue aside with its carrier, a task path or a folder and item. Name every one in the overview, so a re-run while an earlier folder sits unanswered files nothing twice. When every issue is carried, stop: `✅ Every open feedback issue is already on the board.`
-
-## Step 3: claim the folder
-
-Run `canon records ordinal intake feedback-triage --claim --json` and take its `name`. The verb creates the folder in the same act, so two sessions opening at once never share one. Where the installed binary carries no such subcommand, report it and stop rather than picking an ordinal by hand.
-
-## Step 4: measure each issue
-
-For each remaining issue, measure its claim against the tree during this pass, never carrying a figure from the issue forward, since it states what was true when filed.
-
-- Grep for the construct its defect names and count the sites
-- Check whether the behavior it asks for exists
-- Search the log for a commit or pull request that shipped it under another task
-- Run the issue's Repro section in a form that writes nothing when it is one command that works here, and say on `Problem:` what it showed
-- Mark the item `not reproduced here` when the repro names another project's paths or needs more, per `## Repro versus groundwork` in the intake standard
-
-Classify each against the toolkit's own surfaces:
-
-- **Direct fix.** A size, not an answer, so it suggests `plan` and `Fix:` says a short plan covers it. One surface, one file, no architectural choice. A typo, a stale reference, a one-line correction.
-- **Plan-worthy.** Multiple files, a new skill or rule, a behavior change, or a cross-surface move.
-- **Needs clarification.** The observed and expected behavior conflict or the surface is unnamed. The item asks the operator for the missing detail.
-
-Strip the reporting project's specifics from the fix, being its filenames, frameworks, deploy targets, and label values. The issue describes one project, and the fix serves every project that installs the toolkit.
-
-Name the commit the pass measured against in the overview.
-
-## Step 5: write the items
-
-Write one item per issue in the intake item format, one cluster file per domain the fix touches, numbered in read order. Head each item `### N. <defect> (#NNN)` so an answer finds its issue.
-
-- `Problem:` states what this pass measured, with the count, path, or commit behind it
-- `Fix:` states the class from Step 4 and the change it names
-- `Open:` reads `plan, ask, or decline?` on every item
-- `Suggested:` opens with exactly one of those tokens, then the reason
-- `You:` ships empty
-
-Write `00-overview.md` last, per the intake standard, with the counts by token, an open-questions list linking each item, the commit measured against, and every issue skipped in Step 2 with its carrier. Where the pass runs out of context before the index, write `99-next-session.md` naming the last issue filed.
-
-## Output
-
-```plaintext
-📂 Opened .canon/intake/<nn>-feedback-triage/
-
-**Filed:** <N> issues across <N> clusters, measured against <sha>
-**Skipped:** <n> already carried
-**Suggested:** <n> plan, <n> ask, <n> decline
-
-Next: /canon:plan-intake-answer to answer the `You:` slots
-```
-
-An answered plan item promotes through `task-board` with an `Issue: #NNN` line, and the shipping pull request's `Closes #NNN` drains the queue. Closing a declined issue on GitHub stays the operator's act.
-
-## Notes
-
-- The `feedback` label is what `canon feedback` and the `toolkit-feedback.yml` issue form both apply.
-- This skill files and never reimplements. `plan-intake-answer` owns the answers and `task-board` owns the task a plan item becomes.

package/claude/skills/plan-ready/REQUIREMENT.md

@@ -1,35 +0,0 @@
----
-name: plan-ready
-description: Why writing a ready folder, its overview, the thin plan, and the task row is one invocation rather than four hand writes, and where the boundary against the planning and shipping skills falls
----
-
-# Plan ready requirement
-
-## Gap
-
-A session handing finished files to a worker writes the folder, the overview, the plan, and the task row by hand, and the four drift. A destination missing from the plan's `## Files to touch` is invisible to `plan-reach`, so a second track writes the same file.
-
-Numbering scans one place, so an ordinal can reuse a number an archive already spent, and a bare phase label reserves nothing. A draft beside the real files, or no verbatim-source line, sends the worker off to write its own version. A main-root write from a worktree lands in a copy nobody reads, and the archive move goes unreported.
-
-## Must
-
-- Refuse before writing when the operator named no finished file or a named file does not resolve
-- Read the ordinal from the live folder and the archive together, and take the label from `canon tasks next-label --claim`, stopping on a binary that predates the flag
-- Derive the overview's `destinations` and the plan's `## Files to touch` from one list and compare them before reporting
-- Copy each finished file whole into the folder with nothing else, and write the plan's `## Constraints` line naming the folder as the verbatim source
-- Place the task's row by the branches `task-board` states, route main-root writes through `Bash`, and name the archive move in the closing report
-
-## Must not
-
-- Edit a finished file, since the worker copies verbatim
-- Hardcode a branch type or restate the folder shape
-- Write `priority.md` or `backlog.md` where an orchestrator is on the roster or the session is a worker or planner
-- Automate the archive move or start the worker
-
-## Out of scope
-
-- Writing a plan for a change nobody has written, which `plan-feature` owns
-- Copying the folder into a worktree and shipping it, which `role-worker` owns
-- A task file for a row with no ready folder, which `task-board` owns
-- Shipping a branch, which `git-ship` owns
-- The folder's shape and lifecycle, which `references/ready.md` owns

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

@@ -1,136 +0,0 @@
----
-name: plan-ready
-description: Writes a ready folder for finished files, its `00-overview.md`, the thin plan that points at it, and the task with a board row placed, reported to an orchestrator, or left to the operator, in one invocation. Use when asked to "write a ready folder", "hand these files to a worker", "package these finished files for a worker", "make a ready handoff", or when a session already holds the exact text of a skill, rule, or doc and a worker should copy it rather than author it. Do NOT use to plan a change nobody has written yet, which is `plan-feature`, to copy a folder into a worktree and ship it, which is `role-worker`, or to file a task with no finished files behind it, which is `task-board`.
-metadata:
-  family: generate
----
-
-# Plan ready
-
-A warm session that has already written a change hands the exact text to the worker that ships it. This skill writes the three artifacts that handoff needs and stops before anyone is dispatched.
-
-Read these in parallel before writing:
-
-- `${CLAUDE_SKILL_DIR}/references/ready.md`: the folder layout, the overview frontmatter, the mirrored tree, and the thin-plan contract
-- `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`: the plan's sections and its answer contract
-- `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`: the task file's shape and origin lines
-- `${CLAUDE_SKILL_DIR}/references/assembly.md`: the overview and thin-plan templates and the destination match check
-
-## Guards
-
-- If the operator named no finished file, stop: `❌ No finished file named. A ready folder carries text that already exists, so write the files first or use /canon:plan-feature.`
-- If a named file does not resolve, stop: `❌ <path> does not exist. Name a file that is already written.`
-- Resolve `<main-root>` as `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. The folder, the plan, and the task all live there.
-
-## Step 1: read the finished files
-
-1. Take each finished file with the destination path the operator gave it. A file arriving with no destination is asked for once, since the mirrored tree cannot place it.
-2. Read every file whole. The overview states what the worker still owns beyond copying, and that comes off the files, not off the operator's description of them.
-3. Take the branch type from `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`, never from a list carried here.
-4. Derive one kebab slug for the change. The folder, the plan, and the task all carry it.
-
-## Step 2: allocate the ordinal and the label
-
-Read `<main-root>/.canon/ready/` and `<main-root>/.canon/ready/archive/` together and take the highest `<nn>` across both, plus one. A folder set with no entry takes `01`. Keep this skill-local. No verb allocates a ready ordinal, and two writers running at once can claim one number, so re-read the folder immediately before Step 3 writes.
-
-Claim the label through the verb rather than reading it bare or scanning for it:
-
-```bash
-canon tasks next-label --claim --json
-```
-
-The claim reserves the label under `.canon/ordinal-locks/`, so a second session allocating at the same moment gets the next one. A bare read reserves nothing and can return a label a live claim already holds.
-
-Branch on the record's `reason` rather than on the exit code, taking `label` from a record that carries one.
-
-- `label-contended` means re-run the claim
-- Report the verb as unavailable and stop when the binary carries no `next-label` subcommand, or prints no record for an unknown `--claim`, since it predates the flag
-- Never fall back to a bare read or a label picked by hand, which reopens the collision the claim exists to prevent
-
-## Step 3: write the overview
-
-Write `<main-root>/.canon/ready/<nn>-<slug>/00-overview.md` from the template in `${CLAUDE_SKILL_DIR}/references/assembly.md`. Set `destinations` from the Step 1 list and nothing else, and state in prose what the worker still owns, or `nothing further` where the files are the whole change.
-
-## Step 4: mirror the tree
-
-Copy each finished file to `<main-root>/.canon/ready/<nn>-<slug>/<destination path>`, one command per file, so the tree mirrors the destinations exactly.
-
-```bash
-install -D -m 0644 <source> <main-root>/.canon/ready/<nn>-<slug>/<destination path>
-```
-
-- Copy whole and edit nothing. A change wanted now is made in the source file first and copied after.
-- Carry no notes, alternates, or drafts into the folder. Anything else belongs in the plan or the pull request body.
-- Write each of these at the main root, routed the way `session-worktree` states. Create a whole new file with a heredoc.
-
-## Step 5: write the thin plan
-
-Write `<main-root>/.canon/plans/feature-<slug>.md` from the template, by heredoc, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
-
-- List every Step 1 destination under `## Files to touch`, each with one clause on why it changes, pointing at the folder's copy rather than restating it.
-- Add a `## Constraints` line naming the ready folder as the verbatim source for those paths.
-- Name the branch type from Step 1 in `## Summary`. Write `None identified.` under `## Questions` unless a call is genuinely the operator's.
-
-Run the match check in `${CLAUDE_SKILL_DIR}/references/assembly.md` before going further. The two lists are one list, and a path in either without the other stops the run.
-
-## Step 6: write the task
-
-Write `<main-root>/.canon/tasks/<label>-<slug>.md` by heredoc from the label Step 2 claimed, never calling the verb again, which would claim another. Its frontmatter, H1, and `## Outcomes` follow `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`.
-
-Write a `Ready:` line beside the `Plan:` line pointing at the folder, then point the task at the plan through the verb:
-
-```bash
-canon tasks plan-link <task-stem> .canon/plans/feature-<slug>.md --json
-```
-
-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.
-
-### Place the row
-
-A task file with no row is a dropped task, so place the row in the same pass. The plan exists and no worker holds it yet, so the row takes `## Up next`, per the tests in `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`.
-
-A path `canon tasks plan-reach` reports as claimed is a shared file rather than a hold. Name each one and its holder wherever the row is reported, so whoever controls the board decides whether a contract, a relocation, or a sweep holds the row.
-
-### Check the roster
-
-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 same-repository row under another `sessionId` whose `name` starts with `orchestrator-`. A refused read counts as failed.
-
-- **Orchestrator found.** Write neither file. Message that session with the row's title, the plan link, and the group with its reason, so two sessions never write the board at once.
-- **Not found, and this session's name starts with `worker-` or `planner-`.** Write neither file, since both role bodies ban a board write. Report the row and its group in Step 8.
-- **Not found otherwise, or the roster read fails.** Run `canon tasks place <stem> --group up-next --waiting "Planned, not dispatched yet"`, since stopping on a failed read strands the task.
-
-Say which branch fired in Step 8.
-
-Regenerate the task index after writing, since a hook on `Write|Edit` never fires on `Bash`:
-
-```bash
-canon indexes regen .canon/tasks
-```
-
-## Step 7: validate
-
-```bash
-canon records validate plans --json
-canon markdown audit <main-root>/.canon/ready/<nn>-<slug>/00-overview.md
-canon markdown audit <main-root>/.canon/plans/feature-<slug>.md
-```
-
-Fix what the records name in the files this run wrote and re-run once. Report a finding on a file it did not write, such as a neighbor folder missing its overview, without repairing it.
-
-## Step 8: report
-
-```plaintext
-✅ Ready folder written: .canon/ready/<nn>-<slug>/
-   Plan: .canon/plans/feature-<slug>.md
-   Task: .canon/tasks/<label>-<slug>.md
-   Row: <label> <title>, <written under ## Up next | reported to <orchestrator name> | left for the operator to place>, <reason>
-   Archive on ship: canon tasks archive moves the folder to .canon/ready/archive/<nn>-<slug>/
-```
-
-Name the archive move every time, so whoever ships knows the verb carries the folder and needs no step of their own.
-
-## Rules
-
-- Edit no finished file. The worker copies verbatim, so a change belongs in the source before this runs.
-- Restate nothing the standards own. A shape question is answered by `ready.md` and a plan question by `plan.md`.
-- Dispatch nothing. Starting the worker belongs to whoever runs the board.

package/claude/skills/plan-ready/references/assembly.md

@@ -1,75 +0,0 @@
----
-name: assembly
-description: The overview and thin-plan templates for a ready folder, and the match check between the two lists of destinations
----
-
-# Assembly
-
-Loaded from Step 3 and Step 5 of `plan-ready`. The shape rules live in `${CLAUDE_SKILL_DIR}/references/ready.md` and `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, so this file holds the fill-in forms and the one check that compares them.
-
-## The overview
-
-```markdown
----
-title: <Change in sentence case>
-description: <one line naming what the handoff carries>
-type: <branch type from branch.md>
-destinations:
-  - <path/to/file>
----
-
-<What the files carry, one bullet each where a file's purpose is not its name.>
-
-<What the worker still owns beyond copying, or "nothing further".>
-```
-
-- Write `destinations` from the Step 1 list in the order the plan will list them.
-- Keep the prose to what the files cannot say themselves, such as a docs sync, a sandbox scenario, a test the folder does not carry, or the order a change lands in.
-
-## The thin plan
-
-```markdown
-# Feature: <short title>
-
-<Two or three sentences on why this ships as a copy rather than as an authoring job.>
-
-## Summary
-
-- <what the change does, one bullet per file group>
-- <branch type and what the worker still owns>
-
-## Constraints
-
-- `.canon/ready/<nn>-<slug>/` holds the verbatim source for every path below. Copy each file whole rather than reading it as a description and writing a version.
-- <a live plan or run row holding a path, when one exists>
-
-## Files to touch
-
-- `<path/to/file>`: copy from the ready folder, <one clause on what it changes>
-
-## Verification
-
-- <the command that proves the copy landed, or "None identified.">
-
-## Risks
-
-- <what could go wrong, or "None identified.">
-
-## Review focus
-
-- <an input the copied files must handle, or "None identified.">
-
-## Questions
-
-None identified.
-```
-
-## The destination match check
-
-Read the overview's `destinations` and the plan's `## Files to touch` paths, then compare the two sets:
-
-- A path in `destinations` and not in the plan is invisible to `plan-reach`, so the plan gains the line.
-- A path in the plan and not in `destinations` names a file the folder does not carry, so either the folder gains the file or the plan loses the line.
-- A path in either list with no file at that relative path inside the folder is a broken mirror. Report it and stop rather than writing a plan around a hole.
-
-Report the sets as equal, or name each path that differs and on which side. Do not report the check as passed without having read both lists.