@erclx/canon 5.36.0 → 5.37.0

package/claude/skills/deprecation-migration/SKILL.md

@@ -93,6 +93,9 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 - A deprecation notice names no replacement or no removal date.
 - The diff adds a replacement and deletes the original in the same change.
 - A fallback or compatibility path has no stated condition for its removal.
+
+### Behavior and callers
+
 - You are adding behavior to the surface being deprecated.
 - Your report says "no callers" without naming the caller kinds the search could not reach.
 - A caller outside the repository was found and the plan still deletes the original.
@@ -104,6 +107,9 @@ Check each line against what the change produced. A line answering no is fixed o
 - The surface is deprecated only if it has a stated cost, a shipped replacement, and a named owner.
 - Every compulsory deprecation states its removal date where a caller looks.
 - Every caller reachable in the repository was migrated, or is named with the reason it was not.
+
+### Checks and fallbacks
+
 - The zero-consumers check covered every caller kind, and the report names the kinds it could not reach.
 - No change both adds the replacement and removes the original.
 - Every fallback left in place states when it goes and who removes it.

package/claude/skills/deprecation-migration/references/adopted.md

@@ -27,6 +27,9 @@ External sources were read and filtered rather than imported. This file is the r
 - The five-question deprecation decision, cut to four. Its unique-value and maintenance-cost questions merge into one question about what keeping the surface costs. Its per-consumer migration-cost question drops, since the Churn Rule puts that cost on the owner rather than weighing it per caller. The owner question from the book takes the freed place.
 - The rule never to deprecate without a replacement, as the third decision question.
 - The strangler and adapter patterns, stated as when each fits rather than as worked code tied to one stack.
+
+#### Migration, zombie code, and red flags
+
 - Expand, migrate, contract, lifted out of its schema section and stated for any surface as three separate changes.
 - Zombie code, narrowed to code that is unowned, uncalled, and still built, and settled by the same zero-consumers check rather than a list of staleness signals.
 - The rationalizations and red flags that carry across stacks, reworded for any surface rather than a service or a column. Two excuse rows come from here:

package/claude/skills/design-taste/SKILL.md

@@ -22,6 +22,9 @@ This is what the population average looks like. Each one is what gets drawn when
 - A violet-to-blue gradient used as the accent.
 - Numbered labels above sections: `001 / Capabilities`, `Phase 02`, `Step 1`.
 - A scroll cue at the bottom of the first screen.
+
+### Details and copy
+
 - A colored dot before every navigation item, row or badge.
 - A glow standing in for elevation, on a pure black or pure white ground.
 - A product screenshot built out of styled rectangles.
@@ -144,6 +147,9 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 - Focus, keyboard, ARIA, alt text, and every accessibility floor: the `ui` governance rules, which fire on the same paths this skill does and are the single source
 - States, empty and loading coverage, destructive confirmation, truncation: the same rules
 - Rendered copy casing, button labels, error message shape: the same rules
+
+### Other skills
+
 - The candidate loop, the arm set, the render, and the pick: `draft-and-pick`
 - The shape of the project's design document and where its values live: `${CLAUDE_SKILL_DIR}/../canvas-board/references/design.md`
 - Reading source for roughness: `ux-audit`. Measuring what a running interface costs to paint: `ux-measure`

package/claude/skills/design-taste/references/craft.md

@@ -53,6 +53,9 @@ Reaching for size is the first instinct and the weakest tool.
 - A link or action that goes nowhere.
 - Navigation with no indication of where the reader currently is.
 - The same portrait used for several different people.
+
+### Content and copy
+
 - Every item dated identically, which no real collection ever is.
 - An exclamation mark in a success message. Confidence is quieter than that.
 - An error opening on an apology rather than on what to do next.

package/claude/skills/design-taste/references/preflight.md

@@ -26,10 +26,15 @@ Skip nothing on the ground that it is obviously fine. A rule is on this list bec
 
 ## Composition
 
+### Section rhythm
+
 - [ ] No layout family used twice. Eight sections carry at least four families
 - [ ] No three consecutive sections sharing the image-and-text split
 - [ ] Small uppercase labels above headings number no more than one per three sections, per `interface-casing`
 - [ ] At most one horizontal marquee
