@erclx/canon 5.41.0 → 5.42.0

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

@@ -50,13 +50,21 @@ A plan failing these is non-conforming even when it satisfies every shape rule b
 ## Filename and slug
 
 - Name the file `feature-<slug>.md`, with `<slug>` two to four kebab-case words naming the concern.
-- Write one concern per file. A request spanning two independent concerns takes two plans rather than one bundling both, since a bundled plan cannot be executed by two sessions or abandoned by half.
-- A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `**Files to touch:**`. One plan filename derives one branch, so batches sharing a file have nothing to open a pull request against once the first merges. State a batch's dependency on the ones before it in its own `**Constraints:**`. A batch that stacks on another and shares most of its files with it folds into that batch as contiguous commits on one branch rather than taking a file, unless its constraints carry ``Judged apart from `feature-<parent>`: <reason>`` with a reason after the colon. `canon records validate plans` reports `stack-foldable` for a stacked batch that has neither.
+- Write one concern per file, since a plan bundling two cannot be executed by two sessions or abandoned by half
 - Derive the slug from the concern rather than from a branch, because the plan is written before the branch exists.
-- Give the branch that executes the plan the same slug. A later surface finds the plan from the branch name and finds nothing when the two spellings differ.
+- Give the executing branch the same slug, since a later surface finds the plan from the branch name and finds nothing when the spellings differ
 
 A plan carries no frontmatter. Its filename is the whole of its identity, so a folder of plans is read by name rather than by a generated catalog.
 
+### Staged batches
+
+A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `**Files to touch:**`. One plan filename derives one branch, so batches sharing a file have nothing to open a pull request against once the first merges.
+
+- State a batch's dependency on the ones before it in its own `**Constraints:**`
+- A batch stacking on another and sharing most of its files folds into that batch as contiguous commits on one branch, rather than taking a file
+- It takes a file anyway when its constraints carry ``Judged apart from `feature-<parent>`: <reason>`` with a reason after the colon
+- `canon records validate plans` reports `stack-foldable` for a stacked batch that has neither
+
 ## Sections
 
 The document opens with `# Feature: <short title>` and one paragraph stating what is being built and why now. The sections below follow in this order.
@@ -73,62 +81,86 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | `**Sources:**`        | the outside sources a decision rests on, each with its quoted passage     | When a decision rests on an outside source |
 
 - Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the others are labels over lists rather than sections of prose.
-- A section written in the other spelling is still that section, since `## Risks` and `**Risks:**` name one thing. Write the table's form in a new plan and leave an existing plan's spelling alone. Either spelling breaks a depth run.
+- A section in the other spelling is still that section, since `## Risks` and `**Risks:**` name one thing, and either spelling breaks a depth run
+- Write the table's form in a new plan and leave an existing plan's spelling alone
 - Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
 - Aim `## Summary` at a person scanning the plan, not at the session executing it. The other sections carry what execution needs.
 
 ### Files to touch entries
 
-- Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against. Lead with the path or lead with a label carrying the path, whichever reads better for the entry.
-- Separate the two halves with a colon, and keep every path the entry declares ahead of it. What sits before the colon reads as a target, so both sides of a rename belong there and a file merely cited by the reason does not.
-- Read the list as what the branch sets out to write rather than as a bound on it, since the doc syncs at ship write past it on nearly every branch. `canon tasks plan-reach <plan>` reads the branch back against this list and every other live plan.
+Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against.
+
+- Lead with the path or with a label carrying the path, whichever reads better for the entry
+- Separate the two halves with a colon, and keep every path the entry declares ahead of it, since what sits before the colon reads as a target
+- Both sides of a rename belong before the colon, and a file merely cited by the reason does not
+- Read the list as what the branch sets out to write rather than a bound, since the doc syncs at ship write past it on nearly every branch
+- `canon tasks plan-reach <plan>` reads the branch back against this list and every other live plan
 
 ### Measured claims
 
-- State every count and every claim about the tree as measured during the pass that wrote the plan. A figure carried in from a summary or an earlier session is the most common way a plan ships the wrong scope.
-- Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
+State every count and every claim about the tree as measured during the pass that wrote the plan. A figure carried in from a summary or an earlier session is the most common way a plan ships the wrong scope.
+
+Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
 
 ### Constraints
 
 Work in flight reaches a plan as a hold or as a shared path. A hold leaves a surface alone and says which of two acts it forbids, rather than leaving the executing session to guess. Neither act is forbidden over a shared path.
 
