@erclx/canon 4.74.0 → 4.75.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.74.0",
+  "version": "4.75.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/create-skill/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: create-skill
 description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to "create a skill", add a skill, or make a new skill.
-disable-model-invocation: true
 ---
 
 # Create skill

package/claude/skills/docs-fold/SKILL.md

@@ -173,7 +173,7 @@ Grep the tree for the name that went, rather than for the paths the diff carries
 
 Report each hit as an ordinary rewrite.
 
-Do not create new entries automatically. Before treating a domain as new, confirm it holds no entry under either spelling, `.claude/context/<domain>.md` or `.claude/context/<domain>/index.md`, since a domain already split into a folder still passes a check that only looked for the flat file. New entries are a deliberate decision: the user invokes `docs-fold --new-context <domain>` (future flag) or hand-creates the file following `${CLAUDE_SKILL_DIR}/../../standards/context.md`. Auto-creation risks padding `.claude/context/` with low-signal entries.
+Create a new entry only for a domain `.claude/context/index.md` already lists but carries no file for, following `${CLAUDE_SKILL_DIR}/../../standards/context.md` for its shape. Before treating a domain as carrying no file, confirm it holds no entry under either spelling, `.claude/context/<domain>.md` or `.claude/context/<domain>/index.md`, since a domain already split into a folder still passes a check that only looked for the flat file. A row in the catalog is the deliberate decision, taken by whoever added it. This step only fills in what that decision left open, and only until the next `canon indexes regen` pass, which rebuilds the catalog from each entry's own frontmatter plus every sibling's and drops a row whose file still does not exist. Create the file before that regen runs, or the row this bar exists to fill in is gone. A domain the catalog does not list at all is a different case: report it and stop, rather than creating an entry or a catalog row for it.
 
 Write each updated entry immediately. Output one line per file, naming the path this run actually wrote rather than always the flat template:
 

package/claude/skills/git-followup/SKILL.md

@@ -29,15 +29,19 @@ A missing tracking ref is no longer a guard. An open pull request proves the bra
 
    The lease is what stops the force from overwriting a commit this session never read. Run the ancestry test only where an upstream resolves, since it reads `@{u}`.
 
