@erclx/canon 5.41.0 → 5.42.0

package/claude/skills/git-pr/references/labels.md

@@ -37,11 +37,11 @@ api = ["services/api/"]
 web = ["apps/web/", "packages/ui/"]
 ```
 
-A label takes more than one prefix when two folders read as one surface. Two labels may claim overlapping prefixes, and a path under both earns both.
-
-Matching is prefix-anchored, so a row written for an authoring root reaches nothing under the copy a project consumes. A surface living only under a dotted folder carries its own prefix on the row that owns its subject, and a folder holding several subjects rather than one splits across the rows that own them.
-
-The map is authored by hand, so a surface added after it was written labels nothing until someone adds a row. `canon labels audit` is what names that surface before the branch merges.
+- A label takes more than one prefix when two folders read as one surface, and a path under two overlapping labels earns both
+- Matching is prefix-anchored, so a row written for an authoring root reaches nothing under the copy a project consumes
+- A surface living only under a dotted folder carries its own prefix on the row owning its subject
+- A folder holding several subjects splits across the rows that own them
+- The map is hand-authored, so a surface added later labels nothing until someone adds a row, and `canon labels audit` names it before the merge
 
 ## Paths a map declines to label
 
@@ -55,44 +55,54 @@ release-managed = ["CHANGELOG.md", "package.json"]
 generated = ["build/manifest.json"]
 ```
 
-A table rather than a comment because the check reads it. A path here is a decision already taken and a path under neither table is a gap nobody has gotten to, and a report that could not tell those apart would be useful about neither.
-
-A path claimed by a `[domains]` row and a `[declined]` row takes the label. It already has a subject, so reporting it as deliberately unlabelled would contradict the label the same run applies.
+- It is a table rather than a comment because the check reads it, separating a decision already taken from a gap nobody has reached
+- A path claimed by both a `[domains]` row and a `[declined]` row takes the label, since it already has a subject
 
 ## Reporting a surface no row reaches
 
+The audit names every changed path no row reaches.
+
 ```bash
 canon labels audit --base <base> --json
 ```
 
-The record carries `labels`, `declined`, and `uncovered`. It exits 2 when `uncovered` has anything in it and 1 when it refuses, with `reason` naming the cause: `no-map` for a project that declared none, and a parse or range failure otherwise.
+The record carries `labels`, `declined`, and `uncovered`. It exits 2 when `uncovered` has anything in it and 1 when it refuses, with `reason` naming the cause, `no-map` for a project that declared none and a parse or range failure otherwise.
 
-It reports and never gates. Whether an uncovered surface deserves a label is a judgment only the person who owns that surface can make, and a push failing on one teaches a contributor to route around the check while nothing about the surface has changed.
-
-What it leaves unmeasured is a prefix reaching no path, so a row left behind by a deleted folder stays in the map. That is the map going stale from the other side and a second measure rather than this one.
+- It reports and never gates, since whether a surface deserves a label is a call only its owner makes
+- A push failing on one teaches a contributor to route around the check while the surface stays unchanged
+- A prefix reaching no path stays unmeasured, so a row left by a deleted folder stays in the map. That staleness needs a second measure.
 
 ## Matching
 
-- Take the changed set from `git diff --name-only <base>...HEAD`, resolved against the same base as the diff the body is written from. The three dots hold whether `<base>` arrives already resolved to a merge base or as a bare ref name, where the two-dot form is correct only in the first case and hands the branch somebody else's merged paths in the second
+- Take the changed set from `git diff --name-only <base>...HEAD`, against the same base the body is written from
+- The three dots hold whether `<base>` is already a merge base or a bare ref, where two dots would hand the branch somebody else's merged paths
 - A path earns a label when the path starts with one of that label's prefixes
 - Collect the distinct labels across the whole set, ordered as the map declares them, so two runs over one branch produce one string
 - Pass the result as a single comma-separated value. An empty result runs no labelling step.
 
 ## Applying
 
