@erclx/canon 5.41.0 → 5.43.0

package/src/audits/catalog.ts

@@ -4,6 +4,7 @@ import type { ReachRefusal } from '@/claude/skills-reach'
 import type { ContextAuditRefusal } from '@/context/audit'
 import type { SweepVerdict } from '@/context/classify/patterns'
 import type { AuditRefusal } from '@/deps/audit'
+import type { RuleAuditRefusal } from '@/gov/audit'
 import type { RestatedRefusal } from '@/gov/restated'
 import type { LabelAuditRefusal } from '@/labels/audit'
 import type { ValidateRefusal as RecordRefusal } from '@/records/validate'
@@ -412,6 +413,33 @@ function restatedCounts(record: unknown): Record<string, number> | undefined {
   })
 }
 
+/**
+ * Counts rules rather than findings, since a rule past four limits is one
+ * rewrite, and keeps the two ledger findings apart because a missing ledger and
+ * a short one are fixed by different passes.
+ */
+function ruleCounts(record: unknown): Record<string, number> | undefined {
+  const rules = asObject(record)?.rules
+  if (!Array.isArray(rules)) return undefined
+
+  let shapeRules = 0
+  let missingLedgers = 0
+  let ledgerMismatches = 0
+
+  for (const raw of rules) {
+    const rule = asObject(raw)
+    const findings = lengthOf(rule?.findings)
+    const ledger = asObject(rule?.ledger)
+    if (findings === undefined || ledger === undefined) return undefined
+
+    if (findings > 0) shapeRules += 1
+    if (ledger.status === 'missing') missingLedgers += 1
+    if ((lengthOf(ledger.mismatches) ?? 0) > 0) ledgerMismatches += 1
+  }
+
+  return { shapeRules, missingLedgers, ledgerMismatches }
+}
+
 function findingsOnly(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -681,6 +709,20 @@ export const AUDITS: readonly AuditSpec[] = [
     ] satisfies RestatedRefusal[],
     counts: restatedCounts,
   },
+  {
+    id: 'rules',
+    label: 'Rule shape and ledgers',
+    argv: ['gov', 'audit', '--json'],
+    // Reports rather than gates. The corpus starts far from zero, and the
+    // `rule-shape` stage already fails a push on each folder once its rewrite
+    // lists it as gated, so gating the whole set here would fail every push.
+    gatingExits: [],
+    corpus: 'tracked',
+    // A target that authors no rule of its own has no corpus here, which is an
+    // absence rather than a break, on the same test the restated sweep takes.
+    absentReasons: ['no-rules'] satisfies RuleAuditRefusal[],
+    counts: ruleCounts,
+  },
   {
     id: 'counts',
     label: 'Self-stated catalog counts',

package/src/claude/cases/workflow.ts

@@ -81,6 +81,11 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Open the preview for that pull request and click through each box on its visual checklist, then post what happened.',
     expect: 'review-ui',
   },
