@erclx/canon 5.74.0 → 5.76.0

package/docs/agents/audits.md

@@ -63,30 +63,30 @@ An audit that finds no corpus reports `absent`, which moves neither the verdict
 
 `canon audits list` reports the first 18 rows. The rows marked `outside` run by hand or from a skill and sit beside the aggregate.
 
-| Id                   | Verb                                | Measures                                                                           | Finding        |
-| -------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- | -------------- |
-| `context`            | `canon context audit`               | Context folder structure, citations, and the requirements record's word cap        | Gates          |
-| `markdown`           | `canon markdown audit`              | Bans, dead links, density, and reference shape                                     | Gates          |
-| `skills`             | `canon claude skills audit`         | Both skill corpora against the skill standards                                     | Gates          |
-| `skills-reach`       | `canon claude skills reach`         | Skill bodies citing a path no target receives                                      | Reports        |
-| `skills-rank`        | `canon claude skills rank`          | Whether skill descriptions separate against a routing case corpus                  | Reports        |
-| `tasks`              | `canon tasks validate`              | Board rows nothing resolves                                                        | Reports        |
-| `records-plans`      | `canon records validate plans`      | Plan records against their shape                                                   | Reports        |
-| `records-groundwork` | `canon records validate groundwork` | Groundwork folders against their shape                                             | Reports        |
-| `records-intake`     | `canon records validate intake`     | Intake folders against their shape                                                 | Reports        |
-| `comments`           | `canon comments scan`               | Comment density by language and kind, and `TODO`, `FIXME`, `HACK`, `XXX`           | Reports        |
-| `test-order`         | `canon gov test-order`              | Implementations that reached branch history before their test                      | Reports        |
-| `secrets`            | `canon secrets scan`                | Credential-shaped values in the shipped tree                                       | Gates          |
-| `labels`             | `canon labels audit`                | Changed paths no row of the label map reaches                                      | Reports        |
-| `restated`           | `canon gov restated`                | Instructions `CLAUDE.md` states that a second surface states too                   | Reports        |
-| `rules`              | `canon gov audit`                   | Rules past a shape limit, and here rules short of a ledger or out of step with one | Reports        |
-| `counts`             | `canon gov counts`                  | Sentences stating a closed catalog's size that disagree with the tree              | Reports        |
-| `census`             | `canon census`                      | File count, extension breakdown, and line total                                    | Reports        |
-| `deps`               | `canon deps audit`                  | Advisories against the resolved dependencies                                       | Reports        |
-| `outside`            | `canon gov citations`               | Rule citations and internal frontmatter globs reaching nothing                     | Gates in check |
-| `outside`            | `canon gov superseded <old> <new>`  | Where the tree still asserts a value a changed convention no longer produces       | Reports        |
-| `outside`            | `canon claude skills drift <ref>`   | Shipped skill bodies rewritten since a ref                                         | Reports        |
-| `outside`            | `canon claude routing`              | Per `CLAUDE.md` section, how many bullets name a path and whether a rule covers it | Reports        |
+| Id                   | Verb                                | Measures                                                                                    | Finding        |
+| -------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------- | -------------- |
+| `context`            | `canon context audit`               | Context folder structure, citations, and the requirements record's word cap                 | Gates          |
+| `markdown`           | `canon markdown audit`              | Bans, dead links, density, and reference shape                                              | Gates          |
+| `skills`             | `canon claude skills audit`         | Both skill corpora against the skill standards, and any ledger under `canon/ledger/skills/` | Gates          |
+| `skills-reach`       | `canon claude skills reach`         | Skill bodies citing a path no target receives                                               | Reports        |
+| `skills-rank`        | `canon claude skills rank`          | Whether skill descriptions separate against a routing case corpus                           | Reports        |
+| `tasks`              | `canon tasks validate`              | Board rows nothing resolves                                                                 | Reports        |
+| `records-plans`      | `canon records validate plans`      | Plan records against their shape                                                            | Reports        |
+| `records-groundwork` | `canon records validate groundwork` | Groundwork folders against their shape                                                      | Reports        |
+| `records-intake`     | `canon records validate intake`     | Intake folders against their shape                                                          | Reports        |
+| `comments`           | `canon comments scan`               | Comment density by language and kind, and `TODO`, `FIXME`, `HACK`, `XXX`                    | Reports        |
+| `test-order`         | `canon gov test-order`              | Implementations that reached branch history before their test                               | Reports        |
+| `secrets`            | `canon secrets scan`                | Credential-shaped values in the shipped tree                                                | Gates          |
+| `labels`             | `canon labels audit`                | Changed paths no row of the label map reaches                                               | Reports        |
+| `restated`           | `canon gov restated`                | Instructions `CLAUDE.md` states that a second surface states too                            | Reports        |
+| `rules`              | `canon gov audit`                   | Rules past a shape limit or out of step with a ledger, and here rules short of one          | Reports        |
+| `counts`             | `canon gov counts`                  | Sentences stating a closed catalog's size that disagree with the tree                       | Reports        |
+| `census`             | `canon census`                      | File count, extension breakdown, and line total                                             | Reports        |
+| `deps`               | `canon deps audit`                  | Advisories against the resolved dependencies                                                | Reports        |
+| `outside`            | `canon gov citations`               | Rule citations and internal frontmatter globs reaching nothing                              | Gates in check |
+| `outside`            | `canon gov superseded <old> <new>`  | Where the tree still asserts a value a changed convention no longer produces                | Reports        |
+| `outside`            | `canon claude skills drift <ref>`   | Shipped skill bodies rewritten since a ref                                                  | Reports        |
+| `outside`            | `canon claude routing`              | Per `CLAUDE.md` section, how many bullets name a path and whether a rule covers it          | Reports        |
 
 A deliberate secret takes a `canon-allow-secret: <reason>` marker. A deliberate citation takes `canon-allow-citation: <reason>` and a deliberate superseded value takes `canon-allow-superseded: <reason>`, each on its own line or the one above. Run any verb with `--help` for its flags and refusal reasons.
 