-5. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
-6. Sync the body and title on every invocation, before the routing below decides on the reply.
+5. Post the evidence comparison, on every invocation including `reply-owned`, since this comment is not the reply step 8 owns. Run `canon pr evidence <number> --json`, resolving `<number>` from `gh pr view --json number`, and read `reason` on the record rather than the exit code.
+   - `no-evidence`: nothing changed under an `evidence/` segment this push. Say nothing and move on.
+   - `ok`: write `body` to `.canon/tmp/pr-evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post the comment with `gh pr comment <number> --body-file <main-root>/.canon/tmp/pr-evidence/body-<number>.md` when the record carries no `commentId`, or edit the existing one in place with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr-evidence/body-<number>.md` when it does. Clean up the tmp file only after the call reports success.
+   - Any other reason is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-tree`, `unreadable-changes`). Report it and continue without stopping the chain.
+6. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
+7. Sync the body and title on every invocation, before the routing below decides on the reply.
    - Run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
    - A fix commit answering a review changes what shipped exactly as much as an ordinary followup does, so the sync cannot wait on the invocation or the comment count below.
    - A body a person edited by hand between rounds gets no special handling: judge it against the tree the same way regardless of who wrote it last, since a hand-edit the fix commit has made stale is the exact drift this sync exists to close.
-7. Route on the invocation and the comment count for the reply alone.
+8. Route on the invocation and the comment count for the reply alone.
    - When invoked with `reply-owned`, skip this step: the caller posts its own reply.
-   - Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first running the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against it, since the hook does not see an inline comment body. The `pull_request` check the git-pr surface carries triggers on a push or an open rather than a plain edit, so neither this comment nor the title and body step 6 synced reaches it.
-   - If it is zero, nothing further runs. The sync in step 6 already did this branch's job.
+   - Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first running the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against it, since the hook does not see an inline comment body. The `pull_request` check the git-pr surface carries triggers on a push or an open rather than a plain edit, so neither this comment nor the title and body step 7 synced reaches it.
+   - If it is zero, nothing further runs. The sync in step 7 already did this branch's job.
 
 ## After completion
 

package/claude/skills/git-pr/SKILL.md

@@ -176,6 +176,27 @@ rmdir <main-root>/.canon/tmp/ui-checklist 2>/dev/null || true
 
 The `rmdir` is a no-op when another branch's pending checklist still sits in the folder, which keeps this step from deleting a handoff that is not its own.
 
+### Post the evidence comparison
+
+Run `canon pr evidence <number> --json` against the number the pull request step above resolved. Read `reason` on the record rather than the exit code.
+
+- `no-evidence`: nothing changed under an `evidence/` segment. Say nothing and move on.
+- `ok`: write `body` to `.canon/tmp/pr-evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post or update the comment:
+
+```bash
+gh pr comment <number> --body-file <main-root>/.canon/tmp/pr-evidence/body-<number>.md
+```
+
+When the record carries a `commentId`, edit that comment in place instead of posting a second one, reading the body field from the tmp file with `@`:
+
+```bash
+gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr-evidence/body-<number>.md
+```
+
+Clean up the tmp file the way the UI-checklist step does, only after the call reports success.
+
+Any other `reason` is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-tree`, `unreadable-changes`). Report it and move on without stopping the chain: a branch that carries no evidence images most of the time should not fail here on a transient git or `gh` read.
+
 ### Record the number on the task
 
 Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.

package/claude/skills/markdown-propose/REQUIREMENT.md

@@ -21,7 +21,7 @@ A second failure compounds the first. A claim copied across several files is cor
 - Grep the named surface for the concern before proposing, so a defect's site count is measured rather than assumed
 - Draft the replacement text, not only the finding
 - Carry three labelled variants on a change whose replacement was invented, and one on a change that corrects text to a recorded fact
-- Write one proposal file per source file under `.canon/proposals/<slug>/` and stop, leaving `You:` empty on every change
+- Write one proposal file per source file under `.canon/proposals/<nn>-<slug>/` and stop, leaving `You:` empty on every change
 - Apply only a change carrying an answer, one file at a time, and re-grep its anchor before applying it
 - Report what each file leaves alone, so a proposal cannot be read as finding everything wanting
 

package/claude/skills/markdown-propose/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: markdown-propose
-description: Reviews a named markdown surface against a named concern, drafts a per-file proposal under `.canon/proposals/<slug>/` carrying a diff and a reason for each change, and stops without editing a source file. Takes the concern and the surface as inputs, such as a claim stated stronger than the record, a fact gone stale, two files disagreeing, or a passage duplicated without derivation. A later invocation applies what the operator answered. Use when asked to "propose a change to CLAUDE.md", "draft a rewrite of this standard", "propose fixes to this doc", "draft alternatives for this passage", or "apply the answered proposals". Do NOT use to report without drafting a replacement (`standards-audit` or `canon markdown audit`), to review a diff already made (`review-branch`), or to file a raw brain dump as findings (`plan-intake`).
+description: Reviews a named markdown surface against a named concern, drafts a per-file proposal under `.canon/proposals/<nn>-<slug>/` carrying a diff and a reason for each change, and stops without editing a source file. Takes the concern and the surface as inputs, such as a claim stated stronger than the record, a fact gone stale, two files disagreeing, or a passage duplicated without derivation. A later invocation applies what the operator answered. Use when asked to "propose a change to CLAUDE.md", "draft a rewrite of this standard", "propose fixes to this doc", "draft alternatives for this passage", or "apply the answered proposals". Do NOT use to report without drafting a replacement (`standards-audit` or `canon markdown audit`), to review a diff already made (`review-branch`), or to file a raw brain dump as findings (`plan-intake`).
 ---
 
 # Markdown propose
@@ -20,7 +20,9 @@ The value is the gate. A rewrite delivered in chat gets applied from memory acro
 
 Two phases share this body, picked by whether a proposal folder already exists for the request's slug.
 
-Derive `<slug>` from the concern and the surface, kebab-case, naming the subject rather than the activity. List `.canon/proposals/` at the main worktree root and match the topic against the folders already there before deriving a fresh one, the same way `plan-intake` matches its own folder. Never match against `.claude/` itself.
+Derive `<slug>` from the concern and the surface, kebab-case, naming the subject rather than the activity. List `.canon/proposals/` at the main worktree root and match the topic against the slug half of each `<nn>-<slug>` folder already there before deriving a fresh one, the same way `plan-intake` matches its own folder. Never match against `.claude/` itself.
+
+With no match, a fresh folder takes the next ordinal in `.canon/proposals/`'s own sequence: list the folders present, take the highest `<nn>`, and increment it, starting at `01` when none exist. That sequence is independent of the one `intake` and `groundwork` share, so a proposals folder never reads or claims from theirs.
 
 - No matching folder, or the operator names a concern and a surface: **Propose**.
 - A matching folder exists and the operator says apply, ship, or commit the answers: **Apply**.
@@ -29,7 +31,7 @@ All `.canon/proposals/` reads and writes resolve at the main worktree root, not
 
 ## Write scope
 
-Write only inside `.canon/proposals/<slug>/`. A source file, a standard, a rule, and a plan all live outside that folder, so this one rule forbids every one of them during the Propose phase. The Apply phase is the one exception, and only for a change carrying a `You:` answer.
+Write only inside `.canon/proposals/<nn>-<slug>/`. A source file, a standard, a rule, and a plan all live outside that folder, so this one rule forbids every one of them during the Propose phase. The Apply phase is the one exception, and only for a change carrying a `You:` answer.
 
 ## Concerns
 
@@ -66,7 +68,7 @@ A matched string means different things in different registers. A word describin
 
 ### 4. Write the proposals
 
-One file per source file under `.canon/proposals/<slug>/`, per `${CLAUDE_SKILL_DIR}/references/format.md`.
+One file per source file under `.canon/proposals/<nn>-<slug>/`, per `${CLAUDE_SKILL_DIR}/references/format.md`.
 
 Draft the replacement text. A proposal reporting a problem without a replacement hands the work back rather than doing it.
 
@@ -97,20 +99,20 @@ Report the counts once the pass stops: files committed, changes applied, changes
 Chat output is the report. This skill persists only the proposal folder itself.
 
 ```plaintext
