@erclx/canon 4.69.0 → 4.70.0

package/src/tasks/archive.ts

@@ -8,6 +8,8 @@ import { recordDir, recordDirs } from '@/record-root'
 const TASKS = 'tasks'
 const PLANS = 'plans'
 const ARCHIVE = 'archive'
+const DECLINED = 'declined'
+const BACKLOG = 'backlog.md'
 
 /**
  * Siblings that sit on the board without being tasks: the generated index, the
@@ -48,6 +50,21 @@ export const ARCHIVE_REFUSALS = [
 
 export type ArchiveRefusal = (typeof ARCHIVE_REFUSALS)[number]
 
+/**
+ * Kept apart from `ARCHIVE_REFUSALS` on purpose. `archive` and `decline`
+ * answer different questions, shipped versus decided-against, and a shared
+ * refusal set would let one archive a task that cannot yet ship or decline
+ * one that already has.
+ */
+export const DECLINE_REFUSALS = [
+  'no-board',
+  'no-match',
+  'ambiguous',
+  'bad-input',
+] as const
+
+export type DeclineRefusal = (typeof DECLINE_REFUSALS)[number]
+
 export type TaskSelector =
   | { readonly kind: 'stem'; readonly stem: string }
   | { readonly kind: 'pull-request'; readonly number: number }