-Apply labels after the pull request resolves, never as a field on the create. A create carrying a label the remote lacks either fails whole or creates the label, depending on the surface, and neither is the map's call. One step against a pull request that already exists covers the create and the edit path alike. It runs over REST, so it works where GraphQL is blocked, and the REST endpoint creates any label it is handed that the remote lacks, so the step reads each name off the remote first and warns on a missing one rather than adding it.
+Apply labels after the pull request resolves, never as a field on the create. A create carrying a label the remote lacks either fails whole or creates the label, depending on the surface, and neither is the map's call.
+
+- One step against an existing pull request covers the create and the edit path alike, over REST, so it works where GraphQL is blocked
+- The REST endpoint creates any label it is handed, so the step reads each name off the remote first and warns on a missing one
 
-`canon labels apply <number>` is that step. It resolves the earned set from the pull request's own files listing, or from the git range when `--base` is passed, binds to the pull request only when its head is the current branch and it is open, and adds each earned label the pull request lacks. `--check` reports what is owed and writes nothing. The record carries `number`, `earned`, `present`, `added`, `owed`, `missingOnRemote`, and `uncovered`.
+### The apply verb
 
-A pull request opened outside this skill, such as by `gh pr create`, takes the same command, since nothing else labels it.
+`canon labels apply <number>` is that step. It resolves the earned set from the pull request's files listing, or from the git range when `--base` is passed, and adds each earned label the pull request lacks.
 
-Labelling runs whenever this skill runs and at no other time. Nothing else computes the set, so a push made any other way leaves the labels exactly as the last run left them. Any caller invoking this skill again reaches the step again, and it recomputes over the whole branch diff rather than over the new commits.
+- It binds only when the pull request's head is the current branch and it is open
+- `--check` reports what is owed and writes nothing
+- The record carries `number`, `earned`, `present`, `added`, `owed`, `missingOnRemote`, and `uncovered`
+- A pull request opened outside this skill, such as by `gh pr create`, takes the same command, since nothing else labels it
 
-An ordinary branch therefore labels once, when the pull request opens. The return leg that answers a review hands its push to `git-followup`, which refreshes the body without invoking this skill, so the commits that answer a review reach no labelling step.
+### When labelling runs
 
-A follow-up push reaching a surface the earlier ones did not merges under-labelled, with nothing to report the miss. Keeping the step in one skill is worth that cost, since a review fix lands in the files the review named and rarely opens a surface the branch had not already touched.
+Labelling runs whenever this skill runs and at no other time, recomputing over the whole branch diff. A push made any other way leaves the labels as the last run left them, so an ordinary branch labels once, when the pull request opens.
 
-The add endpoint adds and never removes. A label a person applied by hand is not this skill's to strip, and a re-run over a branch that has since dropped a surface keeps the label that surface earned.
+- The review return leg pushes through `git-followup`, which refreshes the body without this skill, so commits answering a review reach no labelling
+- A follow-up reaching a new surface merges under-labelled, a cost worth paying since a review fix rarely opens a surface the branch had not touched
+- The add endpoint never removes, so a hand-applied label stays and a surface the branch has since dropped keeps its label
 
 ## A label the remote does not carry
 
@@ -102,9 +112,9 @@ Warn and continue rather than creating it, naming the command in the warning:
 gh label create <name> --description "<text>"
 ```
 
-Creating a label writes to the repository settings from a run the user invoked to open a pull request, and a label created from a typo in the map is harder to notice than a warning is.
+Creating a label writes to the repository settings from a run invoked to open a pull request, and a label created from a map typo is harder to notice than a warning.
 
-The refusal names the label it rejected and applies none of the set, so a warning that reaches nobody leaves the run reading exactly like one that labelled. Surface it beside the result line rather than letting the pull request URL stand alone.
+The refusal names the label it rejected and applies none of the set, so an unseen warning leaves the run reading like one that labelled. Surface it beside the result line rather than letting the pull request URL stand alone.
 
 ## Release pull requests
 
@@ -118,14 +128,21 @@ The labels step of `git-pr` reads from here. Ask the CLI first:
 canon labels audit --base <base> --json
 ```
 