-📂 Opened .canon/proposals/<slug>/
+📂 Opened .canon/proposals/<nn>-<slug>/
 
 **Screened:** <N> files, <N> changes proposed, <N> carrying three variants
 
 **Highest value:** <the single strongest change, one line>
 
-Next: answer the `You:` slots in the files under .canon/proposals/<slug>/,
+Next: answer the `You:` slots in the files under .canon/proposals/<nn>-<slug>/,
 then re-invoke this skill to apply what you answered.
 ```
 
 Use `📂 Resumed` in place of `📂 Opened` on a resume pass. The Apply phase reports instead:
 
 ```plaintext
-✅ Applied .canon/proposals/<slug>/
+✅ Applied .canon/proposals/<nn>-<slug>/
 
 **Committed:** <N> files, <N> changes
 

package/claude/skills/markdown-propose/references/format.md

@@ -4,11 +4,13 @@ Governs the proposal `markdown-propose` writes before it edits anything. The con
 
 ## Folder
 
-- One folder per screening pass at `.canon/proposals/<slug>/`, where the slug names the subject rather than the activity
+- One folder per screening pass at `.canon/proposals/<nn>-<slug>/`, where the slug names the subject rather than the activity
 - One proposal file per source file, named `<nn>-<source filename, its own extension dropped>.md`, so a source already named `CLAUDE.md` becomes `01-CLAUDE.md` rather than `01-CLAUDE.md.md`
 - `00-overview.md` when the pass spans more than two source files, holding the cross-file pattern, the change counts, and the settle order
 - `applied.md` once the first change lands, holding every applied change with its reason and the answer it carried
 
