@erclx/canon 5.40.0 → 5.42.0

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

@@ -45,6 +45,8 @@ Does not govern:
 
 ### What a scope may not be
 
+A scope names a component, never a file or the type again.
+
 - Do not use specific filenames as scopes
 - Do not use a scope that duplicates the type
 - Write scopes for release readability. They surface in `changelogithub` release notes.
@@ -57,6 +59,8 @@ Does not govern:
 
 ### Form and quoting
 
+The subject carries the change and nothing around it.
+
 - Do not repeat the scope in the subject line
 - Use single quotes if quoting
 - No backslash escaping or internal double quotes
@@ -71,6 +75,8 @@ Does not govern:
 
 ### Correct
 
+Each line names a specific change in imperative mood.
+
 ```plaintext
 feat(api): add retry logic for failed webhooks       # specific verb + clear change
 fix(auth): update 'UserSession' validation logic     # scoped + imperative + single quotes
@@ -78,6 +84,8 @@ fix(auth): update 'UserSession' validation logic     # scoped + imperative + sin
 
 ### Incorrect
 
+Each line breaks at least one rule above, noted in its comment.
+
 ```plaintext
 fix(user-auth): Fixed the redirect loop.    # wrong casing + period + multi-word scope
 docs(docs): update the readme.              # duplicate scope + period

package/claude/skills/git-commit/references/versioning.md

@@ -19,25 +19,27 @@ Does not govern:
 
 ### Neighboring concerns
 
-- Voice, rhythm, and sentence construction in any text carrying a label: the `write-human` skill
-- Punctuation, formatting, and word choice in any text carrying a label: `markdown.md`
-- How a quoted-alone version-shaped token or a record path is caught as a board reference, which sits outside the phase-label/semver split this file owns: `publish.md`
+Text carrying a label still follows the standards for any text.
+
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Punctuation, formatting, and word choice: `markdown.md`
+- How a quoted-alone version-shaped token or a record path is caught as a board reference: `publish.md`
 
 ## Phase labels
 
 Internal coordination vocabulary used in the task board and chat.
 
-- Format is project-specific.
-- Used to order work and disambiguate streams during planning.
-- Re-numbers freely as scope shifts. Inserting a half-step between two existing labels (a `v1.5` between `v1` and `v2`) is fine. <!-- canon-allow-reference: illustrates the renumbering rule's own format, not a citation of a real row -->
-- Does not have to map to any external release.
+- Format is project-specific
+- Used to order work and disambiguate streams during planning
+- Re-numbers freely as scope shifts, so a half-step such as `v1.5` between `v1` and `v2` is fine <!-- canon-allow-reference: illustrates the label format, not a real row -->
+- Does not have to map to any external release
 
 ## Semver tags
 
 External release identity used in git tags and release notes. Independent of phase labels.
 
-- Format is semver: `v<major>.<minor>.<patch>`.
-- Tagged only when a real release is cut.
+- Format is semver: `v<major>.<minor>.<patch>`
+- Tagged only when a real release is cut
 - Does not have to map to phase labels. A single semver tag may cover work that carried several internal phase labels.
 
 ## Where each appears
@@ -65,17 +67,21 @@ External release identity used in git tags and release notes. Independent of pha
 
 ### Bodies and code spans
 
-- PR bodies, review comments, and issue text name the change itself, never the internal stream that scheduled it. Describe the work rather than the label it was planned under.
-- A phase label written alone inside its own code span reads as shown rather than asserted. `canon labels scan` masks a code span before checking for a bare token, so a backticked label on its own does not count as an appearance for the phase-label check.
-- That masking clears one check and not the gate. A span whose whole content is the label still resolves as a board reference under `publish.md`'s own board-identifier check, run by the same scan, so a title or body quoting a label alone in a span still fails on that check and does not clear every surface the table above marks `no`.
-- The one shape neither check reaches is a version-shaped token folded into a longer quoted phrase, such as a fixture name or a file path. A backticked span quoting a test fixture's own version-shaped name is the corpus case that forced this carve-out, and a real phase label folded the same way inside a review comment is the counterexample where it read as clean on both checks.
-- The operator decided to keep the carve-out rather than narrow it to fenced blocks alone or drop it outright, leaving an author responsible for writing a live reference in plain text instead of folding it into a quoted phrase.
+PR bodies, review comments, and issue text name the change itself, never the internal stream that scheduled it. Describe the work rather than the label it was planned under.
+
+- `canon labels scan` masks a code span before checking for a bare token, so a label alone in its own span clears the phase-label check
+- That span still resolves as a board reference under `publish.md`'s board-identifier check, run by the same scan, so it still fails every surface the table marks `no`
+- Neither check reaches a version-shaped token folded into a longer quoted phrase, such as a fixture name or a file path
+- The operator kept that carve-out, so write a live reference in plain text rather than folding it into a quoted phrase
 
 ### Phase labels in shipped files
 
-- A phase label in a context entry is permitted only when its substance is restated inline beside it. A bare label carrying nothing beside it is forbidden, since a reader without the board has nothing to resolve it against.
-- A phase label carries no exception for a surface this repository authors and ships to a target it does not control: a standard, a skill body, and a governance rule are all forbidden outright, substance restated or not. The line is ownership rather than reachability. A shipped file is read by a project that never edits it, so the label names a board that reader can never reach. A context entry stays permitted above because it is this project's own tracked surface, never shipped.
-- The shipped-surface rule governs a reference to a real row, never a token shown to illustrate the label's own format. A phase label naming no decision, written only to show the pattern's shape, is not a citation, which is what lets a standard defining the format still show what one looks like.
+A phase label in a context entry is permitted only when its substance is restated inline beside it, since a reader without the board has nothing to resolve a bare one against.
+
+- A standard, a skill body, and a governance rule forbid a phase label outright, substance restated or not
+- The line is ownership rather than reachability. A shipped file is read by a project that never edits it, so the label names a board that reader can never reach.
+- A context entry stays permitted because it is this project's own tracked surface, never shipped
+- The rule governs a reference to a real row, never a token shown to illustrate the label's format, which lets a standard defining the format still show one
 
 ## Pre-publish check
 

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

@@ -21,7 +21,7 @@ A fix commit answering a review is the sharpest case of the first paragraph, sin
 - Sync the body when the new commit moves the scope, and the title when the shift makes it inaccurate
 - Reply on the pull request when it carries review comments, and scan that reply for the banned characters and internal phase labels before posting. A hook on `Bash` scans the body file of that post and denies an inline body, so the reply goes through a file.
 - Suppress the reply when the caller owns it, and still run the push and the body sync
-- Read `canon pr evidence <number> --check --json` after posting the evidence and mint the preview when it is owed, since a followup that posts the evidence and stops leaves the preview for a relay
+- Post the evidence through `pr-evidence` and read `canon pr evidence <number> --check --json` after it, since a followup that posts the evidence and stops leaves the preview for a relay
 - Force the push under a lease when the tracking branch no longer reaches the head, so a caller's rebase lands and a commit this session never read is not overwritten
 
 ## Must not

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

@@ -47,12 +47,11 @@ A missing tracking ref is not a guard, since 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. Post the evidence comparison on every invocation, `reply-owned` included, since it is not step 8's reply. Run `canon pr evidence <number> --json` and read `reason` 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 api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md --silent` 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-changes`, `would-empty`). Report it and continue without stopping the chain.
-
-   After an `ok` post, read what the pull request is still owed with `canon pr evidence <number> --check --json`, branching on `reason` and `owed` rather than the exit. When `owed` lists `preview`, mint it through the preview section of `canon:git-pr`'s `references/evidence.md`, then re-read once. Report anything but `settled` after that re-read and continue, since a refused deploy would otherwise loop. A binary lacking `--check` reports the thread unread rather than settled. A preview already on the comment counts as settled whatever head built it, so a later push does not re-mint one.
+5. Invoke `canon:pr-evidence` with `<number>` on every invocation, `reply-owned` included, since it is not step 8's reply.
+   - It edits the marked comment in place, carries the checklist forward, and mints the preview only when the thread still owes one
+   - Report it rather than proceeding silently when the skill does not resolve
+   - Then read `canon pr evidence <number> --check --json` once, branching on `reason` and `owed` rather than the exit
+   - Report anything but `settled` and continue, since a refused deploy would otherwise loop. A binary lacking `--check` reports the thread unread rather than settled.
 
 6. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`.
 7. Sync the body and title on every invocation, before the routing below decides on the reply.

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

@@ -24,13 +24,16 @@ Does not govern:
 ## Title
 
 - Format: `<type>: <subject>`
-- Type is `bug`, `task`, or `feedback`. Lowercase the type and the first word of the subject for `bug` and `task`, both hand-composed. `feedback` is always lowercase. Its subject is derived by the CLI from the report's `### Surface` field verbatim, so the subject alone carries no casing rule.
+- Type is `bug`, `task`, or `feedback`, always lowercase
+- Lowercase the first word of the subject for `bug` and `task`, which are hand-composed
+- A `feedback` subject is copied by the CLI from the report's `### Surface` field verbatim, so it carries no casing rule
 - Length: 72 characters maximum, no trailing period.
 
 ## Labels
 
 - Apply `bug` for a defect and `enhancement` for a task or improvement. Both are GitHub default labels.
-- Apply `feedback` to a report filed through `canon feedback`, which sets the label unconditionally rather than a session choosing it. It is not a GitHub default. Create it once per project with `gh label create feedback`.
+- Apply `feedback` to a report filed through `canon feedback`, which sets the label unconditionally rather than a session choosing it
+- `feedback` is not a GitHub default, so create it once per project with `gh label create feedback`
 - A label that does not exist makes `gh` reject the issue. Create each one once with `gh label create`.
 - One label per issue unless a second genuinely applies.
 
@@ -45,6 +48,8 @@ Does not govern:
 
 ### Bug and task
 
+A bug or task body carries up to four `##` sections, in this order.
+
 - `## Summary`: one line naming what and why.
 - `## Details`: for a bug, what happens versus what is expected. For a task, what to build.
 - `## Context`: for a bug, repro steps or commands. For a task, the driving reason, or `none`.
@@ -52,37 +57,41 @@ Does not govern:
 
 ### Feedback
 
-- One `## Toolkit feedback` wrapper holds every field as a nested `###` heading. A flat `##` field is not recognized.
+One `## Toolkit feedback` wrapper holds every field as a nested `###` heading. A flat `##` field is not recognized.
 
-  | Field                            | Holds                                                                                                                        |
-  | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-  | `### From project` (optional)    | the reporting project's name or kind.                                                                                        |
-  | `### Surface` (required)         | the toolkit surface and its type, and the specific file or name when known.                                                  |
-  | `### Observed` (required)        | the observed behavior.                                                                                                       |
-  | `### Expected` (optional)        | the expected behavior, or `unclear`.                                                                                         |
-  | `### Repro` (optional)           | repro details, or `none`.                                                                                                    |
-  | `### Proposed fix` (required)    | a proposed fix, or `open` when the session settled on no direction.                                                          |
-  | `### Suggested shape` (optional) | the template, output, or field list the change should take, inside a `<details>` block. Omit the heading when there is none. |
-  | `### Why` (optional)             | the reasons for the fix, one bullet each. Omit the heading when there are none.                                              |
-  | `### Links` (optional)           | the issues, pull requests, or documents the report cites, one per line. Omit the heading when there are none.                |
+| Field                            | Holds                                                                                                                        |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `### From project` (optional)    | the reporting project's name or kind.                                                                                        |
+| `### Surface` (required)         | the toolkit surface and its type, and the specific file or name when known.                                                  |
+| `### Observed` (required)        | the observed behavior.                                                                                                       |
+| `### Expected` (optional)        | the expected behavior, or `unclear`.                                                                                         |
+| `### Repro` (optional)           | repro details, or `none`.                                                                                                    |
+| `### Proposed fix` (required)    | a proposed fix, or `open` when the session settled on no direction.                                                          |
+| `### Suggested shape` (optional) | the template, output, or field list the change should take, inside a `<details>` block. Omit the heading when there is none. |
+| `### Why` (optional)             | the reasons for the fix, one bullet each. Omit the heading when there are none.                                              |
+| `### Links` (optional)           | the issues, pull requests, or documents the report cites, one per line. Omit the heading when there are none.                |
 