package/docs/agents/migrate.md

@@ -21,7 +21,7 @@ kind: reference
 | `record-layout`    | Review receipts, memory archives, feedback, renders, picks, evidence, and the design board into their current folders |
 | `session-defaults` | The seeded session defaults into an existing `.claude/settings.json`, listed below the table                          |
 
-`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies `Agent`, `Task`, and both merge commands, and turns auto memory off. The bullets below add detail per verb.
+`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies subagents and both merge commands, allows the two lease push forms workers run, turns auto memory off, and wires an installed `plan-guard.sh`. The bullets below add detail per verb.
 
 - `skill-names` takes no `--scope`, and skips the changelog, eval transcripts, replay fixtures, and the pointer each renamed `draft-` skill leaves at its old name
 - `surface-roots` moves `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the stamp folder, and leaves `rules/`, `skills/`, `hooks/`, and `settings.json` in place
@@ -56,15 +56,15 @@ Three markers keep an old spelling on a line. Each also covers the nearest non-b
 
 ## Refusals
 
-| Verb               | Refuses when                                                                          |
-| ------------------ | ------------------------------------------------------------------------------------- |
-| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.        |
-| `records`          | A record folder already exists at the destination                                     |
-| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan                |
-| `scratch-evidence` | A destination is occupied                                                             |
-| `record-layout`    | A destination already exists, each move refused on its own                            |
-| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply.   |
-| `session-defaults` | The settings file is not valid JSON, or `permissions` or its `deny` has another shape |
+| Verb               | Refuses when                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.                                     |
+| `records`          | A record folder already exists at the destination                                                                  |
+| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan                                             |
+| `scratch-evidence` | A destination is occupied                                                                                          |
+| `record-layout`    | A destination already exists, each move refused on its own                                                         |
+| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply.                                |
+| `session-defaults` | The settings file is not valid JSON, or `permissions`, `deny`, `allow`, `hooks`, or `PreToolUse` has another shape |
 
 A `rule-layout` destination holding the same bytes marks a duplicate, which `--write` deletes.
 

package/docs/migrations/by-verb.md

@@ -75,8 +75,8 @@ Replace a citation of a skill with no successor by hand, or delete the sentence.
 
 - `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare mention by hand. <!-- canon-keep-retired -->
 - `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request, so replace a bare mention by hand. <!-- canon-keep-retired -->
-- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
-- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, `canon-rollout`, and `canon-feedback-triage` have no successor <!-- canon-keep-retired -->
+- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`, and `canon-feedback-triage` by `canon:issue-triage`. <!-- canon-keep-retired -->
+- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, and `canon-rollout` have no successor <!-- canon-keep-retired -->
 - `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, `ux-walkthrough`, and `plan-ready` have no successor <!-- canon-keep-retired -->
 
 The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
@@ -108,11 +108,17 @@ It moves each surface with `git mv` and repoints every tracked citation. No othe
 
 The seeded `.claude/settings.json` now denies the `Agent` and `Task` tools and both merge commands, and sets `autoMemoryEnabled` to `false`. `canon claude sync` never rewrites a settings file you hold, so it warns while the file holds no default or lacks a merge entry. Removing `Agent` and `Task` later draws no warning.
 
+The plan guard takes two steps. `canon claude init` adds the absent `.claude/hooks/plan-guard.sh`, and the verb below then wires it into `hooks.PreToolUse` for `Bash` and `Write|Edit`. It skips a tool whose matcher already runs the guard, and wires nothing while the script is absent.
+
 ```bash
 canon migrate session-defaults --json
 canon migrate session-defaults --write --json
 ```
 
-The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
+The verb only adds a key or entry that is absent, so a project migrated before an entry runs `--write` once more.
 
-The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session cannot merge. A project migrated before them runs `--write` once more, which also restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after.
+- A person who wants auto memory back sets it in their own `.claude/settings.local.json`
+- `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` stop a session merging
+- A rerun restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after
+- `git push --force-with-lease` and its `origin HEAD` form are allowed exactly, so a worker pushes after a rebase without waiting
+- Any other lease push still goes through auto mode's review, and `canon claude sync` warns while either entry is missing

package/docs/workflow/ai-workflow.md

@@ -41,7 +41,7 @@ See [target projects](../target/projects.md).
 
 Plan and build in session 1, then review and ship in a fresh session 2 when you want a cold reviewer on the diff.
 
-- For a pile of findings, invoke `canon:plan-intake`, and for a grown backlog `canon:backlog-triage`
+- For a pile of findings, invoke `canon:plan-intake`, for a grown backlog `canon:backlog-triage`, and for open GitHub issues `canon:issue-triage`
 - For an unmeasured state with live approaches, invoke `canon:plan-groundwork`
 - Invoke `canon:plan-feature`, implement, and run the `CLAUDE.md` commands until they pass
 - For UI changes, invoke `canon:ui-checklist`

package/docs/workflow/skill-map.md

@@ -22,6 +22,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:plan-intake`        | The input is a pile of findings                    |
 | `canon:plan-intake-answer` | An intake folder holds unread slots                |
 | `canon:backlog-triage`     | The backlog needs pruning                          |