-- Write a hold only for a dependency, a contract the other track consumes, a relocation, or a sweep, which a rebase cannot settle mechanically. A bare shared file is none of these, and forbidding it sends a worker to concede a file the change needs.
+Write a hold only for a dependency, a contract the other track consumes, a relocation, or a sweep, which a rebase cannot settle mechanically. A bare shared file is none of these, and forbidding it sends a worker to concede a file the change needs.
+
 - Forbid conforming that surface to whatever shape the change introduces, which keeps the branch to one concern.
-- Never forbid retargeting a pointer the change breaks. A rename, a split, or a deletion that leaves a citation behind ships a dangling reference, so repairing it is required work rather than scope creep.
+- Never forbid retargeting a pointer the change breaks, since a rename, split, or deletion leaving a citation behind ships a dangling reference
 - Decide both acts for every surface a hold names, not for one file among its siblings.
 - Write a shared path as the track, the path, and the branch that rebases, being the one merging second. The executing session edits the file and keeps both sides on the rebase.
 
+### Stamping a constraint
+
 A constraint measured against work in flight expires when that work merges, as a shared-path line does, so stamp the block with what it was measured against.
 
 - Give the stamp its own leading bullet, written as Measured against `<commit>` on <YYYY-MM-DD>. One stamp covers the whole block.
-- Stamp the commit rather than the track names or a date alone. The constraint already names each track, and a date does not separate two plans written on either side of a merge.
-- Re-test a stamped constraint before honoring it with `git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>`. Any commit it reports means the track landed and the constraint is dead. Fetch and scope the log to the paths in the same command, since a stale ref reads a dead constraint as live and a squashed subject names no track.
+- Stamp the commit rather than the track names or a date alone, since a date does not separate two plans written either side of a merge
 - Read an unstamped constraint as unverified rather than as live, and confirm it against the open pull request list for the named paths.
 
+Re-test a stamped constraint before honoring it, fetching and scoping the log in one command, since a stale ref reads a dead constraint as live and a squashed subject names no track. Any commit it reports means the track landed and the constraint is dead.
+
+```bash
+git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>
+```
+
+### Fan-in and ready constraints
+
 A batch in a fan-in set declares its side in a constraint bullet, ``Fan-in member of `feature-<integrator>` `` on a member and ``Fans in `feature-<a>`, `feature-<b>` `` on the integrator. `batches.md` holds when to fan in, and `canon records validate plans` reports `fan-in-unmatched` for a set whose two sides disagree.
 
 A constraint naming a `.canon/ready/` folder is a third shape beside the hold and the shared path. It makes that folder's files the verbatim source for the paths this plan's `**Files to touch:**` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
 
 ### Verification
 
+Every outcome reaches the review with its proof named.
+
 - Name, for each outcome, the test or the command that proves it, as one bullet leading with the outcome and ending on the command in backticks.
 - Write a command a later session can run as given, from the project root. A description of what would be checked leaves the executing session to invent the check.
 - Name the visual check where no test reaches, and say it is visual, so a reader can tell a proof from a look.
 
 ### Risks
 
-- Name the collision rather than the category. A risk a reader cannot act on is padding.
-- Where the work establishes a resource with more than one consumer, list the consumers and mark each one read or write. A policy stated over that resource has to hold for the writers and not only for the consumer that prompted it.
-- Where the work changes a contract another track consumes, such as an exported signature, a verb's flags or record, or a config key, name the contract and list each consumer. The dispatcher reads this bullet for the contract hold, so a change left out reaches it as a clean shared file.
+Name the collision rather than the category, since a risk a reader cannot act on is padding.
+
+- For a resource with more than one consumer, list the consumers and mark each read or write, so a policy over it holds for every writer
+- For a changed contract another track consumes, such as an exported signature, a verb's flags or record, or a config key, name it and list each consumer
+- The dispatcher reads that contract bullet for the hold, so a change left out reaches it as a clean shared file
 
 ### Review focus
 
+This section is where the planner's understanding of the risk reaches the review pass.
+
 - Name each input or state that would break the change if the implementation got it wrong, one bullet each, with what the change must do there.
-- Write it for the reviewer rather than the builder, since this section is where the planner's understanding of the risk reaches the review pass.
+- Write it for the reviewer rather than the builder
 - Keep it apart from `**Risks:**`. A risk is something the work might collide with, and a focus item is something the finished diff must be shown to handle.
 
 ### Sources
 
