@erclx/canon 4.121.0 → 4.122.0

package/src/records/stale.ts

@@ -0,0 +1,243 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+import {
+  CREATION_ROOT,
+  RECORD_ROOTS,
+  recordDir,
+  SCRATCH,
+  spell,
+} from '@/record-root'
+
+/** The window after which a reviewed entry is due again, in days. */
+export const DEFAULT_REVIEW_DAYS = 30
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+const MEMORY_INDEX = 'index.md'
+
+export interface StaleEntry {
+  /** The filename stem, which is what a review names an entry by. */
+  readonly name: string
+  readonly category: string | null
+  /** `YYYY-MM-DD`, or null when the entry carries no readable review date. */
+  readonly reviewed: string | null
+  /** The raw value of a `reviewed` field that is not a date, present only then. */
+  readonly invalidReviewed?: string
+  readonly due: boolean
+  /** Backticked paths the entry cites that the project root does not hold. */
+  readonly unresolved: readonly string[]
+}
+
+export interface StaleReport {
+  readonly ok: true
+  readonly root: string
+  /** The pen read, relative to the root. */
+  readonly folder: string
+  readonly days: number
+  readonly total: number
+  readonly due: number
+  readonly entries: readonly StaleEntry[]
+}
+
+export const STALE_REFUSALS = ['no-folder'] as const
+
+export type StaleRefusal = (typeof STALE_REFUSALS)[number]
+
+export interface StaleRefused {
+  readonly ok: false
+  readonly reason: StaleRefusal
+  readonly message: string
+}
+
+export type StaleOutcome = StaleReport | StaleRefused
+
+const REVIEWED_FIELD = /^reviewed:[ \t]*(.*?)[ \t]*$/m
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const RAW_FRONTMATTER = /^---\n([\s\S]*?)\n---/
+
+/**
+ * Reads `reviewed` off the raw block rather than the parsed fields, for the
+ * reason `hasOpeningDate` in the validator gives: a YAML parser resolves a
+ * bare `YYYY-MM-DD` to a date on one schema and a string on another.
+ *
+ * A value that is not a calendar date reads as never reviewed and is carried
+ * back so the review can see it, rather than throwing over one hand edit.
+ */
+function readReviewed(
+  text: string,
+): Pick<StaleEntry, 'reviewed' | 'invalidReviewed'> {
+  const block = RAW_FRONTMATTER.exec(text)?.[1]
+  const match = block ? REVIEWED_FIELD.exec(block) : null
+  if (!match) return { reviewed: null }
+
+  const value = match[1].replace(/^(['"])(.*)\1$/, '$2')
+  const parsed = Date.parse(`${value}T00:00:00Z`)
+  const isDate =
+    ISO_DATE.test(value) &&
+    Number.isFinite(parsed) &&
+    new Date(parsed).toISOString().slice(0, 10) === value
+
+  return isDate
+    ? { reviewed: value }
+    : { reviewed: null, invalidReviewed: value }
+}
+
+/**
+ * Tokens that name a session record, scratch at either root, or a checkout,
+ * none of which a tree commits. The scratch spellings come from `spell` so the
+ * legacy root's variant is stated in one place.
+ */
+const UNTRACKED_PREFIXES = [
+  ...RECORD_ROOTS.map((at) => `${at}/${spell(at, SCRATCH)}/`),
+  `${CREATION_ROOT}/`,
+  '.claude/worktrees/',
+]
+
+const INLINE_CODE = /`([^`\n]+)`/g
+const LINE_ANCHOR = /:\d+(?:[-:]\d+)*$/
+const FILE_EXTENSION = /\.[A-Za-z0-9]+$/
+
+/**
+ * Reduces one backticked token to the repository path it cites, or undefined
+ * when it cites none.
+ *
+ * A path is a token carrying a `/` and ending in a file extension once any
+ * line or heading anchor is stripped. A placeholder, an elided path, a glob, a
+ * variable, a URL, and a path outside the project all look like paths and
+ * resolve against nothing in the tree, so each is dropped rather than reported.
+ */
+function toCitedPath(token: string): string | undefined {
+  if (/\s/.test(token) || token.includes('://')) return undefined
+  if (/[<*{$]/.test(token) || token.includes('...')) return undefined
+  if (/^(?:\/|~|\.\.\/)/.test(token)) return undefined
+
+  const path = token
+    .replace(/#.*$/, '')
+    .replace(LINE_ANCHOR, '')
+    .replace(/^\.\//, '')
+
+  if (!path.includes('/') || !FILE_EXTENSION.test(path)) return undefined
+  if (UNTRACKED_PREFIXES.some((prefix) => path.startsWith(prefix)))
+    return undefined
+
+  return path
+}
+
+/** Every distinct repository path a body cites in inline code, in order. */
+export function citedPaths(body: string): string[] {
+  const paths = new Set<string>()
+
+  for (const match of body.matchAll(INLINE_CODE)) {
+    const path = toCitedPath(match[1])
+    if (path) paths.add(path)
+  }
+
+  return [...paths]
+}
+
+function isDue(reviewed: string | null, days: number, now: number): boolean {
+  if (reviewed === null) return true
+  return now - Date.parse(`${reviewed}T00:00:00`) > days * DAY_MS
+}
+
+async function readEntry(
+  root: string,
+  dir: string,
+  file: string,
+  days: number,
+  now: number,
+): Promise<StaleEntry> {
+  const text = (await readFile(join(dir, file), 'utf8')).replaceAll(
+    '\r\n',
+    '\n',
+  )
+  const frontmatter = parseFrontmatter(text)
+  const review = readReviewed(text)
+  const body = text.slice(RAW_FRONTMATTER.exec(text)?.[0].length ?? 0)
+
+  return {
+    name: file.replace(/\.md$/, ''),
+    category: readField(frontmatter, 'category') ?? null,
+    ...review,
+    due: isDue(review.reviewed, days, now),
+    unresolved: citedPaths(body).filter(
+      (path) => !existsSync(join(root, path)),
+    ),
+  }
+}
+
+/**
+ * The order a review takes a batch in: due entries first, and among them the
+ * ones citing a tree that moved, then the longest unreviewed, then by name so
+ * two runs over one pen agree.
+ */
+function compareEntries(left: StaleEntry, right: StaleEntry): number {
+  if (left.due !== right.due) return left.due ? -1 : 1
+
+  const leftMoved = left.unresolved.length > 0
+  const rightMoved = right.unresolved.length > 0
+  if (leftMoved !== rightMoved) return leftMoved ? -1 : 1
+
+  if (left.reviewed !== right.reviewed) {
+    if (left.reviewed === null) return -1
+    if (right.reviewed === null) return 1
+    return left.reviewed < right.reviewed ? -1 : 1
+  }
+
+  return left.name.localeCompare(right.name)
+}
+
+/**
+ * Reports each memory entry's review state and the paths it cites that the
+ * project no longer holds, ordered so a caller takes the first N as a batch.
+ *
+ * It reads the top level of the pen alone. `review/` holds receipts and
+ * `archive/` holds retirements, and neither is an entry a review would queue.
+ * Paths resolve against the project root rather than the entry's folder, since
+ * an entry cites the tree it was written about. It reports and never writes.
+ *
+ * `now` is a parameter so a test can pin the window against fixture dates.
+ */
+export async function staleMemory(
+  root: string,
+  days: number = DEFAULT_REVIEW_DAYS,
+  now: number = Date.now(),
+): Promise<StaleOutcome> {
+  const dir = recordDir(root, 'memory')
+
+  if (!existsSync(dir)) {
+    return {
+      ok: false,
+      reason: 'no-folder',
+      message: `No memory folder at ${dir}, so there are no entries to read.`,
+    }
+  }
+
+  const listed = await readdir(dir, { withFileTypes: true })
+  const files = listed
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        entry.name.endsWith('.md') &&
+        entry.name !== MEMORY_INDEX,
+    )
+    .map((entry) => entry.name)
+
+  const entries = (
+    await Promise.all(
+      files.map((file) => readEntry(root, dir, file, days, now)),
+    )
+  ).toSorted(compareEntries)
+
+  return {
+    ok: true,
+    root,
+    folder: relative(root, dir),
+    days,
+    total: entries.length,
+    due: entries.filter((entry) => entry.due).length,
+    entries,
+  }
+}

package/src/sandbox/expect.ts

@@ -178,7 +178,7 @@ function contentArray(value: unknown): ContentAssertion[] {
     // A bare key written below a `[[content]]` header belongs to that table in
     // TOML, not to the document, so a declaration listing `manual` or
     // `max_turns` after its content blocks parses clean and silently asserts
-    // neither. The arm then named `claude/ui-test`, now
+    // neither. The arm then named `claude/ui-test` (canon-keep-retired), now
     // `claude/ui-checklist`, shipped that way: a turn ceiling that
     // never ran and five manual entries that never reached the unchecked count,
     // while `canon sandbox coverage` counted the arm as armed. Nothing at the

package/src/tasks/archive.ts

@@ -269,6 +269,30 @@ export function readPlanTarget(text: string): string | undefined {
   return match[1] ?? match[2]
 }
 
+/**
+ * Reads every target the first `Plan:` line outside a fenced sample carries,
+ * falling back to the bare-path form. `readPlanTarget` answers only a line
+ * holding exactly one pointer, so this is how a caller tells a line linking
+ * several plans apart from no line at all.
+ */
+export function readPlanTargets(text: string): readonly string[] {
+  const lines = text.split('\n')
+  const fenced = fenceMask(lines)
+  const line = lines.find(
+    (candidate, index) => !fenced[index] && candidate.startsWith('Plan:'),
+  )
+  if (line === undefined) return []
+
+  const rest = line.slice('Plan:'.length)
+  const links = [...rest.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)].map(
+    (match) => match[1],
+  )
+  if (links.length > 0) return links
+
+  const bare = /^[ \t]*(\S+)/.exec(rest)
+  return bare ? [bare[1]] : []
+}
+
 /**
  * Builds a `Plan:` line as a markdown link whose text and target stay in step,
  * the label taken from the target's filename with its extension dropped.
@@ -431,7 +455,7 @@ function isBulletFor(line: string, target: string): boolean {
 
 /**
  * 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`
+ * both, which is how `context-fold` reads the same line. It accepts `../plans/x.md`
  * and `.canon/plans/x.md` as one file, so a gate reading only the first form
  * would pass the second and strand the plan this exists to protect.
  *
@@ -485,7 +509,7 @@ function atOneRoot(path: string, plans: string[], root: string): string {
 
 /**
  * Names the other live tasks whose `Plan:` line lands on the same file. This is
- * the rule `docs-fold` applies before it archives a plan, held here so one
+ * the rule `context-fold` applies before it archives a plan, held here so one
  * question has one implementation: a plan another live task still cites is a
  * plan the sweep is correct to leave, and a guard that read the folder instead
  * refused every task sharing one plan and deadlocked the board against the
@@ -542,7 +566,7 @@ export type CitationOutcome = PlanCitations | ArchiveRefused
 
 /**
  * Answers where one task's plan sits and who else holds it, which is the whole
- * of the last-live-citation rule. `docs-fold` reads this rather than scanning
+ * of the last-live-citation rule. `context-fold` reads this rather than scanning
  * the board itself, so the sweep that moves a plan and the gate that refuses a
  * task archive cannot drift into disagreeing about which plan is free.
  *
@@ -758,7 +782,7 @@ export async function archiveTask(
   const from = join(dir, `${stem}.md`)
   const text = await readFile(from, 'utf8')
 
-  // `docs-fold` ticks outcomes at ship time, before the merge, so an earlier
+  // `context-fold` ticks outcomes at ship time, before the merge, so an earlier
   // slice merging after the last slice shipped would find every box ticked
   // while the last slice is still open. Only the last number closes the task.
   const last = readPullRequest(text).at(-1)

package/src/tasks/record.ts

@@ -353,7 +353,7 @@ export async function recordPlan(
 }
 
 /**
- * Marks the named outcomes `[x]` in place. `docs-fold` runs this against a
+ * Marks the named outcomes `[x]` in place. `context-fold` runs this against a
  * board it can read and cannot edit from a linked worktree, and the positions
  * come from the read it already made.
  */

package/src/tasks/validate.ts

@@ -7,6 +7,7 @@ import {
   isReservedStem,
   readOutcomes,
   readPlanTarget,
+  readPlanTargets,
   readPullRequest,
   resolveLivePlan,
   tasksDir,
@@ -41,6 +42,7 @@ export const FINDING_KINDS = [
   'plan-mismatched',
   'plan-parked',
   'plan-absent',
+  'plan-several',
   'task-unresolved',
   'row-duplicated',
   'row-misshapen',
@@ -563,7 +565,7 @@ async function listTaskStems(dir: string): Promise<string[]> {
 
 /**
  * Resolves a pointer against the board and against the project root both, the
- * way `docs-fold` reads the same line. A fragment is dropped first, since an
+ * way `context-fold` reads the same line. A fragment is dropped first, since an
  * anchor is part of the link and never part of the path.
  */
 function resolves(target: string, dir: string, root: string): boolean {
@@ -728,8 +730,12 @@ async function planDisagreement(
   const file = join(dir, `${row.stem}.md`)
   if (!existsSync(file)) return undefined
 
-  const target = readPlanTarget(await readFile(file, 'utf8'))
+  const text = await readFile(file, 'utf8')
+  const target = readPlanTarget(text)
   if (!target) {
+    const several = severalPlans(text, 'Run now', subject)
+    if (several) return several
+
     return {
       kind: 'plan-uncited',
       group: 'Run now',
@@ -787,7 +793,13 @@ async function groupClaimFinding(
   const file = join(dir, `${row.stem}.md`)
   if (!existsSync(file)) return undefined
 
-  const target = readPlanTarget(await readFile(file, 'utf8'))
+  const text = await readFile(file, 'utf8')
+  const target = readPlanTarget(text)
+  if (!target) {
+    const several = severalPlans(text, row.group, row.stem)
+    if (several) return several
+  }
+
   const live = target ? resolveLivePlan(target, dir, root) : undefined
   const hasLivePlan = live !== undefined && existsSync(live)
 
@@ -814,6 +826,27 @@ async function groupClaimFinding(
   return undefined
 }
 
+/**
+ * Reports a `Plan:` line linking more than one plan. `readPlanTarget` reads
+ * such a line as naming nothing, so without this a caller would report the
+ * line as absent when it is there and breaks the one-plan rule instead.
+ */
+function severalPlans(
+  text: string,
+  group: Finding['group'],
+  subject: string,
+): Finding | undefined {
+  const targets = readPlanTargets(text)
+  if (targets.length < 2) return undefined
+
+  return {
+    kind: 'plan-several',
+    group,
+    subject,
+    message: `cites ${targets.length} plans on its Plan: line (${targets.join(', ')}). One task names one plan, so split the task or drop the extra links.`,
+  }
+}
+
 /**
  * Where a plan pointer lands, resolved against the board and against the
  * project root the way the archive resolves the same line. Neither base

package/standards/memory.md

@@ -56,19 +56,21 @@ Write no entry for a fact another surface already owns. A fact about a domain be
 
 ## Frontmatter
 
-Every entry carries all three fields.
+Every entry carries the three required fields, and a reviewed entry carries a fourth.
 
 ```yaml
 ---
 title: A scope glob wide enough for a correct run can be wide enough for every wrong one
 description: Omit a declaration key whose only passing value admits the whole tree
 category: Project
+reviewed: 2026-09-26
 ---
 ```
 
 - `title` (required): the rule stated as a line a reader can act on, in sentence case.
 - `description` (required): one line naming what the entry settles, so a reader scanning the catalog decides whether to open it.
 - `category` (required): the type in sentence case, which is what groups the catalog.
+- `reviewed` (optional): the `YYYY-MM-DD` date a review last read the entry and kept it. A review writes it and capture never does, so an entry without the field has never been reviewed. A rewrite of the entry carries the field through untouched, since dropping it sends a kept entry back to the front of the queue.
 
 Never write the filename stem as the `title`. The stem is a slug, and an entry titled with it reads as an unwritten file in every catalog that renders the field.
 
@@ -103,6 +105,16 @@ Link a related entry as `[[name]]`, where `name` is the target's filename stem w
 
 The catalog is generated from sibling frontmatter rather than authored. Never hand-edit it, since the next regeneration discards whatever was added by hand.
 
+## Reading
+
+Nothing loads the pen into every session, and that is the design. An entry reaches a reader through one of three paths:
+
+- A review reads the pen in batches, taking entries in the order `canon records stale memory` reports: due entries first, those citing a path the tree no longer holds ahead of the rest, then the longest unreviewed.
+- A resuming session reads the entries matching the task it picks up.
+- Capture reads the catalog to find an existing entry on the same topic before writing a new one.
+
+An entry none of the three reaches is one the pen holds for a review to promote or retire.
+
 ## Collecting a review receipt
 
 A review of the pen writes a receipt recording what it proposed per entry and what was decided. The receipt is collected once every item on it has resolved, and it is held while any item is still pending, since a pending item is decision state the next round reads back.

package/standards/tasks.md

@@ -51,7 +51,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 `task-board` skill creates and archives task files, and the archive carries the task's plan with it. `docs-fold` marks outcomes `[x]` in an existing file. Neither does the other's job.
+The `task-board` skill creates and archives task files, and the archive carries the task's plan with it. `context-fold` marks outcomes `[x]` in an existing file. Neither does the other's job.
 
 ## Ordering
 

package/tooling/astro/reference.md

@@ -58,7 +58,7 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``. <!-- audit-ignore-citations: canon/context/ci.md -->
 
 ## Social card route
 

package/tooling/base/configs/.husky/post-merge

@@ -7,7 +7,7 @@
 # to hand a worker. This is the only event that lands after a merge.
 #
 # Candidates rather than closed tasks, because an all-`[x]` board entry does not
-# mean the work merged. `docs-fold` marks outcomes on the branch as step 1 of
+# mean the work merged. `context-fold` marks outcomes on the branch as step 1 of
 # the ship chain, so a task can read closed while its pull request is still open
 # or already abandoned. The board is gitignored and an archived task has nothing
 # to recover it, so `task-board` confirms the work is on `main` before moving

package/tooling/claude/reference.md

@@ -25,7 +25,7 @@ canon/
 .canon/
 ├── tasks/             ← seeded. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
 ├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
-├── plans/             ← execution detail for multi-step tasks. `feature-*.md` entries swept by docs-fold into `archive/`.
+├── plans/             ← execution detail for multi-step tasks. `feature-*.md` entries swept by context-fold into `archive/`.
 ├── review/            ← one subfolder per producer. `branch/` for review-branch, `feedback/` for canon feedback, `memory/` for memory-review with its own `archive/`, `design/` for canon design render.
 ├── tmp/               ← ephemeral scratch space, safe to delete without loss
 └── memory/            ← session facts no context entry owns. `index.md` regenerated by a hook.

package/tooling/go/reference.md

@@ -57,4 +57,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `go vet ./...` passes ``. Add a Lint row whose assertion reads: `` `golangci-lint run` passes ``. Add a Tests row whose assertion reads: `` `go test -race ./...` exits 0 ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `go vet ./...` passes ``. Add a Lint row whose assertion reads: `` `golangci-lint run` passes ``. Add a Tests row whose assertion reads: `` `go test -race ./...` exits 0 ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/nextjs/reference.md

@@ -50,4 +50,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `next typegen && tsc --noEmit` passes ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `next typegen && tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/php/reference.md

@@ -71,4 +71,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `phpstan analyse` passes ``. Add a Lint row whose assertion reads: `` `php-cs-fixer check` passes ``. Add a Tests row whose assertion reads: `` `phpunit` exits 0 ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `phpstan analyse` passes ``. Add a Lint row whose assertion reads: `` `php-cs-fixer check` passes ``. Add a Tests row whose assertion reads: `` `phpunit` exits 0 ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/python/reference.md

@@ -62,4 +62,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `mypy .` passes ``. Add a Lint row whose assertion reads: `` `ruff check` and `ruff format --check` pass ``. Add a Tests row whose assertion reads: `` `pytest` exits 0 ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `mypy .` passes ``. Add a Lint row whose assertion reads: `` `ruff check` and `ruff format --check` pass ``. Add a Tests row whose assertion reads: `` `pytest` exits 0 ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/vite-react/reference.md

@@ -52,4 +52,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `tsc --noEmit` passes ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/web/reference.md

@@ -84,7 +84,7 @@ Sticky negative knowledge. Do not relearn.
 
 ## CI docs (extend)
 
-Extend `canon/context/ci.md` so the `## Checks` table reflects the web jobs.
+Extend `canon/context/ci.md` so the `## Checks` table reflects the web jobs. <!-- audit-ignore-citations: canon/context/ci.md -->
 
 Append rows: