@erclx/canon 5.38.0 → 5.39.0

package/claude/skills/git-worktree/references/cleanup.md

@@ -0,0 +1,55 @@
+---
+title: Worktree cleanup
+description: Which enumerated worktrees git-worktree cleanup removes, the skip reasons and their order, the preview, and the final command
+---
+
+# Worktree cleanup
+
+Applies to `git-worktree` in `cleanup` mode, after the enumeration has run and the roster read cleanly. The roster stop stays in the skill body.
+
+## The remove set
+
+Include a worktree when every test holds:
+
+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.
+
+### The skip set
+
+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 the operator can clear `dirty` and cannot clear `foreign`. Leading with the transient reason invites a commit or stash that changes nothing.
+
+## Preview
+
+```plaintext
+**Removing:** <count>
+
+| Path | Branch | PR |
+| ---- | ------ | -- |
+
+**Skipping:** <count>
+
+| Path | Branch | Reason |
+| ---- | ------ | ------ |
+```
+
+If the remove set is empty, stop with `❌ Nothing to remove. All linked worktrees are current, dirty, unmerged, or foreign.`
+
+## Final command
+
+After the preview, execute immediately without waiting for user input, since Claude Code's tool permission dialog is the confirmation gate.
+
+```bash
+git -C <MAIN_ROOT> worktree remove <path1> \
+  && git -C <MAIN_ROOT> branch -D <branch1> \
+  && git -C <MAIN_ROOT> worktree remove <path2> \
+  && git -C <MAIN_ROOT> branch -D <branch2> \
+  && git -C <MAIN_ROOT> worktree prune
+```
+
+Chain one `worktree remove` + `branch -D` pair per row in the remove set, then a single `worktree prune` at the end.

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

@@ -1,6 +1,6 @@
 ---
 name: markdown-craft
-description: Carries the format and structure rules for markdown, being headings, paragraph and list shape, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording, and runs the audit after an edit. Use before a substantial markdown edit, when writing a README, a doc, a skill body, or any `.md` file, or when asked "what are the markdown rules" or "which characters are banned". Do NOT use for voice, rhythm, or word choice, which is `write-human`, or for a Mermaid fence or figure, which is `draft-figure`.
+description: Carries the format and structure rules for markdown, being headings, the density limits, paragraph and list shape, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording, and runs the audit after an edit. Use before a substantial markdown edit, when writing a README, a doc, a skill body, or any `.md` file, or when asked "what are the markdown rules" or "which characters are banned". Do NOT use for voice, rhythm, or word choice, which is `write-human`, or for a Mermaid fence or figure, which is `draft-figure`.
 metadata:
   family: answer
 ---
@@ -9,7 +9,7 @@ metadata:
 
 Read `${CLAUDE_SKILL_DIR}/references/markdown.md` before a substantial markdown edit. Every rule in it is a fact a scan can settle, so do not work the banned characters from memory.
 
-Run `canon markdown audit <path>` after the edit. Rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+Run `canon markdown audit <path>` after the edit, and fix every ban and density finding it reports before moving on. Rewrite the sentence carrying a ban hit rather than swapping the token for a near-synonym, and fix a density finding by its shape rather than trimming characters.
 
 ## Routes
 

package/claude/skills/markdown-craft/references/markdown.md

@@ -1,6 +1,6 @@
 ---
 title: Markdown reference
-description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
+description: Headings, density limits, paragraph and list shape, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
 ---
 
 # Markdown reference
