@erclx/canon 4.8.0 → 4.9.0

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/src/teach/workspace.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
+import { buildDesignCss } from '@/design/css'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { type BodyLine, bodyLines } from '@/markdown/scan'
 import { recordDir } from '@/record-root'
@@ -841,3 +842,59 @@ export async function defineTerms(
 
   return { ok: true, slug: found.slug, path, defined: terms }
 }
+
+export interface StylesheetWritten {
+  readonly ok: true
+  readonly slug: string
+  /** Relative to the root, so a caller prints a path a reader can open. */
+  readonly path: string
+  /** False when the workspace already held one and this call left it alone. */
+  readonly written: boolean
+}
+
+export type StylesheetOutcome = StylesheetWritten | TeachRefused
+
+const STYLESHEET_BANNER = [
+  'Seeded by `canon teach stylesheet` from the design source in',
+  'src/design/tokens.ts. The tokens and the two components below are the',
+  'system this workspace renders in. Add lesson rules under them and read a',
+  'value through its custom property rather than restating the hex, which is',
+  'what let one workspace fork the palette from every other.',
+].join('\n   ')
+
+/**
+ * Writes a workspace's one stylesheet from the design source.
+ *
+ * Every workspace used to carry a hand-authored copy, which is how the course
+ * palette forked once per workspace. The name is fixed at `TEACH_STYLESHEET`
+ * and the folder at `TEACH_ASSETS` for the same reason a second lesson has to
+ * reach the file the first one wrote, and this is what puts the values in it.
+ *
+ * An existing stylesheet is left alone rather than replaced. A workspace adds
+ * lesson rules to this file as it goes, so overwriting would discard them, and
+ * `--force` is the caller saying it wants the seed back.
+ */
+export async function writeStylesheet(
+  root: string,
+  selector: string,
+  force = false,
+): Promise<StylesheetOutcome> {
+  const found = await readWorkspace(root, selector)
+  if (!found.ok) return found
+
+  const workspace = found.workspace
+  const rel = join(workspace.path, TEACH_ASSETS, TEACH_STYLESHEET)
+  const path = join(root, rel)
+
+  if (existsSync(path) && !force) {
+    return { ok: true, slug: workspace.slug, path: rel, written: false }
+  }
+
+  await mkdir(join(root, workspace.path, TEACH_ASSETS), { recursive: true })
+  await writeFile(
+    path,
+    buildDesignCss(undefined, { banner: STYLESHEET_BANNER }),
+  )
+
+  return { ok: true, slug: workspace.slug, path: rel, written: true }
+}

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.