@erclx/canon 5.74.0 → 5.76.0

package/src/commands/claude.ts

@@ -34,6 +34,7 @@ import {
   SKILL_LEDGERS,
   PRACTICE_SECTIONS,
   PRACTICE_SKILLS,
+  PROJECT_SKILL_LEDGERS,
   REQUIREMENT_LIMITS,
   REQUIREMENT_SECTIONS,
   RETIRED_REQUIREMENT_SECTION,
@@ -712,6 +713,10 @@ async function runSync(target: string): Promise<number> {
     logWarn(
       'settings.json lacks the merge deny entries. Run `canon migrate session-defaults --write`',
     )
+  } else if (defaults.kind === 'planned' && defaults.plan.lacksPushAllow) {
+    logWarn(
+      'settings.json lacks the lease push allow. Run `canon migrate session-defaults --write`',
+    )
   }
 
   logStep('Scanning .gitignore')
@@ -1772,7 +1777,7 @@ function reportProvenance(report: SkillsAudit): void {
 /**
  * Reports without failing the run for the reason provenance does. The list
  * names shipped folders alone, which the step says so a target reading a pass
- * knows its own skills were never in scope.
+ * knows its own skills were read only against a ledger it wrote.
  */
 function reportPracticeShape(report: SkillsAudit): void {
   logStep('Practice shape')
@@ -1783,7 +1788,10 @@ function reportPracticeShape(report: SkillsAudit): void {
     `A skill on the per-bullet list, ${plural(Object.keys(BULLET_LEDGER_SKILLS).length, 'skill')} here, also matches each reference it does not exempt, and a listed body, to a ledger under ${SKILL_LEDGERS}, one row per bullet under each H2.`,
   )
   logInfo(
-    `Both lists are kept here and name ${plural(PRACTICE_SKILLS.length, 'practice skill')} and ${plural(LEDGER_SKILLS.length, 'ledger skill')}, so a skill outside ${SHIPPED_CORPUS} is never read.`,
+    `Both lists are kept here and name ${plural(PRACTICE_SKILLS.length, 'practice skill')} and ${plural(LEDGER_SKILLS.length, 'ledger skill')}, so a skill outside ${SHIPPED_CORPUS} is never read against them.`,
+  )
+  logInfo(
+    `A tree with no governance/rules/ has each file under ${PROJECT_SKILL_LEDGERS} matched to the skill file of its name, one row per bullet under each H2, and owes none.`,
   )
 
   if (report.practiceShape.length === 0) {

package/src/commands/gov.ts

@@ -646,7 +646,9 @@ export function register(program: Command): void {
         `  A rule under ${CORE_FOLDERS.join(', ')} has its ledger checked where`,
         '  one exists, and under --touched owes one once the branch changed it.',
         '  With no baseline against main, --touched reads no rule as touched.',
-        '  Any other tree reads .claude/rules/project/ alone and asks no ledger.',
+        '  Any other tree reads .claude/rules/project/ and checks the ledger of',
+        '  each rule that has one at canon/ledger/rules/<subfolder>/<slug>.md.',
+        '  A ledger there with no rule is a finding on a whole-corpus read.',
         '  .claude/rules/canon/ is fixed at the toolkit source and never read',
         '  unless named. A named path resolves against --root and must sit',
         '  inside it.',
@@ -757,7 +759,10 @@ function reportAudit(
   intro('canon gov audit')
 
   const shaped = report.rules.filter((reading) => reading.findings.length > 0)
-  const ledgers = report.rules.flatMap(describeLedger)
+  const ledgers = [
+    ...report.rules.flatMap(describeLedger),
+    ...report.orphans.map((path) => `${path}: no rule for this ledger`),
+  ]
 
   logStep('Corpus')
   logInfo(
@@ -791,12 +796,12 @@ function reportAudit(
       'no baseline against main, so --touched reads no core rule as touched',
     )
   }
-  if (report.scope === 'target') {
-    logInfo('not read, since ledgers live in the toolkit and never ship')
-  } else if (ledgers.length === 0) {
-    logInfo('every rule owing a ledger has one, with a row per bullet')
-  } else {
+  if (ledgers.length > 0) {
     for (const line of ledgers) logWarn(line)
+  } else if (report.scope === 'target') {
+    logInfo('every project ledger has its rule and a row per bullet')
+  } else {
+    logInfo('every rule owing a ledger has one, with a row per bullet')
   }
 
   const failing = report.rules.filter(hasFinding).length

package/src/commands/migrate.ts

@@ -1489,9 +1489,13 @@ export function register(program: Command): void {
         'false only when the key is absent. A deny entry is never removed and',
         'an existing autoMemoryEnabled is never changed.',
         '',
+        'Where .claude/hooks/plan-guard.sh exists, also wires it into',
+        'hooks.PreToolUse for Bash and Write|Edit, skipping a tool whose',
+        'matcher already runs it, so a hand wiring is never doubled.',
+        '',
         'A missing settings file is nothing to do. A file that is not valid',
-        'JSON, or whose permissions or deny has an unexpected shape, is',
-        'refused by name and never partly written.',
+        'JSON, or whose permissions, deny, hooks, or PreToolUse has an',
+        'unexpected shape, is refused by name and never partly written.',
         '',
         'Exit codes:',
         '  0  nothing to add, or --write applied the plan',

package/src/commands/take.ts

@@ -28,6 +28,7 @@ type Take = typeof import('@/take/film')
 interface RunOptions {
   readonly out?: string
   readonly reel?: string
+  readonly maxSeconds?: string
   readonly json?: boolean
 }
 
@@ -58,6 +59,10 @@ const TAKE_REFUSALS: Record<TakeRefusal, string> = {
   'browser-missing': 'The headless shell is not installed in this project.',
   'server-unreachable': 'Nothing answered at the URL, so no beat was filmed.',
   'target-missing': 'A step names a target the page does not carry.',
+  'target-offscreen':
+    'A step names a target outside the window, so a setup step must bring it into view first.',
+  'over-cap':
+    'The filmed beats ran past --max-seconds, so the take stopped at the beat that crossed it.',
   'take-failed': 'The take failed against a reachable page.',
 }
 
@@ -80,6 +85,10 @@ export function register(program: Command): void {
       '--reel <file>',
       'Also join the beats into one animated WebP with the pointer drawn',
     )
+    .option(
+      '--max-seconds <n>',
+      'Refuse once the filmed beats run past n seconds in total',
+    )
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -153,6 +162,7 @@ export function register(program: Command): void {
         `  ${INSTALL_BROWSER}`,
         '',
         'Reasons:',
+        '  bad-max-seconds     --max-seconds is not a positive number',
         '  no-plan-file        nothing readable at the plan path',
         '  unreadable-plan     the plan file is not valid JSON',
         '  no-beats            the plan names no beat',
@@ -166,15 +176,18 @@ export function register(program: Command): void {
         '  browser-missing     the headless shell or browser binary is not installed',
         '  server-unreachable  nothing answered at the URL',
         '  target-missing      a step names a target the page does not carry',
+        '  target-offscreen    a step names a target outside the window, so a setup step must bring it into view first',
+        '  over-cap            the filmed beats ran past --max-seconds, naming the',
+        '                      beat that crossed it',
         '  take-failed         the take failed against a reachable page',
         '  reel-failed         every beat was filmed and the reel did not encode',
         '',
-        'A refusal in a beat carries beat. target-missing carries still when the',
-        "page answered a capture, the beat folder's still.jpg as the step met it. A",
-        'beat that fell back to the screencast before refusing carries fallback,',
-        'the reason it fell back. The screencast opens the address a second time,',
-        'so a single-use link is spent by then: check the access before the',
-        'selector.',
+        'A refusal in a beat carries beat. target-missing and target-offscreen',
+        "carry still when the page answered a capture, the beat folder's",
+        'still.jpg as the step met it. A beat that fell back to the screencast',
+        'before refusing carries fallback, the reason it fell back. The',
+        'screencast opens the address a second time, so a single-use link is',
+        'spent by then: check the access before the selector.',
         '',
         'Exit codes:',
         '  0  every beat was filmed, and the reel written when asked for',
@@ -300,6 +313,17 @@ async function runTake(
 
   intro(`canon take ${url}`)
 
+  const maxSeconds =
+    opts.maxSeconds === undefined ? undefined : readRate(opts.maxSeconds)
+  if (opts.maxSeconds !== undefined && maxSeconds === undefined) {
+    return refuse(
+      emitJson,
+      url,
+      'bad-max-seconds',
+      `--max-seconds ${opts.maxSeconds} is not a positive number, such as 12 or 7.5.`,
+    )
+  }
+
   let source: string
   try {
     source = readFileSync(path, 'utf8')
@@ -344,7 +368,12 @@ async function runTake(
   }
 
   logStep('Filming')
-  const result = await taker.take({ url, plan, out: opts.out })
+  const result = await taker.take({
+    url,
+    plan,
+    out: opts.out,
+    ...(maxSeconds === undefined ? {} : { maxSeconds }),
+  })
 
   if (result.status === 'failed') {
     logStep('Refused')

package/src/counts/catalogs.ts

@@ -24,12 +24,10 @@ const REGISTER_IMPORT = /^import \{ register as /gm
 /**
  * Every top-level `canon` command, read off the CLI entry point rather than a
  * catalog verb, because a command carries no `--json` listing of its own
- * siblings. `regen-hero.ts` imports this reader for its `COMMAND_COUNT`
- * rather than a second regex on `src/cli.ts`, so this is the one place that
- * pattern is written.
+ * siblings. Callers import this reader rather than a second regex on
+ * `src/cli.ts`, so this is the one place that pattern is written.
  *
- * This is the one catalog with no meaning outside this repository, the way
- * `regen-hero.ts` documents itself as clone-only for the same reason.
+ * This is the one catalog with no meaning outside this repository.
  */
 export function countCommands(root: string): number | undefined {
   const cli = join(root, 'src', 'cli.ts')

package/src/gate/measures.ts

@@ -1,5 +1,4 @@
-import { createHash } from 'node:crypto'
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import {
   CLIENT_COMMAND_MARKER,
@@ -144,9 +143,6 @@ 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/frames and commit each frame with its image and its stamp.'
-
 function parseJson(payload: string): unknown {
   try {
     return JSON.parse(payload)
@@ -1478,142 +1474,3 @@ async function collectPluginManifests(ctx: MeasureContext): Promise<string[]> {
   )
   return [...seen].sort()
 }
-
-/**
- * A capture set spans two folders. The markup and the template beside it are
- * the authored half and sit under `assets/captures/`, while the image a
- * document points at and the stamp answering for it sit under
- * `assets/frames/`, which is where `--out assets/frames` sends them. They sit
- * outside `assets/evidence/` so a changed marketing image is not read as dev
- * evidence.
- */
-const CAPTURE_MARKUP_DIR = 'assets/captures'
-const CAPTURE_OUTPUT_DIR = 'assets/frames'
-
-/**
- * Every capture under `assets/captures/`, named by the base its three files
- * share.
- *
- * Read off the folder rather than listed, and off the markup specifically,
- * because that is how `resolveCaptureSources` decides what `canon capture
- * assets/captures` renders. A list would fail open on the frame somebody adds
- * next, which is the one nobody thinks to add here, and driving off the PNGs
- * instead would report a missing set for any image in `assets/` that is not a
- * capture.
- */
-function captureBases(root: string): string[] {
-  const dir = join(root, CAPTURE_MARKUP_DIR)
-  if (!existsSync(dir)) return []
-
-  return readdirSync(dir)
-    .filter((name) => name.endsWith('.html'))
-    .map((name) => name.slice(0, -'.html'.length))
-    .sort()
-}
-
-/**
- * The drift assert on the Hero stage covers the markup because the image beside
- * it is a chromium render whose bytes move with the browser. That leaves the
- * artifact a visitor actually sees asserted nowhere, so a branch regenerating
- * the markup and never running the capture would pass every stage while
- * shipping an image with the old counts.
- *
- * `canon capture` records a digest of the markup it rendered and one of the image
- * it wrote, so this reads provenance rather than timing. Comparing the commit
- * that last touched each file passes any pair that moved together whatever the
- * two files hold, which is what a binary conflict resolved by taking either
- * side produces.
- *
- * Both digests are checked because either file can move alone. The markup side
- * catches an edit committed with no capture, and the image side catches an
- * image replaced under markup that never changed. A tree carrying no markup
- * under `assets/captures/` has no set to read and passes, which is correct.
- */
-export const captureStamps: Measure = async (ctx) => {
-  const lines = captureBases(ctx.root).flatMap((base) =>
-    readCaptureSet(ctx.root, base),
-  )
-  if (lines.length === 0) return { emissions: [] }
-
-  return {
-    emissions: [output(lines.join('\n'))],
-    failure: CAPTURE_STAMP_FAILURE,
-  }
-}
-
-/**
- * One capture set, as the lines it has to report and none where it agrees.
- *
- * The markup resolves against the source folder and the two files a render
- * writes resolve against the output folder, so the set spans both rather than
- * hanging off one base directory. Sending any of the three to the wrong folder
- * reports it as missing rather than failing loudly, since a missing file reads
- * the same way whether the path is wrong or the file is.
- */
-function readCaptureSet(root: string, base: string): string[] {
-  const set = [
-    `${CAPTURE_MARKUP_DIR}/${base}.html`,
-    `${CAPTURE_OUTPUT_DIR}/${base}.png`,
-    `${CAPTURE_OUTPUT_DIR}/${base}.stamp`,
-  ]
-
-  const missing = set.filter((rel) => !existsSync(join(root, rel)))
-  if (missing.length > 0) {
-    return [`Missing from the ${base} set: ${missing.join(' ')}`]
-  }
-
-  const [html, png, stamp] = set.map((rel) => join(root, rel))
-  return [
-    ...assertStampField(root, stamp, 'source-sha256', html),
-    ...assertStampField(root, stamp, 'image-sha256', png),
-  ]
-}
-
-/**
- * One digest the stamp recorded against the file it was taken over, returning
- * the lines to report and nothing when the two agree.
- *
- * An absent field reports itself rather than comparing against an empty string,
- * so a stamp predating the current format is distinguishable from a file that
- * moved. Both names in the message come off the paths rather than from
- * arguments, which is what keeps a name from disagreeing with the file it
- * labels once a second capture source calls this.
- */
-export function assertStampField(
-  root: string,
-  stamp: string,
-  field: string,
-  file: string,
-): string[] {
-  const stampLabel = relativeTo(root, stamp)
-  const fileLabel = relativeTo(root, file)
-
-  const recorded = readStampField(stamp, field)
-  if (recorded === undefined) {
-    return [
-      `${stampLabel} carries no ${field} line, so it predates the capture that writes one.`,
-    ]
-  }
-
-  const actual = createHash('sha256').update(readFileSync(file)).digest('hex')
-  if (recorded !== actual) {
-    return [
-      `${stampLabel} records ${field} ${recorded}`,
-      `${fileLabel} hashes to ${actual}`,
-    ]
-  }
-
-  return []
-}
-
-function readStampField(stamp: string, field: string): string | undefined {
-  for (const line of readFileSync(stamp, 'utf8').split('\n')) {
-    const [key, value] = line.trim().split(/\s+/)
-    if (key === `${field}:` && value !== undefined) return value
-  }
-  return undefined
-}
-
-function relativeTo(root: string, path: string): string {
-  return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path
-}

package/src/gate/stages.ts

@@ -8,7 +8,6 @@ import {
 import {
   canonicalRecords,
   auditSet,
-  captureStamps,
   clientCommandCitations,
   designProse,
   documentCeiling,
@@ -191,28 +190,6 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Consumed copies clean',
   },
-  {
-    // Only the markup is asserted for drift. The image beside it is a chromium
-    // render whose bytes move with the browser version, so a drift check over it
-    // would fail on a machine whose chromium differs rather than on a stale
-    // count. The stamp measure below is what covers the image instead.
-    //
-    // The stage covers every frame under `assets/captures/` and keeps the
-    // narrower name, because the label is spelled across the context entries and
-    // the CI table and renaming it buys nothing the pathspec below does not
-    // already say.
-    id: 'hero',
-    label: 'Hero',
-    checks: [
-      {
-        kind: 'command',
-        argv: ['bun', 'scripts/core/regen-hero.ts', '--check'],
-        failure: 'Hero regen health check failed',
-      },
-      { kind: 'measure', measure: captureStamps },
-    ],
-    success: 'Hero clean',
-  },
   {
     // `canon/DESIGN.md`, the web stylesheet, and the tab icon are written
     // from `src/design/tokens.ts`, and none is edited by hand. Three

package/src/gov/audit.ts

@@ -72,6 +72,13 @@ export const CORE_FOLDERS: readonly string[] = [
 
 const SHIPPED_RULES = join('governance', 'rules')
 const LEDGERS = join('governance', 'ledger')
+const TARGET_RULES = join('.claude', 'rules', 'project')
+
+/**
+ * Where a target keeps the ledgers behind its own rules. It sits outside
+ * `.claude/rules/`, where every `.md` loads as a rule, and nothing loads it.
+ */
+export const TARGET_RULE_LEDGERS = join('canon', 'ledger', 'rules')
 
 /** Both corpora authored here, read when the tree is a canon checkout. */
 const CANON_CORPUS: readonly string[] = [
@@ -83,7 +90,7 @@ const CANON_CORPUS: readonly string[] = [
  * What a target authors. `.claude/rules/canon/` is installed from the toolkit
  * and fixed at its source, so a finding there is one the target cannot act on.
  */
-const TARGET_CORPUS: readonly string[] = [join('.claude', 'rules', 'project')]
+const TARGET_CORPUS: readonly string[] = [TARGET_RULES]
 
 export interface ShapeFinding {
   readonly limit: RuleLimit
@@ -135,10 +142,18 @@ export type RuleAuditRefusal = 'no-rules' | 'no-path' | 'outside-root'
 export type RuleAuditReport =
   | {
       readonly kind: 'measured'
-      /** `canon` reads both authored corpora and ledgers, `target` neither. */
+      /**
+       * `canon` reads both authored corpora and the toolkit's ledgers,
+       * `target` its project rules and any ledger the project wrote.
+       */
       readonly scope: 'canon' | 'target'
       readonly corpus: readonly string[]
       readonly rules: readonly RuleReading[]
+      /**
+       * Target ledgers whose rule is gone, read on a whole-corpus read alone,
+       * since a named path scopes the read to the files named.
+       */
+      readonly orphans: readonly string[]
     }
   | {
       readonly kind: 'unreadable'
@@ -336,7 +351,18 @@ export function compareLedger(
 function ledgerFor(
   file: string,
   touched: ReadonlySet<string>,
+  scope: 'canon' | 'target',
 ): { path: string; owed: boolean } | undefined {
+  // A project has no practice-folder list to owe a ledger against, so its
+  // ledger is checked where it exists and never owed.
+  if (scope === 'target') {
+    const prefix = `${TARGET_RULES}${sep}`
+    if (!file.startsWith(prefix)) return undefined
+    return {
+      path: join(TARGET_RULE_LEDGERS, file.slice(prefix.length)),
+      owed: false,
+    }
+  }
   const prefix = `${SHIPPED_RULES}${sep}`
   if (!file.startsWith(prefix)) return undefined
   const rest = file.slice(prefix.length)
@@ -352,8 +378,9 @@ async function readLedger(
   file: string,
   groups: readonly HeadingCount[],
   touched: ReadonlySet<string>,
+  scope: 'canon' | 'target',
 ): Promise<LedgerReading> {
-  const ledger = ledgerFor(file, touched)
+  const ledger = ledgerFor(file, touched, scope)
   if (ledger === undefined) return { status: 'not-required' }
   const { path } = ledger
 
@@ -373,14 +400,29 @@ async function readLedger(
   }
 }
 
+/**
+ * Target ledgers with no rule at the matching `.claude/rules/project/` path,
+ * so a rule moved or renamed away from its ledger is reported rather than
+ * dropping its check silently.
+ */
+function findOrphanLedgers(root: string): string[] {
+  const dir = resolve(root, TARGET_RULE_LEDGERS)
+  if (!existsSync(dir)) return []
+  return listRuleFiles(dir)
+    .map((abs) => relative(dir, abs))
+    .filter((rest) => !existsSync(resolve(root, TARGET_RULES, rest)))
+    .map((rest) => join(TARGET_RULE_LEDGERS, rest))
+}
+
 /**
  * Measures every rule this tree authors, or the files named.
  *
  * A tree holding `governance/rules/` is a canon checkout, read across both
  * authored corpora with a ledger asked of each outside-practice rule and of
  * each core rule in `touched`, and checked for any core rule carrying one.
- * Any other tree is a target, read at `.claude/rules/project/` alone with no
- * ledger asked, since ledgers never ship.
+ * Any other tree is a target, read at `.claude/rules/project/` alone, with
+ * each rule's ledger under `canon/ledger/rules/` checked where one exists and
+ * none owed, since the toolkit's ledgers never ship.
  *
  * `touched` holds paths relative to the root, and leaving it out reads no core
  * rule as touched.
@@ -457,11 +499,14 @@ export async function readRuleAudit(
     rules.push({
       file,
       ...shape,
-      ledger: await readLedger(root, file, groups, touched),
+      ledger: await readLedger(root, file, groups, touched, scope),
     })
   }
 
-  return { kind: 'measured', scope, corpus, rules }
+  const orphans =
+    scope === 'target' && paths.length === 0 ? findOrphanLedgers(root) : []
+
+  return { kind: 'measured', scope, corpus, rules, orphans }
 }
 
 export function hasFinding(reading: RuleReading): boolean {
@@ -487,12 +532,13 @@ export function auditExit(
     readonly exempt?: readonly string[]
   },
 ): number {
+  const counts = (file: string) =>
+    !options.gate ||
+    (options.gated.some((prefix) => file.startsWith(prefix)) &&
+      !options.exempt?.includes(file))
   const failing = report.rules.filter(
-    (reading) =>
-      hasFinding(reading) &&
-      (!options.gate ||
-        (options.gated.some((prefix) => reading.file.startsWith(prefix)) &&
-          !options.exempt?.includes(reading.file))),
+    (reading) => hasFinding(reading) && counts(reading.file),
   )
-  return failing.length > 0 ? 2 : 0
+  const orphaned = report.orphans.filter(counts)
+  return failing.length + orphaned.length > 0 ? 2 : 0
 }

package/src/markdown/scope.ts

@@ -158,6 +158,7 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/context-fold/references/unusable-baseline.md',
   'claude/skills/create-rule/REQUIREMENT.md',
   'claude/skills/create-rule/SKILL.md',
+  'claude/skills/create-rule/references/ledger.md',
   'claude/skills/create-rule/references/rule.md',
   'claude/skills/create-skill/REQUIREMENT.md',
   'claude/skills/create-skill/SKILL.md',
@@ -259,6 +260,8 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/git-worktree/REQUIREMENT.md',
   'claude/skills/git-worktree/SKILL.md',
   'claude/skills/git-worktree/references/cleanup.md',
+  'claude/skills/issue-triage/REQUIREMENT.md',
+  'claude/skills/issue-triage/SKILL.md',
   'claude/skills/markdown-craft/REQUIREMENT.md',
   'claude/skills/markdown-craft/SKILL.md',
   'claude/skills/markdown-craft/references/markdown.md',
@@ -282,6 +285,7 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/pr-evidence/references/evidence.md',
   'claude/skills/proposal-critique/REQUIREMENT.md',
   'claude/skills/proposal-critique/SKILL.md',
+  'claude/skills/proposal-critique/references/adopted.md',
   'claude/skills/review-address/REQUIREMENT.md',
   'claude/skills/review-address/SKILL.md',
   'claude/skills/review-address/references/post-review-findings.md',