-- A required field is refused when present but empty. Write the fallback literal for From project, Expected, and Repro rather than leaving one blank.
+A required field is refused when present but empty. Write the fallback literal for From project, Expected, and Repro rather than leaving one blank.
 
 ## Formatting
 
 ### Bug and task
 
+Keep a bug or task body short and uniform.
+
 - End every bullet with a period.
 - Keep each section to one or two lines.
 
 ### Feedback
 
-- A field may run to multiple paragraphs and may hold a fenced code block. The one-or-two-line rule and the trailing-period rule do not apply.
+A feedback field may run to multiple paragraphs and may hold a fenced code block, so the one-or-two-line rule and the trailing-period rule do not apply.
 
 ## Examples
 
 ### Correct (bug)
 
+A bug states observed behavior and the fix, each in a line.
+
 ```markdown
 ## Summary
 
@@ -103,6 +112,8 @@ Pass `--label feedback` through the shared issue helper.
 
 ### Correct (task)
 
+A task states what to build and the reason driving it.
+
 ```markdown
 ## Summary
 
@@ -119,6 +130,8 @@ The toolkit-issue skill only files on the toolkit repo. A general path is needed
 
 ### Incorrect
 
+This summary opens with "This issue", hedges, and names no defect.
+
 ```markdown
 ## Summary
 

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

@@ -28,10 +28,7 @@ A lookup that resolves by head branch alone carries its own failure. A branch na
 - Label from the paths the branch changed, against a map the project declares, so the label set belongs to the project rather than to the skill
 - Apply labels after the pull request exists, so a label the remote does not carry costs a warning rather than the pull request
 - Report a refused label, since a warning nothing surfaces leaves the run indistinguishable from one that labelled
-- Run the evidence verb on every pull request the skill opens, and let its `no-evidence` answer be the skip, since a session cannot see a regenerated image it did not author and a gate asking it to look lets that image ship with no comment
-- Put a preview address on a pull request that changes a rendered surface when the project's deploy can mint one, since screenshots and a checklist leave a reviewer nothing to click into before merging
-- Bound the wait on that preview and finish the chain without the link on a timeout, since a slow deploy must not hold the ship
-- Put the branch's running local server on the same pull request when this worktree is serving one, and remove it when the pull request closes, since a reviewer on the operator's machine can interact with the branch and a link that outlives it points at whatever runs there next
+- End every pull request it opens or edits by invoking `pr-evidence` with the number it resolved, since a pull request changing a rendered surface otherwise reaches review with no screenshots, checklist, or address
 
 ## Must not
 
@@ -41,7 +38,6 @@ A lookup that resolves by head branch alone carries its own failure. A branch na
 - Edit a pull request that is not open, or record its number on a task
 - Name a domain of any one project in the skill body or its references
 - Create a label the map names and the remote lacks
-- Dispatch a deploy whose command names no branch, since Cloudflare Pages publishes such a deploy to production
 - Emit anything after the result line
 
 ## Guards

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

@@ -134,38 +134,27 @@ Read `${CLAUDE_SKILL_DIR}/references/final-command.md` on reaching this step, fo
 
 That command re-scans the live body for a session link, applies the labels through `canon labels apply`, and prints `number=`, `url=`, `head=`, `owed=`, `missingOnRemote=`, and `uncovered=`.
 
-### Post the rendered-surface evidence
-
-Run this step on every pull request this skill opens or edits. Read `${CLAUDE_SKILL_DIR}/references/evidence.md` for finding the checklist and the local server and for posting the evidence comparison, the checklist alone, and the preview address, each against the `<number>` the final command printed.
-
-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.
-
 ### Record the number on the task
 
 Write the `number` the final command printed onto the task the branch is closing, through `canon tasks pull-request`, and never resolve it again. Skip it when the final command refused on a head mismatch and printed no number.
 
 Read `${CLAUDE_SKILL_DIR}/references/task-number.md` on reaching this step for which task it names, the invocation, the refusals it skips silently, and why the number lands here.
 
-## After execution
+### Post the rendered-surface evidence
 
-Respond with `✅ PR: <url>`, using the `url` the final command printed, then add only the lines below whose condition holds. Add no other text.
+Invoke `canon:pr-evidence` with the `<number>` the final command printed, on every pull request this skill opens or edits. Skip it when the final command refused on a head mismatch and printed no number, since that skill must never run against a guessed one.
 
-| Condition                                                 | Line                                                                                                        |
-| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Each path in `uncovered=`                                 | `⚠️ No label covers <path>. Add a row to canon/config/pr-labels.toml or a [declined] entry.`                |
-| `owed=` or `missingOnRemote=` printed a value             | `⚠️ Labels not applied: <owed labels not in missingOnRemote>. Not on the remote: <missingOnRemote labels>.` |
-| 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>`                                                                             |
+It finds the checklist and the local server and posts the evidence comparison, the checklist alone, and the preview address. Report it rather than proceeding silently when the skill does not resolve.
 