@@ -80,6 +97,27 @@ export interface ArchiveRefused {
 
 export type ArchiveOutcome = ArchiveSuccess | ArchiveRefused
 
+export interface DeclineSuccess {
+  readonly ok: true
+  readonly stem: string
+  readonly from: string
+  readonly to: string
+  readonly priorityRowRemoved: boolean
+  readonly backlogRowRemoved: 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 DeclineRefused {
+  readonly ok: false
+  readonly reason: DeclineRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export type DeclineOutcome = DeclineSuccess | DeclineRefused
+
 export interface TaskOutcomes {
   readonly open: readonly string[]
   readonly closed: readonly string[]
@@ -94,6 +132,10 @@ export function archiveDir(root: string): string {
   return recordDir(root, TASKS, ARCHIVE)
 }
 
+export function declinedDir(root: string): string {
+  return recordDir(root, TASKS, DECLINED)
+}
+
 export const OUTCOME_PATTERN = /^- \[([ xX])\] ?(.*)$/
 
 /**
@@ -238,6 +280,62 @@ export function retargetPlanLine(text: string, target: string): string {
   return text.replace(PLAN_PATTERN, () => planLine(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,
+ * unlike `planLine`.
+ */
+export function declineLine(reason: string, by: string, date: string): string {
+  return `Declined: ${reason}, ${by} on ${date}`
+}
+
+/**
+ * Lines a `Declined:` line anchors after, mirroring `record.ts`'s
+ * `ORIGIN_PREFIXES` with `Pull request:` folded in, since a decline can follow
+ * a pull request that never merged.
+ */
+const DECLINE_ANCHOR_PREFIXES = [
+  'Plan:',
+  'Groundwork:',
+  'Intake:',
+  'Issue:',
+  'Pull request:',
+] as const
+
+function lastAnchorLine(lines: readonly string[]): number | undefined {
+  let found: number | undefined
+
+  for (const [index, line] of lines.entries()) {
+    if (DECLINE_ANCHOR_PREFIXES.some((prefix) => line.startsWith(prefix))) {
+      found = index
+    }
+  }
+
+  return found
+}
+
+/**
+ * Places the `Declined:` line after the origin lines a task carries, the same
+ * scan-and-anchor shape `writePullRequestLine` carries. A decline runs once
+ * per task, so there is no existing line to correct, unlike the
+ * add/correct/unchanged shape a write safe to run twice needs.
+ */
+function insertDeclinedLine(text: string, line: string): string {
+  const lines = text.split('\n')
+  const anchor = lastAnchorLine(lines)
+
+  if (anchor !== undefined) {
+    lines.splice(anchor + 1, 0, line)
+    return lines.join('\n')
+  }
+
+  const heading = lines.findIndex((entry) => entry.startsWith('# '))
+  if (heading === -1) return `${line}\n${text}`
+
+  lines.splice(heading + 1, 0, '', line)
+  return lines.join('\n')
+}
+
 /**
  * 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
@@ -267,6 +365,27 @@ function isRowFor(line: string, target: string): boolean {
   return first !== undefined && first.includes(target)
 }
 
+/**
+ * Drops the declined task's bullet from the backlog. A backlog line is a
+ * bullet carrying a link rather than a table row, so the match is a bullet
+ * prefix and the link target rather than `isRowFor`'s pipe-delimited cell.
+ */
+export function removeBacklogRow(
+  text: string,
+  stem: string,
+): { readonly text: string; readonly removed: boolean } {
+  const target = `](${stem}.md)`
+  const lines = text.split('\n')
+  const kept = lines.filter((line) => !isBulletFor(line, target))
+
+  return { text: kept.join('\n'), removed: kept.length !== lines.length }
+}
+
+function isBulletFor(line: string, target: string): boolean {
+  const trimmed = line.trimStart()
+  return /^[-*]\s/.test(trimmed) && trimmed.includes(target)
+}
+
 /**
  * Resolves the `Plan:` target against the board and against the project root
  * both, which is how `docs-fold` reads the same line. It accepts `../plans/x.md`
@@ -481,11 +600,20 @@ async function matchByPullRequest(
   return read.filter((entry) => entry.number === number).map(({ stem }) => stem)
 }
 
-function refuse(
-  reason: ArchiveRefusal,
+/**
+ * Generic over the refusal vocabulary so `archiveTask` and `declineTask` share
+ * one builder despite answering with two disjoint reason sets.
+ */
+function refuse<Reason extends string>(
+  reason: Reason,
   message: string,
   detail: readonly string[] = [],
-): ArchiveRefused {
+): {
+  readonly ok: false
+  readonly reason: Reason
+  readonly message: string
+  readonly detail: readonly string[]
+} {
   return { ok: false, reason, message, detail }
 }
 
@@ -690,3 +818,78 @@ async function clearPriorityRow(dir: string, stem: string): Promise<boolean> {
 
   return removed
 }
+
+async function clearBacklogRow(dir: string, stem: string): Promise<boolean> {
+  const path = join(dir, BACKLOG)
+  if (!existsSync(path)) return false
+
+  const { text, removed } = removeBacklogRow(await readFile(path, 'utf8'), stem)
+  if (removed) await writeFile(path, text)
+
+  return removed
+}
+
+/**
+ * Declines one task as a single unit: the move, the ordering-or-backlog row
+ * removal, and the index regen. Unlike `archiveTask`, it carries no
+ * outcome-state gate, since a task decided against can sit at any outcome
+ * state, and the two never share a refusal set for the reason
+ * `DECLINE_REFUSALS` states.
+ */
+export async function declineTask(
+  root: string,
+  stem: string,
+  reason: string,
+  by: string,
+): Promise<DeclineOutcome> {
+  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(stem)) {
+    const unmatched = describeUnmatchedStem(stems, stem)
+    return refuse(unmatched.reason, unmatched.message, unmatched.detail)
+  }
+
+  const from = join(dir, `${stem}.md`)
+  const text = await readFile(from, 'utf8')
+
+  const plan = await planToArchive(dir, root, stem, text)
+  const destination = declinedDir(root)
+  const to = join(destination, `${stem}.md`)
+
+  // The plan moves first, the same order archiveTask uses, so the retarget
+  // written below describes a file already at its new path.
+  if (plan) {
+    await mkdir(dirname(plan.to), { recursive: true })
+    await rename(plan.from, plan.to)
+  }
+
+  await mkdir(destination, { recursive: true })
+  await rename(from, to)
+
+  const date = new Date().toISOString().slice(0, 10)
+  const declined = insertDeclinedLine(text, declineLine(reason, by, date))
+  const final = plan
+    ? retargetPlanLine(declined, linkTo(destination, plan.to))
+    : declined
+  await writeFile(to, final)
+
+  const priorityRowRemoved = await clearPriorityRow(dir, stem)
+  const backlogRowRemoved = await clearBacklogRow(dir, stem)
+  const regen = await regenOne(dir, { dryRun: false })
+
+  return {
+    ok: true,
+    stem,
+    from,
+    to,
+    priorityRowRemoved,
+    backlogRowRemoved,
+    indexRegenerated: regen.action === 'written',
+    plan,
+  }
+}

package/src/tasks/label.ts

@@ -1,6 +1,11 @@
 import { existsSync } from 'node:fs'
 import { relative } from 'node:path'
-import { archiveDir, listTaskStems, tasksDir } from '@/tasks/archive'
+import {
+  archiveDir,
+  declinedDir,
+  listTaskStems,
+  tasksDir,
+} from '@/tasks/archive'
 
 /** Every label in the corpus today stops here before rolling to the next major. */
 const MINOR_ROLLOVER = 9
@@ -68,9 +73,10 @@ function next(label: Label): Label {
 
 /**
  * Reports the next unused phase label, read off the true maximum across
- * `.canon/tasks/` and its `archive/` sibling together. A scan confined to the
- * live board is blind to every label the archive already spent, which is what
- * let two sessions hand out the same label within minutes of each other.
+ * `.canon/tasks/` and its `archive/` and `declined/` siblings together. A scan
+ * confined to the live board is blind to every label a settled folder already
+ * spent, which is what let two sessions hand out the same label within
+ * minutes of each other.
  *
  * It reports and never writes. Two sessions calling it in the same second can
  * still take the same answer, since the board is gitignored files rather than
@@ -90,8 +96,10 @@ export async function nextLabel(root: string): Promise<LabelOutcome> {
     }
   }
 
-  const archive = archiveDir(root)
-  const dirs = existsSync(archive) ? [dir, archive] : [dir]
+  const settled = [archiveDir(root), declinedDir(root)].filter((candidate) =>
+    existsSync(candidate),
+  )
+  const dirs = [dir, ...settled]
   const stems = (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
 
   const highest = stems

package/src/tasks/validate.ts

@@ -3,6 +3,7 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 import {
   archiveDir,
+  declinedDir,
   isReservedStem,
   readOutcomes,
   readPlanTarget,
@@ -47,6 +48,7 @@ export const FINDING_KINDS = [
   'touches-collided',
   'blocker-settled',
   'blocker-unresolved',
+  'blocker-declined',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -124,6 +126,7 @@ export interface ValidateReport {
   readonly rows: number
   readonly backlog: number
   readonly tasks: number
+  readonly declined: number
   readonly findings: readonly Finding[]
   readonly untested: readonly Untested[]
   readonly claims: readonly FolderClaim[]
@@ -970,6 +973,20 @@ async function checkCitedTask(
       return settled(group, subject, `waits on ${cited}, which is archived.`)
     }
 
+    if (existsSync(join(declinedDir(root), `${cited}.md`))) {
+      return {
+        findings: [
+          {
+            kind: 'blocker-declined',
+            group,
+            subject,
+            message: `waits on ${cited}, which was declined.`,
+          },
+        ],
+        untested: [],
+      }
+    }
+
     return {
       findings: [
         {
@@ -1158,6 +1175,10 @@ export async function validateBoard(
     : []
 
   const stems = await listTaskStems(dir)
+  const declinedPath = declinedDir(root)
+  const declined = existsSync(declinedPath)
+    ? await listTaskStems(declinedPath)
+    : []
   const parked = await checkParked(rows, root, trunk)
 
   const findings = [
@@ -1175,6 +1196,7 @@ export async function validateBoard(
     rows: rows.length,
     backlog: backlog.length,
     tasks: stems.length,
+    declined: declined.length,
     findings,
     untested: parked.untested,
     claims: checkFolderClaims(rows, root),

package/standards/plan.md

@@ -124,7 +124,7 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 - Write the plan before implementation starts, and treat it as the scope of the run that executes it.
 - Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
 - Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
-- Move the plan to `.canon/plans/archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.canon/plans/` rather than sitting beside it as `.claude/plans-archive/`, so an older layout is a flat sibling by that name and a current one is not.
+- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.canon/plans/` rather than sitting beside it as `.claude/plans-archive/`, so an older layout is a flat sibling by that name and a current one is not.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
 
 ## Anti-patterns

package/standards/tasks.md

@@ -31,6 +31,8 @@ Does not govern:
 ├── priority.md           ← hand-maintained execution order
 ├── backlog.md            ← unordered, what is not being scheduled
 ├── session-<slug>.md     ← optional, what a compaction is about to destroy
+├── archive/              ← shipped tasks, moved by canon tasks archive
+├── declined/             ← decided-against tasks, moved by canon tasks decline
 ├── v09.0-sync-paths.md      # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
 └── v13.0-toolkit-drift.md   # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
 ```
@@ -207,7 +209,7 @@ Every task names where it came from, through a `Plan:`, `Groundwork:`, `Intake:`
 
 A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track, an intake folder, or an open issue that no task points at is work already decided and on its way to being forgotten.
 
-An intake folder answers that direction at folder scope rather than item scope, since one dump dispositions many items and most close without ever becoming a task. What names a folder is every item answered and no task citing it, on the board or in the archive. That is a dump nobody acted on. Counting the archive beside the board is what separates it from one already promoted and shipped, and a check reading the board alone calls every finished folder abandoned.
+An intake folder answers that direction at folder scope rather than item scope, since one dump dispositions many items and most close without ever becoming a task. What names a folder is every item answered and no task citing it, on the board or in the archive. That is a dump nobody acted on. Counting the archive and declined folder beside the board is what separates it from one already promoted and settled, and a check reading the board alone calls every finished folder abandoned.
 
 `Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.canon/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
 
@@ -258,3 +260,15 @@ Archiving a task archives its plan alongside it, when the closing task is that p
 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, 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. Cutting means striking the outcome's body: `- ~~<outcome>~~ <why>`. `archiveTask` reads a struck body as cut whatever its checkbox holds, so a task carrying only cut outcomes still archives and a mixed task carries both counts on its success record.
+
+## Declining
+
+A task decided against moves to `.canon/tasks/declined/` rather than `.canon/tasks/archive/`. The two folders answer different questions: archive means the work shipped, declined means somebody decided against doing it. Neither reading fits a task that is merely unscheduled, which stays on `backlog.md` rather than moving anywhere, since nobody has decided against it and it may still rise when the board has room.
+
+`canon tasks decline` carries no outcome-state gate. A task can be decided against at any outcome state, open outcomes included, which is what separates its refusal set from archive's: the two never share one, since a shared gate would let one archive a task that cannot yet ship or decline one that already has.
+
+The decision is recorded on the task itself with a `Declined:` line, in the `Plan:`/`Pull request:` family: `Declined: <reason>, <who> on <YYYY-MM-DD>`. It anchors the same way `Pull request:` does, after the last origin line the task carries. The line is free prose after the colon, since it names no file to link.
+
+Declining a task moves its plan alongside it the same way archiving does, when the declining task is that plan's last live citation. A plan several tasks share stays where it is, and a declined task's plan lands in `.canon/plans/archive/` indistinguishable from a shipped one by folder alone. The task file under `.canon/tasks/declined/` is what records which it was.
+
+The move clears whichever of `priority.md` or `backlog.md` holds the task's row, since a decided-against task most often comes off the backlog before anyone plans it, but a row already promoted to the ordering file is cleared the same way archive clears it.