+
+### Content and first screen
+
 - [ ] Grid cells equal content items, with no blank tile filling a gap
 - [ ] Lists over five items use something other than a longer list
 - [ ] The first screen carries the point and the primary action without scrolling
@@ -39,9 +44,14 @@ Skip nothing on the ground that it is obviously fine. A rule is on this list bec
 
 Skip this group where the surface draws on a system already settled.
 
+### Space and type
+
 - [ ] Every gap comes from one scale, and the distinct spacing values number under about eight
 - [ ] Space between groups exceeds space within them
 - [ ] The type scale carries five to seven steps, each visibly different from its neighbors
+
+### Color
+
 - [ ] The accent is rare enough to read as an accent
 - [ ] Neutrals sit in one family at one temperature
 - [ ] Adjacent surfaces separate by a little and content separates from ground by a lot
@@ -51,6 +61,9 @@ Skip this group where the surface draws on a system already settled.
 
 - [ ] Shared elements align across every item in a row, and actions form one line
 - [ ] Nothing centered by arithmetic that reads off-center
+
+### Type detail
+
 - [ ] No orphaned word closing a heading
 - [ ] Body text measure is capped
 - [ ] Changing numbers set in tabular figures
@@ -61,6 +74,9 @@ Skip this group where the surface draws on a system already settled.
 - [ ] Every visible string re-read in one pass, with anything broken, unclear or performatively clever rewritten
 - [ ] Every number either real, labeled as sample, or removed
 - [ ] No placeholder that reads as placeholder: generic names, generic company names, reused portraits, identical dates
+
+### Wording
+
 - [ ] No filler verbs
 - [ ] Sentence case throughout, with exceptions per `interface-casing`
 - [ ] Every claim about what the product does is a thing it does

package/claude/skills/docs-sync/references/docs.md

@@ -48,6 +48,9 @@ A page failing these is non-conforming even when it satisfies every shape rule b
 - `title` (required): sentence case, naming the surface the page covers rather than the action a reader takes on it
 - `description` (required): one line naming what the page covers, which is what the folder's catalog shows beside the link
 - `category` (conditional): the shelf the page sits on in that catalog
+
+### Declaring category
+
 - Declare `category` on every page in a folder where any page declares one. A grouped catalog writes the declared shelves and nothing else, so a page omitting the field beside a sibling that carries one is absent from the catalog with nothing reporting it.
 - Omit it on every page or on none. A folder where no page declares one lists flat, which is the right shape for a folder whose pages need no shelves.
 - Spell one shelf's value identically on every page sitting there. The grouping reads the literal string, so a second spelling opens a second shelf holding one page.
@@ -65,6 +68,9 @@ A page failing these is non-conforming even when it satisfies every shape rule b
 - Write for a reader with no access to the source. A sentence that resolves only by opening a file belongs in internal narrative instead.
 - Name the failures a surface produces alongside the path that works. A page documenting success alone sends its reader to the source at the first refusal.
 - Link to the adjacent page rather than restating it. One page owns each surface, and a second copy drifts with nothing comparing the two.
+
+### What to leave out
+
 - Do not restate output a command already prints, such as a full flag table. Name the command that prints it.
 - Do not carry the history of how a surface reached its shape. A page describes the surface as it stands, and the change that moved it is recorded wherever the project tracks work.
 - Do not carry contributor setup or the argument for adopting the project. Both are addressed to a reader who has not installed anything yet.

package/claude/skills/docs-sync/references/readme.md

@@ -51,10 +51,16 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 
 - Required: project description, installation/setup, usage examples, support/help resources
 - Optional: the header block below, features, contributing (link to `CONTRIBUTING.md`), license (link to `LICENSE`)
+
+### Leave out
+
 - Do not include full API documentation. Link to separate docs instead.
 - Do not include license text. Reference the `LICENSE` file.
 - Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
 - Do not include extensive troubleshooting guides. Use a wiki or separate documentation.
+
+### Routing and generator output
+
 - A README that points to the project's own context entries instead of restating them satisfies the required list by routing rather than carrying. A repository documented in `docs/` or `canon/context/` names the entry point and the listing command, then stops. The reader is one hop away, the same way `## Badges` treats zero as complete.
 - A README missing an H1, or whose headings restate the tool that scaffolded it rather than the project, is unedited generator output rather than a page anyone wrote. Draft over it. Nothing here asks a session to preserve a section a scaffold wrote and nobody replaced.
 
