@erclx/canon 5.19.0 → 5.21.0

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/commands/slides.ts

@@ -119,9 +119,11 @@ 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 or a refused link 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.
+ * jszip, or the token module at startup. A fallback, a refused link or chart,
+ * 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
+ * out and exits 1.
  */
 async function renderHtmlFolder(
   sourceDir: string,
@@ -156,6 +158,14 @@ async function renderHtmlFolder(
       `${GREY}│${NC} ${RED}✗${NC} slide ${slide} ${selector} link "${href}" left out: ${reason}\n`,
     )
   }
+  for (const { slide, selector, message } of result.refusedCharts) {
+    process.stderr.write(
+      `${GREY}│${NC} ${RED}✗${NC} slide ${slide} ${selector} chart left out: ${message}\n`,
+    )
+  }
+  for (const notice of result.notices) {
+    process.stderr.write(`${GREY}│${NC} ${RED}✗${NC} ${notice}\n`)
+  }
   if (result.mirrorPath) {
     process.stderr.write(
       `${GREY}│${NC} ${GREEN}✓${NC} mirrored to ${result.mirrorPath}\n`,

package/src/commands/tasks.ts

@@ -65,6 +65,7 @@ const EXIT_FINDINGS = 2
 
 /** Matches `trunk.ts`'s bound on a git subprocess this verb also shells out to. */
 const GIT_TIMEOUT_MS = 10_000
+const GH_TIMEOUT_MS = 10_000
 
 const TRUNK_BRANCHES: readonly string[] = ['main', 'master']
 
@@ -522,7 +523,9 @@ export function register(program: Command): void {
         'Run from a branch other than main or master, a close that ticks a new',
         'box names that branch on a Pending branch: line, which holds the task',
         'against a merge-time archive until canon tasks pull-request records',
-        "the branch's own number.",
+        "the branch's own number. The marker is skipped once gh lists a pull",
+        "request for the branch whose number is already on the task's Pull",
+        'request: line, and a failed gh lookup writes it.',
         '',
         'Examples:',
         '  canon tasks outcome v28.1-trigger-escalation --close 1 --close 3',
@@ -728,6 +731,45 @@ async function workingBranch(): Promise<string | undefined> {
   return branch
 }
 
+/**
+ * The pull request numbers whose head is `branch`, open or not. A failed run,
+ * an unreadable answer, or no `gh` at all returns an empty list, which writes
+ * the marker, the direction that holds a task open rather than archiving it.
+ */
+async function branchPullNumbers(
+  branch: string | undefined,
+): Promise<readonly number[]> {
+  if (branch === undefined) return []
+
+  const result = await execa(
+    'gh',
+    ['pr', 'list', '--head', branch, '--state', 'all', '--json', 'number'],
+    {
+      cwd: process.cwd(),
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (result.exitCode !== 0) return []
+
+  try {
+    const rows: unknown = JSON.parse(result.stdout)
+    if (!Array.isArray(rows)) return []
+
+    return rows
+      .map((row: unknown) =>
+        typeof row === 'object' && row !== null && 'number' in row
+          ? row.number
+          : undefined,
+      )
+      .filter((number): number is number => Number.isInteger(number))
+  } catch {
+    return []
+  }
+}
+
 async function runPlanLink(
   task: string,
   plan: string,
@@ -789,11 +831,13 @@ async function runOutcome(
   }
 
   const root = opts.root ?? (await mainWorktreeRoot())
+  const branch = await workingBranch()
   const outcome = await closeOutcomes(
     root,
     selector,
     raw.map(Number),
-    await workingBranch(),
+    branch,
+    await branchPullNumbers(branch),
   )
 
   return reportOutcome(outcome, emitJson, root)

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/migrate/skill-names.ts

@@ -110,11 +110,6 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
  * what shipped or what a session ran under whatever name was current then, so
  * rewriting one makes it testify to a release or a run that never happened.
  *
- * The pointer left at `docs-fold` is excluded because it exists to answer under
- * the old name, so a later run would move it onto the skill it points at. The
- * exclusion is only safe once the real body has moved, since excluding the path
- * ahead of the first sweep leaves that body behind.
- *
  * The record archives need no entry here. They are gitignored, so the tracked
  * listing every sweep reads never reaches them.
  */
@@ -127,7 +122,5 @@ export const SKILL_NAME_RULES: RenameRules = defineRenameRules({
     'CHANGELOG.md',
     'src/migrate/skill-names.ts',
     'src/migrate/skill-names.test.ts',
-    'claude/skills/docs-fold/SKILL.md',
-    'claude/skills/docs-fold/REQUIREMENT.md',
   ],
 })

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,