@erclx/canon 4.7.0 → 4.8.1

package/src/commands/tasks.ts

@@ -81,7 +81,9 @@ export function register(program: Command): void {
 
   tasks
     .command('archive')
-    .description('Move a shipped task out of the board and clear its ordering')
+    .description(
+      'Move a shipped task and its plan out of the board and clear its ordering',
+    )
     .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
     .helpOption('-h, --help', 'Show this help message')
     .option(
@@ -93,6 +95,10 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'The task carries its plan with it when no other live task cites that',
+        'plan, and the archived task keeps a working Plan: pointer at the new',
+        'path. A plan several tasks share stays where it is.',
         '',
         'Exit codes:',
         '  0  the task was archived',
@@ -812,6 +818,11 @@ function report(
   logStep('Archived')
   logRemove(relative(root, outcome.from))
   logAdd(relative(root, outcome.to))
+  if (outcome.plan) {
+    logRemove(relative(root, outcome.plan.from))
+    logAdd(relative(root, outcome.plan.to))
+    logInfo('retargeted the Plan: line')
+  }
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   outro()
@@ -839,5 +850,11 @@ function recordFor(
     to: relative(root, outcome.to),
     priorityRowRemoved: outcome.priorityRowRemoved,
     indexRegenerated: outcome.indexRegenerated,
+    plan: outcome.plan
+      ? {
+          from: relative(root, outcome.plan.from),
+          to: relative(root, outcome.plan.to),
+        }
+      : null,
   }
 }

package/src/demo/drive.ts

@@ -20,15 +20,12 @@ declare global {
  * the demo feature adds lives here, and `src/commands/demo.ts` reaches it
  * through a dynamic import so no other command resolves the engine at startup.
  *
- * Unlike `@/capture/render`, this module ships. The capture command is excluded
- * from the published package because it regenerates images committed to this
- * repository, and that reason does not transfer to a command whose whole
- * purpose is running in someone else's project.
- *
  * It imports `playwright-core` rather than `@playwright/test`, which stays a
- * development dependency for the capture module. Shipping puts the import in
- * every target's dependency tree, and a target needs the driver rather than a
- * test runner and an assertion library. Both are pinned to one version rather
+ * development dependency the published tarball never carries. Shipping puts the
+ * import in every target's dependency tree, and a target needs the driver
+ * rather than a test runner and an assertion library. Every browser module here
+ * takes the same import for that reason, `@/capture/render` included since it
+ * started shipping too. Both are pinned to one version rather
  * than a range, because `bunx playwright install chromium` fetches the browser
  * revision the installed engine expects and a float would leave a target
  * resolving a binary its engine cannot launch.

package/src/driver/drive.ts

@@ -23,19 +23,18 @@ import type {
  * `src/commands/driver.ts` reaches it through a dynamic import so no other
  * command resolves the engine at startup.
  *
- * Like `@/demo/drive` and `@/inventory/walk`, and unlike `@/capture/render`,
- * this module ships. A command whose whole purpose is measuring someone else's
- * page cannot stay toolkit-only, and nothing here reaches into `@/capture/`,
- * which `files` in `package.json` excludes from the published package, so the
- * two surfaces move independently.
+ * Like `@/demo/drive`, `@/inventory/walk`, and `@/capture/render`, this module
+ * ships. A command whose whole purpose is measuring someone else's page cannot
+ * stay toolkit-only, and nothing here reaches into `@/capture/`, so the two
+ * surfaces move independently.
  *
  * What separates it from `canon capture` is the axis it adds. A render answers
  * about a page as it loads, and every defect that exists only after a menu
  * opens, an answer is chosen, or the page scrolls is invisible to one. Probes
  * therefore run after a step rather than on arrival, and a run reaches the load
- * state by opening with a `wait` step of its own. That matters most where
- * capture does not run, since it is toolkit-only and this command is then the
- * only thing measuring the page at all.
+ * state by opening with a `wait` step of its own. That matters most where no
+ * capture runs against the page, since this command is then the only thing
+ * measuring it at all.
  */
 
 /** Each probe keyed by the name a caller writes in the run. */

package/src/gate/measures.ts

@@ -100,7 +100,7 @@ export const SANDBOX_UNDECLARED_CEILING = 47
 export const AUDITS_BASELINE = '.claude/canon/baseline.json'
 
 export const HERO_STAMP_FAILURE =
-  'The hero set disagrees with the stamp written when the image was captured. Run canon capture assets/hero.html and commit all three files together.'
+  'The hero set disagrees with the stamp written when the image was captured. Run canon capture assets/hero.html --selector .window and commit all three files together.'
 
 function parseJson(payload: string): unknown {
   try {

package/src/gate/stages.ts

@@ -189,7 +189,7 @@ export const STAGES: readonly Stage[] = [
         kind: 'drift',
         pathspec: 'assets/hero.html',
         failure:
-          'Hero counts drifted. Run bun run check, then canon capture assets/hero.html, and commit assets/hero.html with assets/hero.png and assets/hero.stamp.',
+          'Hero counts drifted. Run bun run check, then canon capture assets/hero.html --selector .window, and commit assets/hero.html with assets/hero.png and assets/hero.stamp.',
       },
       { kind: 'measure', measure: heroStamp },
     ],

package/src/inventory/walk.ts

@@ -15,9 +15,9 @@ import type { Subject } from '@/inventory/subjects'
  * and `src/commands/inventory.ts` reaches it through a dynamic import so no
  * other command resolves the engine at startup.
  *
- * Like `@/demo/drive` and unlike `@/capture/render`, this module ships, because
- * a command whose whole purpose is running inside someone else's project cannot
- * stay toolkit-only.
+ * Like `@/demo/drive`, `@/driver/drive`, and `@/capture/render`, this module
+ * ships, because a command whose whole purpose is running inside someone else's
+ * project cannot stay toolkit-only.
  */
 
 /**

package/src/tasks/archive.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
-import { join, relative, resolve } from 'node:path'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { regenOne } from '@/indexes/regen'
 import { isUnder } from '@/paths'
 import { recordDir, recordDirs } from '@/record-root'
@@ -43,7 +43,6 @@ export const ARCHIVE_REFUSALS = [
   'ambiguous',
   'no-outcomes',
   'open-outcomes',
-  'plan-unswept',
   'bad-input',
 ] as const
 
@@ -53,6 +52,12 @@ export type TaskSelector =
   | { readonly kind: 'stem'; readonly stem: string }
   | { readonly kind: 'pull-request'; readonly number: number }
 
+/** A plan carried into the archive alongside the task that was its last citation. */
+export interface PlanMove {
+  readonly from: string
+  readonly to: string
+}
+
 export interface ArchiveSuccess {
   readonly ok: true
   readonly stem: string
@@ -60,6 +65,8 @@ export interface ArchiveSuccess {
   readonly to: string
   readonly priorityRowRemoved: boolean
   readonly indexRegenerated: boolean
+  /** Undefined when the task cited no live plan, or when another task still holds it. */
+  readonly plan: PlanMove | undefined
 }
 
 export interface ArchiveRefused {
@@ -142,16 +149,42 @@ export function readPullRequest(text: string): number | undefined {
   return match ? Number(match[1]) : undefined
 }
 
+/**
+ * The `Plan:` line in either form, the link's target captured ahead of the bare
+ * path. Padding is spaces and tabs rather than `\s`, which spans a newline, so
+ * the match ends at the line and the retarget below cannot swallow the blank
+ * line that follows it.
+ */
+const PLAN_PATTERN = /^Plan:[ \t]*(?:\[[^\]]*\]\(([^)]+)\)|(\S+))[ \t]*$/m
+
 /**
  * Reads the `Plan:` target out of a markdown link, falling back to the older
  * bare-path form. The path is returned as written, relative to the board.
  */
 export function readPlanTarget(text: string): string | undefined {
-  const match = /^Plan:\s*(?:\[[^\]]*\]\(([^)]+)\)|(\S+))\s*$/m.exec(text)
+  const match = PLAN_PATTERN.exec(text)
   if (!match) return undefined
   return match[1] ?? match[2]
 }
 
+/**
+ * Points the task's `Plan:` line at the plan's new home, as a markdown link
+ * whose text and target stay in step. The line is matched with the pattern the
+ * read above uses, so the archive rewrites exactly the line it parsed and never
+ * a second `Plan:` a task displays inside a fenced sample.
+ *
+ * The replacement is built by a function rather than passed as a string,
+ * because `$&` and its siblings are substitution sequences inside a replacement
+ * string. A plan filename carrying one would write a path nobody typed, and
+ * `.canon/plans/` is gitignored, so nothing recovers the pointer it replaced.
+ */
+export function retargetPlanLine(text: string, target: string): string {
+  const name = basename(target)
+  const label = name.endsWith('.md') ? name.slice(0, -'.md'.length) : name
+
+  return text.replace(PLAN_PATTERN, () => `Plan: [${label}](${target})`)
+}
+
 /**
  * Drops the archived task's row from the ordering table. Rows are matched by
  * the link they carry rather than by a line pattern, because a row holds links
@@ -476,28 +509,23 @@ export async function archiveTask(
     )
   }
 
-  const planTarget = readPlanTarget(text)
-  const livePlan = planTarget && resolveLivePlan(planTarget, dir, root)
-
-  // A live plan is unswept only when nothing else on the board holds it. A plan
-  // several tasks share stays live by design, so refusing on the folder alone
-  // parked every one of those tasks behind a sweep that was right to decline.
-  if (livePlan) {
-    const shared = await otherTasksCitingPlan(dir, root, livePlan, stem)
+  const plan = await planToArchive(dir, root, stem, text)
+  const destination = archiveDir(root)
+  const to = join(destination, `${stem}.md`)
 
-    if (shared.length === 0) {
-      return refuse(
-        'plan-unswept',
-        `${stem} is the last task pointing at a live plan. Run /claude-docs to sweep it first, then archive.`,
-        [planTarget],
-      )
-    }
+  // 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.
+  if (plan) {
+    await mkdir(dirname(plan.to), { recursive: true })
+    await rename(plan.from, plan.to)
   }
 
-  const destination = archiveDir(root)
   await mkdir(destination, { recursive: true })
-  const to = join(destination, `${stem}.md`)
   await rename(from, to)
+  if (plan)
+    await writeFile(to, retargetPlanLine(text, linkTo(destination, plan.to)))
 
   const priorityRowRemoved = await clearPriorityRow(dir, stem)
   const regen = await regenOne(dir, { dryRun: false })
@@ -509,9 +537,52 @@ export async function archiveTask(
     to,
     priorityRowRemoved,
     indexRegenerated: regen.action === 'written',
+    plan,
   }
 }
 
+/**
+ * The plan this task carries into the archive with it, or nothing. The merge is
+ * what settles a plan, and the hook reaches this with nobody watching, so the
+ * move sits inside the archive rather than in a second call that could leave
+ * the task archived and the plan live.
+ *
+ * A plan another live task still cites stays where it is. Moving it on the
+ * first task to close strands every other pointer at a path that has gone, and
+ * the sibling has no history behind it to repair the line from.
+ *
+ * A target resolving to no file yields nothing too. A pointer somebody typed
+ * wrong is not a plan to move, and refusing the whole archive over it would
+ * park the board behind a repair the merge cannot make.
+ */
+async function planToArchive(
+  dir: string,
+  root: string,
+  stem: string,
+  text: string,
+): Promise<PlanMove | undefined> {
+  const target = readPlanTarget(text)
+  const live = target && resolveLivePlan(target, dir, root)
+  if (!live || !existsSync(live)) return undefined
+
+  const shared = await otherTasksCitingPlan(dir, root, live, stem)
+  if (shared.length > 0) return undefined
+
+  return {
+    from: live,
+    to: join(recordDir(root, PLANS, ARCHIVE), basename(live)),
+  }
+}
+
+/**
+ * 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
+ * destinations rather than written as the `../plans/` the live task carried.
+ */
+function linkTo(taskDir: string, plan: string): string {
+  return relative(taskDir, plan).split(sep).join('/')
+}
+
 async function clearPriorityRow(dir: string, stem: string): Promise<boolean> {
   const path = join(dir, 'priority.md')
   if (!existsSync(path)) return false

package/src/tasks/validate.ts

@@ -5,6 +5,7 @@ import {
   archiveDir,
   isReservedStem,
   readOutcomes,
+  readPlanTarget,
   readPullRequest,
   tasksDir,
 } from '@/tasks/archive'
@@ -34,6 +35,8 @@ export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
 export const FINDING_KINDS = [
   'plan-unstated',
   'plan-unresolved',
+  'plan-uncited',
+  'plan-mismatched',
   'task-unresolved',
   'row-missing',
   'row-duplicated',
@@ -612,6 +615,78 @@ function checkPlans(
   return findings
 }
 
+/**
+ * Compares the two places one task's plan is written down. The `## Run now` row
+ * carries a `Plan` column and the task file carries its own `Plan:` line, and
+ * the archive reads the second while an operator reads the first, so a pair
+ * that disagrees settles the wrong plan on the merge.
+ *
+ * Both sides resolve before they compare. A row writing `../plans/x.md` and a
+ * task writing `.canon/plans/x.md` name one file, and comparing the strings
+ * would report every such pair as a mismatch.
+ */
+async function checkPlanAgreement(
+  rows: readonly BoardRow[],
+  dir: string,
+  root: string,
+): Promise<Finding[]> {
+  const ready = rows.filter((row) => row.group === 'Run now' && row.plan)
+
+  const found = await Promise.all(
+    ready.map(async (row) => planDisagreement(row, dir, root)),
+  )
+
+  return found.filter((finding): finding is Finding => finding !== undefined)
+}
+
+async function planDisagreement(
+  row: BoardRow,
+  dir: string,
+  root: string,
+): Promise<Finding | undefined> {
+  const subject = row.stem ?? row.label
+  if (!row.stem || !row.plan) return undefined
+
+  const file = join(dir, `${row.stem}.md`)
+  if (!existsSync(file)) return undefined
+
+  const target = readPlanTarget(await readFile(file, 'utf8'))
+  if (!target) {
+    return {
+      kind: 'plan-uncited',
+      group: 'Run now',
+      subject,
+      message: `is rowed against ${row.plan}, and the task file carries no Plan: line, so the archive settles no plan when it ships.`,
+    }
+  }
+
+  const rowed = planPath(row.plan, dir, root)
+  const cited = planPath(target, dir, root)
+  if (rowed === cited) return undefined
+
+  return {
+    kind: 'plan-mismatched',
+    group: 'Run now',
+    subject,
+    message: `is rowed against ${row.plan} and cites ${target} in its own Plan: line. One task names one plan.`,
+  }
+}
+
+/**
+ * Where a plan pointer lands, resolved against the board and against the
+ * project root the way the archive resolves the same line. Neither base
+ * existing leaves the board-relative reading, so two pointers at one absent
+ * file still compare equal and the mismatch check reports nothing.
+ */
+function planPath(target: string, dir: string, root: string): string {
+  const path = target.split('#')[0] || target
+  const fromBoard = resolve(dir, path)
+  if (existsSync(fromBoard)) return fromBoard
+
+  const fromRoot = resolve(root, path)
+  return existsSync(fromRoot) ? fromRoot : fromBoard
+}
+
 /**
  * The half of the `## Run now` test a person cannot check by eye. Two rows a
  * worker may be handed at once must touch disjoint files, and the `Touches`
@@ -984,6 +1059,7 @@ export async function validateBoard(
     ...shapeFindings,
     ...checkMapping(rows, backlog, stems, dir),
     ...checkPlans(rows, dir, root),
+    ...(await checkPlanAgreement(rows, dir, root)),
     ...checkCollisions(rows),
     ...checkOrdinals(rows),
     ...parked.findings,

package/standards/tasks.md

@@ -47,7 +47,7 @@ The handoff takes one file per session for the reason a task does. A single shar
 
 The catalog is the one reader that filters nothing, so it carries a row per sibling alongside the tasks. That is what a folder catalog is for, and the handoffs are what make it worth stating: a board accumulates one row per session that ever wrote one, with nothing pruning them. Anything reading the catalog as the backlog therefore does its own filtering, and a reader that takes every row as a task reports the handoffs as queued work.
 
-The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
+The `claude-tasks` skill creates and archives task files, and the archive carries the task's plan with it. `claude-docs` marks outcomes `[x]` in an existing file. Neither does the other's job.
 
 ## Ordering
 
@@ -247,8 +247,8 @@ The archive nests inside `.canon/tasks/` rather than sitting beside it as a flat
 
 One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.canon/plans/archive/`, sitting inside the folder it archives the same way, and it inherits the board's own ignore entry rather than needing one of its own. The cost is that an archived task does not appear in diffs, which is the cost the live board already carries.
 
-Archiving a task does not archive its plan. `claude-docs` owns the plans sweep and moves a plan only when the closing task is its last live citation, so the sweep runs before the archive rather than after it. The sweep finds its work by scanning the live folder, and a task archived first is beyond its reach for good, leaving the plan with no live task citing it and an archived task pointing at a path nothing will retarget.
+Archiving a task archives its plan alongside it, when the closing task is that plan's last live citation. The archived task's `Plan:` line is retargeted at `../../plans/archive/feature-<slug>.md`, a folder deeper than the live task wrote it, so a completed task still leads to the reasoning behind it. A plan several tasks share stays live and the task archives anyway, since moving it on the first task to close strands every sibling's pointer at a path that has gone.
 
-The `claude-docs` sweep states that ordering in its own body rather than reading it back from a command, which is a duplication accepted with a reason rather than an oversight. A skill reaches a target the moment it merges and the CLI reaches one only when a release publishes, so a body calling a verb the installed `canon` predates gets no record back and sweeps nothing. The two spellings therefore have to agree by hand until a release carries the verb, and the failure they guard against is a plan stranded by the form its citation was written in.
+One act rather than two is what makes the pair safe. The merge is the event that settles a plan, and a `post-merge` hook reaching the archive with nobody watching cannot act on a warning, so a second call after it would be a second failure point leaving the task archived and the plan live.
 
-A task with an open outcome stays on the board. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. The sweep is gated on the same condition, so archiving around an open outcome also leaves the plan behind.
+A task with an open outcome stays on the board, and so does its plan. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file.