@@ -74,6 +80,9 @@ The description of 2-3 sentences follows the block and expands the claim rather
 - A project with no page omits the link and the screenshot. A library or a CLI reads as a complete block with a title, badges, and a claim.
 - A project whose own page carries the screenshot omits it here and keeps the live link, which answers the slot rather than skipping it. Say so in the pull request that drops it.
 - The order is the block's rather than the page's. The screenshot sits last inside the block, which puts it in the first row of content a reader meets below the title, badges, and claim.
+
+#### Themes and wrappers
+
 - A themed light and dark pair counts as one element in the slot rather than two. The block does not require a pair and leaves the handling of themes to the project.
 - Centering the block in an HTML wrapper is optional. Plain markdown reaches every host a README renders on, and a wrapper is styling a project can add.
 - Never invent an element. A mark or a screenshot the project does not hold stays out of the page.
@@ -91,6 +100,9 @@ Stars, forks, download counts, language chips, and "made with" badges fail. The
 - Cap the block at four. A fifth costs more scanning than any badge repays.
 - Give each badge alt text naming what it reports rather than the service that renders it. Write `npm version`, not `shields.io`.
 - Link each badge to the page a doubting reader would check next, which is the registry listing for a version badge and the run history for a status badge. A red badge with no route to the failing run reports a problem and withholds the only thing the reader wants.
+
+#### Pinning and verifying
+
 - Pin a status badge to the branch whose health it claims to report, and confirm the workflow actually runs on that branch. A workflow triggered by pull requests alone never runs on the default branch, so an unpinned badge reports whichever branch ran last and a pinned one reports nothing at all. Fix the trigger, or drop the badge under the rule below.
 - Verify a badge by the value it renders, not by its status code. A badge service answers 200 for a query it cannot satisfy, so a blank badge and a working one look identical to a status check.
 - Zero badges is a correct answer. A private project with no registry presence and no CI has nothing that passes the test, and an empty block beats a padded one.
@@ -100,6 +112,9 @@ Stars, forks, download counts, language chips, and "made with" badges fail. The
 - Open public-facing READMEs with universal problems any reader recognizes, not repo-specific artifact names. Save artifact names for feature or "What is inside" sections.
 - Use relative paths for repository files. Use absolute URLs for external resources.
 - Include practical usage snippets for core functionality
+
+### Per project kind
+
 - For libraries/tools: include API quickstart
 - For applications/products: include usage instructions and configuration options
 - For CLI tools: include command examples with flags

package/claude/skills/draft-and-pick/SKILL.md

@@ -41,6 +41,9 @@ Every arm of a round sits as one frame on one canvas page, side by side. The com
 - Label each arm inside its frame with its id and its cost. The composite capture draws no captions, so the label is how the render carries what the question will ask about.
 - Theme every arm off the `data-theme` attribute the canvas sets on each frame's root, so the canvas theme toggle sets the whole set at once. A set spanning both themes cannot be compared, since the operator has to hold one arm in memory while reading the next.
 - Give no arm a script that stores a theme and reapplies it on load. That script overwrites the toggle, shows one frame in the other theme, and passes a fresh browser profile because the stored value is not there yet.
+
+#### Default path and live app
+
 - Take the live-app branch instead when the surface under decision is a running app: lift the rendered markup and link a copy of the built stylesheet rather than inlining, per `${CLAUDE_SKILL_DIR}/references/live-arms.md`.
 - On the default path, inline every style, script, and asset the frame needs. A frame resolves nothing outside its own page folder, so one reaching for a build step or a network font renders without it and the arms differ by something nobody chose.
 - On the default path, name a real font first in the stack, one the machine has or the frame embeds, such as the project's own family from its design tokens. A generic keyword such as `system-ui` or `sans-serif` is refused, since it resolves to a different font on each machine. The capture refuses a frame that would rewrap against a substitute rather than shipping a false comparison, so a frame naming no font at all is refused on whatever the default resolves to.
@@ -63,6 +66,9 @@ canon canvas capture <page> --composite --json
 - Read the PNG's `path` off the record. The composite shows every frame in its default theme, so look at the other theme on the live canvas where the arms carry two.
 - `canon canvas capture` needs a browser binary the toolkit does not install. When it refuses for that reason, report the refusal and name `bunx playwright install chromium` as the repair, stop the canvas server if this run started it, then stop rather than describing an arm nobody has seen.
 - A capture refusing on a font names the family it read off the frame's text. Take the repair `canon:canvas-board` Step 6 gives and capture again.
