@erclx/canon 5.25.0 → 5.26.0

package/src/commands/records.ts

@@ -30,6 +30,11 @@ import {
   type StaleReport,
   staleMemory,
 } from '@/records/stale'
+import {
+  type CanonicalDoc,
+  type CanonicalReport,
+  staleCanonical,
+} from '@/records/stale-canonical'
 import {
   type Finding,
   type FindingRemedy,
@@ -85,8 +90,11 @@ interface StaleCommandOptions extends ValidateCommandOptions {
   readonly days?: string
 }
 
-/** The one kind `stale` reads, since only a memory entry carries a review date. */
-const STALE_KINDS = ['memory'] as const
+/**
+ * The kinds `stale` reads. A memory entry ages by days in the shared pen, and
+ * a canonical doc ages by the releases shipped since its review.
+ */
+const STALE_KINDS = ['memory', 'canonical'] as const
 
 interface OrdinalCommandOptions extends ValidateCommandOptions {
   readonly claim?: boolean
@@ -270,14 +278,17 @@ export function register(program: Command): void {
     .option('--json', 'Add a machine-readable record on stdout')
     .option(
       '--days <n>',
-      `Days after a review before an entry is due again (default ${DEFAULT_REVIEW_DAYS})`,
+      `Days after a review before a memory entry is due again (default ${DEFAULT_REVIEW_DAYS})`,
+    )
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the main worktree except on canonical',
     )
-    .option('--root <path>', 'Project root, defaulting to the main worktree')
     .addHelpText(
       'after',
       [
         '',
-        'Reads the top-level entries of the memory folder, never review/, archive/,',
+        'memory: reads the top-level entries of the memory folder, never review/, archive/,',
         'or index.md. An entry is due when it carries no reviewed date, a reviewed',
         'value that is not a date, or one older than --days. A path is a backticked',
         'token holding a / and a file extension, resolved against the project root',
@@ -288,17 +299,24 @@ export function register(program: Command): void {
         'Entries are ordered due first, then those citing a missing path, then the',
         'longest unreviewed, then by name, so a review takes the first N as a batch.',
         '',
+        'canonical: reads REQUIREMENTS.md and ARCHITECTURE.md at whichever surface',
+        'root carries each, in the current worktree since both are tracked. Each',
+        'reports its reviewed date and the release tags merged into HEAD after that',
+        'day, or never when it carries no date. --days does not apply.',
+        '',
         'Exit codes:',
         '  0  the reading completed, whatever it found',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'It gates nothing and writes nothing. A due entry is a queue position rather',
-        'than a failure, and a missing path is a prompt for the review to judge.',
+        'than a failure, and a missing path or a release count is a prompt for the',
+        'review to judge.',
         '',
         'Examples:',
         '  canon records stale memory',
         '  canon records stale memory --json',
         '  canon records stale memory --days 60 --json',
+        '  canon records stale canonical --json',
         '',
       ].join('\n'),
     )
@@ -560,6 +578,8 @@ async function runStale(
     )
   }
 
+  if (kind === 'canonical') return runStaleCanonical(opts, emitJson)
+
   const days = Number(opts.days ?? DEFAULT_REVIEW_DAYS)
 
   if (!Number.isInteger(days) || days <= 0) {
@@ -588,6 +608,68 @@ async function runStale(
   return 0
 }
 
+/**
+ * Both docs are tracked, so the root is the checkout the caller stands in. The
+ * main worktree would answer from its own copy and miss a stamp this branch
+ * just wrote.
+ */
+async function runStaleCanonical(
+  opts: StaleCommandOptions,
+  emitJson: boolean,
+): Promise<number> {
+  if (opts.days !== undefined) {
+    return reportRefusal(
+      'canon records stale',
+      {
+        reason: 'bad-days',
+        message:
+          '--days does not apply to canonical, which counts releases rather than days.',
+      },
+      emitJson,
+    )
+  }
+
+  const root = opts.root ?? (await currentWorktreeRoot())
+  const outcome = await staleCanonical(root)
+
+  if (!outcome.ok)
+    return reportRefusal('canon records stale', outcome, emitJson)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify(outcome)}\n`)
+    return 0
+  }
+
+  intro('canon records stale')
+  logStep('Canonical')
+
+  if (outcome.docs.length === 0) {
+    logInfo('neither REQUIREMENTS.md nor ARCHITECTURE.md exists')
+  } else {
+    for (const doc of outcome.docs) logInfo(describeCanonical(doc, outcome))
+  }
+
+  if (!outcome.tagged) logInfo('no release tags merged into HEAD')
+  outro()
+  return 0
+}
+
+function describeCanonical(
+  doc: CanonicalDoc,
+  outcome: CanonicalReport,
+): string {
+  if (doc.reviewed === null) {
+    return doc.invalidReviewed === undefined
+      ? `${doc.path}: never reviewed`
+      : `${doc.path}: reviewed value is not a date: ${doc.invalidReviewed}`
+  }
+
+  const since = outcome.tagged
+    ? `${plural(doc.releasesSince ?? 0, 'release')} since`
+    : 'no releases to count'
+  return `${doc.path}: reviewed ${doc.reviewed}, ${since}`
+}
+
 function staleRow(entry: StaleEntry): string[] {
   return [
     entry.name,

package/src/commands/sandbox.ts

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
-import { execScript } from '@/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   assertedPercent,
@@ -26,6 +25,7 @@ import {
   type RunEnvelope,
   type Verdict,
 } from '@/sandbox/expect'
+import { runSandbox } from '@/sandbox/provision'
 import { sandboxTree } from '@/sandbox/tree'
 import {
   frameError,
@@ -36,6 +36,7 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
@@ -69,11 +70,39 @@ function reportAbsentScenarioTree(): boolean {
   return true
 }
 
+/** Holds fixture content for scenarios rather than scenarios of its own. */
+const FIXTURES_DIR = 'fixtures'
+
 /**
- * Holds fixture content for scenarios rather than scenarios of its own.
- * Twin of the `-not -name fixtures` filter in `scripts/manage-sandbox.sh`.
+ * The provision verb takes positional words rather than options, since `reset`
+ * and `clean` share its slot with a target, so its usage is written out here
+ * rather than generated by commander.
  */
-const FIXTURES_DIR = 'fixtures'
+function showProvisionHelp(): void {
+  const { GREY, NC, WHITE } = palette(process.stdout)
+  const lines = [
+    `${GREY}┌${NC}`,
+    `${GREY}├${NC} ${WHITE}Usage:${NC} canon sandbox [cat:cmd]`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Arguments:${NC}`,
+    `${GREY}│${NC}    cat:cmd   ${GREY}# Scenario to provision (e.g. git:commit)${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Commands:${NC}`,
+    `${GREY}│${NC}    reset     ${GREY}# Reset sandbox to baseline${NC}`,
+    `${GREY}│${NC}    clean     ${GREY}# Wipe the sandbox${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Options:${NC}`,
+    `${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Examples:${NC}`,
+    `${GREY}│${NC}    canon sandbox`,
+    `${GREY}│${NC}    canon sandbox git:commit`,
+    `${GREY}│${NC}    canon sandbox reset`,
+    `${GREY}│${NC}    canon sandbox clean`,
+    `${GREY}└${NC}`,
+  ]
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
 
 /** A run that reported nothing counts as clean, so only real signals fail. */
 const CLEAN_ENVELOPE: RunEnvelope = { isError: false, turns: 0, denials: 0 }
@@ -477,14 +506,25 @@ export function register(program: Command): void {
     .action(async (_opts: unknown, cmd: Command) => {
       if (reportAbsentScenarioTree()) return
 
-      const args = cmd.args
+      const mismatch = checkoutMismatchWarning(process.cwd())
+      if (mismatch !== undefined) logWarn(mismatch)
+
+      // `--no-header` is the frame opt-out for a caller that already opened
+      // one, which `sandbox/run.sh` and the picker below both do.
+      const isHeader = cmd.args[0] !== '--no-header'
+      const args = isHeader ? cmd.args : cmd.args.slice(1)
 
-      if (args.length === 0) {
-        const resolved = await interactivePicker()
-        await execScript('manage-sandbox.sh', ['--no-header', resolved])
-      } else {
-        await execScript('manage-sandbox.sh', args)
+      if (args[0] === '-h' || args[0] === '--help') {
+        showProvisionHelp()
+        return
       }
+
+      const target = args[0] ?? (await interactivePicker())
+      process.exitCode = await runSandbox(PROJECT_ROOT, {
+        isHeader: isHeader && args[0] !== undefined,
+        target,
+        arm: args[1] === '' ? undefined : args[1],
+      })
     })
 
   sandbox

package/src/commands/slides.ts

@@ -1,14 +1,13 @@
-import { existsSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { INSTALL_BROWSER } from '@/browser/engine'
 import { creationRel, SCRATCH } from '@/record-root'
-import { LAYOUTS } from '@/slides/layouts'
+import { listDecks, resolveDeck, SLIDES_FOLDER } from '@/slides/decks'
 import { openDeck } from '@/slides/open'
-import { renderSlidesDoc } from '@/slides/render'
-import type { Variant } from '@/slides/styles'
 import { intro, outro, palette } from '@/ui'
 
+const SLIDES_AT = creationRel(process.cwd(), SLIDES_FOLDER)
+
 export function register(program: Command): void {
   const slides = program
     .command('slides')
@@ -19,77 +18,34 @@ export function register(program: Command): void {
     .command('render')
     .helpOption('-h, --help', 'Show this help message')
     .description(
-      'Render a SLIDES.md source, or a folder of HTML slides, into a PowerPoint deck',
+      `Render a deck under ${SLIDES_AT}/, or a folder of HTML slides, into a PowerPoint deck`,
     )
-    .option(
-      '-s, --source <path>',
-      'Source SLIDES.md file, or a folder of .html slides read in filename order',
-      '.claude/SLIDES.md',
+    .argument(
+      '[deck]',
+      'Deck name or folder, defaulting to the only deck when there is one',
     )
     .option(
       '-o, --out <path>',
       'Output directory',
       creationRel(process.cwd(), SCRATCH, 'render', 'slides'),
     )
-    .option('-v, --variant <variant>', 'Override variant (light or dark)')
     .option(
       '-m, --mirror <path>',
       'Copy the deck to this directory after writing',
     )
     .option('--open', 'Open the deck after writing')
     .action(
-      async (opts: {
-        source: string
-        out: string
-        variant?: string
-        mirror?: string
-        open?: boolean
-      }) => {
+      async (
+        deck: string | undefined,
+        opts: { out: string; mirror?: string; open?: boolean },
+      ) => {
         try {
-          const sourcePath = resolve(process.cwd(), opts.source)
-          const outDir = resolve(process.cwd(), opts.out)
-          if (!existsSync(sourcePath)) {
-            fail(`${opts.source} not found`)
-          }
+          const root = process.cwd()
+          const resolved = resolveDeck(root, deck)
+          if (resolved.status === 'refused') fail(resolved.message)
+          const outDir = resolve(root, opts.out)
           const mirror = resolveMirror(opts.mirror)
-          if (statSync(sourcePath).isDirectory()) {
-            if (opts.variant !== undefined) {
-              fail('--variant applies to a SLIDES.md source, not a folder')
-            }
-            await renderHtmlFolder(sourcePath, outDir, mirror, opts.open)
-            return
-          }
-          const variant = parseVariant(opts.variant)
-          const { GREEN, GREY, NC, RED } = palette(process.stderr)
-          intro('Render slides')
-          const result = await renderSlidesDoc(sourcePath, outDir, {
-            variant,
-            mirror,
-          })
-          process.stderr.write(
-            `${GREY}│${NC} ${GREEN}✓${NC} ${result.slideCount} slides\n${GREY}│${NC} ${GREEN}✓${NC} ${result.pptxPath}\n`,
-          )
-          const validNames = LAYOUTS.map((layout) => layout.name).join(', ')
-          for (const { value, slideNumbers } of result.unrecognizedLayouts) {
-            const noun = slideNumbers.length === 1 ? 'slide' : 'slides'
-            process.stderr.write(
-              `${GREY}│${NC} ${RED}✗${NC} unrecognized layout "${value}" on ${noun} ${slideNumbers.join(', ')}. Valid layouts: ${validNames}\n`,
-            )
-          }
-          if (result.mirrorPath) {
-            process.stderr.write(
-              `${GREY}│${NC} ${GREEN}✓${NC} mirrored to ${result.mirrorPath}\n`,
-            )
-          }
-          if (opts.open) {
-            const target = result.mirrorPath ?? result.pptxPath
-            const opened = await openDeck(target)
-            const mark = opened ? `${GREEN}✓${NC}` : `${RED}✗${NC}`
-            process.stderr.write(
-              `${GREY}│${NC} ${mark} ${opened ? 'opened' : 'could not open'} ${target}\n`,
-            )
-          }
-          outro()
+          await renderHtmlFolder(resolved.dir, outDir, mirror, opts.open)
         } catch (error) {
           reportFailure(error)
         }
@@ -99,18 +55,23 @@ export function register(program: Command): void {
   slides
     .command('list')
     .helpOption('-h, --help', 'Show this help message')
-    .description('List the available slide layouts')
-    .option('--json', 'Output the layout catalog as JSON')
+    .description(`List the decks under ${SLIDES_AT}/`)
+    .option('--json', 'Output the decks as JSON')
     .action((opts: { json?: boolean }) => {
+      const decks = listDecks(process.cwd())
       if (opts.json) {
-        process.stdout.write(`${JSON.stringify(LAYOUTS)}\n`)
+        process.stdout.write(`${JSON.stringify(decks)}\n`)
         return
       }
       const { GREEN, GREY, NC } = palette(process.stderr)
-      intro('Slide layouts')
-      for (const layout of LAYOUTS) {
+      intro('Slide decks')
+      if (decks.length === 0) {
+        process.stderr.write(`${GREY}│${NC} No deck under ${SLIDES_AT}/\n`)
+      }
+      for (const { name, title, slides: count, path } of decks) {
+        const noun = count === 1 ? 'slide' : 'slides'
         process.stderr.write(
-          `${GREY}│${NC} ${GREEN}✓${NC} ${layout.name}  ${GREY}${layout.description}${NC}\n`,
+          `${GREY}│${NC} ${GREEN}✓${NC} ${name}  ${GREY}${title}, ${count} ${noun}, ${path}${NC}\n`,
         )
       }
       outro()
@@ -121,8 +82,7 @@ export function register(program: Command): void {
  * The converter loads on demand, so no other command resolves pptxgenjs,
  * jszip, or the token module at startup. A fallback, a refused link, chart, or
  * effect, or a token the master fell back on reports one line each and keeps
- * the exit at 0, as an unrecognized layout does on the markdown path, since the
- * deck is written either way. A malformed `deck.json` refuses before any slide is laid
+ * the exit at 0, since the deck is written either way. A malformed `deck.json` refuses before any slide is laid
  * out and exits 1.
  */
 async function renderHtmlFolder(
@@ -192,12 +152,6 @@ async function renderHtmlFolder(
   outro()
 }
 
-function parseVariant(value: string | undefined): Variant | undefined {
-  if (value === undefined) return undefined
-  if (value === 'light' || value === 'dark') return value
-  fail(`Invalid variant "${value}". Use light or dark.`)
-}
-
 function resolveMirror(value: string | undefined): string | undefined {
   const mirror = value ?? process.env.CANON_SLIDES_MIRROR
   return mirror ? resolve(process.cwd(), mirror) : undefined
@@ -205,9 +159,9 @@ function resolveMirror(value: string | undefined): string | undefined {
 
 /**
  * Carries a fail-fast message from a validation helper to the action that
- * called it. `fail` has to keep its `never` return, since that is what makes
- * `parseVariant` exhaustive to the compiler, and a helper deep in the call
- * stack cannot set `process.exitCode` and unwind on its own.
+ * called it. `fail` keeps its `never` return so the compiler narrows past it,
+ * and a helper deep in the call stack cannot set `process.exitCode` and unwind
+ * on its own.
  */
 class SlidesError extends Error {}
 

package/src/context/audit.ts

@@ -4,7 +4,7 @@ import { BARE_NAME, IGNORE_MARKER } from '@/context/citations'
 import type { AuditedFolder } from '@/context/folders'
 import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
 import { documentHeight } from '@/markdown/structure'
-import { isStubSeed } from '@/seed-marker'
+import { isStubSeed } from '@/tooling/seed-marker'
 
 /**
  * Checkpoint quoted from the standard stating it. It is not a cap.

package/src/design/tokens.ts

@@ -2,11 +2,8 @@
  * The design system's one source of values.
  *
  * `canon/DESIGN.md` is rendered from this module rather than read by it, so
- * the document a person opens is a view and this file is the fact. Every
- * rendering surface reads from here in the form it can take: a CSS surface
- * takes custom properties through `@/design/css`, and the slide renderer takes
- * bare hex through `bareHex` below, because PowerPoint has no concept of a
- * custom property.
+ * the document a person opens is a view and this file is the fact. A CSS
+ * surface reads it as custom properties through `@/design/css`.
  *
  * The two artifacts can disagree, which is what the `design` gate stage exists
  * to catch. Nothing else compares them.
@@ -371,16 +368,3 @@ export function colorValue(
 ): string | undefined {
   return tokens.color.find((token) => token.role === role)?.value
 }
-
-/**
- * The adapter the slide renderer takes. `PptxGenJS` receives color as
- * `{ color: theme.background }` and wants six hex digits with no leading `#`,
- * so the shared thing is the value and this is the per-consumer form.
- *
- * The hex is raised to upper case because that is the spelling
- * `src/slides/styles.ts` has always written, and the only one a diff of a
- * rendered deck reads cleanly against.
- */
-export function bareHex(value: string): string {
-  return value.replace(/^#/, '').toUpperCase()
-}

package/src/docs/read.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { basename, join } from 'node:path'
-import { stripFrontmatter } from '@/frontmatter'
+import { stripFrontmatter } from '@/markdown/frontmatter'
 import { SURFACE_ROOTS } from '@/surface-root'
 
 const INDEX_TOPIC = 'index'

package/src/{github.ts → feedback/github.ts}

@@ -6,7 +6,7 @@ import {
   failureDetail,
   type CreateIssueOptions,
   type CreateIssueResult,
-} from '@/github-format'
+} from '@/feedback/github-format'
 
 const GH_TIMEOUT_MS = 30_000
 

package/src/gate/measures.ts

@@ -18,6 +18,7 @@ import {
 import { isOverWordCap, measureRequirements } from '@/context/requirements'
 import {
   auditSkills,
+  LEDGER_SKILLS,
   PRACTICE_LEDGER,
   PRACTICE_SKILLS,
   SHIPPED_CORPUS,
@@ -411,8 +412,9 @@ export const skillProvenance: Measure = async (ctx) => {
 }
 
 /**
- * Every listed practice skill against the closing sections and the ledger
- * `standards/skill-practice.md` requires of one.
+ * Every listed practice skill against the closing sections, and every skill on
+ * the wider ledger list against the ledger, both of which
+ * `standards/skill-practice.md` requires.
  *
  * Read in-process for the reason `skillProvenance` is, so the verb keeps its
  * missing-requirement-only exit. The list names shipped folders alone, so a
@@ -434,14 +436,14 @@ export const skillPracticeShape: Measure = async (ctx) => {
       .join(', ')
     return {
       emissions: [],
-      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named, or the ledger at ${PRACTICE_LEDGER}.`,
+      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named to a practice skill, or the ledger at ${PRACTICE_LEDGER} to any skill on the ledger list.`,
     }
   }
 
   return {
     emissions: [
       info(
-        `${plural(PRACTICE_SKILLS.length, 'practice skill')} carry every closing section and a ledger`,
+        `${plural(PRACTICE_SKILLS.length, 'practice skill')} carry every closing section, and ${plural(LEDGER_SKILLS.length, 'listed skill')} carry a ledger`,
       ),
     ],
   }

package/src/gov/citations.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { $ } from 'bun'
-import { isMarked } from '@/exempt-marker'
+import { isMarked } from '@/sweep/exempt-marker'
 import { gitEnv } from '@/git-env'
 import { listRuleFiles } from '@/gov/payload'
 import { parseFrontmatter } from '@/indexes/frontmatter'

package/src/gov/payload.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { basename, resolve } from 'node:path'
-import { stripFrontmatter } from '@/frontmatter'
+import { stripFrontmatter } from '@/markdown/frontmatter'
 
 /**
  * Lists installed rules in the order the payload concatenates them. Sorting by

package/src/gov/superseded.ts

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { isBinary } from '@/binary'
-import { isMarked } from '@/exempt-marker'
+import { isBinary } from '@/sweep/binary'
+import { isMarked } from '@/sweep/exempt-marker'
 import { listRepositoryFiles } from '@/git-files'
 
 /**

package/src/markdown/ceiling.ts

@@ -8,7 +8,7 @@ import { CHECKPOINTS, documentHeight } from '@/markdown/structure'
  *
  * The whole line rather than anywhere on it, so a standard quoting the marker
  * inside a code span to document it does not exempt itself. A marker with no
- * reason does not count, for the reason `isMarked` in `src/exempt-marker.ts`
+ * reason does not count, for the reason `isMarked` in `src/sweep/exempt-marker.ts`
  * gives: a bare token reads as a line that meant to say something and did not.
  */
 const EXEMPT_MARKER = /^<!--\s*canon-length-exempt:[ \t]*(\S.*?)\s*-->$/

package/src/record-root.ts

@@ -76,6 +76,7 @@ export const RECORD_ENTRIES: readonly string[] = [
   'proposals',
   'ready',
   'review',
+  'slides',
   'tasks',
   'teach',
   'transcripts',

package/src/records/backup.ts

@@ -43,6 +43,7 @@ export const BACKED_FOLDERS = [
   'plans',
   'proposals',
   'review',
+  'slides',
   'tasks',
   'teach',
   'transcripts',

package/src/records/push-guard.ts

@@ -1,6 +1,6 @@
 import { lstat, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { isBinary } from '@/binary'
+import { isBinary } from '@/sweep/binary'
 import { scanText } from '@/secrets/scan'
 
 /**