+| `canon:issue-triage`       | Open GitHub issues need measuring before planning  |
 | `canon:plan-groundwork`    | The state is unmeasured and approaches compete     |
 | `canon:decision-escalate`  | Open decisions turn on your preference             |
 | `canon:proposal-critique`  | A proposal needs questioning before it is built    |

package/governance/detect.toml

@@ -20,6 +20,10 @@
 deps = []
 files = [".claude/skills", "claude/skills"]
 
+["rule"]
+deps = []
+files = [".claude/rules/project"]
+
 ["ci-workflow"]
 deps = []
 files = [".github/workflows"]

package/governance/ledger/claude/rule.md

@@ -0,0 +1,16 @@
+---
+title: Rule rule ledger
+description: Decisions behind governance/rules/claude/rule.md, one row per bullet
+---
+
+# Rule rule ledger
+
+The rule is a core rule, so every row is a house choice rather than a citation. Each names what goes wrong without its bullet and the option the bullet beat, with the date it was decided.
+
+## Rule files
+
+| Bullet                          | Source                                                                                                                                                                                          | Read       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load create-rule before an edit | House choice: a session hand-editing rules without the skill shipped defects `canon gov audit` passed (issue 2842). It beat relying on the audit alone                                          | 2026-10-29 |
+| Report an unresolved skill      | House choice: a project that installed governance without the plugin has no `create-rule`, and a silent skip hides that. It beat omitting the line                                              | 2026-10-29 |
+| Audit each touched rule         | House choice: the audit catches the shape and ledger defects the skill's checklist names, so running it before the commit closes the loop. It beat leaving the audit to the pre-push gate alone | 2026-10-29 |

package/governance/rules/claude/rule.md

