@erclx/canon 5.73.0 → 5.75.0

package/governance/ledger/skills/write-human/SKILL.md

@@ -0,0 +1,62 @@
+---
+title: Write human skill ledger
+description: Sources for claude/skills/write-human/SKILL.md, one row per bullet and ordered step in its concern groups
+---
+
+# Write human skill ledger
+
+The field is plain-language writing and technical editing. Government plain-language guidance from GOV.UK and digital.gov, the Google and Microsoft developer style guides, and Nielsen Norman Group's reading research carry most rows. Purdue OWL carries the cadence rows, whose thresholds are the toolkit's own.
+
+`## The bans stay in force`, `## Machine tells`, and `## Source material` point elsewhere and hold no bullet, so they take no table. The five ordered steps under `## Revising a passage` each take a row, the way a bullet does.
+
+## What yields and what does not
+
+| Bullet                               | Source                                                                                                                                                                                           | Read       |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| A surface's own voice wins           | House choice: a changelog or commit standard that fixes its own voice would otherwise answer to two authorities, and the session picks whichever it read last                                    | 2026-10-28 |
+| The yield covers voice alone         | House choice: a declared warmer voice would otherwise excuse the fragment, the padding, and the tells, which read as defects in every register                                                   | 2026-10-28 |
+| Terse reference prose is the default | [Microsoft Learn style quick start](https://learn.microsoft.com/en-us/contribute/content/style-quick-start): "Don't waste words. Be affirmative and don't use extra words or lots of qualifiers" | 2026-10-28 |
+
+## Voice
+
+| Bullet                                | Source                                                                                                                                                                                                                        | Read       |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A reader scanning, not studying       | [How users read on the web](https://www.nngroup.com/articles/how-users-read-on-the-web/): "79 percent of our test users always scanned any new page they came across", and 16 percent read word by word                       | 2026-10-28 |
+| Active voice and present tense        | [digital.gov, Writing for understanding](https://digital.gov/guides/plain-language/writing): "Active voice makes it clear who should do what", and "The simplest and strongest form of a verb is present tense"               | 2026-10-28 |
+| Name the actor                        | [Google style guide, Active voice](https://developers.google.com/style/voice): "In passive voice, it's easy to neglect to indicate who or what is performing a particular action"                                             | 2026-10-28 |
+| Direct verbs and plain words          | [GOV.UK, Use clear language](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/clear-language/): "Do not use formal or long words when easy or short ones will do"                    | 2026-10-28 |
+| Drop marketing words                  | [GOV.UK A to Z, Words to avoid](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/style-guides/a-to-z-style-guide/#words-to-avoid): "leverage (unless in the financial sense), use 'influence' or 'use'" | 2026-10-28 |
+| Drop vague qualifiers                 | [Google style guide, Word list](https://developers.google.com/style/word-list): "just" is "Usually, just is a filler word that you can delete without affecting your meaning"                                                 | 2026-10-28 |
+| Direct on fact, hedged on doubt       | [Microsoft Learn style quick start](https://learn.microsoft.com/en-us/contribute/content/style-quick-start): "Be affirmative and don't use extra words or lots of qualifiers"                                                 | 2026-10-28 |
+| Assume developer-level knowledge      | [GOV.UK, Meet user needs](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/meet-user-needs/): "only include what someone needs to know so they can complete a task"                  | 2026-10-28 |
+| Front-load, and every sentence is new | [Microsoft, Top 10 tips](https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice): "Lead with what's most important. Front-load keywords for scanning"                                                          | 2026-10-28 |
+
+## Rhythm
+
+| Bullet                              | Source                                                                                                                                                                                                                                                                | Read       |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Read the paragraph as one block     | House choice: cadence is a property of the run, so an edit made line by line clears each sentence and leaves the paragraph as flat as it was                                                                                                                          | 2026-10-28 |
+| Longest and shortest within five    | [Purdue OWL, Sentence variety](https://owl.purdue.edu/owl/general_writing/academic_writing/sentence_variety/index.html): "Too many sentences with the same structure and length can grow monotonous for readers". The five-word spread is the toolkit's own threshold | 2026-10-28 |
+| Three alike openings is a pattern   | [Purdue OWL, Sentence variety](https://owl.purdue.edu/owl/general_writing/academic_writing/sentence_variety/index.html): "If too many sentences start with the same word, especially The, It, This, or I, prose can grow tedious for readers"                         | 2026-10-28 |
+| Vary the shape, not the word        | [Purdue OWL, Sentence variety](https://owl.purdue.edu/owl/general_writing/academic_writing/sentence_variety/index.html): the monotony it names comes from "the same structure and length", so a new first word over one structure leaves it in place                  | 2026-10-28 |
+| Never buy variety with a fragment   | [Microsoft Learn style quick start](https://learn.microsoft.com/en-us/contribute/content/style-quick-start): small words "(such as "a," "the," "that," and "is") are crucial for machine translation. Be sure to include them"                                        | 2026-10-28 |
+| A connective for flow, never rhythm | House choice: a connective added to vary cadence names no relation the sentences carry, so it reads as the padding the density rules cut                                                                                                                              | 2026-10-28 |
+
+## Density
+
+| Bullet                          | Source                                                                                                                                                                                           | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| One claim per sentence          | [digital.gov, Write short sentences](https://digital.gov/guides/plain-language/writing/clear-short): "Express only one idea in each sentence"                                                    | 2026-10-28 |
+| Cut a restatement               | [Microsoft, Top 10 tips](https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice): "Give customers just enough information to make decisions confidently. Prune every excess word" | 2026-10-28 |
+| Compress without the verb going | [Microsoft Learn style quick start](https://learn.microsoft.com/en-us/contribute/content/style-quick-start): "Include the "small words"", since words "understood for context" are still needed  | 2026-10-28 |
+| Resolve a pronoun to its noun   | [Google style guide, Pronouns](https://developers.google.com/style/pronouns): "Avoid vague and confusing references between a pronoun and its antecedent"                                        | 2026-10-28 |
+
+## Revising a passage
+
+| Bullet                             | Source                                                                                                                                                                             | Read       |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Read the whole passage first       | House choice: an edit made before the whole is read polishes a sentence a later paragraph makes redundant                                                                          | 2026-10-28 |
+| Mark lengths and openings          | House choice: the counts the rhythm rules name are invisible until written down, and the flattest run carries most of the uniformity a reader hears                                | 2026-10-28 |
+| Cut a sentence adding no claim     | House choice: shortening a sentence that carries no claim leaves the padding in place at a smaller size                                                                            | 2026-10-28 |
+| Re-read model text for the tells   | [Wikipedia, Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing): it catalogs patterns model output carries, such as "LLMs overuse the rule of three" | 2026-10-28 |
+| Run the audit and rewrite each hit | House choice: a near-synonym swapped for a flagged token clears the scan and keeps the habit, the failure that narrowed the markdown standard to characters                        | 2026-10-28 |

package/governance/ledger/skills/write-human/density.md

@@ -0,0 +1,36 @@
+---
+title: Information density reference ledger
+description: Sources for claude/skills/write-human/references/density.md, one row per bullet
+---
+
+# Information density reference ledger
+
+The field is plain-language writing and technical editing. The Google and Microsoft developer style guides and digital.gov's plain-language guide carry the sourced rows. `## Measuring a paragraph` holds prose and no bullet, so it takes no table.
+
+## What to cut
+
+| Bullet                             | Source                                                                                                                                                                                                    | Read       |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A restatement at another altitude  | [Microsoft, Top 10 tips](https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice): "Give customers just enough information to make decisions confidently. Prune every excess word"          | 2026-10-28 |
+| A setup clause naming the subject  | [Microsoft, Top 10 tips](https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice): "Edit out you can when it isn't necessary. Avoid weak phrasing like there is, there are, and there were" | 2026-10-28 |
+| A qualifier changing no truth      | [Microsoft Learn style quick start](https://learn.microsoft.com/en-us/contribute/content/style-quick-start): "Be affirmative and don't use extra words or lots of qualifiers"                             | 2026-10-28 |
+| An example repeating the one above | House choice: a second example teaching what the first taught doubles the reading for no new case, and the reader goes looking for the difference                                                         | 2026-10-28 |
+| A transition naming the relation   | House choice: a transition such as `Additionally` before an addition restates the relation the sentence order already shows, so it adds a word and no claim                                               | 2026-10-28 |
+
+## What never to cut
+
+| Bullet                             | Source                                                                                                                                                                                                          | Read       |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The verb                           | [Microsoft Learn style quick start](https://learn.microsoft.com/en-us/contribute/content/style-quick-start): small words "(such as "a," "the," "that," and "is") are crucial for machine translation"           | 2026-10-28 |
+| A qualifier that bounds a claim    | [Google style guide, Excessive claims](https://developers.google.com/style/excessive-claims): "avoid superlatives like best, simplest, fastest, never, and always", the claim a dropped bound turns `most` into | 2026-10-28 |
+| The source and the date of a claim | House choice: a measurement with no ref or date cannot be re-run, so a later reader cannot tell a current number from a stale one                                                                               | 2026-10-28 |
+| The actor                          | [Google style guide, Active voice](https://developers.google.com/style/voice): "Make clear who's performing the action"                                                                                         | 2026-10-28 |
+
+## Keeping a compressed sentence unambiguous
+
+| Bullet                           | Source                                                                                                                                                                                                            | Read       |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Resolve every pronoun            | [Google style guide, Write for a global audience](https://developers.google.com/style/translation): "if a pronoun is ambiguous, then replace it with the appropriate noun"                                        | 2026-10-28 |
+| Attach every modifier            | [Google style guide, Write for a global audience](https://developers.google.com/style/translation): "place a word like only immediately before the word or phrase that it relates to"                             | 2026-10-28 |
+| Quantify an amount               | [Google style guide, Excessive claims](https://developers.google.com/style/excessive-claims): avoid a statement "about performance or cost that isn't easily verifiable with data that's available to the reader" | 2026-10-28 |
+| Split two claims joined by `and` | [digital.gov, Write short sentences](https://digital.gov/guides/plain-language/writing/clear-short): "Break up your idea into parts and make each one the subject of its own sentence"                            | 2026-10-28 |

package/governance/ledger/skills/write-human/machine-tells.md

@@ -0,0 +1,30 @@
+---
+title: Machine tells reference ledger
+description: Sources for claude/skills/write-human/references/machine-tells.md, one entry per tell, held as lists since the reference carries no ledgered bullet
+---
+
+# Machine tells reference ledger
+
+The field is plain-language writing and technical editing, narrowed to the patterns editors flag in model-written text. Wikipedia's Signs of AI writing, which the humanizer catalog `adopted.md` names is built on, carries most tells. Every source below was read on 2026-10-28.
+
+The reference states each tell as prose under its own H2, and its one list is `## Contents`, which the audit skips. A table here would count rows against no bullet and fail, so each tell takes a list entry instead.
+
+## Sourced to the catalog of model tells
+
+- Rule of three: [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) says "LLMs overuse the rule of three"
+- Inline-header lists: the same page says model output "often includes vertical lists formatted in a specific way"
+- Closing restatement: the same page names section summaries, which older models "often added" to longer outputs
+- Escalating parallel clauses: the same page names negative parallelisms, which read "as though it is clearing up a common misconception"
+- Empty superlative frames: the same page says "LLM writing often puffs up the importance of the subject matter"
+
+## Sourced to a style guide
+
+- Synonym cycling: [Google, Write for a global audience](https://developers.google.com/style/translation) says "If you use different names for the same thing", readers "might think you're referring to different concepts"
+- Adverb propping: [Google, Excessive claims](https://developers.google.com/style/excessive-claims) rules out a claim "that isn't easily verifiable with data that's available to the reader"
+- Passive voice with an unnamed actor: [Google, Active voice](https://developers.google.com/style/voice) says "Make clear who's performing the action"
+
+## House choices
+
+- False ranges: a `from X to Y` over items with no scale claims a coverage the sentence never lists, so a reader cannot check what falls inside
+- Question as transition: a question standing between paragraphs delays the answer by one line and adds no claim, the padding the density rules cut
+- A colon or comma where the dash was: a session told to drop a banned dash swaps the mark and keeps the join, so the ban clears and the habit stays

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.73.0",
+  "version": "5.75.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/ci/docs-only.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Reports whether a pull request changes anything besides Markdown, called by
+# the changes job in verify.yml to skip the macOS tests on a docs-only change.
+# Prints code=false only when git lists at least one changed file and every
+# one ends in .md, so a missing base, a failed diff, or an empty diff runs the
+# tests rather than skipping them. Renames are split into a delete and an add,
+# so a code file renamed to .md still counts as code.
+#
+# Usage: docs-only.sh <base>
+# Writes to $GITHUB_OUTPUT, or stdout outside Actions, and always exits 0.
+
+set -e
+
+out=${GITHUB_OUTPUT:-/dev/stdout}
+code=true
+
+if [ $# -eq 1 ] && files=$(git diff --name-only --no-renames "$1" HEAD) && [ -n "$files" ]; then
+  if ! grep -qv '\.md$' <<<"$files"; then
+    code=false
+  fi
+fi
+
+echo "code=$code" >>"$out"
+echo "code=$code" >&2

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/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/misc.ts

@@ -7,6 +7,20 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Bundle up every open call that only I can make and ask me all at once.',
     expect: 'decision-escalate',
   },
+  {
+    prompt: 'What do you need me to decide before you keep going?',
+    expect: 'decision-escalate',
+  },
+  {
+    prompt:
+      'Poke holes in this plan before we build it. Is the problem even real?',
+    expect: 'proposal-critique',
+  },
+  {
+    prompt:
+      'CI keeps failing on the install step and the plan is to add a retry. Is the cause actually ours, and is this fix worth it?',
+    expect: 'proposal-critique',
+  },
   {
     prompt:
       'Show me a few different treatments for this callout so I can pick one by looking.',

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[] {
@@ -119,7 +120,13 @@ export const BULLET_LEDGER_SKILLS: Readonly<Record<string, BulletLedgerScope>> =
     },
     [join(SHIPPED_CORPUS, 'teach-craft')]: { exempt: [], body: true },
     [join(SHIPPED_CORPUS, 'test-craft')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'test-first')]: { exempt: [], body: true },
     [join(SHIPPED_CORPUS, 'codebase-layout')]: { exempt: [], body: true },
+    [join(SHIPPED_CORPUS, 'search-craft')]: { exempt: [], body: true },
+    [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. */
@@ -134,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',
@@ -161,6 +177,9 @@ export const PRACTICE_LEDGER = join('references', 'adopted.md')
  */
 const EXTERNAL_LINK = /\]\(\s*https?:\/\/|<https?:\/\//
 
+/** The address an inline link or an autolink cites, captured for comparison. */
+const EXTERNAL_ADDRESS = /\]\(\s*(https?:\/\/[^)\s]+)|<(https?:\/\/[^>\s]+)>/g
+
 /**
  * A table cell opening on the marker the governance ledgers already use for a
  * rule the toolkit chose, so one check reads every ledger alike.
@@ -277,6 +296,8 @@ interface ReferenceLedger {
   readonly ledgerRel: string
   /** Undefined when the ledger file is absent. */
   readonly mismatches: readonly LedgerMismatch[] | undefined
+  /** Every source the ledger links, normalized by `sourceKey`. */
+  readonly sources: readonly string[]
 }
 
 interface SkillText {
@@ -302,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) => ({
@@ -334,6 +358,7 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
         sources,
       ),
       ...sources.flatMap(practiceFindings),
+      ...projectLedgers,
     ],
     referenceContents: sources.flatMap((source) =>
       source.bodies.flatMap(contentsFindings),
@@ -453,17 +478,76 @@ async function readReferenceLedgers(
     files.map(async ({ path, text }) => {
       const ledgerRel = skillLedgerPath(folder, path)
       const ledgerPath = join(root, ledgerRel)
-      const mismatches = existsSync(ledgerPath)
-        ? compareLedger(
-            ledgerGroups(text, path === 'SKILL.md'),
-            countLedgerRows(await Bun.file(ledgerPath).text()),
-          )
+      const ledger = existsSync(ledgerPath)
+        ? await Bun.file(ledgerPath).text()
         : undefined
-      return { rel: join(skillRel, path), ledgerRel, mismatches }
+      const mismatches =
+        ledger === undefined
+          ? undefined
+          : compareLedger(
+              ledgerGroups(text, path === 'SKILL.md'),
+              countLedgerRows(ledger),
+            )
+      return {
+        rel: join(skillRel, path),
+        ledgerRel,
+        mismatches,
+        sources: ledger === undefined ? [] : linkedSources(ledger),
+      }
     }),
   )
 }
 
+/**
+ * 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
@@ -681,6 +765,7 @@ function practiceFindings(source: SkillSource): SkillFinding[] {
   return [
     ...sections,
     ...ledgerFindings(source),
+    ...duplicateFindings(source),
     ...source.referenceLedgers.flatMap(referenceLedgerFindings),
     ...source.staleExemptions.map((rel) => ({
       rel,
@@ -710,17 +795,78 @@ function ledgerFindings(source: SkillSource): SkillFinding[] {
     return [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
   }
 
-  const cites = bodyLines(source.ledger)
-    .filter((line) => !line.fenced)
+  const lines = bodyLines(source.ledger).filter((line) => !line.fenced)
+  const cites = lines
     .map((line) => maskCodeSpans(line.text))
     .some((text) => EXTERNAL_LINK.test(text) || HOUSE_CHOICE.test(text))
   if (cites) return []
+  if (pointsAtLedgers(source, lines)) return []
 
   return [
     { rel: source.rel, detail: `ledger cites nothing: ${PRACTICE_LEDGER}` },
   ]
 }
 
+/**
+ * A skill on the per-bullet list cites its sources in its ledger folder, so a
+ * record whose every link moved there is left pointing at the folder instead.
+ * A skill off the list has nowhere else for a source to live.
+ */
+function pointsAtLedgers(
+  source: SkillSource,
+  lines: readonly { text: string }[],
+): boolean {
+  if (BULLET_LEDGER_SKILLS[source.rel] === undefined) return false
+  const folder = `${join(SKILL_LEDGERS, source.folder)}/`
+  return lines.some((line) => line.text.includes(folder))
+}
+
+/**
+ * The source record keeps a source no ledger row cites, so a link in both
+ * places is a second copy that drifts on the first edit to either.
+ */
+function duplicateFindings(source: SkillSource): SkillFinding[] {
+  if (source.ledger === undefined) return []
+  if (BULLET_LEDGER_SKILLS[source.rel] === undefined) return []
+
+  const ledgered = new Map<string, string>()
+  for (const entry of source.referenceLedgers) {
+    for (const key of entry.sources) {
+      if (!ledgered.has(key)) ledgered.set(key, entry.ledgerRel)
+    }
+  }
+
+  return [...new Set(linkedSources(source.ledger))].flatMap((key) => {
+    const ledgerRel = ledgered.get(key)
+    if (ledgerRel === undefined) return []
+    return [
+      {
+        rel: join(source.rel, PRACTICE_LEDGER),
+        detail: `duplicate source: ${key} in ${ledgerRel}`,
+      },
+    ]
+  })
+}
+
+/** Every external address a text links outside fences and code spans. */
+function linkedSources(text: string): string[] {
+  return bodyLines(text)
+    .filter((line) => !line.fenced)
+    .flatMap((line) =>
+      [...maskCodeSpans(line.text).matchAll(EXTERNAL_ADDRESS)].map((match) =>
+        sourceKey(match[1] ?? match[2] ?? ''),
+      ),
+    )
+}
+
+/**
+ * An anchor and a trailing slash reach the same page, so both drop. A commit
+ * pin names a different version, so the path stays as written.
+ */
+function sourceKey(address: string): string {
+  return address.replace(/#.*$/, '').replace(/\/+$/, '')
+}
+
 /**
  * Asks only the shipped corpus for a family, since the family names the skill
  * map group a skill's row sits under and an internal skill takes no row.

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/claude.ts

@@ -34,6 +34,7 @@ import {
   SKILL_LEDGERS,
   PRACTICE_SECTIONS,
   PRACTICE_SKILLS,
+  PROJECT_SKILL_LEDGERS,
   REQUIREMENT_LIMITS,
   REQUIREMENT_SECTIONS,
   RETIRED_REQUIREMENT_SECTION,
@@ -1772,7 +1773,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 +1784,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