-The record carries `labels`, the set this branch earns, and `uncovered`, the changed paths no row of the map reaches. Join `labels` with commas into `pr_labels`, which the skill's final command takes. Report each `uncovered` path beside the result line, naming the map so the reader knows where a row would go, since a surface nobody covered merges bare and nothing else says so.
+Join the record's `labels`, the set this branch earns, with commas into `pr_labels`, which the final command takes. Report each `uncovered` path beside the result line, naming the map so the reader knows where a row would go, since an uncovered surface merges bare and nothing else says so.
+
+### Reading the reason
 
-Branch on the record rather than on the exit. An operator's shell profile may wrap `canon` in a function whose status comes from a trailing command, and the binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike.
+Branch on the record rather than on the exit. A shell profile may wrap `canon` in a function whose status comes from a trailing command, and the binary exits 1 for an unknown subcommand and an ordinary refusal alike.
 
-A `reason` of `no-map` is the answer that the project declared no map, which earns no labels and no warning: a label set this skill supplied would be a guess about that project's surfaces. Stop there and label nothing.
+- `no-map` means the project declared no map, so label nothing and warn about nothing, since a set this skill supplied would be a guess
+- `unreadable-map`, `no-domains`, `no-base`, `unreadable-changes`, and `bad-base` take the fallback below, with a warning naming the reason
+- A map with a typo still has rows a prefix can reach, and reading its refusal as absence would open the pull request bare and silent
 
-Every other `reason` is a map or a range the verb could not read, which is `unreadable-map`, `no-domains`, `no-base`, and `unreadable-changes`, plus `bad-base` for a ref this skill resolved wrongly. Take the fallback below and warn beside the result line, naming the reason. A map with a typo in it still has rows a prefix match can reach, and reading the refusal as an absence would open the pull request with no labels and nothing said, which is the surface merging bare that the verb exists to name.
+### The fallback
 
-The fallback is reading `canon/config/pr-labels.toml`, or `.claude/canon/pr-labels.toml` when the project has not moved, and matching it against the name-only diff per `## Matching` above. It also covers no record coming back at all, which is an installed `canon` predating the verb, since a skill reaches a target the moment it merges while the CLI reaches one only when a release publishes. Naming both spellings matters exactly here: the binary old enough to need this fallback is the same binary that may predate the move, so the project's map can still sit at the older path. The fallback labels correctly. It reports an uncovered path only when `canon labels audit` answered, passing that record's `uncovered` on as `pr_uncovered`, and a binary too old for the audit has none to pass.
+Read `canon/config/pr-labels.toml`, or `.claude/canon/pr-labels.toml` when the project has not moved, and match it against the name-only diff per `## Matching`. The fallback labels correctly.
 
-Leave `pr_labels` empty when no map resolves or no prefix matches, which skips the labelling command rather than running it against nothing.
+- It also covers no record at all, an installed `canon` predating the verb, since a skill reaches a target on merge and the CLI only on release
+- Both spellings matter here, since the binary old enough to need the fallback may predate the move too
+- It reports an uncovered path only when `canon labels audit` answered, passing that record's `uncovered` as `pr_uncovered`
+- Leave `pr_labels` empty when no map resolves or no prefix matches, which skips the labelling command

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

@@ -42,6 +42,8 @@ Does not govern:
 
 ### What to leave out
 
+A body describes the new behavior and nothing the diff or the commits already say.
+
 - Do not describe historical behavior or unchanged code. Describe new behavior only.
 - Do not include future promises or speculative documentation
 - Do not explain obvious changes (formatting, renaming variables)
@@ -54,38 +56,49 @@ Does not govern:
 
 ### Context section
 