+A source earns an entry only once someone opened it.
+
 - Give each entry a link, the decision it backs, and the passage relied on in double quotes.
 - Mark a source that could not be fetched `unverified` and never quote it. A quote for a page nobody opened is the failure this section exists to prevent.
 - Cite no source that was found and not opened, following the lead rule in `groundwork.md`.
@@ -158,14 +190,19 @@ An execution that deviates rewrites the suggestion into the form below, leaving
 
 ### Preference questions and answers
 
+The suggestion line is the planner's, and the answer line belongs to whoever owns the call.
+
 - Write `- Suggested: needs your call, <why>` where the answer turns on preference rather than on a technical default. Fabricating a default there hides an open question behind an accepted answer.
 - Never fill an `- Answer:` slot on behalf of the person who owns it. Recording the pick as the suggestion is what the suggestion line is for.
 
 ### Overrides and settled questions
 
-- Rewrite the `- Suggested:` line to the pick execution made when it deviates from an unanswered question, and leave the slot blank. The prohibition above reaches the answer line alone, so the suggestion line is where a deviation goes.
-- Open the rewritten text with `overridden at execution to <pick>,` and follow it with the measurement that moved the pick. The fixed phrase is what tells an override from an authored suggestion, which routinely carries a number too.
-- Take a deviation from an answered question back to whoever answered it rather than rewriting either line. A filled slot is a decision already made, and a suggestion rewritten under one leaves the plan holding two picks with no default resolving them.
+A deviation from an unanswered question rewrites the `- Suggested:` line to the pick execution made and leaves the slot blank, since the prohibition above reaches the answer line alone.
+
+- Open the rewritten text with `overridden at execution to <pick>,` and follow it with the measurement that moved the pick
+- The fixed phrase tells an override from an authored suggestion, which routinely carries a number too
+- Take a deviation from an answered question back to whoever answered it rather than rewriting either line
+- A filled slot is a decision already made, and a suggestion rewritten under one leaves two picks with no default resolving them
 - Answer in place when a question is settled in conversation, so the file and the decision do not disagree.
 
 The plan is archived at ship, so the same deviation takes one line in the open task's `## Findings` naming what shipped. The plan holds why the pick moved and the task holds what the tree now has.

package/claude/skills/plan-groundwork/references/groundwork-spikes.md

@@ -31,7 +31,8 @@ The file is optional, since measuring what is already there settles most questio
 Each spike carries four things:
 
 - The open question it answers, named by file and number. A spike attached to no question is a runaway.
-- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, since an arm pointed at a fixture inside the project measured the project, plus the exact command and the repetition count.
+- The method, stated fully enough for a later reader to re-run it, with the exact command and the repetition count.
+- The fixture and where it lived, since an arm pointed at a fixture inside the project measured the project
 - The result, and which question it closes. Record a spike that settles nothing too, so a later pass does not pay for it twice.
 - The measured cost, even for a single read, and the caveats bounding what the result proves. Cost is a report rather than a limit, and it makes the next spike estimable.
 
@@ -47,6 +48,8 @@ A file a reader opens to verify how a result was produced or what it showed live
 
 Open no other subfolder: `spikes/`, `web/`, and `research/` fold into these three, with a fetched page in `clones/` and a reference-site screenshot in `evidence/`.
 
+### Harnesses and read checks
+
 Reach for a test harness the project already carries before building one. An experiment no existing harness can express is a finding for the folder, not a new abstraction.
 
 Never count transcript matches to show a file was read. An instruction naming a path puts it in the transcript whether or not anything opened it, so the check is the tool call.

package/claude/skills/plan-groundwork/references/groundwork.md

@@ -44,9 +44,11 @@ Does not govern:
 
 - Name the folder `<nn>-<slug>`, a two-digit ordinal and a kebab-case slug.
 - The ordinal marks a folder per track, opened once and worked over time, unlike a file addressed by name, one with its own sorting prefix, or one overwritten on purpose.
-- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in one atomic act, so two sessions opening at once never share a number. The two kinds share one order.
+- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest across `.canon/groundwork/` and `.canon/intake/`, since the two kinds share one order
+- The claim creates the folder in the same atomic act, so two sessions opening at once never share a number
 - With neither folder holding an entry, the first one opened takes `01`, whatever number a track's own files start at.
-- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
+
+Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 
 ## What a working track looks like
 
@@ -86,20 +88,15 @@ A folder missing `06` and `07` is live, and that is its only status marker.
 
 ## README.md
 