@@ -11,7 +11,7 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 
 - [Scope](#scope)
 - [Headings](#headings)
-- [Paragraphs and lists](#paragraphs-and-lists)
+- [Density](#density)
 - [Code and identifiers](#code-and-identifiers)
 - [Dates](#dates)
 - [Punctuation](#punctuation)
@@ -23,63 +23,99 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 
 ## Scope
 
-Governs what a check can decide about a markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, file references, the spelling convention, what prose may claim about its sources, and the wording of a catalog title and description. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because these rules are written across every document and have no shape of their own.
+Governs what a check can decide about a markdown file, being headings, density, paragraph and list shape, code spans and fences, the date form, punctuation, emphasis, file references, spelling, what prose may claim about its sources, and the wording of a catalog title and description.
 
-The two frontmatter fields it reaches are `title` and `description`. They are named here rather than in the statement above, since a backticked token in a scope statement's first sentence is published as the standard's jurisdiction.
+It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets. It carries no template, since these rules run across every document and have no shape of their own.
 
-The split with the voice guidance is what reads the rule rather than what the rule covers. The character bans ship as data `canon markdown audit` and the installed audit hook both read, so a violation is measured on every run. Word choice, cadence, rhythm, and information density are judgments a reader settles, and those travel in the `canon:write-human` skill, which a markdown edit routes to.
+- The two frontmatter fields it reaches are `title` and `description`, named here since a backticked token in a scope statement's first sentence is published as its jurisdiction
+- The character bans ship as data that `canon markdown audit` and the installed audit hook both read, so every run measures a violation
 
 Does not govern:
 
-- Voice, rhythm, sentence construction, and information density, which the `write-human` skill carries
-- What sections a document has, or what belongs in each: the standard for that document type
-- Which frontmatter fields a document carries, which is that standard's own subject. This file governs the wording of a `title` and a `description` and nothing else about them.
+- Voice, rhythm, sentence construction, and word choice, which the `canon:write-human` skill carries and a markdown edit routes to
+- What sections a document has, or what belongs in each, which the standard for that document type sets
+- Which frontmatter fields a document carries, which is that standard's subject
 - The text inside a fenced block, which follows the conventions of its own language rather than these
-- Phase-label and semver discipline, which is `versioning.md`. The scan that applies these bans to finished text on its way out, and whether a pull request or issue number is backticked, which turns on where the text is published rather than on the text, are `publish.md`.
+- Phase-label and semver discipline, which is `versioning.md`, and the outbound ban scan and issue-number backticks, which turn on where text is published and are `publish.md`
 
 ## Headings
 
-- H1 for document title, H2 for main sections, H3 for subsections
-- Use sentence case for all headings (H1, H2, H3). The audit reports a heading or a frontmatter `title` with a capitalized word after the first, and a proper noun it reports stays as it is.
-- Proper nouns and product names retain their casing in headings
-- Shape a record as H2 per section and H3 per item a reader looks up by name, with a few bullets or prose under each H3. Use a table only for a fixed-shape set.
+- H1 for document title, H2 for main sections, H3 for subsections, and no H4
+- Use sentence case for every heading. The audit reports a heading or a frontmatter `title` with a capitalized word after the first.
+- Proper nouns and product names keep their casing, whatever the audit reports
+- Shape a record as H2 per section and H3 per item a reader looks up by name. Use a table only for a fixed-shape set.
 
 ### Seams
 
-- Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint, not a cap.
-- Count rendered lines rather than source lines, wrapping each source line at 80 columns and summing the heights. Source lines undercount a file authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. A checkpoint another standard states counts the same unit, so a file measured one way never sits beside a run measured another.
-- Keep a whole document at or under 300 rendered lines, counted over the full source with frontmatter and fenced blocks included, since a session pays for every line it loads. This one is a ceiling rather than a checkpoint. `canon markdown audit` lists every document past it without failing the run, and a gate stage reads the same number, so whether a push fails on it is the project's gate to decide. Split the document at a seam rather than compressing it.
-- Exempt a file named `CHANGELOG.md`, which a release tool rewrites, and a document carrying `<!-- canon-length-exempt: <reason> -->` on a line of its own outside a fenced block. A marker naming no reason exempts nothing.
+Every depth number counts rendered lines, each source line wrapped at 80 columns. Source lines undercount a file authored one line per bullet, where fifteen paragraph-bullets render past sixty lines.
+
+- Past roughly 40 rendered lines with no heading breaking them, add a subheading at the seam. Measure the longest such run, excluding fenced code. The number is a checkpoint, not a cap.
+- A checkpoint another standard states counts the same unit, so a file measured one way never sits beside a run measured another
+- Keep a whole document at or under 300 rendered lines, frontmatter and fences included, since a session pays for every line it loads. Split it at a seam rather than compressing it.
+- The 300 lines are a ceiling. `canon markdown audit` lists each document past it without failing, and a gate stage reads the same number, so the project's gate decides whether a push fails.
+
+The ceiling exempts a file named `CHANGELOG.md`, which a release tool rewrites. It also exempts a document carrying `<!-- canon-length-exempt: <reason> -->` on its own line outside a fence, and a marker naming no reason exempts nothing.
 
 ### Exempt blocks
 
-- Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own to this checkpoint, which measures depth. The cap on a run of bullets is a separate rule under Paragraphs and lists. A catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides.
-- Mixing prose with that list, or nesting levels inside it, ends the exemption at any weight.
-- Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint.
-- Prose either side of the table ends that exemption, since the block has a seam and a heading breaks it there.
+Two kinds of block are exempt from the 40-line checkpoint, since a subheading dropped into either splits something that belongs together.
+
+- A block whose lines are all list items at one level averaging under roughly 130 characters, since a flat list of short peers is already navigable
+- Weight decides rather than count, since a catalog of one-liners and a stack of paragraphs reach one count and read nothing alike. The cap on a bullet run is a separate rule.
+- Mixing prose into that list, or nesting levels in it, ends the exemption at any weight
+- A block whose lines are all table rows, at any length, since a subheading inside one splits the table rather than the run
+- Prose either side of the table ends that exemption, since the block has a seam and a heading breaks it there
 
 ### Bold section markers
 
-- Break a run on a bold section marker holding its line alone, the way a heading breaks one. A document whose template separates sections with `**Risks:**` rather than `## Risks` has written the seam a reader lands on, and reading only the heading reported every such file at its full length whatever it carried.
-- Require the marker to start at column zero and to be the whole line. `**Risks:**` breaks a run, a bold phrase opening a sentence stays emphasis, and an indented one stays a label inside its list item.
-- Break a colon-less marker on either of two signals, since no one test separates every marker from a sentence set in bold. A label that is one whole code span breaks at any width, which is how a bold line holding only a backticked path reads as the file heading it is. Anything else breaks at 20 characters or fewer, which reaches `**Testing**` and leaves a bold sentence as prose.
+A bold section marker holding its line alone breaks a run the way a heading does. A template separating sections with `**Risks:**` rather than `## Risks` has written the seam a reader lands on.
 
-## Paragraphs and lists
+- The marker starts at column zero and is the whole line. A bold phrase opening a sentence stays emphasis, and an indented one stays a label inside its list item.
+- A colon-less marker breaks on either of two signals, since no one test separates every marker from a sentence set in bold
+- A label that is one whole code span breaks at any width, so a bold line holding only a backticked path reads as the file heading it is
+- Anything else breaks at 20 characters or fewer, which reaches `**Testing**` and leaves a bold sentence as prose
 
-- Use prose by default. Reserve bullets for discrete, unrelated items.
-- Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
-- Past roughly 700 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. Two long sentences satisfy the sentence cap and still overload the reader. This number sits well above the bullet checkpoint because a paragraph is read straight through and a bullet is scanned. A paragraph a branch adds or grows past it fails the push in a context entry through the `paragraph-growth` gate stage, and an unchanged long paragraph passes. Elsewhere it is the audit's warning and no more.
+## Density
 
-### Bullets
+Six limits keep a file scannable on sight, each a fact `canon markdown audit` measures that fails the push wherever the surface's gate is on. Open an H3 with a lead sentence or a table, then a few bullets or a short paragraph, since monotone text is the defect whether all prose or all bullets.
 
-- Keep bullets tight. Past roughly 250 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, the overflow belongs in prose. A bullet a branch adds or grows past it fails the push in a context entry through the `paragraph-growth` gate stage, and an unchanged one passes until edited. Elsewhere it is the audit's warning and no more. The number is a checkpoint rather than a cap.
-- Keep a run of consecutive top-level bullets to 5 or fewer under one heading, and fold a longer one into prose, an H3 per item, or a split at the seam. A blank line, a continuation, and a nested item do not break the run, and a paragraph or heading does. The audit reports a longer run and the `bullet-stacks` gate stage fails it.
-- Leave a run whose every item opens with a bold label or a link as it is, since each item names its own subject. A task box (`[ ]`) is not a link, so a checklist counts as plain bullets. Numbered items do not count toward the cap. Governance rules and `REQUIREMENT.md` sit outside it, since a rule is one imperative per bullet.
-- Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.
-- Use dashes (`-`) not asterisks (`*`) for bulleted lists
+| Rule                | Limit                                             |
+| ------------------- | ------------------------------------------------- |
+| Paragraph length    | 350 characters                                    |
+| Paragraphs in a row | 2 at most                                         |
+| Bullet length       | 200 characters                                    |
+| Bullets in a row    | 5 plain bullets at most                           |
+| Heading depth       | H3 at most, no H4                                 |
+| H3 opening          | First block under an H3 is a paragraph or a table |
+
+Rules, `CLAUDE.md`, a requirements or design record, a changelog, examples, and `.canon/` records take no density finding, since a rule is one imperative per bullet and each record keeps its own shape.
+
+### How each limit counts
+
+A paragraph is read straight through and a bullet is scanned, so the paragraph limit sits above the bullet one. Four sentences to a paragraph stays advice rather than a limit.
+
+- A paragraph's length folds in the lines that wrap it. A paragraph inside a list item counts toward its bullet, never as a paragraph or toward a run.
+- A bullet's length counts its continuation lines and excludes any bullet nested under it
+- A heading, list, table, fence, or bold section marker ends a run of paragraphs
+- A blank line, a continuation, and a nested item do not break a run of bullets, and a paragraph or a heading does
+- A run whose every item opens with a bold label or a link is exempt from the run limit, since each item names its own subject. A task box is not a link, so a checklist counts as plain.
+
+Numbered items do not count toward a bullet run. Fix a finding by its shape, splitting a paragraph at its next logical boundary and folding a long run into prose, an H3 per item, or a split at the seam. A rewrite may cut repetition and history, and never a stated reason.
+
+### Content
+
+A file can pass every limit and still say too much.
+
+- State one fact per bullet, with its reason in the same sentence, as "X, so Y"
+- State what holds now. History and rejected options go in a decision record.
+- Do not write a sentence that restates its heading or the line above it
+- Collapse a stack of bullets narrating one subsystem into one H3 with one narrative, since splitting a heavy bullet into light ones reads no better
 
 ### Bullet form
 
+A bullet's punctuation follows its sentence count, and a list opens unannounced.
+
+- Use dashes (`-`) not asterisks (`*`) for bulleted lists
 - Do not end single-sentence or fragment bullets with a period. Use periods when a bullet has two or more sentences.
 - For key path lists, use colon format: `- \`src/\`: description`. Never use an em dash.
 - Do not introduce a list with a "Here are the X:" or "The following X:" lead-in
@@ -87,7 +123,7 @@ Does not govern:
 ## Code and identifiers
 
 - Wrap commands, API names, file paths, and code identifiers in backticks
-- Use a language identifier on all fenced code blocks (`markdown`, `typescript`, `plaintext`). Never use a bare ` ``` `
+- Use a language identifier on every fenced code block, such as `markdown`, `typescript`, or `plaintext`. Never use a bare ` ``` `.
 - In ASCII tree diagrams, use `←` for inline annotations. Never use `#`.
 
 ## Dates
@@ -102,13 +138,14 @@ Does not govern:
 
 ## Language
 
-- Use American English spelling
-- Open a sentence with its subject and action, not filler (`Note that`, `Basically`), a hollow connective (`That being said`, `It's worth noting`), or a gerund windup (`Leveraging the API...`). Substantive transitions that carry a real relationship are fine.
+Use American English spelling.
+
+- Open a sentence with its subject and action, not filler (`Basically`), a hollow connective (`It's worth noting`), or a gerund windup (`Leveraging the API...`). A real transition is fine.
 - Do not use the negative parallelism pattern (`It's not X, it's Y`, `not because X, but because Y`)
 - Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
 - Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
 
-### Claims
+A claim carries the weight its source gives it and no more.
 
 - Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
 - Do not inflate significance. State what a thing does rather than calling it `a major milestone` or `a turning point for the field`.
@@ -116,14 +153,15 @@ Does not govern:
 - Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
 - Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
 
-One command reads the character bans under `## Punctuation`. `canon markdown audit` ships them as package data, so a project that installed no standards is measured the same as one that did, and this file states them for a reader rather than for the parser. The spelling line above states a convention and ships no set, so a project's spell checker is what enforces it.
+One command reads the character bans under `## Punctuation`. `canon markdown audit` ships them as package data, so a project that installed no standards is measured the same as one that did. This file states them for a reader rather than for the parser, and the spelling line ships no set, so a project's spell checker enforces it.
 
 ## Frontmatter descriptions
 
-When frontmatter carries a short `title` or `description` used for catalog display:
+When frontmatter carries a `title` or `description` used for catalog display:
 
 - `title`: sentence case, identifies the file uniquely against its siblings in the same catalog. Proper nouns retain their casing. No trailing period.
-- `description`: sentence case, names the specific topics covered so a reader can decide whether to open the file. Lead with concrete subjects, strip filler like "guide to", "overview of", or "documentation about". No trailing period, no leading article (`the`, `a`).
+- `description`: sentence case, names the specific topics covered so a reader can decide whether to open the file. No trailing period, no leading article (`the`, `a`).
+- Lead a `description` with concrete subjects, and strip filler like "guide to", "overview of", or "documentation about"
 - Do not mechanically reuse the H1 as the description.
 
 ## Emphasis and dividers
@@ -134,8 +172,9 @@ When frontmatter carries a short `title` or `description` used for catalog displ
 ## Links and file references
 
 - Use descriptive anchor text for links. Avoid `click here` or `read more`.
-- Wrap file references in backticks by default. Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) and in an index file, whose rows exist to be followed. Never repeat the path verbatim as the label.
-- A relative link's destination resolves against the filesystem, over the same corpus the ban scan reads. A destination carrying a template placeholder in angle brackets, such as `<slug>` or `<name>`, reads as an illustration rather than a literal path and is exempt.
+- Wrap file references in backticks by default. Never repeat the path verbatim as a link label.
+- Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) and in an index file, whose rows exist to be followed
+- A relative link resolves against the filesystem over the corpus the ban scan reads, and one carrying a placeholder in angle brackets, such as `<slug>`, is an exempt illustration
 
 ## Examples
 
@@ -144,29 +183,19 @@ Each pair shows a banned pattern and its fix.
 ```markdown
 Bad: See [canon/context/retrieval.md](canon/context/retrieval.md) for the retrieval flow.
 Good: See `canon/context/retrieval.md` for the retrieval flow.
-```
 
-```markdown
 Bad: Read [docs/development.md](docs/development.md) before contributing.
 Good: Read the [development guide](docs/development.md) before contributing.
-```
 
-```markdown
 Bad: In order to configure the server, you'll need to ensure that the port is set.
 Good: Set `port` in the server config.
-```
 
-```markdown
 Bad: It's not just a cache. It's a system for intelligent memory management.
 Good: The cache is an LRU store. It evicts the least-recently-used entry when full.
-```
 
-```markdown
 Bad: Leveraging the retry mechanism, developers can build more resilient integrations.
 Good: Use the `retry` option for failed webhooks. Set `maxRetries` to 3.
-```
 
-```markdown
 Bad: It might be worth considering whether to enable caching.
 Good: Enable caching for read-heavy endpoints. Skip it for writes.
 ```

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

@@ -12,7 +12,14 @@ metadata:
 - If no feature description is provided, stop: `❌ No feature description. Describe what you want to add.`
 - Do not implement anything. Output the plan and stop.
 - When the feature description spans two or more independent concerns, write one plan file per concern. Do not bundle them under a single slug.
-- Before Step 3, name the next three questions you would ask about what the ask must achieve, and predict the operator's answer to each from the ask and the project context. An answer you can predict settles its criterion, which Step 3 writes as a `**Verification:**` bullet rather than a question. Only a prediction still open goes under `**Questions:**` with a `- Suggested:` line, so a fully specified ask carries none and Small mode stays reachable. When you can predict none of the three, so no checkable success criterion can be stated, ask before Step 3 through whatever route reaches the operator, including a message to a dispatching session. The test reads the ask's success criteria, never the plan's open questions, which a `- Suggested:` line answers.
+
+### Predict the next three questions
+
+Before Step 3, name the next three questions you would ask about what the ask must achieve, and predict the operator's answer to each. The test reads the ask's success criteria, never the plan's open questions.
+
+- A predictable answer settles its criterion, which Step 3 writes as a `**Verification:**` bullet rather than a question
+- Only a prediction still open goes under `**Questions:**` with a `- Suggested:` line, so a fully specified ask carries none and Small mode stays reachable
+- When you can predict none of the three, ask before Step 3 through whatever route reaches the operator, including a message to a dispatching session
 
 ## Step 1: read the Claude setup
 
@@ -22,26 +29,29 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `canon/REQUIREMENTS.md`: feature scope and non-goals
 - `.canon/tasks/index.md`: current scope and status, then any task file the feature relates to
 
-Also read these when the feature touches code or UI. Skip them for prose, docs, catalog, or config-only changes:
+Also read `canon/DESIGN.md` when the feature touches code or UI, for visual intent and component rules, with values read from the stylesheet its lead names. Skip it for prose, docs, catalog, or config-only changes.
 
-- `canon/DESIGN.md`: visual intent and component rules, with values read from the stylesheet its lead names
-
-Coding standards live in `.claude/rules/`. Claude Code loads them automatically. Path-scoped rules apply to the files they match.
+Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match.
 
 ## Step 2: scan relevant source files
 
-Based on the feature description, identify and read source files that are directly relevant. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+Read the source files directly relevant to the feature, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+
+Measure against the tree rather than recall, since a count carried from an earlier session or a summary is the most common way a plan ships the wrong scope.
 
-Measure against the tree rather than recall. Grep for each construct the plan will name and count the sites, so the plan carries the count the tree holds today. The tree tells a new path what exists beside it, not where it belongs, so a flat folder is a reading to place against rather than a pattern to copy. Confirm any work the plan sequences behind is still open, so it does not lead with an item that already shipped.
+- Open each file before describing what is in it
+- Grep for each construct the plan will name and count the sites
+- Confirm any work the plan sequences behind is still open
+- Read a flat folder as a reading to place against rather than a pattern to copy, since the tree shows what exists beside a new path, not where it belongs
 
-Open each file before describing what is in it. A count or a claim carried from an earlier session, a summary, or another document is the most common way a plan ships the wrong scope.
+### Outside sources
 
-When a decision the plan will make rests on an outside practice or a third-party behavior, invoke `canon:search-craft` before searching, fetch each source, and record the passage relied on. Skip this for a plan that rests on nothing outside the project.
+When a decision rests on an outside practice or a third-party behavior, invoke `canon:search-craft` before searching, fetch each source, and record the passage relied on. Skip this for a plan that rests on nothing outside the project.
 
-- Ask the fetch for the verbatim passage, and confirm the wording through `curl` where a decision turns on exact wording, since `WebFetch` returns a model's answer rather than the page.
-- Route a Claude Code subject to the `claude-code-guide` agent.
-- Mark a source that could not be fetched as unverified rather than citing recall.
-- Report it rather than proceeding silently when `canon:search-craft` does not resolve.
+- Confirm exact wording through `curl` where a decision turns on it, since `WebFetch` returns a model's answer rather than the page
+- Route a Claude Code subject to the `claude-code-guide` agent
+- Mark a source that could not be fetched as unverified rather than citing recall
+- Report it rather than proceeding silently when `canon:search-craft` does not resolve
 
 ## Step 3: build the plan
 
@@ -49,37 +59,30 @@ The section list, what each section holds, and the suggested-and-answer contract
 
 What this skill adds on top of the standard:
 
-- Reframe a vague ask as success criteria before writing `**Files to touch:**`. Each criterion names something observable and a check that decides it, such as a measure and the threshold it must stay under, drawn from the ask or the project context. "Make it faster" names no criterion, while a stated budget for one path does. Each criterion becomes one `**Verification:**` bullet.
-- Confirm a concrete project or use case drives the feature before shaping it, and lift patterns from that project where precedent exists. A feature with no named user is a guess about what one will want.
+- Reframe a vague ask as success criteria before `**Files to touch:**`, each an observable result and its check, which becomes one `**Verification:**` bullet. "Make it faster" names none.
+- Confirm a concrete project or use case drives the feature, and lift patterns from it where precedent exists. A feature with no named user is a guess.
 - Prefer one layout that serves both a new and a grown project over a dual-mode toggle or a migration shim. Two modes double what every later change has to hold.
 
 ### Suggestions and sections
 
-- Apply senior judgment to every `- Suggested:` line. Pick the best option and state it in one line with its reason or main tradeoff. No padding, no alternatives unless they change the pick.
-- Suggest a real default when best practice, the codebase, or prior context points to one.
-- Load the `canon:codebase-layout` skill before writing the `**Files to touch:**` entries when any of them names a file or folder that does not exist yet, and give each new path its placement reason in its entry. Skip the load when every entry edits an existing file. Report it rather than proceeding silently when the skill does not resolve.
-- Write `**Verification:**` as one bullet per outcome naming the test or command that proves it, and `**Review focus:**` as the inputs or states that would break the change. You understood the risk before any diff existed, and these two sections carry it to the executing session and to the reviewer.
+Every `- Suggested:` line takes senior judgment, picking the best option in one line with its reason or main tradeoff, and naming alternatives only when they change the pick.
+
+- Suggest a real default when best practice, the codebase, or prior context points to one
+- Load `canon:codebase-layout` before `**Files to touch:**` when an entry names a path that does not exist yet, and give each new path its placement reason. Report it if it does not resolve.
+- Write `**Verification:**` as one bullet per outcome naming the test or command that proves it
+- Write `**Review focus:**` as the inputs or states that would break the change, carrying the risk you understood to the executor and the reviewer
 
 ### Sources and size
 
-- Cite the `**Sources:**` entry for every decision Step 2 sourced, each with its quoted passage or the word `unverified`.
-- Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one.
+A small feature produces a short plan, not a padded one.
+
+- Cite the `**Sources:**` entry for every decision Step 2 sourced, each with its quoted passage or the word `unverified`
+- Prefer `None identified.` over low-signal fillers
 - When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
 
 ## Pull request boundaries
 
-A plan sequencing its work into batches declares where one pull request ends, here rather than at ship time. A dependency chain cannot be split once it is built, so the choice exists only while the batches are still a plan.
-
-- One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename, so a `**Batch N**` sub-heading inside one file's `**Files to touch:**` shares that one branch across every batch, and the batch that merges first strands every batch behind it with nothing left to open a pull request against. Write a plan opening five batches as five files before the first line of any of them.
-- State a dependent batch's dependency on the ones before it in its own `**Constraints:**`, naming the earlier batch's slug and stacking rather than merging into it. A batch that builds after another and shares most of its files with it folds into that batch as contiguous commits on one branch, since each pull request pays a fixed cost a same-file slice cannot earn back, and the rebases between stacked slices land on the same files. Keep a batch apart only where a reviewer or the operator would judge it apart: a contract a later batch is built against, a taste call the operator judges in its own sitting, or a fold that would exceed one review. Write that reason as ``Judged apart from `feature-<parent>`: <reason>`` in the batch's `**Constraints:**`. `canon records validate plans` reports a stacked batch that should have folded, and its thresholds live there.
-- Mark each batch dependent or independent by comparing the file sets rather than the descriptions. A batch sharing no file with another is independent and earns its own branch even where both arrived in one request. One run measured at 68 files carried three such batches into a single review because nothing drew the boundary.
-
-### Slicing and sequence
-
-- Slice a batch by one user-visible path end to end rather than by layer, so each batch ships something a person can exercise. The slice decides what a batch contains, and the file-set comparison above still decides whether two batches depend on each other, so two slices sharing a file stay marked dependent. A path too thin to pay a pull request of its own folds forward into the next.
-- Sequence the riskiest batch first, so the batch most likely to change the plan is built while every later batch can still move. A sweep is the one exception and stays last even when it is the riskiest, per the next bullet.
-- Sequence a sweep last. A batch deliberately rewriting files earlier batches touched is coherent as the final one and forces every batch behind it into one review anywhere else.
-- Keep each batch's commits contiguous once the work starts. A later fix to an earlier batch belongs on that batch's own commits, since a batch interrupted by another cannot be lifted onto its own branch afterward.
+A plan sequencing its work into batches declares where each pull request ends, since a dependency chain cannot be split once it is built. Read `${CLAUDE_SKILL_DIR}/references/batches.md` when the plan carries more than one batch, for the one-file-per-batch rule, when a dependent batch folds, and the build order. A single-batch plan skips it.
 
 ## Step 4: output
 
@@ -88,11 +91,11 @@ Decide the mode based on what Step 3 produced:
 - **Small** when the plan touches 2 files or fewer, has no architectural or cross-cutting choices, and both Risks and Questions come out `None identified.`
 - **Full** otherwise
 
-A consumer list is a `Risks` entry, which already forces Full. Establishing a resource with more than one consumer, where at least one writes, is a cross-cutting choice wherever that list ends up living, so such a plan stays Full even at two files.
+A consumer list is a `Risks` entry, which already forces Full. A resource with more than one consumer, at least one writing, is a cross-cutting choice, so such a plan stays Full even at two files.
 
 ### Small mode
 
-Output the plan to chat. Do not write a plan file. The markers match the standard's, so a plan that later grows into a file keeps the shape it was drafted in.
+Output the plan to chat and write no plan file. The markers match the standard's, so a plan that later grows into a file keeps its shape.
 
 ```markdown
 **Files to touch:**
@@ -104,7 +107,7 @@ Output the plan to chat. Do not write a plan file. The markers match the standar
 - <outcome>: `<test or command that proves it>`
 ```
 
-Small mode carries no `**Review focus:**`, since it already requires Risks to come out `None identified.` and a change with no risk leaves the reviewer no breaking input to name.
+Small mode carries no `**Review focus:**`, since its Risks already came out `None identified.` and the reviewer has no breaking input to name.
 
 If real questions exist, include a numbered `**Questions:**` section below, each with a `- Suggested:` line and an `- Answer:` slot:
 
@@ -120,17 +123,20 @@ Omit empty sections. Do not print `None identified.` in chat.
 
 ### Full mode
 
-Derive a 2-to-4-word kebab-case slug from the feature description. Write the full plan to `.canon/plans/feature-<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist.
+Derive a 2-to-4-word kebab-case slug from the feature description. Write the plan to `.canon/plans/feature-<slug>.md` at the main worktree root, resolved the way `session-worktree` does, creating the directory if needed.
+
+The plan is a main-root write, from a linked worktree and from a background session at the main root alike, so it goes out as a heredoc routed the way `session-worktree` states. Copy the shape from the template in `${CLAUDE_SKILL_DIR}/references/plan.md` rather than from this body, so one edit to the standard moves every plan.
 
-The plan is a main-root write, from a linked worktree and from a background session sitting at the main root with none entered alike, so it goes out as a heredoc, routed the way `session-worktree` states.
+### Checking the written plan
 
-The file follows the template in `${CLAUDE_SKILL_DIR}/references/plan.md`. Copy the shape from there rather than from this body, so one edit to the standard moves every plan.
+Two commands check the file once it lands, and both write nothing.
 
-Run `canon records validate plans` after writing the file when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold, and it writes nothing.
+- Run `canon records validate plans` when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold.
+- Run `canon markdown audit .canon/plans/feature-<slug>.md`, naming the file, since the gitignored plan reaches no other gate. Rewrite a hit's sentence rather than swapping the token.
 
-Run `canon markdown audit .canon/plans/feature-<slug>.md` beside it, naming the file. `.canon/plans/` is gitignored and the audit's default path set is what git lists, so no other gate ever opens a plan, and six ban hits landed across four plans written without this call. Rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+When Step 1 resolved an existing task, run `canon tasks plan-link <task> .canon/plans/feature-<slug>.md` right after the file lands, naming the stem Step 1 read. Skip it when Step 1 found no task, and report a refusal rather than stopping, since `canon tasks validate` still catches an unlinked task through `plan-uncited`.
 
-When Step 1 resolved an existing task for this feature, run `canon tasks plan-link <task> .canon/plans/feature-<slug>.md` right after the file lands, naming the stem Step 1 read. Skip the call when Step 1 found no task, since there is nothing to link yet. Report a refusal rather than stopping on it. The plan file is already written, and `canon tasks validate` still catches an unlinked task through `plan-uncited` if this call cannot run.
+### Chat output
 
 Then output in chat:
 
@@ -145,7 +151,7 @@ Then output in chat:
 Next: /session-worktree
 ```
 
-Show only the path line and the `Next:` line when there are no questions. The `.canon/plans/` directory is gitignored. Do not stage or commit the file.
+Show only the path line and the `Next:` line when there are no questions. The `.canon/plans/` directory is gitignored, so do not stage or commit the file.
 
 Do not proceed to implementation until the user explicitly says to continue.
 
@@ -153,6 +159,6 @@ Do not proceed to implementation until the user explicitly says to continue.
 
 After the plan is written, the user may re-ping with follow-up questions or pushback. Keep chat output to a decision-help shape.
 
-- State each pick as one-line pick plus one-line reason. Do not use section headers, context blocks, or multi-section breakdowns in chat. Those belong in the plan file.
-- Put numbered decisions to resolve at the bottom of the response, not interleaved with findings.
-- When a finding needs more than two lines to explain, update `.canon/plans/feature-<slug>.md` in place with the detail and point the user at the file instead.
+- State each pick as one-line pick plus one-line reason. Section headers, context blocks, and multi-section breakdowns belong in the plan file.
+- Put numbered decisions to resolve at the bottom of the response, not interleaved with findings
+- When a finding needs more than two lines, update `.canon/plans/feature-<slug>.md` in place and point the user at the file

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

@@ -0,0 +1,46 @@
+---
+title: Pull request boundaries reference
+description: How a plan sequencing its work into batches declares where each pull request ends, how dependent batches stack or fold, and the order batches build in
+---
+
+# Pull request boundaries reference
+
+Applies to a feature plan that sequences its work into more than one batch. A dependency chain cannot be split once it is built, so the boundary is declared while the batches are still a plan rather than at ship time.
+
+## One batch, one file
+
+One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename.
+
+- A `**Batch N**` sub-heading inside one file's `**Files to touch:**` shares that branch across every batch, so the first merge strands the rest
+- Write a plan opening five batches as five files before the first line of any of them
+
+## Dependent batches
+
+State a dependent batch's dependency on the ones before it in its own `**Constraints:**`, naming the earlier batch's slug and stacking rather than merging into it.
+
+A batch that builds after another and shares most of its files folds into that batch as contiguous commits on one branch. Each pull request pays a fixed cost a same-file slice cannot earn back, and the rebases between stacked slices land on the same files.
+
+### Judged apart
+
+Keep a batch apart only where a reviewer or the operator would judge it apart. Write that reason as ``Judged apart from `feature-<parent>`: <reason>`` in the batch's `**Constraints:**`.
+
+- A contract a later batch is built against
+- A taste call the operator judges in its own sitting
+- A fold that would exceed one review
+
+`canon records validate plans` reports a stacked batch that should have folded, and its thresholds live there.
+
+### Marking dependence
+
+Mark each batch dependent or independent by comparing the file sets rather than the descriptions. A batch sharing no file with another is independent and earns its own branch even where both arrived in one request.
+
+One run measured at 68 files carried three such batches into a single review because nothing drew the boundary.
+
+## Slicing and sequence
+
+Slice a batch by one user-visible path end to end rather than by layer, so each batch ships something a person can exercise. The file-set comparison still decides dependence, so two slices sharing a file stay marked dependent.
+
+- Fold a path too thin to pay a pull request of its own forward into the next
+- Sequence the riskiest batch first, so the batch most likely to change the plan is built while every later batch can still move
+- Sequence a sweep last, even when it is the riskiest. A batch rewriting files earlier batches touched forces every batch behind it into one review anywhere else.
+- Keep each batch's commits contiguous once the work starts, since a batch interrupted by another cannot be lifted onto its own branch afterward