-- `## Technical context` (optional): 1-2 lines of architectural reasoning explaining why, not what
+`## Technical context` is optional and carries 1-2 lines of architectural reasoning explaining why, not what.
+
 - Omit Technical context for docs, config, or trivial changes
 - Use bullet points for multiple reasons, one sentence for a single reason
 
 ### Testing section
 
-- `## Testing` (optional): specify exact commands or test cases run
+`## Testing` is optional and names the exact commands or test cases run.
+
 - Omit Testing for docs, config, or trivial sync changes
 - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
 
 ### Reviewer section and visuals
 
-- `## For the reviewer` (optional): what the reviewing session should confirm, one bullet per request
+`## For the reviewer` is optional and lists what the reviewing session should confirm, one bullet per request.
+
 - Visuals: include only when they clarify architecture, UI, or complex logic flows
-- The list is closed. A body carries the sections above and nothing after the last of them, which covers a trailer a harness appends once the body is composed. `canon labels scan` holds the list: it fails a level-two heading outside the five above, and a body missing `## Summary` or `## Key changes`. A review body and a release-please body are exempt.
+- The list is closed, so a body carries nothing after its last section, including a trailer a harness appends once the body is composed
+- `canon labels scan` fails a level-two heading outside the five above, and a body missing `## Summary` or `## Key changes`
+- A review body and a release-please body are exempt
 
 ## Testing discipline
 
 - Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
 - Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
 - Quote the count or output the run reported, never a figure carried from elsewhere.
-- A ticked box describes the tree as it stands, not as it stood when it was written. A later commit that removes or replaces what it names makes the box false, and the branch that made that commit corrects it in the same pass, the same as any other stale claim in the body.
+- A ticked box describes the tree as it stands. A later commit removing or replacing what it names makes the box false.
+- The branch that made that commit corrects the box in the same pass, as with any other stale claim in the body
 
 ### Human-only boxes
 
-- Leave a box unchecked only when a human is required, and name which human and why on the same line.
-- Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
-- What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.
-- A tool refusal that actually fired is a capability gap, and the line says which refusal rather than naming the cost behind it. A refusal predicted and never met is not one.
+Leave a box unchecked only when a human is required, and name which human and why on the same line. The agent runs everything else.
+
+- Human-only covers visual or aesthetic judgment, credentials or a live third-party service, and a second machine or a fresh OS
+- It also covers judgment about whether a boundary or an abstraction reads correctly
+- A human is required by a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not.
+- An arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned
+- A tool refusal that actually fired is a capability gap, and the line names the refusal rather than the cost. A refusal predicted and never met is not one.
 
 ### Live sessions and reviewer requests
 
+A live agent session is never the human a box waits on.
+
 - A live agent session is not a human. A box reading `needs a live session driving the skill` names the thing writing the description, so that run is owed rather than blocked.
 - Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
 
@@ -97,6 +110,8 @@ Does not govern:
 
 ### Template
 
+Every section a body may carry, in order.
+
 ```markdown
 ## Summary
 
@@ -124,6 +139,8 @@ Does not govern:
 
 ### Correct
 
+Each line's comment names the rule it follows.
+
 ```markdown
 ## Summary
 
@@ -151,6 +168,8 @@ Update auth middleware to enforce jwt expiration checks. # imperative + direct o
 
 ### Incorrect
 