-Orients. Holds no findings.
+Orients and holds no findings. It states the phase out loud in its first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
 
 - A one-line definition of the investigation
 - A `## Why` section stating why the track is running now
 - A file-map table of filename and what it holds, kept current
 - A `## Method` section splitting internal sources from external ones, naming which were used and which were not yet done, and listing under a leads heading any external source found but not opened
+- Closing `## Prior art` and `## Source citation` sections, the second stating the rule below so a returning session finds it in the folder
 
-### Closing sections and phase
-
-- A `## Prior art` section
-- A `## Source citation` section stating the rule below, so a returning session finds it in the folder
-- The phase stated out loud in the first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
-
-Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. Without one, a later reader cannot tell a fetched page from recall. A source found and not read is listed as a lead and is never cited, since a link to a page nobody opened is worse than no link. Listing it stops a later pass re-searching for it.
+Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder, so a later reader can tell a fetched page from recall. A source found and not read is listed as a lead and never cited, since a link to a page nobody opened is worse than none. Listing it stops a later pass re-searching for it.
 
 Where the track supersedes an earlier plan or an earlier folder, name it and say not to go looking for it. Without that, the old reasoning keeps circulating.
 
@@ -117,11 +114,10 @@ Written when the subject is large enough to run away. Holds constraints, risks,
 
 ## 06-decision.md
 
-Closes the folder. Everything above it is input. Write it from the skeleton under `## Template`, with an H3 per dropped alternative.
+Closes the folder. Everything above it is input. Write it from the skeleton under `## Template`, with an H3 per dropped alternative, a list that stops a future session re-proposing a rejected idea.
 
-`## Revisit when` carries the "Overturned by" line of each lean that became the decision, as written. A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section.
-
-The dropped list stops a future session re-proposing a rejected idea.
+- `## Revisit when` carries the "Overturned by" line of each lean that became the decision, as written
+- A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section
 
 ## 07-next-session.md
 
@@ -158,7 +154,9 @@ A lean is weaker than a plan's suggestion: it records the current read on an ope
 
 ## Template
 
-### README.md
+The orienting README comes first, then the closing decision, with an H3 per dropped alternative.
+
+**`README.md`**
 
 ```markdown
 ---
@@ -203,7 +201,7 @@ Every claim about a source outside the project carries a link. A source found
 and not read is listed as a lead and is never cited.
 ```
 
-### 06-decision.md
+**`06-decision.md`**
 
 ```markdown
 ---

package/claude/skills/plan-intake/references/intake.md

@@ -7,7 +7,7 @@ description: Folder layout, ordinal naming, reserved index number, frontmatter a
 
 Applies to an intake folder at `.canon/intake/<nn>-<slug>/`. One folder holds one dump, filed by domain, and every finding in it is an item carrying a measured problem, one proposed fix, and a verdict.
 
-The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and neither protects against a compaction dropping a session's reasoning before anyone has pushed. No check reaches its contents, so the shape below survives only by being read.
+The folder is gitignored. Where a records remote is configured, `canon records push` and `canon records pull` protect it against losing the machine, and elsewhere they refuse with `no-remote`. Neither saves reasoning a compaction drops before a push. No check reaches its contents, so the shape below survives only by being read.
 
 <!-- canon-length-exempt: the folder shape and the item template share one reader, and a split into a second reference is queued as its own change -->
 
@@ -41,11 +41,13 @@ Does not govern:
 
 ## Folder name
 
-- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug. This is the folder's own ordinal, distinct from the `NN-<domain>.md` numbering a cluster file carries inside it.
+- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal and a kebab-case slug, distinct from the `NN-<domain>.md` numbering of its cluster files
 - The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
-- Claim the ordinal through `canon records ordinal intake <slug> --claim`, which reads the highest one already present across both `.canon/intake/` and `.canon/groundwork/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
-- With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a dump, which starts at `00` and disagrees with groundwork's own first required file.
-- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
+- Claim the ordinal through `canon records ordinal intake <slug> --claim`, which reads the highest across `.canon/intake/` and `.canon/groundwork/`, since the two share one creation order
+- The claim creates the folder in the same atomic act, closing the race a read-then-create leaves open between two sessions opening at once
+- With neither folder holding an entry, the first one opened takes `01`, never read off a dump's inner numbering, which starts at `00`
+
+Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 
 ## What a working intake looks like
 
@@ -68,9 +70,8 @@ An intake failing these is non-conforming even when it satisfies every shape rul
 
 `00` is the only reserved number. Everything else is read order, and the domain rides in the filename so a reader knows what `07-tooling.md` holds without opening it.
 
-Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. A folder whose shape is fixed can reserve its numbers, and that half of the convention does not transfer.
-
-Let the file count follow the number of separable domains. A large dump with two domains is a small folder.
+- Do not reserve mid-range numbers, since clusters differ per dump and a contract over `06` would force every intake into one dump's shape
+- Let the file count follow the number of separable domains. A large dump with two domains is a small folder.
 
 ## Frontmatter and dating
 
@@ -113,35 +114,39 @@ Where an item touches a task already on the board, say so in the index rather th
 ```
 
 - `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
-- Number items per cluster file, and give a finding split after the fact a letter suffix on the number it came from, as in `3a` beside `3`. Renumbering the items below it instead moves every label a reader or an answer already cited.
-- `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default.
-- `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
-
-Two heading levels is the right depth inside a cluster file. A third means the cluster should have been its own file.
+- Number items per cluster file, giving a finding split later a letter suffix such as `3a` beside `3`, since renumbering moves every cited label
+- `Suggested:` is required whenever `Open:` is present, since `ok` against two defensible options carries no information
+- Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default
+- `Overlaps:` never replaces `Worth it:`, since an item a live board task might have wrong is the one whose verdict matters most
 
-An item may carry a bolded standalone line between the bullets where a finding needs a name of its own. Keep it rare. Everything fitting the four bullets belongs in them.
+Two heading levels is the right depth inside a cluster file. A third means the cluster should have been its own file. An item may carry a rare bolded standalone line between the bullets where a finding needs a name of its own, and everything fitting the four bullets belongs in them.
 
 ## The answer contract
 
-`You:` belongs to the operator and ships empty on every item.
+`You:` belongs to the operator and ships empty on every item. Empty means unread and never agreement, so accepting a verdict is typed as one token, `- **You:** ok`.
 
-Empty means unread. It never means agreement. Accepting a verdict is typed as one token, `- **You:** ok`.
+- Never fill a `You:` slot, and never infer a disposition from an empty one
+- On a resume pass, report unread items by count rather than deciding them
 
-That inverts the plan file's contract, where a blank answer slot means accept the suggestion, and the inversion is deliberate. A plan is read in one sitting with every question already surfaced in conversation. An intake folder is read over weeks, so an empty slot is ambiguous between accepting the verdict and never having reached the item, and the second reading is far more likely. Acting on silence as consent ships a change nobody approved.
+### Why silence is not consent
 
-Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
+This inverts the plan file's contract, where a blank slot means accept the suggestion. A plan is read in one sitting with every question already surfaced. An intake folder is read over weeks, so an empty slot more likely means nobody reached the item, and acting on it ships a change nobody approved.
 
-A slot is filled two ways. The operator types into the cluster file, or answers in chat and a verb lands the selection on the item. Both put the answer on the item, which is what keeps retrieval working, and neither lets a session decide one. An answer given in conversation and never written back leaves the item unread, since the file rather than the conversation is the record.
+### Filling a slot
 
-An item already carrying an answer is refused rather than overwritten, whichever route the second answer arrives by. A filled slot is a decision already made, and revising one is the operator editing their own line.
+The operator types into the cluster file, or answers in chat and a verb lands the selection on the item. Both put the answer on the item, which keeps retrieval working, and neither lets a session decide one.
 
-## Retrieval
+- An answer given in conversation and never written back leaves the item unread, since the file is the record
+- An item already carrying an answer is refused rather than overwritten, whichever route the second answer takes
+- Revising a filled slot is the operator editing their own line
 
-Answers live on items, so one pass over the folder reports every touched slot.
+## Retrieval
 
-A session with the toolkit CLI on PATH reads the folder through `canon intake list`, which reports per-folder counts bare and one folder's items with `--json`, and takes `--unread` to keep only the empty slots. It is the surface under test, and it skips the index and every fenced sample, which the greps below cannot do.
+Answers live on items, so one pass over the folder reports every touched slot. With the toolkit CLI on PATH, read the folder through `canon intake list`, the surface under test.
 
