@erclx/canon 5.42.0 → 5.43.0

package/governance/rules/claude/skill.md

@@ -11,7 +11,9 @@ paths:
 
 ## Skill files
 
-- Load the `canon:create-skill` skill before a hand edit to a `SKILL.md` or a `REQUIREMENT.md`. It carries the skill structure, the requirement shape, and the path rules for a skill body. Report it rather than proceeding silently when the skill does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
-- Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `canon:create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
-- Re-read a skill body this session edited before invoking that skill again in the same session.
-- Do not read a resolved file path in a held body as evidence the body is current.
+- Load the `canon:create-skill` skill before a hand edit to a `SKILL.md` or a `REQUIREMENT.md`, since it carries the skill structure, the requirement shape, and the path rules.
+- Report it rather than proceeding silently when `canon:create-skill` does not resolve, as in a project that installed governance without the plugin.
+- Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whoever drafted it, `canon:create-skill` included.
+- Carry its third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
+- Re-read a skill body this session edited before invoking that skill again in the same session. Revisit when Claude Code reloads a skill body edited after the session first invoked it.
+- Do not read a resolved file path in a held body as evidence the body is current. Revisit when Claude Code marks a held skill body stale once its source changes.

package/governance/rules/tooling/ci-workflow.md

@@ -1,55 +1,22 @@
 ---
-description: Enforce GitHub Actions job naming, granularity, dependency wiring, and bun pinning
+description: Keep GitHub Actions commit-back steps and token scopes safe, and route workflow authoring to the ci-workflow skill
 paths:
   - '.github/workflows/**'
 ---
 
 # CI workflow standards
 
-## Triggers and pinning
-
-- Include `workflow_dispatch` alongside the primary trigger on every workflow.
-- Pin every action to a major version tag. Never `@latest` or `@main`.
-- Run every job on `ubuntu-latest`.
-
-## Job naming
-
-- Name every job as an emoji followed by a title, such as `🛡️ Checks`, `🧪 Unit Tests`, `📦 Build Check`, `🎭 E2E Tests`, or `🚀 Deploy`.
-
-## Job granularity
-
-- Fold static analysis, unit tests, and build into one job while the gate runs under two minutes end to end.
-- Split them into parallel jobs once a run log puts the gate past two minutes.
-- Give E2E, release, and deploy a job each from the start.
-
-## Job dependencies
-
-- Use `needs` for a data dependency, where a job consumes another job's artifact, or for a job whose cost is prohibitive against the gate in front of it. Leave every other job unwired so it runs in parallel.
-- Gate E2E on the job that uploads the build artifact.
-- Gate release and deploy on E2E.
-- Emit a deploy, publish, or release job with a placeholder step and name what the caller fills in. Never guess a deploy command.
-
-## Artifacts
-
-- Upload an artifact on `if: failure()` alone, with `retention-days: 7`.
-
-## Bun stack
+## Authority
 
-- Use `oven-sh/setup-bun@v2` with `bun-version: latest`.
-- Install with `bun install --frozen-lockfile`.
-- Key the Playwright browser cache on the Playwright version string, never a static key.
+- Load the `canon:ci-workflow` skill for triggers, pinning, job shape, artifacts, and the Bun stack. Report it rather than proceeding silently when the skill does not resolve.
 
 ## Commit-back
 
-- Commit a refreshed file back to the pull request branch only when the branch's own change moved it. Report the diff without committing when something outside the branch can move it, such as a count read at build time or a font that renders differently per machine, since that commit lands on a branch that never asked for it.
+- Commit a refreshed file back to the pull request branch only when that branch's change moved it. Report the diff when an outside input can move it, such as a build-time count or a font.
 - Commit only what a deterministic step regenerates from source, and run the diff check before the commit step so an unchanged capture pushes nothing.
 - Skip a pull request from a fork with `github.event.pull_request.head.repo.full_name == github.repository`, since the default token cannot push to a fork's branch.
-- Set the concurrency group on the ref so a newer push cancels the run committing onto a stale head.
-- Set `HUSKY: 0` on the commit step when the runner lacks a tool a hook shells out to.
 - Never commit back to the trunk. A commit with no pull request and no reviewer needs an operator's decision, not a workflow's.
-- Leave `workflow_dispatch` off a commit-back workflow. A manual run has no branch to commit onto, so the trigger would pass and do nothing.
-- Fail a template's first step while a path list still holds its placeholder, so an unfinished install fails loudly rather than never firing.
 
-## Authority
+## Token scopes
 
-- Load the `canon:ci-workflow` skill for the workflow template and the per-project adaptation. Report it rather than proceeding silently when the skill does not resolve.
+- In a workflow with more than one job, add a write scope to the job that needs it, never to the workflow-level block, so every other job keeps the read-only token.

package/governance/rules/ui/design-reference.md

@@ -0,0 +1,37 @@
+---
+description: Build UI against the tracked design references under canon/design, and show each reference beside its build in the pull request
+paths:
+  - 'canon/design/**'
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.vue'
+  - '**/*.svelte'
+  - '**/*.astro'
+  - '**/*.html'
+  - '**/*.css'
+  - '**/*.scss'
+---
+
+# Design reference standards
+
+## Where the design lives
+
+- Build UI against `canon/design/`, never against the canvas directly.
+- Land a picked or changed canvas design in `canon/design/` through the project's design sync, as its own pull request, before any feature builds against it.
+- Never copy, edit, or delete a reference file under `canon/design/` by hand.
+- Add a new surface's row to the index in `canon/design/` before running the sync, and remove it only in the change that removes the surface.
+
+## Building against a reference
+
+- Open each reference image and its frame HTML, light and dark, before changing the surface they show.
+- Match the reference closely or identically, taking sizes, spacing, and colors from the frame HTML.
+
+## Showing the comparison
+
+- Put each changed surface's reference image beside its built capture, light and dark, in the pull request description.
+- Name each place the build departs from its reference, with its reason, in the pull request description.
+- Report an unexplained departure from a reference as a review finding.
+
+## Naming
+
+- Give each app part one plain kebab-case folder under `canon/design/`, and name each file `<name>-dark` or `<name>-light`.

package/governance/rules/writing/markdown.md

@@ -9,7 +9,8 @@ paths:
 ## Format
 
 - Never write an em dash or a semicolon. `canon markdown audit` reads the full ban list from the package.
-- Load the `canon:markdown-craft` skill before a substantial markdown edit for headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording. Report it rather than proceeding silently when the skill does not resolve.
+- Load the `canon:markdown-craft` skill before a substantial markdown edit, for headings, structure, code spans, dates, punctuation, emphasis, file references, spelling, and frontmatter.
+- Report it rather than proceeding silently when `canon:markdown-craft` does not resolve.
 - Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
 
 ## Voice

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.42.0",
+  "version": "5.43.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -55,7 +55,7 @@
     "execa": "^9.5.2",
     "highlight.js": "^11.12.0",
     "jszip": "^3.10.1",
-    "playwright-core": "1.59.1",
+    "playwright-core": "1.64.1",
     "pptxgenjs": "^4.0.1",
     "preact": "^11.0.0"
   },
@@ -64,7 +64,7 @@
     "@astrojs/react": "^5.0.4",
     "@commitlint/cli": "^20.4.1",
     "@commitlint/config-conventional": "^20.4.1",
-    "@playwright/test": "1.59.1",
+    "@playwright/test": "1.64.1",
     "@tailwindcss/vite": "^4.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@types/bun": "^1.2.10",
@@ -73,11 +73,11 @@
     "happy-dom": "^20.14.5",
     "husky": "^9.1.7",
     "micromatch": "^4.0.8",
-    "oxfmt": "0.72.0",
-    "oxlint": "1.87.0",
+    "oxfmt": "0.73.0",
+    "oxlint": "1.88.0",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
-    "prettier-plugin-tailwindcss": "^0.7.2",
+    "prettier-plugin-tailwindcss": "^0.8.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5"
   }

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/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)
+    })
 }