+Each line's comment names the rule it breaks.
+
 ```markdown
 ## Summary
 

package/claude/skills/git-pr/references/publish.md

@@ -7,7 +7,7 @@ description: Scan an author runs against finished text, the cross-reference form
 
 ## Scope
 
-Governs the scan an author runs against finished text on its way out, the form a pull request or issue reference takes in every destination, and the responses available when a source it reaches for cannot be read. It is an attribute standard rather than a document-type one, so it applies wherever no automated check covers the text, whether that text is leaving through a channel or sitting in the repository, and it carries no template because a scan has no document to shape.
+Governs the scan an author runs against finished text on its way out, the form a pull request or issue reference takes in every destination, and the response when a source the scan reaches for cannot be read. As an attribute standard it applies wherever no automated check covers the text, and carries no template.
 
 Does not govern:
 
@@ -18,68 +18,82 @@ Does not govern:
 
 ## When it runs
 
-Wherever text leaves through a channel no automated check covers, the author is the only gate and runs this scan. Text sent to another service, written to a path the project's checks exclude, and text inside a fenced block are the usual cases. The surface that publishes the text is what knows which gap applies, so it names its own rather than reading one here.
+Wherever text leaves through a channel no automated check covers, the author is the only gate and runs this scan. Text sent to another service, text written to a path the checks exclude, and text inside a fenced block are the usual cases.
 
-Run the scan as an explicit step against the finished text. Having read the underlying rules before drafting does not cover it, because the check has to happen after the text exists.
+- The surface publishing the text knows which gap applies, so it names its own rather than reading one here
+- Run the scan as an explicit step against the finished text, since the check has to happen after the text exists
 
-Scope every check below by destination. Text published to a remote takes all of them. Text staying in the repository takes the character bans alone, since those hold wherever the text lands, and skips whichever check depends on the reader holding something only this checkout carries. The two checks below that depend on it say so under their own headings.
+### Scope by destination
+
+Text published to a remote takes every check below. Text staying in the repository takes the character bans alone, since those hold wherever the text lands.
+
+- Phase labels and board identifiers depend on the reader holding this checkout, so repository text skips both
+- Session links depend on the reader holding the account, a narrower dependency stated under their own heading
 
 ## Banned characters
 
 `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` holds the character bans. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
 
-`canon labels scan` fails on these characters in a title or body, outside a code span or a link, so the scan is the check and the read above is the reason. It holds a pull request and a posted review alike.
-
-Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.
+- `canon labels scan` fails on these characters in a title or body outside a code span or a link, for a pull request and a posted review alike
+- Restructure the sentence rather than substituting the character, since a semicolon swapped for a period keeps the shape the ban exists to remove
 
 ## Phase labels
 
 `${CLAUDE_SKILL_DIR}/../git-commit/references/versioning.md` holds the label rule and the table of surfaces. Read it at scan time rather than working the format from memory.
 
-This check is one of the two the destination rule above scopes. The reader inside the repository has the task board and the reader on a remote does not.
+The reader inside the repository has the task board and the reader on a remote does not, so this check is scoped by destination.
 
 ## Board identifiers
 
-A phase label is one way text names the board, and a path under a record root is the other. Both resolve for a reader holding this checkout and neither resolves for anyone else, so this check is the second one the destination rule scopes.
+A phase label is one way text names the board, and a path under a record root is the other. Both resolve for a reader holding this checkout and for nobody else, so this check is scoped by destination too.
 
-Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/feedback/` names a folder the remote's reader cannot open.
+- A code span whose whole content is a label is still the label and a hit. A longer token inside a span is a fixture name and stays.
+- A path under a record root is gitignored and absent from every clone, so `.canon/feedback/` names a folder the remote's reader cannot open
+- Tracked `canon/` and `.claude/` paths are no hit, since `canon/context/surfaces/governance.md` resolves everywhere
+- Every path under `.canon/` is a hit whichever folder it names, since one ignore line covers the root whole
 
