@erclx/canon 4.68.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/src/teach/nav.ts

@@ -109,6 +109,17 @@ const GLOSSARY_FILTER_SCRIPT = `<script>
   var input = document.getElementById("gfilter");
   var list = document.getElementById("gloss");
   if (!input || !list) return;
+  function updateGroups() {
+    list.querySelectorAll(".gloss-group").forEach(function (heading) {
+      var el = heading.nextElementSibling;
+      var any = false;
+      while (el && !el.classList.contains("gloss-group")) {
+        if (el.style.display !== "none") any = true;
+        el = el.nextElementSibling;
+      }
+      heading.style.display = any ? "" : "none";
+    });
+  }
   input.addEventListener("input", function () {
     var q = input.value.toLowerCase();
     var n = 0;
@@ -118,6 +129,7 @@ const GLOSSARY_FILTER_SCRIPT = `<script>
       if (match) n++;
     });
     list.classList.toggle("none", n === 0);
+    updateGroups();
   });
   var clear = list.querySelector(".clear");
   if (clear) {
@@ -457,8 +469,90 @@ function renderGlossaryEntry(entry: string): string {
   return `<div class="gterm"><b>${escapeHtml(term)}</b><span>${escapeHtml(definition)}</span></div>`
 }
 
-function renderGlossarySection(entries: readonly string[]): string {
-  const rendered = entries.map(renderGlossaryEntry).join('')
+const FIRST_SEEN_PATTERN = / First seen in (.+)\.$/
+
+/**
+ * The lesson or reference page an entry's own "First seen in" sentence
+ * names, absent when the entry predates that citation convention.
+ */
+function firstSeenFile(entry: string): string | undefined {
+  return FIRST_SEEN_PATTERN.exec(entry)?.[1]
+}
+
+/**
+ * `firstSeenFile` names a page free-form, per the `--first-seen` flag it
+ * comes from, so it may carry a directory prefix a lesson's own `file` does
+ * not. Comparing basenames is what keeps `lessons/0001-x.html` and
+ * `0001-x.html` resolving to the same lesson without a suffix match risking
+ * a false hit across two differently-prefixed filenames.
+ */
+function matchingLesson(
+  file: string,
+  metas: readonly LessonMeta[],
+): LessonMeta | undefined {
+  const basename = file.split('/').pop()
+  return metas.find((meta) => meta.file === basename)
+}
+
+interface GlossaryGroup {
+  readonly heading: string
+  readonly entries: readonly string[]
+}
+
+const OTHER_TERMS_HEADING = 'Other terms'
+
+/**
+ * Groups already-alphabetical glossary entries by the lesson their own
+ * "First seen in" sentence names, in lesson order. An entry naming a
+ * reference page instead, or carrying no citation at all, cannot be
+ * attributed to a lesson and trails in its own group, keeping the
+ * alphabetical order the source entries already carry.
+ */
+function groupGlossaryEntries(
+  entries: readonly string[],
+  metas: readonly LessonMeta[],
+): readonly GlossaryGroup[] {
+  const byLesson = new Map<string, string[]>()
+  const other: string[] = []
+
+  for (const entry of entries) {
+    const file = firstSeenFile(entry)
+    const lesson = file ? matchingLesson(file, metas) : undefined
+
+    if (lesson) {
+      const list = byLesson.get(lesson.file) ?? []
+      list.push(entry)
+      byLesson.set(lesson.file, list)
+    } else {
+      other.push(entry)
+    }
+  }
+
+  const groups: GlossaryGroup[] = []
+  for (const meta of metas) {
+    const list = byLesson.get(meta.file)
+    if (list) groups.push({ heading: meta.title, entries: list })
+  }
+  if (other.length > 0) {
+    groups.push({ heading: OTHER_TERMS_HEADING, entries: other })
+  }
+
+  return groups
+}
+
+function renderGlossaryGroup(group: GlossaryGroup): string {
+  const entries = group.entries.map(renderGlossaryEntry).join('')
+
+  return `<h3 class="gloss-group">${escapeHtml(group.heading)}</h3>${entries}`
+}
+
+function renderGlossarySection(
+  entries: readonly string[],
+  metas: readonly LessonMeta[],
+): string {
+  const rendered = groupGlossaryEntries(entries, metas)
+    .map(renderGlossaryGroup)
+    .join('')
 
   return `<h2>Glossary <span class="count">${entries.length}</span></h2>
 <input class="filter" type="search" id="gfilter" aria-label="Filter glossary terms" aria-controls="gloss" placeholder="term">
@@ -610,7 +704,7 @@ async function renderContentsPage(
     referenceRows
       ? `<h2>Reference pages</h2>\n<ul class="toc">${referenceRows}</ul>`
       : '',
-    renderGlossarySection(detail.glossary),
+    renderGlossarySection(detail.glossary, metas),
   ]
     .filter((section) => section !== '')
     .join('\n\n')

package/standards/glossary.md

@@ -58,6 +58,14 @@ A glossary failing these is non-conforming even when it satisfies every shape ru
 - Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
 - State a departure from any rule above in the file itself, naming what it departs from and why. A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name.
 
+## Rendered grouping
+
+Applies to a rendered glossary page, never to the source file above, which stays the flat alphabetical list the `## Grouping` rules above govern.
+
+- Group a rendered glossary by the lesson its own "First seen in" citation names, ordered by lesson order, under a sub-heading naming the lesson's title rather than its filename.
+- Trail with an "Other terms" group holding any entry the citation cannot attribute to a lesson, whether it names a reference page instead or carries no citation at all. Keep it in the alphabetical order the source file already carries.
+- Keep the workspace-wide term filter matching against every group, and drop a group's own heading once filtering leaves nothing under it.
+
 ## Template
 
 ```markdown

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.