@erclx/canon 5.19.0 → 5.20.0

package/src/claude/cases/misc.ts

@@ -84,6 +84,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Find me the strongest evidence on whether rent control reduces housing supply. Where should I look?',
     expect: 'search-craft',
   },
+  {
+    prompt:
+      'The composed demo video looks generic and the zoom drags. What should the captions say, and how fast should the push-in be?',
+    expect: 'video-craft',
+  },
   {
     prompt:
       "I've got the plan approved and it touches the parser, the command, and the docs. How should I build it so I don't end up with one giant diff?",

package/src/claude/routing.ts

@@ -196,7 +196,7 @@ function frontmatter(text: string): string {
  *
  * A glob opening `**` reaches every folder in the tree, so it answers that a
  * file type is governed and never that a named path is. Counting one would
- * report every markdown path covered by `801-markdown` and leave the column
+ * report every markdown path covered by the markdown rule and leave the column
  * saying nothing a reader could act on.
  */
 function isAnchored(glob: string): boolean {

package/src/commands/canvas.ts

@@ -13,7 +13,7 @@ import {
   readSelection,
   renamePage,
 } from '@/canvas/content'
-import { captureCanvas } from '@/canvas/capture'
+import { captureCanvas, captureComposite } from '@/canvas/capture'
 import {
   type EditRefused,
   editFrameAtIndex,
@@ -468,6 +468,10 @@ export function register(program: Command): void {
       .option(
         '-o, --out <path>',
         'The PNG for a frame, or the folder for a page; defaults to session scratch',
+      )
+      .option(
+        '--composite',
+        'Capture a page as one PNG with every frame at its layout position; --out is then the PNG',
       ),
   )
     .addHelpText(
@@ -478,18 +482,25 @@ export function register(program: Command): void {
         'the injected tokens are in the PNG and each frame renders at its own',
         'width. The raw file on disk is never captured.',
         '',
+        'With --composite, each frame is clipped to its box as on the board and',
+        'shows in its default theme, with no captions or selection outline.',
+        '',
         'Exit codes:',
         '  0  every frame rendered',
         '  1  refused or a frame failed, with the reason on stderr or in the JSON record',
         '',
       ].join('\n'),
     )
-    .action(async (target: string, opts: RootOptions & { out?: string }) => {
+    .action(async (target: string, opts: CaptureOptions) => {
       const resolved = await resolveRoot(opts)
       if (!resolved.ok) {
         process.exitCode = refuse(resolved, opts.json ?? false)
         return
       }
+      if (opts.composite) {
+        process.exitCode = await runComposite(resolved.root, target, opts)
+        return
+      }
       let outcome: Awaited<ReturnType<typeof captureCanvas>>
       try {
         outcome = await captureCanvas(
@@ -543,6 +554,69 @@ export function register(program: Command): void {
     })
 }
 
+interface CaptureOptions extends RootOptions {
+  readonly out?: string
+  readonly composite?: boolean
+}
+
+async function runComposite(
+  root: string,
+  target: string,
+  opts: CaptureOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  let outcome: Awaited<ReturnType<typeof captureComposite>>
+  try {
+    outcome = await captureComposite(
+      root,
+      target,
+      opts.out ? resolve(process.cwd(), opts.out) : undefined,
+    )
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return refuse({ ok: false, reason: 'capture-failed', detail }, emitJson)
+  }
+  if (!outcome.ok) return refuse(outcome, emitJson)
+
+  const { target: item, result } = outcome.composite
+  if (result.status === 'failed') {
+    if (emitJson) {
+      writeJson({
+        ok: false,
+        composite: {
+          page: item.page,
+          status: result.status,
+          reason: result.reason,
+        },
+      })
+    }
+    intro(BANNER)
+    logError(`${item.page}: ${result.reason}`)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    writeJson({
+      ok: true,
+      composite: {
+        page: item.page,
+        status: result.status,
+        path: result.pngPath,
+        width: result.width,
+        height: result.height,
+      },
+    })
+  }
+  intro(BANNER)
+  logAdd(
+    `${item.page} composite of ${plural(item.composite.placements.length, 'frame')}`,
+  )
+  logInfo(`${displayPath(result.pngPath)} ${result.width}x${result.height}`)
+  outro()
+  return 0
+}
+
 /** NaN for a value that is not a number, which the content module refuses. */
 function parsePosition(raw: string | undefined, fallback: number): number {
   if (raw === undefined) return fallback

package/src/commands/gov.ts

@@ -12,6 +12,7 @@ import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel, SCRATCH } from '@/record-root'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
+import { regenStandardRules } from '@/gov/standard-rules'
 import { installRules, lookupRules } from '@/gov/install'
 import { buildGovCatalog, describeRule, describeStack } from '@/gov/list'
 import { buildRulesPayload, listRuleFiles } from '@/gov/payload'
@@ -190,15 +191,19 @@ export function register(program: Command): void {
 
   gov
     .command('regen')
-    .description("Rebuild a repository's own .claude/rules/ from its record")
+    .description(
+      "Rebuild the standard-pointer rules and a repository's own .claude/rules/",
+    )
     .helpOption('-h, --help', 'Show this help message')
     .option('--root <path>', 'Repository root to regenerate', PROJECT_ROOT)
     .addHelpText(
       'after',
       [
         '',
-        'Reads internal/governance.toml and installs the stack it names, plus',
-        'any rules under internal/rules/. Unlike install and sync, this runs',
+        'First writes governance/rules/standards/ from the paths: and rule:',
+        'fields in each standard under standards/. Then reads',
+        'internal/governance.toml and installs the stack it names, plus any',
+        'rules under internal/rules/. Unlike install and sync, this runs',
         'against the toolkit root, whose .claude/rules/ is produced output.',
         '',
       ].join('\n'),
@@ -1114,7 +1119,17 @@ async function runRegen(
     if (mismatch !== undefined) logWarn(mismatch)
   }
 
-  const result = await regenConsumedRules(resolve(opts.root ?? PROJECT_ROOT))
+  const root = resolve(opts.root ?? PROJECT_ROOT)
+
+  // The consumed copy installs from `governance/rules/`, so the band this
+  // writes has to be fresh before that copy is built from it.
+  const generated = await regenStandardRules(root)
+  if (!generated.ok) {
+    process.stderr.write(`Standard-rules regen failed: ${generated.reason}\n`)
+    return 1
+  }
+
+  const result = await regenConsumedRules(root)
 
   if (!result.ok) {
     process.stderr.write(`Consumed-rules regen failed: ${result.reason}\n`)

package/src/commands/sandbox.ts

@@ -346,6 +346,7 @@ function runCoverage(options: CoverageOptions): void {
 interface EquivalenceOptions {
   readonly base: string
   readonly includeAnchor?: boolean
+  readonly stubRemote?: boolean
   readonly out?: string
   readonly masks: boolean
   readonly json?: boolean
@@ -372,6 +373,7 @@ async function runEquivalence(
       targets,
       base: options.base,
       includeAnchor: options.includeAnchor === true,
+      stubRemote: options.stubRemote === true,
       useMasks: options.masks,
       out: options.out,
     })
@@ -568,6 +570,10 @@ export function register(program: Command): void {
       '--include-anchor',
       'Also run the arms that push to the shared GitHub anchor, one at a time (attended)',
     )
+    .option(
+      '--stub-remote',
+      'Run the anchor arms against a local bare repository and a stub gh, writing nothing to the shared anchor',
+    )
     .option('--out <dir>', 'Keep the provisioned trees and logs in this folder')
     .option(
       '--no-masks',
@@ -583,6 +589,7 @@ export function register(program: Command): void {
         '  canon sandbox equivalence claude:plan-feature --base origin/main',
         '',
         'Provisions offline only and never runs sandbox/run.sh or a claude binary.',
+        '--stub-remote also runs the anchor arms, and wins over --include-anchor.',
         'Exit codes: 0 when every compared arm is identical or red the same way',
         'on both sides, 1 on any difference, exit mismatch, or enumeration error.',
       ].join('\n'),

package/src/gate/stages.ts

@@ -192,11 +192,17 @@ export const STAGES: readonly Stage[] = [
         argv: ['gov', 'regen'],
         failure: 'Consumed-copy regen failed',
       },
+      {
+        kind: 'drift',
+        pathspec: 'governance/rules/standards',
+        failure:
+          'Standard-pointer rules drifted. Run bun run check and commit governance/rules/standards and .claude/rules.',
+      },
       {
         kind: 'drift',
         pathspec: '.claude/rules',
         failure:
-          'Consumed copies drifted. Run bun run check and commit .claude/rules.',
+          'Consumed copies drifted. Run bun run check and commit governance/rules/standards and .claude/rules.',
       },
     ],
     success: 'Consumed copies clean',

package/src/gov/citations.ts

@@ -266,7 +266,7 @@ export function collectCitations(text: string): RawCitation[] {
  *
  * A rule spelling a whole path there is declaring that exact artifact, and a
  * body line naming it again is naming what the rule governs rather than
- * pointing a reader somewhere. `governance/rules/canon/660-diagrams.md` tells
+ * pointing a reader somewhere. `governance/rules/standards/diagrams.md` tells
  * its reader to convert a `.claude/DIAGRAMS.md` left by an older install, which
  * is correctly absent from this tree and correctly named in the rule.
  */

package/src/gov/standard-rules.ts

@@ -0,0 +1,179 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { basename, join, relative } from 'node:path'
+import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
+import { parseFrontmatter } from '@/indexes/frontmatter'
+
+const STANDARDS_REL = 'standards'
+
+/** The band the generated rules ship in, named for what they point at. */
+export const STANDARD_RULES_BAND = 'standards'
+
+export type StandardRulesResult =
+  | { readonly ok: true; readonly written: readonly string[] }
+  | { readonly ok: false; readonly reason: string }
+
+interface StandardRule {
+  readonly name: string
+  readonly sourceRel: string
+  readonly title: string
+  readonly description: string
+  readonly paths: readonly string[]
+  readonly bullets: readonly string[]
+}
+
+export function standardRulesDir(root: string): string {
+  return join(rulesSourceDir(root), STANDARD_RULES_BAND)
+}
+
+/**
+ * Generates one path-scoped rule per standard whose frontmatter carries
+ * `paths:`. The standard owns the glob and the operative bullets, so the rule
+ * is output, committed beside the authored bands so every reader of
+ * `governance/rules/` sees it as an ordinary file.
+ *
+ * Every standard is read and checked before anything is written, so a refusal
+ * leaves the previous output whole rather than half cleared.
+ */
+export async function regenStandardRules(
+  root: string,
+): Promise<StandardRulesResult> {
+  const standardsDir = join(root, STANDARDS_REL)
+  if (!existsSync(standardsDir)) return { ok: true, written: [] }
+
+  const reserved = reservedNames(root)
+  const rules: StandardRule[] = []
+
+  for (const file of readdirSync(standardsDir).sort()) {
+    if (!file.endsWith('.md')) continue
+    const read = readStandard(root, file, reserved)
+    if (typeof read === 'string') return { ok: false, reason: read }
+    if (read !== undefined) rules.push(read)
+  }
+
+  const dir = standardRulesDir(root)
+  await rm(dir, { recursive: true, force: true })
+  if (rules.length > 0) await mkdir(dir, { recursive: true })
+
+  const written: string[] = []
+  for (const rule of rules) {
+    const dest = join(dir, `${rule.name}.md`)
+    await writeFile(dest, renderStandardRule(rule))
+    written.push(relative(root, dest))
+  }
+
+  return { ok: true, written }
+}
+
+/**
+ * Band folders and authored rule basenames. A bare-word rule name equal to a
+ * band would install the whole band through `--add`, and one equal to an
+ * authored rule would shadow it in the name index.
+ */
+function reservedNames(root: string): {
+  readonly bands: ReadonlySet<string>
+  readonly rules: ReadonlySet<string>
+} {
+  const bands = new Set<string>([STANDARD_RULES_BAND])
+  const rules = new Set<string>()
+
+  for (const rel of listRuleSourcePaths(root)) {
+    const segments = rel.split('/')
+    if (segments.length > 1) bands.add(segments[0])
+    if (segments[0] === STANDARD_RULES_BAND) continue
+    rules.add(basename(rel, '.md'))
+  }
+
+  return { bands, rules }
+}
+
+/** A rule to render, `undefined` for a standard with no `paths:`, or a reason. */
+function readStandard(
+  root: string,
+  file: string,
+  reserved: ReturnType<typeof reservedNames>,
+): StandardRule | string | undefined {
+  const sourceRel = `${STANDARDS_REL}/${file}`
+  const fields = parseFrontmatter(
+    readFileSync(join(root, STANDARDS_REL, file), 'utf8'),
+  )?.fields
+  if (fields === undefined || fields.paths === undefined) return undefined
+
+  const name = basename(file, '.md')
+  if (!isStringList(fields.paths)) {
+    return `${sourceRel}: paths must be a list of strings`
+  }
+  if (fields.rule !== undefined && !isStringList(fields.rule)) {
+    return `${sourceRel}: rule must be a list of strings`
+  }
+  if (reserved.bands.has(name)) {
+    return `${sourceRel}: name collides with a rule band folder`
+  }
+  if (reserved.rules.has(name)) {
+    return `${sourceRel}: name collides with an authored rule`
+  }
+
+  return {
+    name,
+    sourceRel,
+    title: typeof fields.title === 'string' ? fields.title : name,
+    description:
+      typeof fields.description === 'string' ? fields.description : '',
+    paths: fields.paths,
+    bullets: fields.rule ?? [],
+  }
+}
+
+function isStringList(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+  )
+}
+
+function renderStandardRule(rule: StandardRule): string {
+  const scope = rule.description.replace(/\.$/, '')
+  const pointer = [
+    `Follow the ${rule.name} standard for ${lowerFirst(scope)}.`,
+    'It is the single source.',
+    `Read it with \`canon standards ${rule.name}\`.`,
+  ].join(' ')
+
+  return [
+    '---',
+    `# Generated by \`canon gov regen\` from ${rule.sourceRel}. Edit that frontmatter, not this file.`,
+    `description: ${yamlScalar(rule.description)}`,
+    'paths:',
+    ...rule.paths.map((glob) => `  - ${yamlQuoted(glob)}`),
+    '---',
+    '',
+    `# ${rule.title.replace(/\breference$/, 'standards')}`,
+    '',
+    '## Authority',
+    '',
+    ...[pointer, ...rule.bullets].map((bullet) => `- ${bullet}`),
+    '',
+  ].join('\n')
+}
+
+function lowerFirst(text: string): string {
+  return text.charAt(0).toLowerCase() + text.slice(1)
+}
+
+/** Plain when YAML would read it back unchanged, single-quoted otherwise. */
+function yamlScalar(text: string): string {
+  const isPlain =
+    text !== '' &&
+    !/^[-?:,[\]{}#&*!|>'"%@`\s]/.test(text) &&
+    !/: |\s#|:$|\s$/.test(text)
+  return isPlain ? text : yamlQuoted(text)
+}
+
+/**
+ * Quoted the way Prettier's `singleQuote` leaves YAML, so the drift check
+ * never fights the formatter: single quotes unless the text holds one and
+ * double quotes would need no escape.
+ */
+function yamlQuoted(text: string): string {
+  if (text.includes("'") && !/["\\]/.test(text)) return `"${text}"`
+  return `'${text.replaceAll("'", "''")}'`
+}

package/src/sandbox/equivalence.ts

@@ -17,6 +17,7 @@ import {
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { collectCoverage, DEFAULT_ARM } from '@/sandbox/coverage'
+import { createStubRemote, readStubManifest } from '@/sandbox/stub-remote'
 
 /** Holds fixture content rather than scenarios. Twin of the filter in `sandbox.ts`. */
 const FIXTURES_DIR = 'fixtures'
@@ -136,6 +137,8 @@ export interface EquivalenceOptions {
   readonly targets: readonly string[]
   readonly base: string
   readonly includeAnchor: boolean
+  /** Runs anchor arms against a local bare repository and a stub `gh`, never the shared anchor. */
+  readonly stubRemote?: boolean
   readonly useMasks: boolean
   readonly out?: string
 }
@@ -516,7 +519,15 @@ function configDirFor(dir: string): string {
   return `${dir}.config`
 }
 
-function provisionEnv(arm: Arm, dir: string): NodeJS.ProcessEnv {
+function stubDirFor(dir: string): string {
+  return `${dir}.stub`
+}
+
+function provisionEnv(
+  arm: Arm,
+  dir: string,
+  stubbed = false,
+): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {
     ...process.env,
     CANON_NON_INTERACTIVE: '1',
@@ -524,6 +535,7 @@ function provisionEnv(arm: Arm, dir: string): NodeJS.ProcessEnv {
     CANON_SANDBOX_RUN_ID: PINNED_RUN_ID,
     CLAUDE_CONFIG_DIR: configDirFor(dir),
   }
+  if (stubbed) Object.assign(env, createStubRemote(stubDirFor(dir)))
   if (arm.arm === undefined) delete env.SANDBOX_SCENARIO
   else env.SANDBOX_SCENARIO = arm.arm
 
@@ -541,13 +553,14 @@ async function provision(
   arm: Arm,
   dir: string,
   logPath: string,
+  stubbed: boolean,
 ): Promise<Provisioned> {
   rmSync(dir, { recursive: true, force: true })
   rmSync(configDirFor(dir), { recursive: true, force: true })
   const exit = await runProcess(
     'bun',
     [join(root, 'src', 'cli.ts'), 'sandbox', `${arm.category}:${arm.command}`],
-    { cwd: root, env: provisionEnv(arm, dir), logPath },
+    { cwd: root, env: provisionEnv(arm, dir, stubbed), logPath },
   )
   const log = readFileSync(logPath, 'utf8').split(root).join(ROOT_PLACEHOLDER)
 
@@ -592,8 +605,12 @@ async function checkHead(
   }
 }
 
-function withExit(manifest: Manifest, run: Provisioned): Manifest {
-  const next = new Map(manifest)
+function withExit(
+  manifest: Manifest,
+  run: Provisioned,
+  stub?: Manifest,
+): Manifest {
+  const next = new Map([...manifest, ...(stub ?? [])])
   next.set('exit', String(run.exit))
   next.set('log', run.log)
 
@@ -608,16 +625,20 @@ async function runArm(
   headRoot: string,
   masks: readonly Mask[],
   declared: boolean,
+  stubbed: boolean,
 ): Promise<ArmRecord> {
   const key = armKey(arm)
   const dir = join(workDir, 'arms', `arm-${index}`)
   const logPath = join(workDir, 'logs', `arm-${index}.log`)
 
-  const base = await provision(baseRoot, arm, dir, logPath)
-  const baseManifest = withExit(buildManifest(dir), base)
+  const stubManifest = (): Manifest | undefined =>
+    stubbed ? readStubManifest(stubDirFor(dir)) : undefined
 
-  const head = await provision(headRoot, arm, dir, logPath)
-  const headManifest = withExit(buildManifest(dir), head)
+  const base = await provision(baseRoot, arm, dir, logPath, stubbed)
+  const baseManifest = withExit(buildManifest(dir), base, stubManifest())
+
+  const head = await provision(headRoot, arm, dir, logPath, stubbed)
+  const headManifest = withExit(buildManifest(dir), head, stubManifest())
 
   // Kept beside the logs, so a reader of an `--out` folder can see what a
   // difference was rather than only that one exists.
@@ -643,6 +664,7 @@ async function runArm(
     : undefined
 
   rmSync(configDirFor(dir), { recursive: true, force: true })
+  rmSync(stubDirFor(dir), { recursive: true, force: true })
 
   return {
     arm: key,
@@ -770,8 +792,13 @@ export async function runEquivalence(
   try {
     const baseRoot = join(workDir, 'base')
     const baseCommit = git(options.root, ['rev-parse', options.base])
-    const runnable = arms.filter((a) => !a.anchor || options.includeAnchor)
-    const skipped = arms.filter((a) => a.anchor && !options.includeAnchor)
+    const stubRemote = options.stubRemote === true
+    const runnable = arms.filter(
+      (a) => !a.anchor || options.includeAnchor || stubRemote,
+    )
+    const skipped = arms.filter(
+      (a) => a.anchor && !options.includeAnchor && !stubRemote,
+    )
 
     const indexed = new Map(arms.map((a, i) => [armKey(a), i]))
     const run = (arm: Arm): Promise<ArmRecord> =>
@@ -783,18 +810,20 @@ export async function runEquivalence(
         options.root,
         masks,
         declaredKeys.has(armKey(arm)),
+        stubRemote && arm.anchor,
       )
 
     // Anchor arms force-push `main` and recreate a pull request on one shared
-    // remote, so they run strictly one at a time.
+    // remote, so they run strictly one at a time. A stub remote is private to its
+    // arm, so those arms join the pool.
+    const shared = (a: Arm): boolean => a.anchor && !stubRemote
     const offline = await pool(
-      runnable.filter((a) => !a.anchor),
+      runnable.filter((a) => !shared(a)),
       CONCURRENCY,
       (arm) => run(arm),
     )
     const anchored: ArmRecord[] = []
-    for (const arm of runnable.filter((a) => a.anchor))
-      anchored.push(await run(arm))
+    for (const arm of runnable.filter(shared)) anchored.push(await run(arm))
 
     const records: ArmRecord[] = [
       ...offline,