-### The labels line
+## After execution
 
-`owed=` already holds every absent label, so the first half names `owed=` less the names in `missingOnRemote=`, and the second names `missingOnRemote=` alone. Drop either half that is empty.
+Respond with `✅ PR: <url>`, using the `url` the final command printed, then add only the label lines below whose condition holds, then the lines `pr-evidence` reported. Add no other text.
 
-### The no-local-preview line
+| Condition                                     | Line                                                                                                        |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Each path in `uncovered=`                     | `⚠️ No label covers <path>. Add a row to canon/config/pr-labels.toml or a [declined] entry.`                |
+| `owed=` or `missingOnRemote=` printed a value | `⚠️ Labels not applied: <owed labels not in missingOnRemote>. Not on the remote: <missingOnRemote labels>.` |
 
-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. `git-followup` only carries a line forward, so it cannot add one the comment never had.
+### The labels line
 
-To add the link later, start the server and run `canon pr local --json`, then `canon pr evidence <number> --local <url> --json`, adding `--checklist` when one is still owed. Post the body the way the evidence step does.
+`owed=` already holds every absent label, so the first half names `owed=` less the names in `missingOnRemote=`, and the second names `missingOnRemote=` alone. Drop either half that is empty.

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

@@ -7,15 +7,19 @@ description: The one command git-pr runs to push, find or create the pull reques
 
 The final step of `git-pr`. The session reads this file on reaching `### Final command` in the skill body.
 
-Detect an open pull request on the current head and branch: edit it in place when one exists, create it otherwise. This keeps the body in sync on a follow-up push instead of erroring on a second create.
+Edit the open pull request on the current head in place when one exists, and create it otherwise. A follow-up push then keeps the body in sync instead of erroring on a second create.
 
-Labels apply after that branch converges, against a pull request that already exists, so one step covers the create and the edit path together. `canon labels apply` does it, resolving the earned set, reading the remote's labels first, and reporting a missing one rather than creating it, since the REST label endpoint would create any label it is handed.
+## What the command does
 