-Under the tracked `canon/` and `.claude/` folders there is no hit, since `canon/context/surfaces/governance.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
+### Fixing a hit
 
-Rewrite a hit to name what the reader can reach rather than deleting it. A row's subject stated plainly replaces its label, and what a record folder holds, said in a sentence, replaces its path.
+Rewrite a hit to name what the reader can reach rather than deleting it. State a row's subject plainly in place of its label, and say in a sentence what a record folder holds in place of its path.
 
-`canon labels scan` runs this check and the phase-label one over a pull request title and body, and over a posted review's own text once one is submitted. Any other channel, a plain issue comment among them, is still the author's own scan.
+`canon labels scan` runs this check and the phase-label one over a pull request title and body, and over a posted review's text once submitted. Any other channel, a plain issue comment among them, is still the author's own scan.
 
 ## Session links
 
-A link to one Claude Code session names the session that wrote the text rather than the change the text describes. It enters because the harness tells the composing session to end its published text with one, so the author writes it deliberately and it reads as required rather than as a slip. That is what carries it past a scan the same author runs, and it is why a rule stating the ban does not reach the case: the session is following an instruction it was given, and reads its own compliance as correct.
-
-This check depends on the reader holding the account rather than the checkout, which is narrower than the dependency the destination rule above scopes. A reader inside this checkout opens a record path and still cannot open a session, since the session resolves for the one account that started it and for nobody else. The scoping still sits at the invocation site, because `canon labels scan` reads a pull request title and body and reaches no other text.
-
-Delete a hit rather than rewriting it. The other two checks replace a hit with what the reader can reach instead, and a session has no such form, so what stands in its place is the body already written above it.
+A link to one Claude Code session names the session that wrote the text rather than the change it describes. The harness tells the composing session to end its published text with one, so the author writes it deliberately and reads that compliance as correct. That is how it passes a scan the same author runs.
 
-Removing the link before a merge does not substitute for never writing it. One branch removed it, read the live body back clean, and the squashed commit landed carrying it anyway off an earlier snapshot, which is permanent on the trunk.
+- The session resolves only for the account that started it, so a reader inside this checkout still cannot open it
+- The scoping sits at the invocation site, because `canon labels scan` reads a pull request title and body and no other text
+- Delete a hit rather than rewriting it, since a session has no reachable form and the body above it already stands in its place
+- Removing it before a merge is no substitute for never writing it, since a squash can land it from an earlier snapshot, permanently on the trunk
 
 ## Cross-reference form
 
-A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it, and in backticks where it does not. Both spellings are correct, each in one place, so a reference moved from one destination to the other is rewritten rather than copied.
+A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it and in backticks where it does not, so a reference moved between destinations is rewritten rather than copied.
 
-Text published to a remote is the auto-linking half: a pull request body, an issue body, a comment on either, and a commit message. Write `#123` there, and `owner/repo#123` where the reference crosses repositories, which the same auto-linking reaches. A markdown file browsed from the repository tree is the other half, where neither spelling links and the backticked one marks the number as an identifier. <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy -->
+| Destination                                               | Form                                                                                                                                                         |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Pull request or issue body, a comment on either, a commit | `#123`, or `owner/repo#123` across repositories <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy --> |
+| A markdown file browsed from the repository tree          | the number in backticks, since neither spelling links there                                                                                                  |
+| Content installed into another repository                 | qualified against a different, resolvable repository, or no number                                                                                           |
 
-Content that installs into another repository is the third destination, and it splits on which repository the number names. A skill body loads from a plugin cache and a docs page is read through `canon docs`, so the reader holds their own repository rather than the one a bare number belongs to. Qualifying a number against a different, resolvable repository fixes that, since the reader can open that repository even without this one.
+A commit message takes the bare form even though the log links nothing, since the remote is what the form is chosen for. Text quoted from another surface keeps the spelling it arrived with, since rewriting it reports the source as saying something it never said.
 
-Qualifying it against `erclx/canon` fixes nothing, because a reader holding only the plugin cache or the published package still cannot open this repository's own history. A same-repository citation takes no number here at all, bare or qualified. State the fact the citation was standing in for instead, and where the identifier is the only trace of a one-off incident rather than a reproducible count, carry it into the `canon/context/` entry that owns the surface.
+### Installed content
 
