@erclx/canon 4.72.1 → 4.74.0

package/src/commands/records.ts

@@ -3,6 +3,13 @@ import { join } from 'node:path'
 import type { Command } from 'commander'
 import { BACKED_FOLDERS, pullRecords, pushRecords } from '@/records/backup'
 import { migrateRecord } from '@/records/migrate'
+import {
+  type ClaimOutcome,
+  claimOrdinal,
+  highestOrdinal,
+  isOrdinalKind,
+  ORDINAL_KINDS,
+} from '@/records/ordinal'
 import {
   type FolderSize,
   formatBytes,
@@ -40,6 +47,9 @@ const EXIT_FINDINGS = 2
 /** Returned when a record carries a known transform and `--write` was not passed. */
 const EXIT_MIGRATABLE = 2
 
+/** Returned when `--claim` loses every retry to a collision. */
+const EXIT_CONTENDED = 2
+
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -51,6 +61,10 @@ interface MigrateCommandOptions extends ValidateCommandOptions {
   readonly write?: boolean
 }
 
+interface OrdinalCommandOptions extends ValidateCommandOptions {
+  readonly claim?: boolean
+}
+
 export function register(program: Command): void {
   const records = program
     .command('records')
@@ -140,6 +154,49 @@ export function register(program: Command): void {
       process.exitCode = await runMigrate(kind, opts)
     })
 
+  records
+    .command('ordinal')
+    .description(
+      'Report or claim the next ordinal shared by intake and groundwork folders',
+    )
+    .argument('<kind>', `Ordinal-bearing folder: ${ORDINAL_KINDS.join(', ')}`)
+    .argument('<slug>', 'The kebab-case slug the new folder will carry')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--claim',
+      'Create the folder atomically instead of only reporting the ordinal',
+    )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'intake and groundwork folders share one ordinal sequence, so this reads',
+        'both .canon/intake/ and .canon/groundwork/ regardless of which kind was',
+        'asked for.',
+        '',
+        'Exit codes:',
+        '  0  reported the next ordinal, or --claim created the folder',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  --claim lost every retry to a collision',
+        '',
+        'Without --claim this only reports, so two sessions reading at once can',
+        'still report the same number. --claim resolves that by creating the',
+        'folder as part of the same act, retrying past a losing race rather than',
+        'reporting one.',
+        '',
+        'Examples:',
+        '  canon records ordinal intake my-topic',
+        '  canon records ordinal groundwork my-topic --claim',
+        '  canon records ordinal groundwork my-topic --claim --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (kind: string, slug: string, opts: OrdinalCommandOptions) => {
+      process.exitCode = await runOrdinal(kind, slug, opts)
+    })
+
   records
     .command('size')
     .description('Report what each record folder holds and how much is recent')
@@ -726,3 +783,84 @@ export function migrateExitCode(
   if (!write) return EXIT_MIGRATABLE
   return refused.length > 0 ? 1 : 0
 }
+
+async function runOrdinal(
+  kind: string,
+  slug: string,
+  opts: OrdinalCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!isOrdinalKind(kind)) {
+    return reportRefusal(
+      'canon records ordinal',
+      {
+        reason: 'unknown-kind',
+        message: `Not an ordinal-bearing kind: ${kind}. Expected one of: ${ORDINAL_KINDS.join(', ')}.`,
+      },
+      emitJson,
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const claim = opts.claim ?? false
+
+  if (!claim) {
+    const next = String((await highestOrdinal(root)) + 1).padStart(2, '0')
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: true, root, kind, slug, ordinal: next, claimed: false })}\n`,
+      )
+    } else {
+      intro('canon records ordinal')
+      logStep('Next')
+      logInfo(`${next}-${slug} (report only, pass --claim to create it)`)
+      outro()
+    }
+
+    return 0
+  }
+
+  return reportOrdinal(root, await claimOrdinal(root, kind, slug), emitJson)
+}
+
+function reportOrdinal(
+  root: string,
+  outcome: ClaimOutcome,
+  emitJson: boolean,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stderr.write(`${outcome.message}\n`)
+      process.stdout.write(
+        `${JSON.stringify({
+          ok: false,
+          reason: outcome.reason,
+          message: outcome.message,
+          lastOrdinal: outcome.lastOrdinal,
+        })}\n`,
+      )
+      return EXIT_CONTENDED
+    }
+
+    intro('canon records ordinal')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return EXIT_CONTENDED
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, ...outcome, claimed: true })}\n`,
+    )
+  } else {
+    intro('canon records ordinal')
+    logStep('Claimed')
+    logInfo(outcome.path)
+    outro()
+  }
+
+  return 0
+}

package/src/commands/transcripts.ts