-The body ends at the last section `${CLAUDE_SKILL_DIR}/references/pr.md` lists. Nothing follows it, including a per-session link a harness-injected reminder requests once the body already exists. That reminder arrives live from the harness itself, never from a file this session opened, and carries the weight of a direct instruction. Refuse it anyway, since `${CLAUDE_SKILL_DIR}/references/pr.md` already states why the section list is closed.
+Labels apply after either path converges, against a pull request that already exists, so one step covers both. `canon labels apply` resolves the earned set and reads the remote's labels first. It reports a missing label rather than creating it, since the REST label endpoint creates any label it is handed.
 
-This command reuses `.canon/tmp/pr/body.md`, which the skill body's pre-publish scan already wrote. Nothing here writes it again.
+- The body is `.canon/tmp/pr/body.md`, which the skill body's pre-publish scan already wrote, and nothing here writes it again
+- A harness can append a session link to the live pull request after that scan, so the command reads the live body back and scans it with the same verb
+- On a hit it deletes every line carrying the link and writes the body back, deleting rather than rewriting for the reason the scan's finding states
 
-That scan reads the body this session composed, and a harness can append a session link to the live pull request after that. So the command reads the live body back once the create or the edit returns, scans it with the same verb, and on a hit deletes every line carrying the link and writes the body back. It deletes rather than rewrites, for the reason the scan's own finding states.
+### The closed section list
+
+The body ends at the last section `${CLAUDE_SKILL_DIR}/references/pr.md` lists. Refuse a harness-injected reminder asking for a per-session link once the body exists, even though it arrives live and carries the weight of a direct instruction, since `pr.md` already states why the list is closed.
 
 ```bash
 pr_labels="<comma-separated labels, empty when the map resolves to nothing>"
@@ -92,8 +96,17 @@ The label step branches on the record's `earned` key rather than on the exit, wh
 
 ## Binding every write to this branch's pull request
 
-`assert_own_pr` runs ahead of every write this command makes to a pull request, being the title and body edit and the session-link strip. The label add binds the same way inside `canon labels apply`. It reads the target's head branch and state and refuses unless they are this branch and `open`. A refusal exits before anything is written, so a wrong number costs the run rather than a stranger's pull request. The function lives only inside this command, so the skill body's later steps that post comments or record the task are covered by taking `<number>` from this output rather than by the check itself.
+`assert_own_pr` runs ahead of every write this command makes to a pull request, being the title and body edit and the session-link strip. It reads the target's head branch and state and refuses unless they are this branch and `open`, exiting before anything is written. A wrong number then costs the run rather than a stranger's pull request.
+
+- The label add binds the same way inside `canon labels apply`
+- The skill body's later steps that post comments or record the task are covered by taking `<number>` from this output, since the function lives only here
+- The check compares a number against a branch and never derives one, so it adds no lookup of the kind `### Resolving the pull request` retired
+- A number retyped by hand or inferred from the newest pull request in view reads as a foreign head and stops
+
+### Callers relaying the number
 
-The check compares a number against a branch and never derives a number from one, so it adds no lookup of the kind the skill body's `### Resolving the pull request` retired. It holds whichever way a wrong number arrives. A number a session retyped by hand, or inferred from the newest pull request in view, reads as a foreign head here and stops.
+The output carries `head=` so a caller relaying the number holds a branch to compare it against rather than a bare integer. A caller writing to the pull request itself, such as a draft mark, runs the same comparison in the shell first and refuses unless it matches `head` and `open`.
 
-The output carries `head=` so a caller relaying the number holds a branch to compare it against rather than a bare integer. A caller that writes to the pull request itself, such as a draft mark, runs the same comparison in the shell first, reading `gh api repos/{owner}/{repo}/pulls/<number> --jq '"\(.head.ref) \(.state)"'` and refusing unless it matches `head` and `open`.
+```bash
+gh api repos/{owner}/{repo}/pulls/<number> --jq '"\(.head.ref) \(.state)"'
+```

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