+
+### Handing over
+
 - Hand over the address rather than a description. Emit the canvas link first on its own line, naming the page, then the PNG path on its own line. A still answers how a thing looks and answers none of a hover response, a scroll-linked position, or a pace, which the live frame does.
 - Never report a visual result you have not looked at. A claim about appearance with no render behind it is a guess.
 - Look to judge rather than to confirm. Reading the image back to check it rendered satisfies the rule above and still hands over weak work, so name the weakest thing on the page in a sentence. Where that sentence would embarrass the work, fix it and hand over the second version. Say the remaining weakness out loud either way, so the operator is not hunting for what you already know.
@@ -75,6 +81,9 @@ Put the choice to the operator through the structured question surface, since a
 - One option per arm, labeled with the arm's id and carrying its cost as the description.
 - Rank the recommendation first and mark it `(Recommended)`.
 - Author the real arms only. The surface appends its own escapes for a free-text answer and for reopening the question, so writing either as an option ships a duplicate the tool rejects.
+
+### Taking the answer
+
 - Take no pick on the operator's behalf when two arms are both defensible and the difference is taste. That call is theirs, and a silent one is the failure this skill exists to prevent.
 - Read `canon canvas selection --json` when the answer points at the canvas rather than naming an arm, such as "the selected one". Resolve it against the record's `page` as well as its `frame`, since every round names its arms `arm-<id>` from the same ids. A selected frame on the current round's page is the pick. One on an earlier round's page picks that round's arm, which is a revert, so name the round back to the operator before acting on it. A fresh element inside a picked frame is a correction Step 5 carries by its `index`.
 - Treat `selection: null`, a frame on a page this run did not add, or an element carrying `stale: true` as no answer, and ask again rather than guessing.
@@ -118,6 +127,9 @@ Cite these rather than restating them. A step reimplemented here rots against th
 - `plan-feature` plans the work once the pick is made, and declares the pull request boundary that plan carries
 - `design-taste` carries the layer catalog, the ordering, grey-boxing, and the defaults an arm should reach past
 - `write-human` carries the voice for any copy an arm puts in front of a reader
+
+### Git and review
+
 - `git-stage`, `git-pr`, and `git-followup` carry the commits and the pull request
 - `review-pr` and `review-address` run the review pass
 - `canon:canvas-board` carries the canvas start-and-check sequence, the main-root write route for a frame, and the selection and capture refusals

package/claude/skills/draft-doc/references/context.md

@@ -24,7 +24,7 @@ A project the surface move has not reached keeps its context folder under `.clau
 
 - Read the domain's own folders and files well enough to answer the standard's three questions: where things live, why they are that way, and how to add one more of what the domain holds.
 - Draft `title` and `description` frontmatter, then `## Overview`, `## Layout` (folder ownership lines only, never a file-by-file list), and `## Decisions` or `## Gotchas` wherever the domain's history supplies a non-obvious choice or a workaround worth preserving.
-- Keep the standard's ordering: `Overview`, `Layout`, `Decisions`, `Gotchas`, then anything else.
+- Keep the standard's closed set and order: `Overview`, `Layout`, `Decisions`, `Gotchas`. A topic of the domain's own is an H3 under one of them, per `context.md` in the `context-fold` skill's references.
 
 ## Write
 

package/claude/skills/draft-doc/references/readme.md

@@ -65,6 +65,9 @@ Between agent-facing and plugin alone, a repository with no plugin manifest take
 - Open the page with the standard's header block, filling each slot from what Detect found: mark, title, badges, a one-line claim from the manifest description, the live link, then the product screenshot.
 - Fill the screenshot slot only with an image the project already commits, referenced with alt text naming what it depicts. This kind cannot capture one. Omit the slot when no such image exists and say so in the preview. Never write a placeholder path or invent a mark.
 - Omit the link and the screenshot for a project with no page, and the mark for a project with none, without a note in the drafted page. A project with a page and no known URL gets the screenshot slot, and the Confirm step asks for the link.