+The folder's own `<nn>` and a proposal file's own `<nn>` are two independent counters. The folder's ordinal records when the pass was opened, counted within `.canon/proposals/` alone rather than shared with `plan-groundwork` or `plan-intake`'s sequence, and a proposal file's ordinal inside it records settle order, the dependency order changes apply in. Reading one as the other gets a pass dated wrong or an apply ordered wrong.
+
 The name carries both structures the folder has. The basename pairs a proposal to its source so a reader opens the two side by side, and the number is the settle order, which is a dependency rather than a preference: a file other files quote is settled first. Do not group proposals by theme.
 
 A proposal opened after the initial pass takes the next free number, and the folder is never renumbered. Its number records when the site was found rather than where it belongs in the dependency order. Renumbering to restore the order would rewrite the names of files already carrying answers, which costs more than the ordering is worth once applying has started.
@@ -95,13 +97,13 @@ The folder is gitignored, and backed wherever a records remote is configured. It
 Count the unread changes per file:
 
 ```bash
-grep -c '^- \*\*You:\*\*$' .canon/proposals/<slug>/*.md
+grep -c '^- \*\*You:\*\*$' .canon/proposals/<nn>-<slug>/*.md
 ```
 
 Report every answer given, against the change it sits under:
 
 ```bash
-awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print "   "$0}' .canon/proposals/<slug>/*.md
+awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print "   "$0}' .canon/proposals/<nn>-<slug>/*.md
 ```
 
 Both walk `###` headings, which is the mechanical reason an answer typed anywhere else is lost.

package/claude/skills/plan-feature/SKILL.md

@@ -31,7 +31,7 @@ Coding standards live in `.claude/rules/`. Claude Code loads them automatically.
 
 ## Step 2: scan relevant source files
 
-Based on the feature description, identify and read source files that are directly relevant. Do not read entire directories speculatively.
+Based on the feature description, identify and read source files that are directly relevant. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
 
 Measure against the tree rather than recall. Grep for each construct the plan will name and count the sites, so the plan carries the count the tree holds today. Confirm any work the plan sequences behind is still open, so it does not lead with an item that already shipped.
 

package/claude/skills/review-pr/SKILL.md

@@ -242,9 +242,9 @@ A minor the dispatched worker declines is what needs a surface that survives the
 
 Read the state off the most recent review comment rather than off the presence of a closed one. A close-out does not close the pull request, so a commit pushed after it gets its own pass, and that pass reopens the review under `## Review` when it raises a finding of any grade.
 
-Both of this skill's headings anchor as a section distinct from human threads, and neither invents beyond what the whole set already states. That set is five headings across two families, stated here once so `role-orchestrator`'s poll and every reply-posting skill cite it rather than carry a copy. The review family, `## Review` and `## Review closed`, belongs to this skill alone, and the reply family, `## Review response`, `## Rebase`, and `## Post-review findings`, belongs to `review-address`.
+Both of this skill's headings anchor as a section distinct from human threads, and neither invents beyond what the whole set already states. That set is six headings across three families, stated here once so `role-orchestrator`'s poll and every reply-posting skill cite it rather than carry a copy. The review family, `## Review` and `## Review closed`, belongs to this skill alone. The reply family, `## Review response`, `## Rebase`, and `## Post-review findings`, belongs to `review-address`. The third family is a single heading, `## Evidence`, which `canon pr evidence` posts through `git-pr` and `git-followup` and which answers no comment already on the thread, so the poll excludes it from the unclassified count without reading it as a reply that owes a re-review.
 
-The first reply heading answers a finding this skill posted, the second reports a stale branch resolved without one, and the third carries a finding a worker produces after a close-out rather than in answer to one already on the thread, since a finding produced late is still a finding. A comment posted under a heading outside these five reaches the poll as unclassified rather than as silence, so an invented sixth heading is a gap the next run reports instead of one it repeats. Do not append the PR number, which GitHub already renders above the comment.
+The first reply heading answers a finding this skill posted, the second reports a stale branch resolved without one, and the third carries a finding a worker produces after a close-out rather than in answer to one already on the thread, since a finding produced late is still a finding. A comment posted under a heading outside these six reaches the poll as unclassified rather than as silence, so an invented seventh heading is a gap the next run reports instead of one it repeats. Do not append the PR number, which GitHub already renders above the comment.
 
 Name the scope in every summary line after the first pass, since a reader cannot otherwise tell a narrow read from a full one. When the fallback in Step 2 fired, replace the commit count with `Re-reviewed the full change, the prior pass's commit is no longer on the branch`.
 