+  {
+    prompt:
+      'I pushed another commit to the open PR. Update the screenshot comparison on it so the reviewer sees the current head.',
+    expect: 'pr-evidence',
+  },
   {
     prompt:
       'The screencast draft is finished. Turn it into an actual video now.',

package/src/claude/settings.ts

@@ -5,6 +5,10 @@ import { dirname } from 'node:path'
 const DEFAULT_INDENT = '  '
 const INDENT = /^([ \t]+)\S/m
 
+// The pair setup once wrote to suppress Claude's attribution. Only this exact
+// value is retracted, since anything else is a person's own choice.
+const RETIRED_ATTRIBUTION = { commit: '', pr: '' }
+
 export type SettingsRecord = Record<string, unknown>
 
 export interface SettingsKey {
@@ -107,10 +111,10 @@ export function planSettings(
   }
   keys.push({ label: 'statusLine', changed: statusLineChanged })
 
-  const attribution = template.attribution
-  const attributionChanged = !equals(next.attribution, attribution)
-  if (attributionChanged) next.attribution = attribution
-  keys.push({ label: 'attribution', changed: attributionChanged })
+  if (equals(next.attribution, RETIRED_ATTRIBUTION)) {
+    delete next.attribution
+    keys.push({ label: 'attribution', changed: true })
+  }
 
   const permissions = asRecord(next.permissions)
   const merged: SettingsRecord = { ...permissions }

package/src/commands/claude.ts

@@ -69,6 +69,7 @@ import {
   serializeSettings,
   writeSettings,
 } from '@/claude/settings'
+import { readSessionDefaults } from '@/migrate/session-defaults'
 import { copyPreservingMode } from '@/sync/copy'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import { recordDir } from '@/roots/record'
@@ -255,7 +256,7 @@ export function register(program: Command): void {
 
   claude
     .command('setup')
-    .description('One-shot user-level config (statusline, attribution)')
+    .description('One-shot user-level config (statusline, permissions)')
     .argument('[dest]', 'User config directory', join(homedir(), '.claude'))
     .helpOption('-h, --help', 'Show this help message')
     .action(async (dest: string) => {
@@ -663,6 +664,15 @@ async function runSync(target: string): Promise<number> {
     else logWarn(`${name}/ missing. Run \`canon claude init\``)
   }
 
+  // Sync never rewrites an existing settings file, so a target seeded before
+  // the session defaults learns of them only here.
+  const defaults = await readSessionDefaults(resolved, PROJECT_ROOT)
+  if (defaults.kind === 'planned' && defaults.plan.predates) {
+    logWarn(
+      'settings.json lacks the session defaults. Run `canon migrate session-defaults --write`',
+    )
+  }
+
   logStep('Scanning .gitignore')
   const chain = claudeChain(PROJECT_ROOT)
   const pruned = await pruneGitignore(chain, resolved)

package/src/commands/gov.ts

@@ -32,6 +32,16 @@ import {
   SEED_REL,
   SHIPPED_SKILLS_REL,
 } from '@/gov/restated'
+import {
+  auditExit,
+  hasFinding,
+  PRACTICE_FOLDERS,
+  readRuleAudit,
+  RULE_GATED_FOLDERS,
+  RULE_LIMITS,
+  type RuleAuditReport,
+  type RuleReading,
+} from '@/gov/audit'
 import {
   CITATION_MARKER,
   type CitationReport,
@@ -123,6 +133,12 @@ interface CountsOptions {
   readonly json?: boolean
 }
 
+interface AuditOptions {
+  readonly root?: string
+  readonly json?: boolean
+  readonly gate?: boolean
+}
+
 /** What a reader does about each way the sweep produced no reading. */
 const RESTATED_REFUSALS: Record<RestatedRefusal, string> = {
   'no-instructions': `No ${INSTRUCTIONS_REL} here, or it carries no bullet, so there is no instruction corpus to sweep.`,
@@ -573,6 +589,188 @@ export function register(program: Command): void {
     .action((opts: RestatedOptions) => {
       process.exitCode = runRestated(opts)
     })
+
+  gov
+    .command('audit')
+    .description(
+      'Report every rule past a shape limit, and in this repository every outside-practice rule missing a source ledger',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .argument(
+      '[paths...]',
+      'Rule files or folders of rules to read, defaulting to the corpus',
+    )
+    .option('--root <path>', 'Tree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--gate',
+      'Set 2 only for a finding in a gated folder, which the push stage reads',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Limits, each a finding one past its number:',
+        `  words      ${RULE_LIMITS.words} words in the body`,
+        `  bullets    ${RULE_LIMITS.bullets} bullets in the file`,
+        `  h2         ${RULE_LIMITS.h2} H2 headings`,
+        `  perH2      ${RULE_LIMITS.perH2} bullets under one H2, the text above the first H2 a group`,
+        `  chars      ${RULE_LIMITS.chars} characters in one bullet, continuation lines folded in`,
+        `  sentences  ${RULE_LIMITS.sentences} sentences in one bullet`,
+        '  emphasis   any CRITICAL, IMPORTANT, MUST, ALWAYS, NEVER, or "you must"',
+        '             outside a code span',
+        '',
+        'Corpus:',
+        '  A tree holding governance/rules/ reads it and internal/rules/, and',
+        `  asks a ledger of each rule under ${PRACTICE_FOLDERS.join(', ')}`,
+        '  at governance/ledger/<folder>/<slug>.md, one table row per bullet',
+        '  under a heading of the same name.',
+        '  Any other tree reads .claude/rules/project/ alone and asks no ledger.',
+        '  .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.',
+        '',
+        `Gated folders: ${RULE_GATED_FOLDERS.length === 0 ? 'none yet' : RULE_GATED_FOLDERS.join(', ')}`,
+        '',
+        'Exit codes:',
+        '  0  no finding, or under --gate no finding in a gated folder',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one finding, or under --gate one in a gated folder',
+        '',
+        'Reasons:',
+        '  no-rules      the tree holds no rule corpus to read, or a named folder holds no rule',
+        '  no-path       a named path does not exist',
+        '  outside-root  a named path sits outside --root',
+        '',
+        'Examples:',
+        '  canon gov audit',
+        '  canon gov audit .claude/rules/project/api.md',
+        '  canon gov audit --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (paths: string[], opts: AuditOptions) => {
+      process.exitCode = await runAudit(paths, opts)
+    })
+}
+
+/**
+ * Reports by default and gates only under `--gate`, and there only for the
+ * folders `RULE_GATED_FOLDERS` lists. The corpus starts far from zero, so the
+ * push stage fails on a folder once its rewrite has brought it there.
+ */
+async function runAudit(
+  paths: readonly string[],
+  opts: AuditOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = await readRuleAudit(root, paths)
+  const emitJson = opts.json ?? false
+
+  if (report.kind === 'unreadable') {
+    intro('canon gov audit')
+    logStep('Refused')
+    logError(report.message)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: report.reason, message: report.message })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportAudit(report, root, paths.length > 0)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        limits: RULE_LIMITS,
+        gated: RULE_GATED_FOLDERS,
+        ...report,
+      })}\n`,
+    )
+  }
+
+  return auditExit(report, {
+    gate: opts.gate ?? false,
+    gated: RULE_GATED_FOLDERS,
+  })
+}
+
+function describeLedger(reading: RuleReading): string[] {
+  const { ledger } = reading
+  if (ledger.status === 'missing') {
+    return [`${reading.file}: no ledger at ${ledger.path}`]
+  }
+  if (ledger.status !== 'present') return []
+  return ledger.mismatches.map(
+    (mismatch) =>
+      `${ledger.path}: ${mismatch.heading ?? '(above the first H2)'} has ${mismatch.rows} row(s) for ${mismatch.bullets} bullet(s)`,
+  )
+}
+
+function reportAudit(
+  report: Extract<RuleAuditReport, { kind: 'measured' }>,
+  root: string,
+  named: boolean,
+): void {
+  intro('canon gov audit')
+
+  const shaped = report.rules.filter((reading) => reading.findings.length > 0)
+  const ledgers = report.rules.flatMap(describeLedger)
+
+  logStep('Corpus')
+  logInfo(
+    named
+      ? `${report.rules.length} named rule(s) in ${root}`
+      : `${report.rules.length} rule(s) under ${report.corpus.join(' and ')} in ${root}`,
+  )
+
+  logStep('Shape')
+  if (shaped.length === 0) {
+    logInfo('every rule is within the six limits and carries no emphasis word')
+  } else {
+    for (const reading of shaped) {
+      for (const finding of reading.findings) {
+        const at =
+          finding.line === undefined
+            ? reading.file
+            : `${reading.file}:${finding.line}`
+        logWarn(
+          finding.limit === 'emphasis'
+            ? `${at}: emphasis word`
+            : `${at}: ${finding.limit} ${finding.count} past ${finding.max}`,
+        )
+      }
+    }
+  }
+
+  logStep('Ledgers')
+  if (report.scope === 'target') {
+    logInfo('not read, since ledgers live in the toolkit and never ship')
+  } else if (ledgers.length === 0) {
+    logInfo('every outside-practice rule has a ledger row per bullet')
+  } else {
+    for (const line of ledgers) logWarn(line)
+  }
+
+  const failing = report.rules.filter(hasFinding).length
+  logStep('Summary')
+  logInfo(
+    `${failing} of ${report.rules.length} rule(s) carry a finding: ${shaped.length} with a shape finding, ${ledgers.length} ledger finding(s)`,
+  )
+  logInfo(
+    RULE_GATED_FOLDERS.length === 0
+      ? 'no folder is gated yet, so --gate passes every finding'
+      : `gated: ${RULE_GATED_FOLDERS.join(', ')}`,
+  )
+
+  outro()
 }
 
 /**

package/src/commands/migrate.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { listRepositoryFiles } from '@/git/files'
 import { indexSourceRules } from '@/gov/adapter'
@@ -25,6 +25,11 @@ import {
   type RuleLayoutPlan,
   walkFlatRules,
 } from '@/migrate/rule-layout'
+import {
+  applySessionDefaults,
+  readSessionDefaults,
+  type SessionDefaultsRead,
+} from '@/migrate/session-defaults'
 import {
   SKILL_CITATION_MAP,
   SKILL_NAME_MAP,
@@ -50,7 +55,7 @@ import {
 } from '@/migrate/scratch-evidence'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import { readStamp, stampedHashes } from '@/sync/stamp'
-import { logError, logInfo, logStep, logWarn, plural } from '@/cli/ui'
+import { logAdd, logError, logInfo, logStep, logWarn, plural } from '@/cli/ui'
 
 interface SweepOptions {
   readonly json?: boolean
@@ -959,6 +964,81 @@ function toRuleLayoutRecord(
   }
 }
 
+interface SessionDefaultsOptions {
+  readonly json?: boolean
+  readonly write?: boolean
+  readonly root?: string
+}
+
+/**
+ * Adds the seeded session defaults to a target settings file that predates
+ * them. A missing file is nothing to do, since `canon claude init` seeds the
+ * whole file with the defaults already in it.
+ */
+async function runSessionDefaults(
+  opts: SessionDefaultsOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
+  const read = await readSessionDefaults(root, PROJECT_ROOT)
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(toSessionDefaultsRecord(read, opts.write))}\n`,
+    )
+  }
+
+  if (read.kind === 'refused') {
+    logError(read.reason)
+    return 1
+  }
+
+  if (read.kind === 'absent') {
+    logInfo(`No ${read.path}, so there is nothing to migrate.`)
+    return 0
+  }
+
+  for (const key of read.plan.keys) {
+    if (key.changed) logAdd(key.label)
+    else logInfo(key.label)
+  }
+
+  if (!read.plan.changed) {
+    logInfo('Session defaults already present.')
+    return 0
+  }
+
+  if (!opts.write) {
+    logWarn('Nothing was written. Pass --write to apply this plan.')
+    return 2
+  }
+
+  await applySessionDefaults(read)
+  logStep(`Wrote ${read.path}.`)
+  return 0
+}
+
+function toSessionDefaultsRecord(
+  read: SessionDefaultsRead,
+  wrote: boolean | undefined,
+): unknown {
+  if (read.kind === 'refused') {
+    return { ok: false, wrote: false, reason: read.reason }
+  }
+  if (read.kind === 'absent') {
+    return { ok: true, wrote: false, path: read.path, keys: [] }
+  }
+  return {
+    ok: true,
+    wrote: wrote === true && read.plan.changed,
+    path: read.path,
+    keys: read.plan.keys,
+  }
+}
+
 export function register(program: Command): void {
   const migrate = program
     .command('migrate')
@@ -1322,4 +1402,43 @@ export function register(program: Command): void {
     .action(async (opts: RuleLayoutOptions) => {
       process.exitCode = await runRuleLayout(opts)
     })
+
+  migrate
+    .command('session-defaults')
+    .description('Add the seeded session defaults to a target settings file')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Apply the plan rather than reporting it')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Adds Agent and Task to permissions.deny in .claude/settings.json,',
+        'appending to the list without reordering it, and sets',
+        'autoMemoryEnabled to false only when the key is absent. A deny entry',
+        'is never removed and an existing autoMemoryEnabled is never changed.',
+        '',
+        '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.',
+        '',
+        'Exit codes:',
+        '  0  nothing to add, or --write applied the plan',
+        '  1  refused: the toolkit root, or an unreadable settings file',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'Examples:',
+        '  canon migrate session-defaults',
+        '  canon migrate session-defaults --write',
+        '  canon migrate session-defaults --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: SessionDefaultsOptions) => {
+      process.exitCode = await runSessionDefaults(opts)
+    })
 }