+
+### Types and badges
+
 - Cover every applicable project type from the standard's `## Content` list rather than picking the closest one.
 - Candidate badges: check for a published package (a registry field in the manifest), a CI workflow, and a `LICENSE` file.
 - State each candidate's rendered value in the preview rather than trusting a fetch's status code, since a badge service answers 200 for a query it cannot satisfy.

package/claude/skills/draft-figure/references/mermaid.md

@@ -34,8 +34,14 @@ A diagram failing these is non-conforming even when it satisfies every shape rul
 - Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction whenever that subgraph links outward, and an architecture diagram links across its subgraphs as the normal case, so top-bottom is a declaration rather than a guarantee.
 - Restructure a diagram that renders diagonal or left-to-right. Repeating the direction keyword does not fix it.
 - Render a context, component, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
+
+### Rows and edges
+
 - Do not let independent nodes render in a row. A row of siblings reads as a sequential chain and asserts a pipeline the system does not have.
 - Do not converge many edges on one node from one side. A crossing bundle is unreadable whatever it encodes.
+
+### Labels and subgraphs
+
 - Keep node labels short. Three or four words max. Detail goes in the paragraph below the diagram.
 - Use `<br/>` for a second short line on a node when the label is two ideas, never for a sentence.
 - Subgraphs are for grouping unrelated lanes such as offline versus online or browser versus server. Do not subgraph a single linear flow.

package/claude/skills/draft-slides/SKILL.md

@@ -41,6 +41,9 @@ The render injects the project's token stylesheet ahead of each slide's own styl
 - Use the project's custom properties, such as `var(--color-accent)`, for every color, face, and spacing value the stylesheet defines. Read the names from `.claude/design/base.css` and any overrides under `.claude/design/project/`. When neither exists, say the deck renders unstyled rather than inventing values to cover it.
 - Leave the `--color-*` roles to the stylesheet rather than redefining them in a slide. The master reads its colors off the first slide's `<html>`, and a slide body computing its own `--color-text` is reported, since the bands keep the master's colors.
 - Vary the composition across slides. Never repeat a title over bullets on every slide. Reach for columns, a row of large numbers, a grid of cards, a chart, a pull quote, and section dividers.
+
+### Fit and shapes
+
 - Keep titles short and lines tight, so text fits its box at the size the design sets rather than overflowing the frame.
 - Never write centered body text.
 - Prefer CSS the converter maps to native shapes. An element computing a property it cannot map is drawn as a picture of itself and reported on stderr, so a slide full of gradients and filters stops being editable.

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

@@ -22,6 +22,9 @@ Does not govern:
 - Length: 50 characters maximum
 - Casing: kebab-case only, no underscores or camelCase
 - Description: 2 words maximum, up to 4 only when genuinely needed for specificity
+
+### Description content
+
 - Capture the core change, not the commit message verbatim
 - For branches with multiple commits, use the unifying concern as the description.
 - Do not duplicate type in description (e.g., `feat/feature-login`)
@@ -30,17 +33,19 @@ The upper bound reads 4 rather than 3 for every branch, whoever named it. It was
 
 ## Types
 
-- `feat`: new feature or capability
-- `fix`: bug fix
-- `refactor`: structural changes (not a fix or feature)
-- `docs`: documentation only (README)
-- `chore`: maintenance tasks (deps, tooling, configs)
-- `perf`: performance improvements
-- `test`: add or modify tests
-- `style`: code formatting (whitespace, semicolons)
-- `build`: build system changes (webpack, npm scripts)
-- `ci`: CI/CD pipeline changes (GitHub Actions)
-- `revert`: revert a previous commit
+| Type       | Use                                         |
+| ---------- | ------------------------------------------- |
+| `feat`     | new feature or capability                   |
+| `fix`      | bug fix                                     |
+| `refactor` | structural changes (not a fix or feature)   |
+| `docs`     | documentation only (README)                 |
+| `chore`    | maintenance tasks (deps, tooling, configs)  |
+| `perf`     | performance improvements                    |
+| `test`     | add or modify tests                         |
+| `style`    | code formatting (whitespace, semicolons)    |
+| `build`    | build system changes (webpack, npm scripts) |
+| `ci`       | CI/CD pipeline changes (GitHub Actions)     |
+| `revert`   | revert a previous commit                    |
 
 ## Examples
 

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

@@ -23,23 +23,28 @@ Does not govern:
 
 ## Types
 