-Write `owner/repo#123` and `owner/repo@abc1234` for a citation of a different, resolvable repository, across every such surface. `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or on the line above.
+A skill body loads from a plugin cache and a docs page is read through `canon docs`, so the reader holds their own repository rather than the one a bare number belongs to.
 
-Choose the number over the sha where the citation names a decided change, since a pull request number resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape a context entry already uses. The choice holds for both spellings this section fixes, the bare form a remote auto-links and the qualified form a cross-repository citation carries.
+- Write `owner/repo#123` and `owner/repo@abc1234` for a different, resolvable repository, which the reader can open without this one
+- Qualifying against `erclx/canon` fixes nothing, since a reader holding the cache or the package still cannot open this repository's history
+- A same-repository citation takes no number, so state the fact it stood in for, and carry a one-off incident's identifier into the `canon/context/` entry owning the surface
+- `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or the line above
 
-A commit message takes the bare form even though it is also read through the log, where nothing links. The remote is what the form is chosen for, since a reader in the log loses only a link that plain text never carried.
+### Number or sha
 
-Text quoted from another surface keeps the spelling it arrived with. A reference inside a quotation belongs to what is being quoted rather than to the text doing the quoting, so rewriting it reports the source as having said something it never said.
+Choose the number where the citation names a decided change, since it resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape a context entry already uses. The choice holds for the bare and the qualified spelling alike.
 
 ## An unreadable source
 
 Stop and name the source when one this scan reaches for cannot be read. Do not scan what resolved and report the result.
 
-A run that covers half its sources and says nothing is worse than one that visibly did not happen, because the surfaces running this scan are the ones that describe themselves as the only gate. A clean result from a half-run scan is read as coverage.
+A half-run scan that says nothing is worse than one that visibly did not happen, because the surfaces running this scan describe themselves as the only gate. Its clean result is read as coverage.

package/claude/skills/git-pr/references/task-number.md

@@ -7,22 +7,34 @@ description: How git-pr writes the pull request number the final command printed
 
 The last step of `git-pr` before its report, reached on every run whose final command printed a number.
 
-Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. A final command that refused on a head mismatch printed no number, so this step writes nothing on that run. `${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.
+Write the `number` the final command printed onto the task the branch is closing, and never resolve it again. A lookup by branch alone can return a closed pull request sharing that head, per `${CLAUDE_SKILL_DIR}/REQUIREMENT.md`. A final command that refused on a head mismatch printed no number, so this step writes nothing on that run.
 
-The task is the one whose `Plan:` line names the plan this branch implemented. Name that plan by its file, which is `.canon/plans/feature-<slug>.md` at the main worktree root with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. `plan-feature` writes the plan under the branch slug, so the two correspond on any branch that came through the plan-to-execute path. When the session already knows which plan it implemented, because a caller read it earlier in the chain, use that filename instead of re-deriving.
+## Name the plan
+
+The task is the one whose `Plan:` line names the plan this branch implemented. That plan is `.canon/plans/feature-<slug>.md` at the main worktree root, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`.
+
+- `plan-feature` writes the plan under the branch slug, so the two correspond on any branch that came through the plan-to-execute path
+- When a caller earlier in the chain already read the plan, use that filename instead of re-deriving
+- The slug is a guess at the plan rather than a fact about the task, so the verb re-checks it against the board and refuses on a near miss
 
 ```bash
 canon tasks pull-request <number> --plan feature-<slug> --json
 ```
 
-The slug is a guess at which plan this branch carries rather than a fact about the task, which is why the verb re-checks it against the board and refuses instead of writing on a near miss. A branch whose slug names no plan file falls to the silent skip below, the same as one whose plan no task cites.
+## What the verb writes
+
+The verb resolves the board at the main worktree root in-process, the root `session-worktree` resolves on entry. It is the route because the write edits an existing main-root file, which `session-worktree` routes through a verb.
+
+- It adds `Pull request: #NNN` under the task's `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines, and corrects the number in place when the line exists
+- A line already reading as a list of `#NNN` entries takes the new number appended, reported as `appended`, so a task shipped in slices keeps every pull request
+- The same write drops this branch from the `Pending branch:` line `canon tasks outcome` wrote, which lets the merge-time archive close the task
 
-The verb resolves the board at the main worktree root in-process, adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already carries, and corrects the number in place when the line exists. This is the route because the write is an edit inside an existing main-root file, which `session-worktree` routes through a verb. That root is the one `session-worktree` resolves on entry.
+## Refusals
 
-The correction reaches only a line that does not read as a list of `#NNN` entries. A line that does takes the new number appended rather than replaced, reported as `appended`, so a task shipped in slices keeps every pull request.
+Skip silently when the record is `ok: false` and `reason` is `no-board`, `no-match`, or `ambiguous`, meaning no board, no task naming the plan, or more than one. A guessed write would compound each, since a wrong match archives the wrong task unattended once the branch merges. Report any other refusal rather than swallowing it.
 
-The same write drops this branch from the task's `Pending branch:` line, which `canon tasks outcome` wrote when the branch ticked an outcome, so this step is what lets the merge-time archive close the task.
+A branch whose slug names no plan file lands on `no-match`, the same as one whose plan no task cites.
 
-Skip this silently when the record is `ok: false` and `reason` is `no-board`, `no-match`, or `ambiguous`. Those are the three cases a guessed write would compound: no board, no task naming the plan, or more than one. One pull request names one task, and a wrong match archives the wrong task unattended once the branch merges. Report any other refusal rather than swallowing it.
+## Why the number
 
-The number is what lets the merge close the task. Every merge on `main` is a squash carrying it in the subject, so the number survives where a branch name does not, and `post-merge` reads it back to call `canon tasks archive`. Writing it here rather than at worktree time is what makes it a pull request number rather than a branch the squash discards.
+Every merge on `main` is a squash carrying the number in its subject, so the number survives where a branch name does not. `post-merge` reads it back to call `canon tasks archive`, which is why this step runs at pull request time rather than at worktree time.

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

@@ -89,7 +89,7 @@ On a `passing` wake, run `canon pr evidence <number> --check --json` against the
 | Any other `reason`, such as `gh-failed` | Stop and report it, since an unread thread is not a settled one                                         |
 | No record, or an unknown flag error     | The binary predates `--check`, so report the thread unread and continue without claiming it was checked |
 
-On `owed`, run the named steps from `canon:git-pr`'s `references/evidence.md`, evidence first and then preview, and re-read with the same command. Continue only on `settled`, and stop on any other reading with the `reason` and the `owed` list, never looping back.
+On `owed`, invoke `canon:pr-evidence` with the number, which runs the evidence step first and then the preview the thread owes, and re-read with the same command. Continue only on `settled`, and stop on any other reading with the `reason` and the `owed` list, never looping back.
 
 A refused preview step or a failed deploy leaves `preview` owed on the re-read, so that is the stop and not a retry. The read is a closing step, so the draft mark stays the only thing between steps 8 and 9, and a caller closing on its own block waits on the same wake.
 

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

@@ -30,7 +30,14 @@ A plan lost to deletion, or carrying two answers to one question, fails both.
 ## Lifecycle
 
 - Write the plan before implementation starts, and treat it as the scope of the run that executes it. A subject that has to be measured before anyone can plan against it takes a measurement track first.
-- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
-- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the suggested-and-answer contract in `plan.md` fixes which line takes it.
-- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down. A flat `.claude/plans-archive/` sibling is the older layout.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
+- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
+
+### Amending and archiving
+
+A plan changes in place and leaves only by a move.
+
+- Amend the plan in place when a decision changes mid-flight, never appending a passage narrating the change, which leaves two answers to reconcile
+- An execution-time deviation from a suggestion is one such amendment, and the suggested-and-answer contract in `plan.md` fixes which line takes it
+- Move the plan to `.canon/plans/archive/` when its work ships or is declined, and never delete it, since it records the rejected alternative
+- A flat `.claude/plans-archive/` sibling is the older layout.