@erclx/canon 5.31.0 → 5.33.0

package/src/pr/paths.ts

@@ -3,12 +3,12 @@ import { findBacktickSpans } from '@/markdown/backticks'
 /**
  * The heading whose bullets state what a branch changed.
  *
- * Read alone, and never widened to a sibling section. `## Technical Context`
+ * Read alone, and never widened to a sibling section. `## Technical context`
  * legitimately names files a branch never touched, such as an install stamp
  * inside a target, so a reader that took the whole body would manufacture a
  * finding out of every argument the author made for the change.
  */
-export const KEY_CHANGES = 'Key Changes'
+export const KEY_CHANGES = 'Key changes'
 
 /** What one bullet claimed, kept with its bullet so a finding can quote it. */
 export interface PathClaim {
@@ -86,7 +86,7 @@ const BARE_LINE = /^:\d+(?:-\d+)?$/
  * `canon markdown audit .claude/rules --json` carries a slash and names no file.
  * Angle brackets answer a second, since `.canon/plans/feature-<slug>.md`
  * describes a shape rather than naming a file. A glob and a caret describe a
- * shape too, `^src/` being a grep pattern one body spelled in Key Changes, and
+ * shape too, `^src/` being a grep pattern one body spelled in Key changes, and
  * a leading anchor names something outside this repository.
  *
  * Deliberately not shared with `classifySpan` in `@/gov/citations`, which asks
@@ -307,7 +307,7 @@ function resolveSpan(span: string): ResolvedSpan | undefined {
 }
 
 /**
- * Every path the `## Key Changes` section claims a change to.
+ * Every path the `## Key changes` section claims a change to.
  *
  * `roots` names the entries the tree holds at its top level, which is what
  * separates a whole path from one written partially. It is passed in rather

package/src/records/backup.ts

@@ -30,7 +30,7 @@ import { type BlockedPath, guardPayload } from '@/records/push-guard'
  * rather than named here. That is what keeps this list at one line per surface
  * as archives spread, which a sibling-per-archive layout could not.
  *
- * `RECORD_KINDS` in `validate.ts` overlaps this on five names and carries one
+ * `RECORD_KINDS` in `validate.ts` overlaps this on four names and carries one
  * more that no backup reaches. The two lists differ on purpose: one is what a
  * standard governs, this is what a disk loss would take, and `standards` is
  * tracked so a backup would carry a second copy of committed files.
@@ -39,7 +39,6 @@ export const BACKED_FOLDERS = [
   'diagrams',
   'groundwork',
   'intake',
-  'memory',
   'plans',
   'proposals',
   'review',
@@ -51,6 +50,15 @@ export const BACKED_FOLDERS = [
   'walkthroughs',
 ] as const
 
+/**
+ * Folders a retired kind left at a legacy `.claude` root that the allowlist
+ * must still read, so a half-finished move that strands one still trips
+ * `split-roots`. Absent from `BACKED_FOLDERS` because nothing writes them, and
+ * absent from `RETIRED_FOLDERS` because that list stages a deletion and this
+ * folder is an archive to keep.
+ */
+const LEGACY_RECORD_FOLDERS = ['memory'] as const
+
 /**
  * Names that have left `BACKED_FOLDERS` and whose removal still has to reach a
  * records history once.
@@ -124,7 +132,9 @@ function isExcluded(name: string): boolean {
  */
 function foldersAt(dir: string): string[] {
   if (basename(dir) === '.claude') {
-    return BACKED_FOLDERS.filter((folder) => existsSync(join(dir, folder)))
+    return [...BACKED_FOLDERS, ...LEGACY_RECORD_FOLDERS].filter((folder) =>
+      existsSync(join(dir, folder)),
+    )
   }
 
   const entries = existsSync(dir)
@@ -378,7 +388,7 @@ async function enclosingRemotes(
  * Clears the four gates both verbs share and returns the records remote URL.
  *
  * The last two are the ones the payload depends on. This repository is public,
- * so a records branch on any of its remotes serves the memory pen and the
+ * so a records branch on any of its remotes serves the plans and the
  * groundwork trails to anyone who fetches all refs. Comparing the configured
  * URL against every remote of the enclosing repository is what keeps a
  * misconfigured `origin` from publishing them, and refusing when that list
@@ -416,7 +426,7 @@ async function resolveRemote(
   if (!enclosing) {
     return refuse(
       'remote-unreadable',
-      `Cannot read the remotes of the project at ${root}, so the records origin cannot be checked against them. Records carry the memory pen and the groundwork trails, and an unchecked origin risks publishing them.`,
+      `Cannot read the remotes of the project at ${root}, so the records origin cannot be checked against them. Records carry the plans and the groundwork trails, and an unchecked origin risks publishing them.`,
     )
   }
 
@@ -424,7 +434,7 @@ async function resolveRemote(
   if (enclosing.identities.includes(url)) {
     return refuse(
       'remote-shared',
-      `The records origin ${remote.text} is a remote of this project. Records carry the memory pen and the groundwork trails, so they need a repository of their own.`,
+      `The records origin ${remote.text} is a remote of this project. Records carry the plans and the groundwork trails, so they need a repository of their own.`,
     )
   }
 

package/src/records/ordinal.ts

@@ -4,7 +4,7 @@ import { recordDir } from '@/roots/record'
 
 /**
  * The two record folders that share one ordinal sequence, per
- * `standards/intake.md` and `standards/groundwork.md`. A folder opened as
+ * `claude/skills/plan-intake/references/intake.md` and `claude/skills/plan-groundwork/references/groundwork.md`. A folder opened as
  * either kind blocks the same number for the other, so the two read together
  * rather than each keeping a count of its own.
  */

package/src/records/prune.ts

@@ -35,7 +35,8 @@ const LEGACY_MOVES: ReadonlyMap<string, string> = new Map([
  * Scratch-root names a different migration moves out of scratch for good,
  * derived from that migration's own table rather than duplicated in a second
  * hand-kept list. `RECORD_LAYOUT_MOVES` names `memory-archive`, the
- * retired-entry archive `603-memory` says never to delete, and `PROMOTED_FOLDERS`
+ * retired-entry archive of the memory kind, which is never offered for deletion,
+ * and `PROMOTED_FOLDERS`
  * names an evidence folder a durable record cites by name. A project that has
  * not run either migration still carries these at the scratch root, where an
  * ordinary slug's own age test would eventually offer them.

package/src/records/stale-canonical.ts

@@ -3,11 +3,10 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 import { gitEnv } from '@/git/env'
-import { readReviewed } from '@/records/stale'
 import { surfaceDir } from '@/roots/surface'
 
-/** The two records whose drift is identity rather than a stale path. */
-const CANONICAL_DOCS = ['REQUIREMENTS.md', 'ARCHITECTURE.md'] as const
+/** The record whose drift is identity rather than a stale path. */
+const CANONICAL_DOCS = ['REQUIREMENTS.md'] as const
 
 export interface CanonicalDoc {
   /** Relative to the root, at whichever surface root carries the doc. */
@@ -22,6 +21,37 @@ export interface CanonicalDoc {
   readonly latestRelease: string | null
 }
 
+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<CanonicalDoc, '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 }
+}
+
 export interface CanonicalReport {
   readonly ok: true
   readonly root: string

package/src/records/validate.ts

@@ -22,7 +22,6 @@ export const RECORD_KINDS = [
   'plans',
   'groundwork',
   'intake',
-  'memory',
   'standards',
   'teach',
 ] as const
@@ -60,7 +59,6 @@ export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
 export const FINDING_KINDS = [
   'name-malformed',
   'title-missing',
-  'title-is-slug',
   'section-missing',
   'scope-unanchored',
   'entry-unreasoned',
@@ -72,7 +70,6 @@ export const FINDING_KINDS = [
   'state-missing',
   'closing-partial',
   'item-incomplete',
-  'category-mismatch',
   'operator-call-phrasing',
   'batch-unsplit',
   'source-unquoted',
@@ -81,22 +78,12 @@ export const FINDING_KINDS = [
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
 
-/**
- * The transforms `migrate.ts` carries. Most finding kinds have none, since a
- * transform is only safe where the old shape is recoverable from the file
- * itself, so this stays optional on `Finding` rather than required.
- */
-export const FINDING_REMEDIES = ['category-from-name'] as const
-
-export type FindingRemedy = (typeof FINDING_REMEDIES)[number]
-
 export interface Finding {
   readonly kind: FindingKind
   /** The record the finding sits in, relative to the validated folder. */
   readonly record: string
   readonly subject: string
   readonly message: string
-  readonly remedy?: FindingRemedy
 }
 
 export interface ValidateReport {
@@ -214,9 +201,8 @@ function finding(
   record: string,
   subject: string,
   message: string,
-  remedy?: FindingRemedy,
 ): Finding {
-  return { kind, record, subject, message, remedy }
+  return { kind, record, subject, message }
 }
 
 async function listMarkdown(dir: string): Promise<string[]> {
@@ -934,169 +920,6 @@ async function checkWorkspace(dir: string, slug: string): Promise<Finding[]> {
   ]
 }
 
-const MEMORY_INDEX = 'index.md'
-const MEMORY_FIELDS = ['title', 'description', 'category'] as const
-
-/**
- * The filename prefix and the `category` field are one fact in two spellings,
- * so the map is the whole type list and the comparison against it is what
- * catches a prefix outside the set, a field disagreeing with the prefix, and a
- * casing drift that would open a second group in the catalog.
- */
-export const CATEGORY_BY_TYPE = {
-  feedback: 'Feedback',
-  project: 'Project',
-  user: 'User',
-  reference: 'Reference',
-} as const
-
-export type MemoryType = keyof typeof CATEGORY_BY_TYPE
-
-const MEMORY_TYPES = Object.keys(CATEGORY_BY_TYPE) as readonly MemoryType[]
-
-export const MEMORY_NAME = /^([a-z]+)-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/
-
-/** The two markers a rule-bearing body carries, on top of the rule line itself. */
-const MEMORY_MARKERS = ['**Why:**', '**How to apply:**'] as const
-
-export function memoryType(value: string): MemoryType | undefined {
-  return MEMORY_TYPES.find((type) => type === value)
-}
-
-/**
- * The one missing-field shape `migrate.ts` can repair: `category` alone,
- * recoverable from the same filename prefix `checkMemory` already read it
- * from. `title` and `description` are prose nobody wrote down, so a finding
- * naming either carries no remedy.
- */
-function memoryRemedy(
-  missing: readonly string[],
-  named: MemoryType | undefined,
-): FindingRemedy | undefined {
-  return named && missing.length === 1 && missing[0] === 'category'
-    ? 'category-from-name'
-    : undefined
-}
-
-export function checkMemory(name: string, text: string): Finding[] {
-  const findings: Finding[] = []
-  const match = MEMORY_NAME.exec(name)
-  const named = match ? memoryType(match[1]) : undefined
-
-  if (!named) {
-    findings.push(
-      finding(
-        'name-malformed',
-        name,
-        name,
-        `is not named <type>-<slug>.md with a type of ${MEMORY_TYPES.join(', ')}.`,
-      ),
-    )
-  }
-
-  const frontmatter = parseFrontmatter(text)
-  const missing = MEMORY_FIELDS.filter(
-    (field) => !readField(frontmatter, field),
-  )
-
-  if (missing.length > 0) {
-    findings.push(
-      finding(
-        'frontmatter-incomplete',
-        name,
-        name,
-        `carries no ${missing.join(' and no ')}.`,
-        memoryRemedy(missing, named),
-      ),
-    )
-  }
-
-  // Its own kind rather than `title-missing`, which means an absent heading on a
-  // plan. One kind covering both leaves a caller filtering the JSON unable to
-  // tell a record with no title from one whose title is its own slug.
-  if (readField(frontmatter, 'title') === name.replace(/\.md$/, '')) {
-    findings.push(
-      finding(
-        'title-is-slug',
-        name,
-        name,
-        'is titled with its own filename, so the catalog renders a slug where the rule belongs.',
-      ),
-    )
-  }
-
-  const category = readField(frontmatter, 'category')
-
-  // Reported against the prefix alone. A name the prefix rule already failed
-  // has no type to compare against, and reporting it twice names one defect as
-  // two.
-  if (named && category && category !== CATEGORY_BY_TYPE[named]) {
-    findings.push(
-      finding(
-        'category-mismatch',
-        name,
-        category,
-        `is not ${CATEGORY_BY_TYPE[named]}, which the filename prefix declares.`,
-      ),
-    )
-  }
-
-  return [
-    ...findings,
-    ...checkMemoryBody(
-      name,
-      text.slice(frontmatter?.raw.length ?? 0),
-      named ?? category,
-    ),
-  ]
-}
-
-/**
- * A `user` or `reference` entry is a single sentence by design, so the markers
- * are checked only where a rule is being stated. The type is read off the
- * prefix, falling back to the category so a misnamed file is still checked
- * against the shape it claims.
- */
-function checkMemoryBody(
-  name: string,
-  text: string,
-  claimed: string | undefined,
-): Finding[] {
-  const type = claimed && memoryType(claimed.toLowerCase())
-  if (type !== 'feedback' && type !== 'project') return []
-
-  const body = linesOutsideFences(text).filter((line) => line.trim().length > 0)
-
-  const findings: Finding[] = []
-  const opening = body[0]
-
-  if (!opening || MEMORY_MARKERS.some((marker) => opening.startsWith(marker))) {
-    findings.push(
-      finding(
-        'section-missing',
-        name,
-        'the rule line',
-        'is absent, so the entry carries a rationale with no rule to apply.',
-      ),
-    )
-  }
-
-  for (const marker of MEMORY_MARKERS) {
-    if (!body.some((line) => line.startsWith(marker))) {
-      findings.push(
-        finding(
-          'section-missing',
-          name,
-          marker,
-          `is required on a ${type} entry and the body carries no such line.`,
-        ),
-      )
-    }
-  }
-
-  return findings
-}
-
 const STANDARD_INDEX = 'index.md'
 const STANDARD_FIELDS = ['title', 'description'] as const
 
@@ -1225,7 +1048,7 @@ export function checkStandard(name: string, text: string): Finding[] {
  */
 const FOLDER_CHECK: Readonly<
   Record<
-    Exclude<RecordKind, 'plans' | 'memory' | 'standards'>,
+    Exclude<RecordKind, 'plans' | 'standards'>,
     (dir: string, slug: string) => Promise<Finding[]>
   >
 > = {
@@ -1279,15 +1102,6 @@ export async function validateRecords(
 
   if (kind === 'plans') return validateFiles(dir, kind, checkPlan)
 
-  if (kind === 'memory') {
-    return validateFiles(
-      dir,
-      kind,
-      checkMemory,
-      (file) => file === MEMORY_INDEX,
-    )
-  }
-
   // The walk stays flat, matching install and the catalog.
   if (kind === 'standards') {
     return validateFiles(

package/src/roots/record.ts

@@ -56,7 +56,7 @@ const CANON_SCRATCH = 'tmp'
  * Everything absent from this list is committed and never lands under the
  * record root, which is the rule the move ran on. `rules`, `skills`, and
  * `hooks` stay under `.claude/` because the vendor reads them there, while
- * `context`, `wireframes`, and the loose documents are tracked surfaces that
+ * `context` and the loose documents are tracked surfaces that
  * `surface.ts` resolves under `canon/` instead. A seed and a
  * superseded-layout report each ask this rather than assuming a root.
  */

package/src/sandbox/census.ts

@@ -71,7 +71,7 @@ export function listSkills(root: string): string[] {
  *
  * `<category>-<command>` is the rule `canon/context/sandbox/coverage/census.md` states, and it
  * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
- * rest: `claude/target-setup.sh` drives the `target-setup` skill, not a `claude-target-setup` that
+ * rest: `claude/target-setup.ts` drives the `target-setup` skill, not a `claude-target-setup` that
  * does not exist. Stating one spelling and shipping two is what let the audit
  * report a paired skill as unpaired.
  *

package/src/sandbox/coverage.ts

@@ -44,13 +44,9 @@ function listScenarios(sandboxDir: string): ScenarioCoverage[] {
   const scenarios: ScenarioCoverage[] = []
 
   for (const category of listCategories(sandboxDir)) {
-    // A stem in both forms counts once, and provisioning refuses it by name.
-    const { scenarios: files, ambiguous } = listScenarioFiles(
-      join(sandboxDir, category),
-    )
-    const commands = [...files.map((f) => f.command), ...ambiguous].sort()
+    const { scenarios: files } = listScenarioFiles(join(sandboxDir, category))
 
-    for (const command of commands) {
+    for (const { command } of files) {
       scenarios.push({ category, command, armed: [] })
     }
   }

package/src/sandbox/equivalence.ts

@@ -22,7 +22,6 @@ import {
   listCategories,
   listScenarioFiles,
   loadScenario,
-  type ScenarioKind,
 } from '@/sandbox/scenario'
 import { createStubRemote, readStubManifest } from '@/sandbox/stub-remote'
 
@@ -153,28 +152,6 @@ export function armKey(arm: Arm): string {
   return arm.arm === undefined ? scenario : `${scenario}/${arm.arm}`
 }
 
-/**
- * Reads the quoted arguments of `select_or_route_scenario`, joining a call that
- * continues across backslash-newline pairs. The first argument is the prompt and
- * the rest are arm names. A call this cannot see returns no arms, which the
- * coverage cross-check in `enumerateArms` turns into an error rather than a
- * smaller list.
- */
-export function parseArmNames(source: string): string[] {
-  const start = source.search(/select_or_route_scenario\b/)
-  if (start === -1) return []
-
-  const call = source
-    .slice(start)
-    .replace(/\\\n/g, ' ')
-    .split('\n')[0]
-    ?.replace(/^select_or_route_scenario/, '')
-
-  return [...(call ?? '').matchAll(/"([^"]*)"/g)]
-    .map((match) => match[1] ?? '')
-    .slice(1)
-}
-
 function matchesTarget(
   category: string,
   command: string,
@@ -199,25 +176,14 @@ function matchesArm(arm: Arm, targets: readonly string[]): boolean {
 }
 
 /**
- * Reads a scenario's arm names and anchor flag: off a bash file's source, and
- * off a TypeScript module's own keys, which is what its stage routes on.
+ * Reads a scenario's arm names and anchor flag off its module's own keys, which
+ * is what its stage routes on.
  */
 function readArms(
   file: string,
-  kind: ScenarioKind,
 ):
   | { ok: true; anchor: boolean; names: string[] }
   | { ok: false; error: string } {
-  if (kind === 'sh') {
-    const source = readFileSync(file, 'utf8')
-
-    return {
-      ok: true,
-      anchor: /^use_anchor\s*\(\)/m.test(source),
-      names: parseArmNames(source),
-    }
-  }
-
   try {
     const definition = loadScenario(file)
 
@@ -250,17 +216,12 @@ export function enumerateArms(
   const coverage = collectCoverage(root)
 
   for (const category of listCategories(sandboxDir)) {
-    const { scenarios, ambiguous } = listScenarioFiles(
-      join(sandboxDir, category),
-    )
-    for (const command of ambiguous)
-      if (matchesTarget(category, command, targets))
-        errors.push(`${category}:${command} exists as both .sh and .ts`)
+    const { scenarios } = listScenarioFiles(join(sandboxDir, category))
 
-    for (const { command, file, kind } of scenarios) {
+    for (const { command, file } of scenarios) {
       if (!matchesTarget(category, command, targets)) continue
 
-      const declared = readArms(file, kind)
+      const declared = readArms(file)
       if (!declared.ok) {
         errors.push(`${category}:${command} did not load: ${declared.error}`)
         continue

package/src/sandbox/expect.ts

@@ -354,7 +354,7 @@ function checkWriteScope(
   // none, and without this the declaration vanishes from the verdict entirely:
   // no result, no skipped entry, and no contribution to the unchecked count that
   // exists to surface exactly this. The `undefined` branch above cannot stand in,
-  // since `run.sh` always passes `--writes` and `readPathList` returns `[]` for an
+  // since `canon sandbox run` always passes `--writes` and `readPathList` returns `[]` for an
   // empty file. An arm whose output escaped the snapshot reads as a clean run,
   // which is the vacuous pass the harness exists to remove.
   if (writes.length === 0) {
@@ -377,7 +377,7 @@ function checkWriteScope(
 }
 
 /**
- * `run.sh` watches two toolkit roots for a write to shared session scratch
+ * `canon sandbox run` watches two toolkit roots for a write to shared session scratch
  * during a run, and reports every one it finds as an unattributed escape with
  * no arm able to fail on it. An arm whose skill legitimately reaches outside
  * the sandbox tree declares the destinations here, and the harness asserts
@@ -388,8 +388,8 @@ function checkWriteScope(
  * nothing skips rather than passing on a fabricated zero. An escape-scope
  * declaration exists to bound a side effect nothing requires, so zero escapes
  * is the outcome a correct run produces and reports as a pass outright,
- * provided a watched root held something to watch. `run.sh`'s `snapshot_root`
- * returns an empty manifest both when a watch ran clean and when none of the
+ * provided a watched root held something to watch. `snapshotRoot` in
+ * `src/sandbox/headless/watch.ts` returns an empty manifest both when a watch ran clean and when none of the
  * four watched directories existed under a root, and the two produce the same
  * empty `escapes` list. `watched` is what tells them apart: a run that had
  * nothing to watch reports unmeasured rather than passing on a diff it never