-- `feat`: new feature or capability
-- `fix`: bug fix
-- `refactor`: structural changes (not a fix or feature)
-- `docs`: documentation only (README)
-- `chore`: maintenance tasks (deps, tooling, configs)
-- `perf`: performance improvements
-- `test`: add or modify tests
-- `style`: code formatting (whitespace, semicolons)
-- `build`: build system changes (webpack, npm scripts)
-- `ci`: CI/CD pipeline changes (GitHub Actions)
-- `revert`: revert a previous commit
+| Type       | Use                                         |
+| ---------- | ------------------------------------------- |
+| `feat`     | new feature or capability                   |
+| `fix`      | bug fix                                     |
+| `refactor` | structural changes (not a fix or feature)   |
+| `docs`     | documentation only (README)                 |
+| `chore`    | maintenance tasks (deps, tooling, configs)  |
+| `perf`     | performance improvements                    |
+| `test`     | add or modify tests                         |
+| `style`    | code formatting (whitespace, semicolons)    |
+| `build`    | build system changes (webpack, npm scripts) |
+| `ci`       | CI/CD pipeline changes (GitHub Actions)     |
+| `revert`   | revert a previous commit                    |
 
 ## Scope vocabulary
 
 - Single lowercase word representing a system component
 - Prefer single word
 - Use kebab-case only when two words are genuinely needed for specificity
+
+### What a scope may not be
+
 - 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.
@@ -49,6 +54,9 @@ Does not govern:
 - Use imperative mood (`add` not `added`)
 - Describe the actual technical change, not that something changed
 - Do not use vague verbs (`improve`, `refine`, `enhance`)
+
+### Form and quoting
+
 - Do not repeat the scope in the subject line
 - Use single quotes if quoting
 - No backslash escaping or internal double quotes

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

@@ -16,6 +16,9 @@ Does not govern:
 - The format of a phase label, which is project-specific by the rule below
 - Task filenames and folder layout: `tasks.md`
 - Commit subject, branch name, and pull request title format: `commit.md`, `branch.md`, and `pr.md`
+
+### 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`
@@ -59,11 +62,17 @@ External release identity used in git tags and release notes. Independent of pha
 - Commit subjects do not embed phase labels.
 - Git tags use semver only. Phase labels never become tags.
 - A PR that cuts a release may reference its semver tag in the title or body. Phase labels still do not appear.
+
+### 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.
+
+### 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.

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

@@ -53,15 +53,18 @@ Does not govern:
 ### Feedback
 
 - One `## Toolkit feedback` wrapper holds every field as a nested `###` heading. A flat `##` field is not recognized.
-- `### 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.
 
 ## Formatting

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

@@ -14,6 +14,11 @@ Read these files in parallel:
 - `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`: branch format, valid types, and constraints
 - `${CLAUDE_SKILL_DIR}/references/pr.md`: structure, rules, and banned phrases
 - `${CLAUDE_SKILL_DIR}/references/labels.md`: label map format, matching, and the missing-label warning. Skip when the project has no `canon/config/pr-labels.toml` and no `.claude/canon/pr-labels.toml`.
+
+### Writing standards
+
+Read these in the same pass:
+
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for all generated text
 - The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 - `${CLAUDE_SKILL_DIR}/../git-commit/references/versioning.md`: phase label vs semver discipline

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

@@ -21,12 +21,12 @@ Governs a pull request title and body: their format and the sections the body ca
 
 Does not govern:
 
-- Commit subject format, which shares the title form: `commit.md`
-- Branch naming: `branch.md`
-- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
-- Whether a quoted label, a gitignored record path, or a link to one Claude Code session may appear in a title or body, which `canon labels scan` fails on: `publish.md`
-- Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
-- Punctuation and formatting in pull request prose: `markdown.md`
+- **`commit.md`**: commit subject format, which shares the title form
+- **`branch.md`**: branch naming
+- **`versioning.md`**: whether a phase label or a semver tag may appear in a title or body
+- **`publish.md`**: whether a quoted label, a gitignored record path, or a link to one Claude Code session may appear in a title or body, which `canon labels scan` fails on
+- **the `write-human` skill**: voice, rhythm, and sentence construction in pull request prose
+- **`markdown.md`**: punctuation and formatting in pull request prose
 
 ## Title
 
@@ -39,6 +39,9 @@ Does not govern:
 - Use imperative mood for all content (`add`, `fix`, `refactor`)
 - Do not start with "This PR," "This commit," "Included are," or "I have"
 - Do not use buzzwords (`seamless`, `robust`, `game-changer`, `enhanced`)
+
+### What to leave out
+
 - 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)
@@ -48,12 +51,21 @@ Does not govern:
 
 - `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
 - `## Key changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
+
+### Context section
+
 - `## Technical context` (optional): 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
 - 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
 - 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.