package/claude/skills/role-orchestrator/scripts/poll.sh

@@ -32,19 +32,25 @@ if [ -z "$BASE_REF" ]; then
 fi
 BASE_BRANCH="${BASE_REF#origin/}"
 
-# These five strings are owned elsewhere and pinned here. `review-pr`
-# writes `## Review` and `## Review closed`, and states the full five-heading
+# These six strings are owned elsewhere and pinned here. `review-pr`
+# writes `## Review` and `## Review closed`, and states the full six-heading
 # set once, beside the threshold it already states once. `review-address`
 # writes `## Review response`, `## Rebase`, and `## Post-review findings`, the
 # last for a finding a worker produces after a close-out rather than in answer
-# to one already on the thread. All three surfaces ship separately, so a
-# heading added in either skill breaks a test here that no check reaches across.
+# to one already on the thread. `canon pr evidence`, run through `git-pr` and
+# `git-followup`, writes `## Evidence`. All these surfaces ship separately, so
+# a heading added in any of them breaks a test here that no check reaches
+# across.
 #
-# Both families match on the first line alone so the tests stay symmetric. The
-# reply family carries `## Rebase` and `## Post-review findings` beside
-# `## Review response` because neither answers a comment already on the thread,
-# which is why both were kept outside the `## Review` family rather than folded
-# into it.
+# All three families match on the first line alone so the tests stay
+# symmetric. The reply family carries `## Rebase` and `## Post-review
+# findings` beside `## Review response` because neither answers a comment
+# already on the thread, which is why both were kept outside the `## Review`
+# family rather than folded into it. `## Evidence` answers no comment either,
+# and it stays out of the reply family rather than joining it: an evidence
+# comment is not a response to a review, so counting it as one would send the
+# poll back for a re-review nothing asked for. It is excluded from the
+# unmatched filter below instead, on its own.
 #
 # The review family reaches this file through `canon pr review-state` rather
 # than through a filter of its own, so the two headings are pinned here only in
@@ -81,7 +87,7 @@ JQ_UNMATCHED_STATE='
     | select(startswith("## "))
     | select(. != "## Review" and . != "## Review closed"
               and . != "## Review response" and . != "## Rebase"
-              and . != "## Post-review findings")
+              and . != "## Post-review findings" and . != "## Evidence")
   ] as $unclassified
   | ($unclassified | length | tostring)
     + " "

package/claude/skills/teach-workspace/references/lesson-craft.md

@@ -35,12 +35,7 @@ Every element competes with the material for attention.
 
 ## Diagrams
 
-A diagram earns its place when a relationship, a boundary, a path, a before-and-after, is the point of the passage rather than decoration for it. Most passages do not clear that bar, and a lesson reaching for a diagram on every section is the failure the neighboring `## Restraint` section already guards against. When prose or a list already carries that point, leave it there.
-
-- Wrap it in a `<figure>` holding an inline `<svg>` and a `<figcaption>` that names what to take from the diagram rather than what it shows. Let the figure run wider than the prose column, since a diagram cramped to the reading measure loses the labels it needs.
-- Draw it by hand, as plain shapes and lines authored directly in the markup, not exported from a diagramming tool.
-- Color every fill and stroke through a custom property the workspace's own stylesheet defines, never a literal hex value, which is the same rule that stylesheet's opening comment already states for every rule added under it. The diagram then re-colors itself on the same switch that re-colors the page.
-- Give the `<svg>` an accessible name: `role="img"` with `aria-label` for one short line, or `aria-labelledby` pointing at a `<title>` element inside it for a longer one.
+Follow `${CLAUDE_SKILL_DIR}/../../standards/figures.md` for when a diagram earns its place, the render-first policy between Mermaid and freehand SVG, and the wrapping, color, and accessibility rules every figure carries. A lesson reaching for a diagram on every section is the failure the neighboring `## Restraint` section already guards against.
 
 ## Quiz construction
 