-The greps stay for a reader without the CLI, and they overcount by whatever the folder displays in a fence.
+- Bare, it reports per-folder counts, `--json` gives one folder's items, and `--unread` keeps only the empty slots
+- It skips the index and every fenced sample, which the greps below cannot do
+- The greps stay for a reader without the CLI, and they overcount by whatever the folder displays in a fence
 
 ```bash
 awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print "   "$0}' *.md

package/claude/skills/pr-evidence/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: pr-evidence
+description: What posting a pull request's rendered-surface evidence is for, the gaps it closes, and what it refuses to do
+---
+
+# PR evidence requirement
+
+## Gap
+
+Without this skill, the evidence a pull request carries is one step inside `git-pr`. A session refreshing the screenshots on a new head either reruns a title and body it did not mean to touch, or borrows the step's reference by path. Two skills borrowed it that way, and each copy drifted.
+
+A session judging from the diff whether an evidence image changed cannot see a regenerated image it did not author, so the image ships with no comment. A reviewer holding screenshots and a checklist has nothing to click into, and a slow deploy holds the ship chain while it waits for an address.
+
+## Must
+
+- Run the evidence verb on every pull request it is given and let `no-evidence` be the skip, since asking a session to look lets an unseen image ship with no comment
+- Run alone against an open pull request, resolving the number from the branch when none is passed, so a later head gets evidence without a body rewrite
+- Edit the one marked comment in place on a later run, so a re-post never duplicates the thread or drops a carried checklist
+- Put a preview address on a pull request changing a rendered surface when the project's deploy can mint one, since a reviewer needs a page to click into
+- Bound the wait on that preview and finish without the link on a timeout, since a slow deploy must not hold the ship
+- Link the branch's running local server when this worktree serves one, since a reviewer on the operator's machine can drive the branch
+- Drop that link when the pull request closes, since a link outliving its branch points at whatever runs there next
+
+## Must not
+
+- Dispatch a deploy whose command names no branch, since Cloudflare Pages publishes such a deploy to production
+- Create a pull request, or post against a number it guessed, since a write to a wrong number lands on another branch's thread
+- Call a GraphQL-backed `gh` subcommand, since the cloud review-address leg runs this skill through `git-followup`
+- Print a result line of its own, since `git-pr` prints one and its report ends with the lines this skill returns
+- Exist only for the author to type its name. `git-pr`, `git-followup`, and `git-ship` each invoke it, and a review of the catalog drops it when none does.
+
+## Guards
+
+- Stop and ask for the number when none was passed and no open pull request resolves for the branch
+
+## Out of scope
+
+- The title, body, labels, and pre-publish scan, which `git-pr` owns
+- Writing the checklist, which `ui-checklist` owns. This skill only consumes the handoff file and removes it after posting.
+- Driving the checklist in the running app, which `review-ui` owns

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

@@ -0,0 +1,53 @@
+---
+name: pr-evidence
+description: Posts the rendered-surface evidence on an open pull request, being the screenshot comparison with the UI checklist, the checklist alone when git refuses the comparison, the local server link, and the preview address, editing the one marked comment in place on every later head. Use when asked to "post the evidence", "refresh the screenshots on the PR", or "re-post the evidence on the new head", and as the closing step of `git-pr`. Do NOT use to write a pull request's title or body, which is `git-pr`, or to write the checklist, which is `ui-checklist`.
+metadata:
+  family: after-pr
+---
+
+# PR evidence
+
+The evidence a pull request carries is owed again on every new head, while its title and body are not. This skill posts it against one pull request number, so `git-pr` runs it as its last step and any session can run it alone after a push.
+
+## Resolve the pull request
+
+Take the number the caller passed and look nothing up. `git-pr` passes the number its final command printed, and never invokes this skill when that command refused on a head mismatch and printed none.
+
+Run bare, resolve the open pull request for the current branch:
+
+```bash
+canon pr head --json
+```
+
+Read `reason` on the record rather than the exit code, since a shell function wrapping `canon` can flatten it to zero.
+
+- A record carrying `number`: hold it for every step below
+- Any refusal, including `gh-failed` for a branch with no open pull request, stops the run with `❌ No open pull request resolved for this branch: <message>. Pass the number and re-run.`
+- Never create a pull request here and never guess a number, since a write to a wrong number lands on another branch's thread
+
+## Post the evidence
+
+Read `${CLAUDE_SKILL_DIR}/references/evidence.md` and run its sections in order against the number, being the checklist, the local server, the evidence comparison, the checklist alone, and the preview address.
+
+- Every post and edit goes through `gh api` over REST, since a cloud session's proxy refuses the GraphQL that `gh pr` runs on
+- Never judge from the diff whether an evidence image changed, since the verb answers `no-evidence` for a branch that changed none and a session cannot see an image it did not author
+- A lone run on a later head edits the marked comment through the record's `commentId` and passes no `--checklist` for a handoff already deleted, since the verb carries the checklist forward
+
+## Report
+
+Collect only the lines below whose condition holds, and nothing when none does. A lone run prints them. A run another skill invoked hands them back to that caller and prints nothing, since `git-pr` prints its own result line and then these lines, and printing here too shows them twice.
+
+| Condition                                                 | Line                                                               |
+| --------------------------------------------------------- | ------------------------------------------------------------------ |
+| A checklist posted in the evidence comment                | `📋 Posted the UI checklist to <number>, in the evidence comment.` |
+| A checklist posted alone                                  | `📋 Posted the UI checklist to <number>, on its own.`              |
+| The preview step returned an address                      | `🔗 Preview: <url>`                                                |
+| The evidence step posted the local link                   | `🖥️ Local preview: <url>`                                          |
+| The local step refused and evidence or a checklist posted | `🖥️ No local preview: <reason>`                                    |
+| A git refusal or a preview refusal the reference reports  | `⚠️ <reason>: <message>`                                           |
+
+### The no-local-preview line
+
+It fires when the local step refused as `no-server` or `no-listener-reader`, since that pull request changes a rendered surface and a reviewer could have used the link. A later run only carries a link forward, so it cannot add one the comment never had.
+
+To add the link later, start the server and run this skill again, adding `--checklist` to the evidence call when one is still owed.

package/claude/skills/pr-evidence/references/evidence.md

@@ -0,0 +1,150 @@
+---
+title: Rendered-surface evidence
+description: How pr-evidence finds the UI checklist and the local server, posts the evidence comparison or the checklist alone as the fallback for a git refusal, and adds the preview address, for a change that touches a rendered surface
+---
+
+# Rendered-surface evidence
+
+The procedure of `pr-evidence`, run in order against one pull request number. It runs on every pull request with no test on the diff ahead of it, since `no-evidence` is the silent branch for one that changes no rendered surface.
+
+## Contents
+
+- [Find the UI checklist](#find-the-ui-checklist)
+- [Find the local server](#find-the-local-server)
+- [Post the evidence comparison](#post-the-evidence-comparison)
+- [Post the UI checklist alone](#post-the-ui-checklist-alone)
+- [Post the preview address](#post-the-preview-address)
+
+## Find the UI checklist
+
+`ui-checklist` writes a visual checklist to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. This skill is the file's sole consumer.
+
+- Resolve the main root the way `session-worktree` does, `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-` falling back to `pwd`
+- A missing file means no checklist was produced, and the two steps below each skip their checklist half
+- Scan an existing file against `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` before either step posts it, the same as the body
+- The evidence step decides where it lands, since a checklist reads next to its screenshots and posting it alone is the fallback for a refused render
+
+## Find the local server
+
+A reviewer on the operator's machine can open the branch's running dev server, which screenshots and a checklist cannot stand in for. Ask the verb before the evidence step, so the first evidence comment already carries the link:
+
+```bash
+canon pr local --json
+```
+
+The verb reports the lowest port serving an HTML page whose process runs inside this worktree, never one in another worktree or the main checkout, which shows a different branch. `canon pr local --help` states the contract. Read `reason` on the record rather than the exit code.
+
+- `ok`: hold the record's `url` for the evidence step below.
+- `no-server` or `no-listener-reader`: hold the reason for the closing report and pass no link. Never start a server here, since one started inside the ship chain has no owner to stop it.
+- Anything else, including no record or an older binary's unknown-subcommand error: move on silently, as a skip rather than a stop.
+
+### Where the link lands
+
+Pass `--local` to the evidence step only on an `ok`. The binary answering `ok` is the one carrying the flag, so a binary lacking the verb never meets a flag it would reject.
+
+- With a checklist, a diff carrying no evidence image still renders `ok`, and the link rides on the address line under `## Evidence`, above the checklist
+- A link with neither an evidence image nor a checklist still reports `no-evidence`, so a branch changing no rendered surface gets no comment holding a link alone
+- A seeded workflow drops the whole address line once the pull request closes, hosted and local together, so neither link outlives its branch
+
+## Post the evidence comparison
+
+Run the verb once against the pull request number. Pass `--checklist` when the checklist step found a file and `--local` when the step above returned `ok`, and leave each flag off otherwise:
+
+```bash
+canon pr evidence <number> --checklist <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md --local <url> --json
+```
+
+One call answers both questions because a checklist decides `no-evidence`. A diff carrying a checklist and no evidence image renders `ok` with the checklist in a marked body, so the checklist lands in the one comment a later call finds and edits.
+
+- Pass `--checklist` only for a file that exists
+- The verb refuses as `unreadable-checklist` on a path it cannot read or one holding nothing, a caller bug rather than a transient failure
+- Stop and repair the path on that refusal rather than posting a body with the checklist silently dropped
+
+### Reading the record
+
+Read `reason` on the record rather than the exit code.
+
+- `no-evidence`: nothing changed under an `evidence/` segment and no checklist was passed. Say nothing about the evidence and move on.
+- `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root, then post or update the comment:
+
+```bash
+gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md --silent
+```
+
+Both posts in this file use the REST issue-comments endpoint, since the `gh pr` subcommands run on GraphQL and a cloud session's GitHub proxy refuses it. `git-followup` runs this skill, so a GraphQL post here would break the cloud review-address leg.
+
+When the record carries a `commentId`, edit that comment in place instead of posting a second. The body reads from the tmp file with `@`, which needs `-F`, since `-f` posts the path itself as the body:
+
+```bash
+gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md
+```
+
+Delete the handoff file and the tmp body once that call reports success, per the cleanup below, since the checklist now lives on the pull request.
+
+### Git refusals
+
+Any other `reason` is a mirrored git refusal, being `gh-missing`, `gh-failed`, `no-base`, `unreadable-changes`, or `would-empty`. Report it and move on without stopping the chain, since a branch that rarely carries evidence images should not fail on a transient read.
+
+Fall through to the checklist step, which posts the checklist alone rather than losing it.
+
+## Post the UI checklist alone
+
+Run this step only as the fallback, when the evidence step reported a git refusal and a checklist file exists, since every other branch with a checklist rendered `ok` and carried it. The comment carries no marker, so a later `canon pr evidence` call reports no `checklist` for it.
+
+```bash
+gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@<main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md --silent
+```
+
+### Cleanup
+
+Run the cleanup only once the call that carried the checklist reports success, whichever step that was. On a failure, stop and leave the file, since a retry needs it and deleting it loses the only copy.
+
+The cleanup is a main-root delete, so it goes out as a plain `rm` and then a plain `rmdir`, routed the way `session-worktree` states:
+
+```bash
+rm <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
+```
+
+```bash
+rmdir <main-root>/.canon/tmp/handoff/ui-checklist 2>/dev/null || true
+```
+
+- The `rmdir` is a no-op while another branch's pending checklist sits in the folder, so this step never deletes a handoff not its own
+- `git-followup` re-runs `canon pr evidence` with no `--checklist`, and the verb carries the checklist forward out of the comment it edits
+- A tick survives a render at the head its stamp names and is cleared by one at a newer head, so the next UI pass earns it again
+
+## Post the preview address
+
+Run this step when the evidence step returned `ok`, the fallback posted a checklist, or `canon pr evidence <number> --check --json` lists `preview` in `owed`. Otherwise skip it silently.
+
+- The first two mean the pull request changes a rendered surface, and a reviewer holding a checklist with no screenshots needs the live page most
+- The third is how `git-ship` reaches this step alone when an earlier run's deploy timed out
+- An evidence record carrying a `commentId` takes the third alone, since a preview already on the comment counts as settled whatever head built it, so a later push does not re-mint one
+- The evidence comment is already posted, so the reviewer has the screenshots while the deploy runs
+
+```bash
+canon pr preview <number> --json
+```
+
+### What the verb refuses
+
+The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. `canon pr preview --help` states the contract. It refuses before dispatching anything in two cases.
+
+- The deploy command passes no `--branch`, since that deploy would publish the branch to production
+- The workflow's push path filter matches no changed path, since a dispatch ignores that filter and the site would show none of the change
+
+### Reading the preview record
+
+Read `reason` on the record rather than the exit code.
+
+- `ok`: re-render the evidence body with the address under `## Evidence`, then post or update it as the evidence step does, through the same tmp file and the record's `commentId`:
+
+```bash
+canon pr evidence <number> --preview <url> --json
+```
+
+The hosted address opens the address line, and a local link already on the comment follows it, carried forward with no flag.
+
+- `no-deploy` or `unserved`: the project deploys nothing a dispatch can start, or its site builds from nothing this branch changed. Say nothing and move on.
+- `unfenced`, `no-alias`, `run-failed`, `timeout`, or a mirrored `gh` refusal: report the record's `message` and move on without stopping the chain
+- A missing link costs the reviewer a click, and a held ship costs the whole chain