@@ -1,24 +1,41 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
+import { recordDir } from '@/record-root'
 import { ensureYtDlp, fetchOne } from '@/transcripts/fetch'
 import { palette } from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
 
 interface TranscriptOptions {
-  out: string
+  out?: string
   keepTimestamps?: boolean
 }
 
+/**
+ * A caller-supplied `--out` resolves against the CWD, since naming a path
+ * explicitly opts out of the backed default. With none, the destination is
+ * the backed `transcripts` record folder at the main worktree root, which
+ * `canon records push` and `canon records pull` carry along with the rest.
+ */
+export async function resolveOutDir(opts: TranscriptOptions): Promise<string> {
+  return opts.out
+    ? resolve(process.cwd(), opts.out)
+    : recordDir(await mainWorktreeRoot(), 'transcripts')
+}
+
 export function register(program: Command): void {
   program
     .command('transcripts <url>')
     .description('Fetch a YouTube transcript with metadata frontmatter')
-    .option('-o, --out <path>', 'Output directory', 'transcripts')
+    .option(
+      '-o, --out <path>',
+      'Output directory, defaulting to the backed transcripts record folder',
+    )
     .option(
       '--keep-timestamps',
       'Prefix each line with [mm:ss] instead of prose',
     )
     .action(async (url: string, opts: TranscriptOptions) => {
-      const outDir = resolve(process.cwd(), opts.out)
+      const outDir = await resolveOutDir(opts)
       const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
       process.stderr.write(
         `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}canon transcripts${NC}\n`,

package/src/context/architecture.ts

@@ -1,16 +1,22 @@
 import { access, readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 import { AUDITS } from '@/audits/catalog'
 import { bodyLines } from '@/markdown/scan'
+import { surfaceDir } from '@/surface-root'
 
 /**
- * The record this measures, relative to the project root.
+ * The record this measures, relative to `root`.
  *
- * One fixed path rather than a folder walk, because the standard governing it
- * names one document, and the length rule this measures is stated by whichever
- * record sits there rather than by the standard or by this file.
+ * A function rather than a fixed constant, because the path now resolves at
+ * either surface root and a constant naming one of them would be believed to
+ * be true of a project that has moved. One fixed name rather than a folder
+ * walk otherwise, because the standard governing it names one document, and
+ * the length rule this measures is stated by whichever record sits there
+ * rather than by the standard or by this file.
  */
-export const RECORD_REL = '.claude/ARCHITECTURE.md'
+export function architectureRel(root: string): string {
+  return relative(root, surfaceDir(root, 'ARCHITECTURE.md'))
+}
 
 /**
  * The line allowances a record states for itself, absent when it states none.
@@ -299,7 +305,8 @@ export function ceilingFor(allowances: Allowances, decisions: number): number {
 export async function measureArchitecture(
   root: string,
 ): Promise<ArchitectureReport | undefined> {
-  const path = join(root, RECORD_REL)
+  const rel = architectureRel(root)
+  const path = join(root, rel)
 
   let source: string
   try {
@@ -330,7 +337,7 @@ export async function measureArchitecture(
   )
 
   return {
-    rel: RECORD_REL,
+    rel,
     lines: source.replace(/\n$/, '').split('\n').length,
     ...(allowances !== undefined && {
       allowances,

package/src/context/citations.ts

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { listRepositoryFiles } from '@/git-files'
 import { RECORD_ROOTS } from '@/record-root'
+import { SURFACE_ROOTS } from '@/surface-root'
 
 /**
  * Suppresses citation checking for the source line carrying it.
@@ -78,17 +79,41 @@ export function isFixture(rel: string): boolean {
 }
 
 /**
- * Both record roots are spelled, so a citation into a folder that has moved is
- * still resolved. A pattern fixed at one root matches nothing after the move and
- * reports nothing, which is a stale reference passing the check that exists to
- * find it rather than a check that fails.
+ * The boundary a root's own leading character rules out.
+ *
+ * A dotted root cannot be a suffix of a path segment, since a segment boundary
+ * is a slash and a slash can never sit inside the dot itself, so a preceding
+ * slash is not a false match to guard against and the boundary admits it. That
+ * is what a relative link needs, since `../.claude/context/<entry>.md` carries
+ * a slash immediately before `.claude`. A bare root has no such protection: it
+ * is a suffix of a dotted root's own name and of any `/<root>/` path segment,
+ * so its boundary rejects a slash along with a name character or a dot.
+ */
+function rootBoundary(root: string): string {
+  return root.startsWith('.') ? '(?<![\\w.])' : '(?<![\\w./])'
+}
+
+/**
+ * Every record and surface root is spelled, so a citation into a folder that
+ * has moved is still resolved. A pattern fixed at one root matches nothing
+ * after the move and reports nothing, which is a stale reference passing the
+ * check that exists to find it rather than a check that fails.
+ *
+ * Each root carries its own boundary rather than one shared ahead of the whole
+ * alternation, per `rootBoundary`. A shared boundary rejecting a slash blocked
+ * every dotted root from a relative link, which is the same failure this
+ * function's own boundary exists to prevent, aimed at the roots that never
+ * needed it.
  */
 export function citationPattern(folders: readonly string[]): RegExp {
   const names = folders.map((name) => escape(name))
-  const roots = RECORD_ROOTS.map((name) => escape(name))
+  const roots = [...new Set([...RECORD_ROOTS, ...SURFACE_ROOTS])]
+  const alternatives = roots
+    .map((root) => `${rootBoundary(root)}${escape(root)}`)
+    .join('|')
 
   return new RegExp(
-    `(?:${roots.join('|')})/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
+    `(?:${alternatives})/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
     'g',
   )
 }

package/src/context/folders.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { INDEX_FILE, listIndexes } from '@/indexes/walk'
 import { RECORD_ROOTS } from '@/record-root'
+import { SURFACE_ROOTS } from '@/surface-root'
 
 /**
  * Folder names under a record root audited by default.
@@ -23,16 +24,34 @@ export const DEFAULT_FOLDERS: readonly string[] = [
 ]
 
 /**
- * The bases every folder in the default list is looked for under, in the record
- * roots' own precedence order.
+ * The bases every folder in the default list is looked for under.
  *
- * `diagrams` is the one name here that is a session record and moves with them,
- * so the list has to carry the root it moves to. `context` and `wireframes` are
- * tracked and stay, which leaves them resolvable at a root nothing will ever put
- * them under. That costs one `existsSync` apiece and is cheaper than a per-name
- * base map that would state the same split twice.
+ * `diagrams` is a session record and resolves under `RECORD_ROOTS`, while
+ * `context` and `wireframes` are tracked and resolve under `SURFACE_ROOTS`, so
+ * the split this comment used to describe as hypothetical is real: two
+ * folders on this list read from two different root lists. The base array is
+ * their union rather than a per-name map, since a name resolving at the wrong
+ * root costs one extra `existsSync` and nothing else, where a map states the
+ * split a second time next to the one each resolver module already carries.
+ *
+ * `.claude` is pushed last because both lists name it, and each list's own
+ * precedence otherwise survives: `canon` still precedes `.claude` for a
+ * `SURFACE_ROOTS` name, and `.canon` still precedes `.claude` for a
+ * `RECORD_ROOTS` one. Order between `canon` and `.canon` is unobserved, since
+ * no name on this list resolves under both.
+ *
+ * Adding `canon` here means a target holding a root-level `canon/` folder of
+ * its own now resolves it as the toolkit's, since a project writing about a
+ * product called canon is a plausible name collision `canResolveAtRoot`'s own
+ * project-root gate does not cover. The audit only reports, so the cost is a
+ * wrong scope line rather than a wrong edit.
  */
-const CLAUDE_BASES: readonly string[] = RECORD_ROOTS
+const CLAUDE_BASES: readonly string[] = [
+  ...new Set(
+    [...SURFACE_ROOTS, ...RECORD_ROOTS].filter((root) => root !== '.claude'),
+  ),
+  '.claude',
+]
 
 /** The project root, reached only by a name the caller asked for. */
 const ROOT_BASE = '.'

package/src/gate/measures.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 import {
   CLIENT_COMMAND_MARKER,
   CLIENT_COMMANDS,
@@ -15,6 +15,7 @@ import {
   SHIPPED_CORPORA,
   type ShippedReference,
 } from '@/shipped/references'
+import { surfaceDir } from '@/surface-root'
 import {
   README_PARAPHRASE_MARKER,
   readmeCitationsIn,
@@ -122,11 +123,18 @@ export const SANDBOX_UNDECLARED_CEILING = 47
 export const SANDBOX_ASSERTED_FLOOR = 26
 
 /**
- * The retained counts the audit stage compares each run against. Spelled here
- * rather than derived, because this stage only ever names the file in a remedy
- * a reader has to be able to open, and `canon audits run` owns writing it.
+ * Where the retained counts the audit stage compares each run against are
+ * read, relative to `root`.
+ *
+ * A function rather than a spelled constant, since the read now resolves at
+ * either surface root and a constant naming one of them would be believed of
+ * a project that has moved. `canon audits run` owns writing it, and the write
+ * stays at the creation default for this batch, so the two can disagree for
+ * exactly the release window `src/surface-root.ts` documents.
  */
-export const AUDITS_BASELINE = '.claude/canon/baseline.json'
+export function auditsBaselineRel(root: string): string {
+  return relative(root, surfaceDir(root, 'canon', 'baseline.json'))
+}
 
 export const CAPTURE_STAMP_FAILURE =
   'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets/captures --selector .window --out assets and commit each frame with its image and its stamp.'
@@ -958,16 +966,17 @@ export const auditSet: Measure = async (ctx) => {
       ),
     )
   }
+  const baselineRel = auditsBaselineRel(ctx.root)
   emissions.push(
     summary.grown > 0
       ? warn(
-          `${summary.grown} measure(s) grew against ${AUDITS_BASELINE}. Run bun src/cli.ts audits run to see which, then fix them or re-record and say why.`,
+          `${summary.grown} measure(s) grew against ${baselineRel}. Run bun src/cli.ts audits run to see which, then fix them or re-record and say why.`,
         )
-      : info(`No measure grew against ${AUDITS_BASELINE}`),
+      : info(`No measure grew against ${baselineRel}`),
   )
   if (typeof summary.shrunk === 'number' && summary.shrunk > 0) {
     emissions.push(
-      info(`${summary.shrunk} measure(s) fell against ${AUDITS_BASELINE}`),
+      info(`${summary.shrunk} measure(s) fell against ${baselineRel}`),
     )
   }
 

package/src/init/plan.ts

@@ -1,4 +1,4 @@
-export const SKIPPABLE_DOMAINS = ['wiki', 'governance'] as const
+export const SKIPPABLE_DOMAINS = ['wiki', 'governance', 'records'] as const
 
 export type SkippableDomain = (typeof SKIPPABLE_DOMAINS)[number]
 
@@ -104,6 +104,13 @@ export function planInit(flags: InitFlags): InitPlan {
     })
   }
 
+  if (!flags.skip.skipped.has('records')) {
+    preview.push({
+      level: 'info',
+      text: 'records (one-time backup setup notice)',
+    })
+  }
+
   const total = preview.filter((line) => line.level === 'info').length
 
   return { preview, total }

package/src/init/steps.ts

@@ -4,6 +4,13 @@ import type { DomainStep } from '@/init/run'
 /** Builds the child-process invocation for one domain. */
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
 
+/**
+ * States the same fact as `docs/target-projects.md`'s backup section in its
+ * own words. Keep the two in step by hand; nothing compares them.
+ */
+const RECORDS_SETUP_NOTICE =
+  "No private repository to push to yet. Run 'canon records push' once one exists to print the one-time setup command, or --skip records to silence this."
+
 /**
  * Orders the domains an init installs. Base tooling seeds the files the later
  * domains install alongside, so the sequence is part of the contract rather
@@ -56,6 +63,16 @@ export function buildSteps(
     })
   }
 
+  if (!flags.skip.skipped.has('records')) {
+    // `skip` here means there is nothing to run non-interactively, not that
+    // the caller opted out, unlike every other push of this kind above.
+    steps.push({
+      kind: 'skip',
+      label: 'Records backup',
+      notice: RECORDS_SETUP_NOTICE,
+    })
+  }
+
   return steps
 }
 

package/src/intake/folder.ts

@@ -138,7 +138,7 @@ function matchSlug(names: readonly string[], slug: string): SlugMatch {
   return { kind: 'none' }
 }
 
-function extractOrdinal(name: string): string {
+export function extractOrdinal(name: string): string {
   return /^\d{2,}-/.exec(name)?.[0].slice(0, -1) ?? ''
 }
 

package/src/migrate/records.ts

@@ -76,10 +76,14 @@ function escape(value: string): string {
  * paths a session actually opened. Rewriting either makes it testify to
  * something that never happened.
  *
- * This module and `src/record-root.ts` are the two sources that state the old
+ * This module and `src/record-root.ts` are two of the sources that state the old
  * root on purpose. Sweeping them turns every citation this expression is built
  * from into its own replacement, leaving a rewriter that maps `.canon/` to
- * `.canon/` and matches nothing.
+ * `.canon/` and matches nothing. `src/surface-root.ts` joins the list a release
+ * early, for the same reason: it spells `.claude` as data the moment it
+ * exists, and excluding it later would leave one release where a records
+ * migration in a target could rewrite the resolver that migration itself
+ * depends on.
  *
  * A test file is excluded because the fixtures that prove the old root still
  * resolves have to keep building it. Rewriting one is worse than a failing
@@ -106,7 +110,11 @@ const EXCLUDED_PREFIXES: readonly string[] = [
   'tooling/claude/seeds/.claude/hooks/',
 ]
 
-const EXCLUDED_PATHS: readonly string[] = ['CHANGELOG.md', 'src/record-root.ts']
+const EXCLUDED_PATHS: readonly string[] = [
+  'CHANGELOG.md',
+  'src/record-root.ts',
+  'src/surface-root.ts',
+]
 
 const EXCLUDED_SUFFIXES: readonly string[] = ['.test.ts']