package/docs/agents/commands.md

@@ -84,6 +84,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon pr head`                  | Compare the head a pull request object reports against the branch tip the remote carries, naming both shas (`--root`, `--json`)                                                                                                                                                                                        |
 | `canon pr checks`                | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean (`--root`, `--json`)                                                                                                                                                                                      |
 | `canon pr review-state`          | Report the commit and instant the last review pass covered, off the pass's own marker rather than the fields GitHub stamps at submission (`--root`, `--json`)                                                                                                                                                          |
+| `canon pr evidence`              | Render a before-and-after comment comparing changed `evidence/` images against the merge base, editing its own prior comment in place rather than posting a second (`--root`, `--json`)                                                                                                                                |
 | `canon repo metadata propose`    | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`)                                                                                                                                                       |
 | `canon repo metadata apply`      | Write an explicitly supplied description, homepage, or topic set to the remote through `gh repo edit` (`--description`, `--homepage`, `--topics`, `--root`, `--json`)                                                                                                                                                  |
 | `canon census [path]`            | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                                                                                                                                                                   |

package/docs/agents/index.md

@@ -28,6 +28,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
+- [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
 - [Records](records.md): The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates

package/docs/agents/pr-evidence.md

@@ -0,0 +1,108 @@
+---
+title: The pull request evidence comparison
+description: What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
+---
+
+# The pull request evidence comparison
+
+`canon pr evidence` renders one comment naming every changed image under an
+`evidence/` path segment, comparing each against the pull request's merge base
+with the trunk. `git-pr` posts it when a pull request opens or is edited, and
+`git-followup` posts it again after every later push, so a reviewer never has
+to open Files Changed to see what a case looked like before and after.
+
+```bash
+canon pr evidence
+canon pr evidence 1341 --json
+```
+
+## Why the comparison anchors at the merge base
+
+The comparison is always base against the current head, never the previous
+push against the new one. A follow-up only ever moves the after side of the
+comment, so what the comment claims can only grow to match what the branch
+actually shows, and a reviewer who opens it midway through a review round
+never reads a stale before image describing an intermediate commit nobody is
+looking at anymore.
+
+## What counts as evidence
+
+A changed path qualifies when one of its segments is literally `evidence` and
+its filename carries an image extension (`png`, `jpg`, `jpeg`, `gif`, `webp`,
+`avif`, `svg`). The second half of that test exists because an `evidence/`
+folder holds whatever else a project keeps beside its captures. This
+repository's own tree carries eight `.md` files, two `.sh` scripts, a `.tsv`,
+a `.json`, and an `.html` file against a single `.png`, and every one of them
+would render as a broken `![]()` embed without the extension filter.
+
+## What the record carries
+
+The record groups every evidence path by state, the remainder of its
+directory under the `evidence/` segment, and within a state by filename stem,
+so a `before/hero.png` and an `after/hero.png` naming the same case group as
+one entry rather than two unrelated files. Each entry carries whether it
+existed at the base commit, which decides whether the comment shows a base
+image or marks the case new.
+
+`reason` on the record is what a caller branches on, not the exit code:
+
+| Reason               | What it means                                                                 |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `ok`                 | A body was rendered. `commentId` is set when a marked comment already exists. |
+| `no-evidence`        | Nothing in the diff carries an `evidence/` segment. An ordinary silent no-op. |
+| `gh-missing`         | `gh` is not on the path, so no pull request could be resolved.                |
+| `gh-failed`          | `gh` could not answer for this repository or branch.                          |
+| `no-branch`          | The pull request carries no head branch name.                                 |
+| `no-object-head`     | The pull request object reported no head commit.                              |
+| `no-base`            | No base resolves against the trunk.                                           |
+| `unreadable-tree`    | git could not read the tree at the base commit.                               |
+| `unreadable-changes` | git could not list what this branch changed.                                  |
+
+`no-evidence` is not a refusal a caller reports. A project on a stack that
+carries no evidence path, such as `base` or `python`, hits this reason on
+every pull request and posts nothing, which is the correct behavior rather
+than a gap.
+
+## What `[number]` selects, and what it does not
+
+Naming a number picks which pull request the rendered body claims to
+describe: its head commit and, when one already exists, the marked comment to
+edit in place. The base and the changed set are always read from the local
+checkout's own history, `git diff` and `git ls-tree` against the merge base
+with the trunk, rather than fetched for the named pull request over the API.
+That is correct for `git-pr` and `git-followup`, which never pass a number
+and always run from the worktree building the branch, so the local checkout
+and the named pull request describe the same branch. Naming a number for a
+pull request built somewhere else compares this checkout's own diff against a
+head commit that describes a different one.
+
+## One comment, found by its own marker
+
+Every body this verb renders ends with a trailing marker naming the head it
+describes:
+
+```markdown
+<!-- pr-evidence: head=<sha> -->
+```
+
+`canon pr evidence` reads that marker back off every comment on the pull
+request, the same way `canon pr review-state` reads its own marker off a
+review body, and reports the REST id of whichever comment carries it as
+`commentId`. A caller with no `commentId` posts a new comment. A caller
+holding one edits that comment in place with a `PATCH` rather than posting a
+second one.
+
+Putting the lookup here, in the one place both `git-pr` and `git-followup`
+call, is what keeps two close-out comments from landing beside each other the
+way `review-pr` once posted, before that skill's own guard existed. It is
+also why this verb renders the whole comment body rather than handing each
+skill a record to format on its own: a fix to the table shape or the
+collapsed-details wrapper lands once, not twice.
+
+## What a collapsed comment still leaves to GitHub
+
+GitHub already draws its own before-and-after comparison on the Files Changed
+tab for any tracked image that changed. This comment does not make that view
+redundant. The diff view shows what moved between two commits a reader has
+already opened, and the comment is what lets a reader see the same comparison
+without opening it at all.

package/governance/rules/ui/440-surface-capture.md

@@ -37,3 +37,4 @@ paths:
 - A project whose own established convention already commits that same comparison may route a flagged case's evidence there instead of a separate evidence folder. Only an established convention already committing the same comparison qualifies, not a preference for skipping a second folder.
 - Commit an evidence case for the first time only after running the capture twice with no code change between the runs and confirming the two outputs are byte-identical.
 - Recommitting an unbounded sweep on every run reaches a gigabyte of repository history inside a hundred merges. A small, committed evidence set is what a reviewer needs and what lets GitHub draw its own before-and-after comparison on the pull request.
+- `git-pr` and `git-followup` maintain a comparison comment on the pull request automatically once a case is committed, so a reviewer never has to open Files Changed to see it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.74.0",
+  "version": "4.75.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/design.ts

@@ -7,6 +7,7 @@ import {
   DESIGN_PROJECT_SUBDIR,
 } from '@/design/adapter'
 import { buildDesignCss } from '@/design/css'
+import { HAND_DRAWN_FONT_FACES } from '@/design/fonts'
 import { renderDesignDoc } from '@/design/render'
 import { DESIGN_BASE_CSS, DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
@@ -80,9 +81,16 @@ export function register(program: Command): void {
       '--no-components',
       'Custom properties only, without the component rules',
     )
-    .action((opts: { components: boolean }) => {
+    .option(
+      '--figures',
+      'Embed the hand-drawn figure fonts (Virgil, Excalifont), which the unconditional component styling never carries on its own',
+    )
+    .action((opts: { components: boolean; figures?: boolean }) => {
       process.stdout.write(
-        buildDesignCss(undefined, { components: opts.components }),
+        buildDesignCss(undefined, {
+          components: opts.components,
+          embedFonts: opts.figures ? HAND_DRAWN_FONT_FACES : undefined,
+        }),
       )
     })