@@ -64,10 +76,16 @@ Does not govern:
 - 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.
+
+### 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.
+
+### Live sessions and reviewer requests
+
 - 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.
 

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

@@ -54,6 +54,9 @@ On the wake, branch on the final record's fields rather than on the exit:
 - `state: passing`: read the evidence thread under `### Settling the evidence thread` below, then continue to After completion on `settled`.
 - `state: failing`: stop the sequence and report the failing check with its URL.
 - `conflicted: true`: stop the sequence and report that the branch conflicts with its base, since no run will start for it. A rebase is the repair.
+
+#### Refused and unsettled reads
+
 - A `reason` and no `state`: the read was refused, such as `no-remote-branch` for a branch deleted on the remote. Stop and report that `reason`. A missing `state` is never a pass.
 - The command hit its timeout and printed no final record: report CI unsettled after 60 minutes, and emit no `✅ Shipped`.
 - The `gh pr checks --watch` fallback ran, which prints a check table rather than a record. Only a printed table carrying at least one check, every one passing, continues to After completion. Any failing check stops the sequence naming it with its URL. Empty or errored output stops the sequence and reports the message, since `no checks reported on the '<branch>' branch` is what a conflicted branch prints, and that fallback has no `conflicted` field to separate it from lag.

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

@@ -36,9 +36,15 @@ Run these commands in parallel to gather git context:
 - Group commits by concern using both commit messages and file paths.
 - Prefer fewer branches: combine related commits into one branch.
 - Only split into separate branches when concerns are clearly independent.
+
+### Primary concern
+
 - Identify the primary concern of the current branch. Rename it using `git branch -m` if the current name does not already match. Skip the rename if it already matches. Secondary concerns are extracted as new focused branches via cherry-pick.
 - If no single concern dominates (dumping-ground branch with no clear primary), split all commits into new focused branches and add `git branch -d <current>` to delete the original.
 - Propose one new branch per secondary concern following branch.md format.
+
+### Independent and stacked
+
 - Classify groups as independent or stacked before generating commands.
 - Independent groups: each group's commits apply to `main` without the others. Base every branch on `main`.
 - Stacked groups: groups are ordered and each depends on the commits before it. Base each branch on the previous group's branch. Cherry-pick only that group's commits onto it. The base branch already carries all prior commits.

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

@@ -31,6 +31,9 @@ Run these commands in parallel to gather git context:
 - Group files by shared concern. A group is a single commit.
 - Files belong together when they implement or modify the same logical unit.
 - A file that clearly stands alone is its own group.
+
+### Order and commands
+
 - Order commits by dependency: commit dependencies before the files that import them.
 - Prefix the full command sequence with `git restore --staged .` to unstage everything, then stage and commit each group in order.
 - For `D` status files, use `git rm <file>`. For `A` or `M` files, use `git add <file>`.

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

@@ -83,12 +83,12 @@ If Enumeration marked the roster unreadable, stop: `❌ Session roster unreadabl
 
 From the enumeration, include a worktree in the remove set when all hold:
 
-- Not the main row.
-- Not the current session's worktree.
-- Not occupied by a live session.
-- Not a `foreign` tree.
-- State is `merged` or `merged (local)`.
-- Working tree is clean.
+1. Not the main row.
+2. Not the current session's worktree.
+3. Not occupied by a live session.
+4. Not a `foreign` tree.
+5. State is `merged` or `merged (local)`.
+6. Working tree is clean.
 
 Every other non-main row goes to the skip set with a one-word reason, the first that applies in this order: `current`, `occupied`, `foreign`, `dirty`, `open`, `closed`, `unmerged`. A `foreign` tree that is also dirty reports `foreign`, since `dirty` is a state the operator can clear and `foreign` is not. Leading with the transient reason invites a commit or stash that changes nothing, after which the row reports `foreign` and holds back anyway.