@@ -0,0 +1,13 @@
+---
+description: Route edits to a rule file to the create-rule skill for its shape and checklist
+paths:
+  - '.claude/rules/project/**/*.md'
+---
+
+# Rule standards
+
+## Rule files
+
+- Load the `canon:create-rule` skill before a hand edit to a rule, since it carries the frontmatter, the shape limits, and the bullet checklist.
+- Report it rather than proceeding silently when `canon:create-rule` does not resolve, as in a project that installed governance without the plugin.
+- Run `canon gov audit` over each rule the edit touched before committing it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.74.0",
+  "version": "5.76.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/ci/refresh-frames-pr.sh

@@ -1,29 +1,29 @@
 #!/usr/bin/env bash
-# Commits the regenerated capture frames onto the refresh branch and opens or
+# Commits the recaptured home baseline onto the refresh branch and opens or
 # updates its pull request, called by refresh-capture-frames.yml after the
-# capture steps. The step holds GH_TOKEN and HUSKY, since the token scope is
+# capture step. The step holds GH_TOKEN and HUSKY, since the token scope is
 # read off the workflow.
 #
 # Hooks stay off, since pre-push runs a check whose format step needs shfmt,
 # which the runner lacks. verify.yml checks the pull request.
 #
-# The frames commit where they rendered, then only the files that commit wrote
+# The baseline commits where they rendered, then only the files that commit wrote
 # or dropped carry onto main fetched now, so a merge landing mid-run neither
-# leaves the branch on an older base nor loses a frame it moved. The pull
+# leaves the branch on an older base nor loses a baseline frame it moved. The pull
 # request resolves by number, since every merged refresh leaves a closed one on
 # the same head.
 set -e
 
 branch=chore/refresh-capture-frames
-title="chore(web): refresh capture frames"
+title="chore(web): refresh home baseline"
 
-if [ -z "$(git status --porcelain assets/captures assets/frames assets/evidence)" ]; then
-  echo "Frames are current, nothing to refresh."
+if [ -z "$(git status --porcelain assets/evidence)" ]; then
+  echo "The home baseline is current, nothing to refresh."
   exit 0
 fi
 git config user.name "github-actions[bot]"
 git config user.email "41898282+github-actions[bot]@users.noreply.github.com" # canon-allow-reference: the bot account id, not a commit
-git add assets/captures assets/frames assets/evidence
+git add assets/evidence
 git commit -m "$title"
 rendered=$(git rev-parse HEAD)
 written=$(git diff --name-only --no-renames --diff-filter=d HEAD~1 HEAD)
@@ -36,8 +36,8 @@ fi
 if [ -n "$dropped" ]; then
   printf '%s\n' "$dropped" | xargs -d '\n' git rm -q --ignore-unmatch --
 fi
-if git diff --cached --quiet -- assets/captures assets/frames assets/evidence; then
-  echo "Main already carries these frames, nothing to refresh."
+if git diff --cached --quiet -- assets/evidence; then
+  echo "Main already carries this baseline, nothing to refresh."
   exit 0
 fi
 git commit -m "$title"
@@ -50,11 +50,10 @@ if [ -z "$number" ]; then
     --title "$title" \
     --body "## Summary
 
-- Refreshes the capture frames from main so their counts and tokens stay current.
+- Refreshes the home page baseline from main so canon pr evidence compares against a current render.
 
 ## Key changes
 
-- Regenerates the count and token bearing frames, their images, and their stamps from main.
 - Recaptures the home page baseline under assets/evidence/home.
 - Merges itself by squash once its required check passes."
   number=$(gh pr list --head "$branch" --state open --json number --jq '.[0].number')

package/src/audits/catalog.ts

@@ -379,7 +379,8 @@ function restatedCounts(record: unknown): Record<string, number> | undefined {
  * a short one are fixed by different passes.
  */
 function ruleCounts(record: unknown): Record<string, number> | undefined {
-  const rules = asObject(record)?.rules
+  const root = asObject(record)
+  const rules = root?.rules
   if (!Array.isArray(rules)) return undefined
 
   let shapeRules = 0
@@ -397,7 +398,11 @@ function ruleCounts(record: unknown): Record<string, number> | undefined {
     if ((lengthOf(ledger.mismatches) ?? 0) > 0) ledgerMismatches += 1
   }
 
-  return { shapeRules, missingLedgers, ledgerMismatches }
+  // A target ledger with no rule sits beside `rules` rather than in it. A
+  // binary predating it carries no `orphans` key, which reads as none.
+  const orphanLedgers = lengthOf(root?.orphans) ?? 0
+
+  return { shapeRules, missingLedgers, ledgerMismatches, orphanLedgers }
 }
 
 function findingsOnly(record: unknown): Record<string, number> | undefined {

package/src/capture/render.ts

@@ -34,10 +34,13 @@ const FONT_PROBE_SIZE = 72
 const FONT_PROBE_TEXT = 'canon capture 0123456789'
 const ABSENT_FAMILY = '__canon_absent_family__'
 
+export type ColorScheme = 'light' | 'dark'
+
 export interface CaptureOptions {
   selector: string
   outDir?: string
   width?: number
+  colorScheme?: ColorScheme
 }
 
 export type CaptureResult =
@@ -60,9 +63,7 @@ export async function captureSources(
   const browser = await chromium.launch()
   try {
     return await Promise.all(
-      sources.map((source) =>
-        captureOne(browser, source, options.selector, options.width),
-      ),
+      sources.map((source) => captureOne(browser, source, options)),
     )
   } finally {
     await browser.close()
@@ -76,8 +77,7 @@ export async function captureSources(
 async function captureOne(
   browser: Browser,
   source: CaptureSource,
-  selector: string,
-  width: number | undefined,
+  { selector, width, colorScheme }: CaptureOptions,
 ): Promise<CaptureResult> {
   /**
    * A viewport rather than a wrapper, since a media query answers to the
@@ -90,11 +90,13 @@ async function captureOne(
     ...(width === undefined
       ? {}
       : { viewport: { width, height: DEFAULT_VIEWPORT_HEIGHT } }),
+    ...(colorScheme === undefined ? {} : { colorScheme }),
   })
   try {
     await page.goto(
       source.kind === 'url' ? source.url : pathToFileURL(source.htmlPath).href,
     )
+    if (colorScheme !== undefined) await applyColorScheme(page, colorScheme)
     const element = page.locator(selector).first()
     if ((await element.count()) === 0) {
       return failed(source, `no element matched ${selector}`)
@@ -177,6 +179,29 @@ function sourceIdentifier(source: CaptureSource): string {
   return source.kind === 'url' ? source.url : source.htmlPath
 }
 
+/**
+ * Writes the theme the three switches a stylesheet reads, being the media
+ * query, a `data-theme` attribute, and a `light` or `dark` class on the root,
+ * which is the set Frameboard's theme toggle writes on every frame. The media
+ * query alone leaves a stylesheet keyed on the attribute in its default set,
+ * which is dark for one `canon design css` emits.
+ *
+ * Written after the load event, so a page script restoring a stored theme on
+ * load has already run and cannot overwrite it.
+ */
+async function applyColorScheme(
+  page: Page,
+  scheme: ColorScheme,
+): Promise<void> {
+  await page.evaluate((theme) => {
+    const root = document.documentElement
+    root.setAttribute('data-theme', theme)
+    root.style.colorScheme = theme
+    root.classList.remove('light', 'dark')
+    root.classList.add(theme)
+  }, scheme)
+}
+
 function failed(source: CaptureSource, reason: string): CaptureResult {
   return { status: 'failed', source: sourceIdentifier(source), reason }
 }

package/src/capture/stamp.ts

@@ -6,13 +6,11 @@ const STAMP_EXTENSION = '.stamp'
 
 /**
  * Provenance for one rendered PNG: the markup it came from and a digest over
- * each side of the pair. `assertStampField` in `src/gate/measures.ts` reads both
- * digests back off the first whitespace-separated token, so the field names, the
- * colon, and the space after it are a contract between the writer and the gate
- * rather than formatting.
+ * each side of the pair. Nothing reads the digests back today, so no check
+ * fails when either side moves.
  *
  * Both sides are recorded because either can move alone. The markup digest
- * catches an edit committed with no capture, and the image digest catches a PNG
+ * would show an edit committed with no capture, and the image digest a PNG
  * replaced under markup that never changed.
  */
 export interface CaptureStamp {

package/src/claude/cases/git.ts

@@ -22,6 +22,11 @@ export const GIT_CASES: readonly SkillCase[] = [
     prompt: 'Turn this bug into a GitHub issue and file it.',
     expect: 'git-issue',
   },
+  {
+    prompt:
+      'Log this bug, but add it to the open issue if one already covers it.',
+    expect: 'git-issue',
+  },
   {
     prompt: 'Close #42 without merging, #57 supersedes it.',
     expect: 'git-pr-close',

package/src/claude/cases/workflow.ts

@@ -96,6 +96,10 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Our backlog only ever grows, measure each row and suggest which to decline.',
     expect: 'backlog-triage',
   },
+  {
+    prompt: 'File the open issues on this repo into an intake folder.',
+    expect: 'issue-triage',
+  },
   // Rot across documents nobody changed is what this reads, rather than a
   // stated rule broken on a given line. It is also not `target-check`, which
   // asks whether a document exists and holds its sections rather than whether

package/src/claude/skills-audit.ts

@@ -82,6 +82,7 @@ export const LEDGER_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'write-human'),
   join(SHIPPED_CORPUS, 'test-first'),
   join(SHIPPED_CORPUS, 'ui-craft'),
+  join(SHIPPED_CORPUS, 'proposal-critique'),
 ]
 
 function references(...names: string[]): string[] {
@@ -125,6 +126,7 @@ export const BULLET_LEDGER_SKILLS: Readonly<Record<string, BulletLedgerScope>> =
     [join(SHIPPED_CORPUS, 'write-human')]: { exempt: [], body: true },
     [join(SHIPPED_CORPUS, 'systematic-debugging')]: { exempt: [], body: true },
     [join(SHIPPED_CORPUS, 'build-in-slices')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'proposal-critique')]: { exempt: [], body: true },
   }
 
 /** Where a per-bullet ledger lives, as `<skill>/<file>.md` below it. */
@@ -139,6 +141,15 @@ export function skillLedgerPath(folder: string, file: string): string {
   return join(SKILL_LEDGERS, folder, inside.startsWith('..') ? file : inside)
 }
 
+/**
+ * Where a target keeps the ledgers behind its own skills, as `<skill>/<file>.md`
+ * below it. A tree holding `governance/rules/` is the toolkit, which keeps its
+ * ledgers at `SKILL_LEDGERS`, so this folder is never read there.
+ */
+export const PROJECT_SKILL_LEDGERS = join('canon', 'ledger', 'skills')
+
+const TOOLKIT_MARKER = join('governance', 'rules')
+
 /** The closing H2s a practice skill carries, matched exactly outside fences. */
 export const PRACTICE_SECTIONS: readonly string[] = [
   'Excuses and rebuttals',
@@ -312,6 +323,9 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
     present.map((corpus) => readCorpus(root, corpus.rel, corpus.dir)),
   )
   const sources = perCorpus.flat()
+  const projectLedgers = existsSync(join(root, TOOLKIT_MARKER))
+    ? []
+    : await readProjectLedgers(root, sources)
 
   return {
     corpora: present.map((corpus, index) => ({
@@ -344,6 +358,7 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
         sources,
       ),
       ...sources.flatMap(practiceFindings),
+      ...projectLedgers,
     ],
     referenceContents: sources.flatMap((source) =>
       source.bodies.flatMap(contentsFindings),
@@ -483,6 +498,56 @@ async function readReferenceLedgers(
   )
 }
 
+/**
+ * Pairs each file a target wrote under `PROJECT_SKILL_LEDGERS` with the skill
+ * file of that name, `SKILL.md` with the body and any other with the reference
+ * at `references/<file>`. Nothing is owed, since a project has no list to owe a
+ * ledger against, so only a ledger that exists is read, and one naming a skill
+ * or a file that is gone is reported rather than skipped.
+ */
+async function readProjectLedgers(
+  root: string,
+  sources: readonly SkillSource[],
+): Promise<SkillFinding[]> {
+  const dir = join(root, PROJECT_SKILL_LEDGERS)
+  if (!existsSync(dir)) return []
+  const paths = [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: dir, onlyFiles: true }),
+  ].sort()
+
+  const perLedger = await Promise.all(
+    paths.map(async (path): Promise<SkillFinding[]> => {
+      const ledgerRel = join(PROJECT_SKILL_LEDGERS, path)
+      const [folder, ...rest] = path.split('/')
+      const owners = sources.filter((source) => source.folder === folder)
+      if (rest.length === 0 || owners.length === 0) {
+        return [{ rel: ledgerRel, detail: `missing skill: ${folder}` }]
+      }
+      const file = rest.join('/')
+      const target = file === 'SKILL.md' ? file : join('references', file)
+      const rows = countLedgerRows(await Bun.file(join(dir, path)).text())
+
+      return owners.flatMap((owner) => {
+        const rel = join(owner.rel, target)
+        const body = owner.bodies.find((entry) => entry.rel === rel)
+        if (body === undefined) {
+          return [{ rel: ledgerRel, detail: `missing file: ${rel}` }]
+        }
+        return referenceLedgerFindings({
+          rel,
+          ledgerRel,
+          mismatches: compareLedger(
+            ledgerGroups(body.text, target === 'SKILL.md'),
+            rows,
+          ),
+          sources: [],
+        })
+      })
+    }),
+  )
+  return perLedger.flat()
+}
+
 /**
  * Directives per H2, `null` for any above the first. A contents list repeats
  * the headings rather than stating a rule, so `## Contents` takes no rows. A

package/src/cli/help.ts

@@ -99,7 +99,7 @@ const EXAMPLES = [
   'canon indexes regen --dry-run --json',
   'canon docs list --json',
   'canon docs agents',
-  'canon capture assets/captures/install.html --selector .window --out assets/frames',
+  'canon capture web/public/previews/design-tokens/index.html --selector body --out assets/evidence',
   'canon inventory focus --json',
   'canon drive http://localhost:4173 run.json --json',
   'canon take http://localhost:4173 plan.json --out takes --json',

package/src/commands/capture.ts

@@ -31,6 +31,9 @@ const DEFAULT_SOURCE = 'assets'
  */
 type Renderer = typeof import('@/capture/render')
 type CaptureResult = Awaited<ReturnType<Renderer['captureSources']>>[number]
+type ColorScheme = import('@/capture/render').ColorScheme
+
+const COLOR_SCHEMES: readonly ColorScheme[] = ['light', 'dark']
 
 /**
  * Holds wiring only. Every browser reference sits behind a dynamic import,
@@ -58,6 +61,10 @@ export function register(program: Command): void {
       '--width <px>',
       'Viewport width in pixels, so a media query resolves at that width',
     )
+    .option(
+      '--color-scheme <scheme>',
+      'Theme to render in, light or dark; defaults to whichever theme the page renders unset',
+    )
     .addHelpText(
       'after',
       [
@@ -70,12 +77,21 @@ export function register(program: Command): void {
         'font-family. --width takes one whole number and sets the viewport, so',
         'run it once per breakpoint with its own --out.',
         '',
+        '--color-scheme sets prefers-color-scheme, a data-theme attribute, and',
+        'a light or dark class on the root, so a stylesheet keyed on any of the',
+        'three renders that theme. Run it once per scheme with its own --out.',
+        '',
       ].join('\n'),
     )
     .action(
       async (
         source: string,
-        opts: { out?: string; selector?: string; width?: string },
+        opts: {
+          out?: string
+          selector?: string
+          width?: string
+          colorScheme?: string
+        },
       ): Promise<void> => {
         /**
          * Refused rather than defaulted, and refused ahead of every other
@@ -102,6 +118,15 @@ export function register(program: Command): void {
           return
         }
 
+        const colorScheme = parseColorScheme(opts.colorScheme)
+        if (colorScheme === null) {
+          frameError(
+            `--color-scheme takes ${COLOR_SCHEMES.join(' or ')}, got ${JSON.stringify(opts.colorScheme)}.`,
+          )
+          process.exitCode = 1
+          return
+        }
+
         const isUrl = isUrlSource(source)
         const sourcePath = isUrl ? source : resolve(process.cwd(), source)
         if (!isUrl && !existsSync(sourcePath)) {
@@ -117,6 +142,7 @@ export function register(program: Command): void {
           results = await renderer.captureSources(sourcePath, {
             selector,
             width,
+            colorScheme,
             outDir: opts.out ? resolve(process.cwd(), opts.out) : undefined,
           })
         } catch (error) {
@@ -160,6 +186,17 @@ function parseWidth(raw: string | undefined): number | undefined {
   return Number.isInteger(value) && value >= 1 ? value : Number.NaN
 }
 
+/**
+ * Undefined for an absent flag and `null` for a value naming no scheme, so the
+ * caller can tell no scheme from a bad one.
+ */
+function parseColorScheme(
+  raw: string | undefined,
+): ColorScheme | undefined | null {
+  if (raw === undefined) return undefined
+  return COLOR_SCHEMES.find((scheme) => scheme === raw) ?? null
+}
+
 /**
  * Closes an open frame around a failure that stopped the whole run rather than
  * one source. Two of them are setup states rather than defects and each names