@erclx/canon 5.40.0 → 5.42.0

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

@@ -20,7 +20,8 @@ Does not govern:
 
 - The problem being solved and for whom, as the record's opening line under the title
 - User-facing goals stated as outcomes, not implementation
-- Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded. A non-goal resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence, and a non-goal resting on scope alone takes none.
+- Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded.
+- A non-goal resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence. One resting on scope alone takes none.
 - Hard constraints that shape every decision, when the project has any
 
 ## What does not go in
@@ -32,17 +33,29 @@ Does not govern:
 
 ## Sections
 
-Require `## Goals` and `## Non-goals`. Add `## Constraints` when the project holds hard limits that shape every decision. Add `## Worldview` when the project holds beliefs that shape every decision, and keep a belief there only when it changes a decision, since a padded worldview turns into a second goals list. Drop a section rather than pad it with filler.
+Require `## Goals` and `## Non-goals`, and drop any other section rather than pad it with filler.
+
+- Add `## Constraints` when the project holds hard limits that shape every decision
+- Add `## Worldview` when the project holds beliefs that shape every decision
+- Keep a belief there only when it changes a decision, since a padded worldview turns into a second goals list
 
 ## Length
 
-This file loads into every session, so its weight is paid before any work starts. Cap it by stating the clause `This record holds at most <n> words.` in the record itself, where a checker reads it and counts every word below the frontmatter. The cap is the record's own, so a record stating none is measured and never gated. The template and the seed a new project installs state it at 600, and a project loosens it by editing the number in its own record. At the cap, cut a goal or a constraint that no longer changes a decision before adding one.
+This file loads into every session, so its weight is paid before any work starts. Cap it by stating the clause `This record holds at most <n> words.` in the record itself, where a checker reads it and counts every word below the frontmatter.
+
+- The cap is the record's own, so a record stating none is measured and never gated
+- The template and the seed a new project installs state 600, and a project loosens it by editing the number in its own record
+- At the cap, cut a goal or a constraint that no longer changes a decision before adding one
 
 ## Lifecycle
 
 The record may carry an optional `reviewed: YYYY-MM-DD` frontmatter field naming the day someone last read it whole for identity drift. Whoever finishes that review sets it as the review's last edit, and `canon records stale canonical` reads it to count the releases shipped since. A record with no field reads as never reviewed.
 
-Later scope arrives as a new section rather than as an extension of the goals. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Once every entry in it has shipped, delete the section, since version history keeps the old text and the document states the project as it stands. Nothing sequences a section into versions. Work reaches the board as discrete tasks under `tasks.md`, and `board.md` orders them by readiness, so a section here states what is wanted and never when it lands.
+Later scope arrives as a new section rather than as an extension of the goals. Name it for what it delivers and state its entries as outcomes, the same way the goals are stated.
+
+- Once every entry in it has shipped, delete the section, since version history keeps the old text and the document states the project as it stands
+- Nothing sequences a section into versions. Work reaches the board as discrete tasks under `tasks.md`, and `board.md` orders them by readiness.
+- A section states what is wanted and never when it lands
 
 ## Template
 

package/claude/skills/draft-doc/references/wiki-kind.md

@@ -11,35 +11,43 @@ The standard's `## Placement` section names the folder a page lands in and the v
 
 ## Guards
 
-- If `<wiki-root>` does not resolve, say so and ask whether to create it before drafting. A project carrying no such folder has never taken the standard's placement rule, so creating it is a decision rather than a step.
+If `<wiki-root>` does not resolve, say so and ask whether to create it before drafting. A project carrying no such folder has never taken the standard's placement rule, so creating it is a decision rather than a step.
 
 ## Placement
 
 The standard sets two tests and a page has to pass both. Run them before drafting anything, since a page failing either is non-conforming however well it is written.
 
-- **Owned outside this repository.** A subject describing how this repository works fails. Refuse and offer the docs or context kind of this skill: `❌ <subject> is owned by this project, so it belongs in the docs surface or a context entry. Re-run draft-doc naming that destination.`
-- **Owned by the vendor the folder split covers.** The standard names one owner and one subfolder. A third-party tool or a vendor-neutral concept fails, however reference-like it reads. Refuse: `❌ <subject> is outside the wiki's folder split. Route it to the docs surface or a skill body rather than adding a second folder for it.`
+| Test                                        | Fails on                                                                        | Refusal                                                                                                                                    |
+| ------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Owned outside this repository               | A subject describing how this repository works                                  | `❌ <subject> is owned by this project, so it belongs in the docs surface or a context entry. Re-run draft-doc naming that destination.`   |
+| Owned by the vendor the folder split covers | A third-party tool or a vendor-neutral concept, however reference-like it reads | `❌ <subject> is outside the wiki's folder split. Route it to the docs surface or a skill body rather than adding a second folder for it.` |
+
+On the first test, offer the docs or context kind of this skill. The standard names one owner and one subfolder for the second.
 
 Do not widen the split to admit a subject. Adding a sibling folder is a change to the standard, argued there, rather than a placement this kind takes on its own.
 
 ## Collision
 
-- Derive the page slug per the standard's `## Naming` section and check whether `<wiki-root>/<vendor>/<slug>.md` already exists. If it does, stop: `❌ <path> already covers this subject. Edit that page against the standard instead of drafting a second one.`
-- Read `<wiki-root>/<vendor>/index.md` and check every title and description it lists against the subject. Stop on a match: `❌ <path> already covers this subject under a different name. Edit that page instead.`
+- Derive the page slug per the standard's `## Naming` section and check whether `<wiki-root>/<vendor>/<slug>.md` already exists
+- If it does, stop: `❌ <path> already covers this subject. Edit that page against the standard instead of drafting a second one.`
+- Read `<wiki-root>/<vendor>/index.md` and check every title and description it lists against the subject
+- Stop on a match: `❌ <path> already covers this subject under a different name. Edit that page instead.`
 
 ## Source
 
 The standard forbids working from training knowledge, so the draft is built on a read rather than on recall.
 
-- Fetch current information through the `claude-code-guide` agent for any subject that agent covers. Its answer is the source the page is written from.
-- Reach a subject the agent does not cover through the owner's own published documentation. Invoke `canon:search-craft` with the skill tool before searching for it, since finding the owner's documentation is the field-and-authority step that skill carries, and report it rather than proceeding silently when the skill does not resolve.
+Fetch current information through the `claude-code-guide` agent for any subject that agent covers, and write from its answer. Reach any other subject through the owner's own published documentation.
+
+- Invoke `canon:search-craft` with the skill tool before that search, since finding the owner's documentation is its field-and-authority step. Report it when it does not resolve.
 - Say the fetch failed and stop rather than substituting recall, even for a subject the session believes it knows. A page sourced from memory ships looking identical to one that was checked.
-- Close the intro with the `Source:` sentence the standard requires, linking the canonical page where one exists and naming the owner alone where the subject has no single URL.
+- Close the intro with the `Source:` sentence the standard requires, linking the canonical page, or naming the owner alone where the subject has no single URL
 - Stamp the read date on a source revised without notice, as `read <date>`. A claim traced to an undated read cannot be checked against what was actually read.
 
 ## Draft
 
-- Draft `title` and `description` frontmatter against the standard's contract, then the intro paragraph closing on `Source:` as a short orientation, then the lesson sections. Let the read of the source decide what is a lesson: keep a fact only when the source page does not state it, and leave reference detail to the source.
+- Draft `title` and `description` frontmatter against the standard's contract, then the intro paragraph closing on `Source:` as a short orientation, then the lesson sections
+- Let the read of the source decide what is a lesson. Keep a fact only when the source page does not state it, and leave reference detail to the source.
 - Write what the fetch returned rather than what the subject is assumed to do.
 - Answer one question per section and stop. A reader arrives to settle something specific rather than to read the page through.
 - Mark a claim the fetch left unsettled rather than smoothing over it. An unmarked gap reads as a checked fact.
@@ -50,4 +58,6 @@ Add `**Source:** <owner, and the read it came from>`, and confirm the source wit
 
 ## Write
 
-Regenerate `<wiki-root>/<vendor>`, naming the folder the page landed in rather than the root above it. The verb rewrites the `index.md` in the folder it is given and does not walk down, so regenerating at the root leaves the vendor catalog untouched. A page absent there is invisible to the next run's Collision step, which then drafts a second page on the same subject.
+Regenerate `<wiki-root>/<vendor>`, naming the folder the page landed in rather than the root above it. The verb rewrites the `index.md` in the folder it is given and does not walk down, so regenerating at the root leaves the vendor catalog untouched.
+
+A page absent from that catalog is invisible to the next run's Collision step, which then drafts a second page on the same subject.

package/claude/skills/draft-figure/references/architecture-set.md

@@ -25,11 +25,15 @@ Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams
 
 ## Sources
 
-- Read `canon/REQUIREMENTS.md`, `canon/context/index.md`, `CLAUDE.md`, and the language manifest (`package.json`, `pyproject.toml`, `Cargo.toml`) when present, plus the top-level folder layout through `ls`. Do not recurse speculatively.
+- Read `canon/REQUIREMENTS.md`, `canon/context/index.md`, `CLAUDE.md`, and the language manifest (`package.json`, `pyproject.toml`, `Cargo.toml`) when present
+- Read the top-level folder layout through `ls`, and do not recurse speculatively
 - When neither planning file exists and no folder structure names a boundary, stop: `❌ No source signal for <view>. Add canon/REQUIREMENTS.md or run inside a project folder.`
 - When the view came from a code scan rather than planning prose, open the caption with `Source: code.` and add `Fidelity is lower than prose-driven figures. Verify against the project's intent.`
 
 ## Caption and prose
 
-- Name one or two code paths a reader can open, in the caption or the prose beside the figure. Cite only paths that exist and spell each one exactly, since a reader deciding whether the figure still holds starts by opening them.
-- Keep implementation detail out of the figure: function names and call signatures, library versions, config keys and environment variable names, retry counts and timeouts, and workarounds needing more than a sentence. That detail belongs in a `canon/context/` entry, which the caption points at by path when a reader needs the mechanism.
+Name one or two code paths a reader can open, in the caption or the prose beside the figure. Cite only paths that exist and spell each one exactly, since a reader deciding whether the figure still holds starts by opening them.
+
+- Keep implementation detail out of the figure, being function names and call signatures, library versions, config keys and environment variable names, retry counts and timeouts
+- A workaround needing more than a sentence stays out too
+- That detail belongs in a `canon/context/` entry, which the caption points at by path when a reader needs the mechanism

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

@@ -9,7 +9,7 @@ Applies to every hand-drawn figure, wherever it is authored. A figure sits insid
 
 ## Scope
 
-Governs a hand-drawn figure wherever one is authored, naming no path because an attribute standard governs a fragment rather than a document type: when it earns its place, the render-first policy routing a graph-shaped subject through Mermaid, the wrapping and caption every figure carries, and its color and accessibility rules. It carries no template, since a figure has no document shape of its own and sits inside one another standard sets.
+Governs a hand-drawn figure wherever one is authored, being when it earns its place, the render-first policy routing a graph-shaped subject through Mermaid, the wrapping and caption every figure carries, and its color and accessibility rules. It names no path and carries no template, since it governs a fragment rather than a document type.
 
 Does not govern:
 
@@ -35,10 +35,12 @@ A figure failing these is non-conforming even when it satisfies every shape rule
 
 ## The render-first policy
 
-- Route a graph-shaped subject, one whose relationship, boundary, or path a flowchart already expresses, through Mermaid's own hand-drawn look rather than through model-authored SVG coordinates. `mermaid.md` governs the fence itself.
-- Reserve freehand inline SVG, plain shapes and lines authored directly in the markup, for a subject that is not graph-shaped. A figure that cannot express its subject through the deterministic path is a worse failure than an inconsistent one drawn by hand, so the hatch stays open rather than forcing every figure through the renderer.
-- Draw a figure in a teach lesson freehand whatever its shape. A lesson letters its figures in a hand font the renderer cannot load, so Mermaid measures every label in a narrower fallback face, and the page then clips the wider text it actually shows.
-- State this as a render-first policy rather than a ban on a tool-exported drawing. Routing a graph-shaped figure through Mermaid is itself running it through an external tool, so a rule banning any diagram "exported from a diagramming tool" would forbid the path this policy requires.
+Route a graph-shaped subject, one whose relationship, boundary, or path a flowchart already expresses, through Mermaid's own hand-drawn look rather than through model-authored SVG coordinates. `mermaid.md` governs the fence itself.
+
+- Reserve freehand inline SVG, plain shapes and lines authored in the markup, for a subject that is not graph-shaped
+- A figure that cannot express its subject through the deterministic path is a worse failure than an inconsistent hand-drawn one, so the hatch stays open
+- Draw a figure in a teach lesson freehand whatever its shape. Its hand font cannot load in the renderer, so Mermaid measures labels in a narrower fallback face and the page clips them.
+- State this as a render-first policy rather than a ban on a tool-exported drawing, since routing through Mermaid is itself running an external tool
 
 ## Wrapping and captioning
 
@@ -47,5 +49,5 @@ A figure failing these is non-conforming even when it satisfies every shape rule
 
 ## Color and accessibility
 
-- Color every fill and stroke through a custom property the surrounding document's own stylesheet defines, never a literal hex value. The figure then re-colors itself on the same switch that re-colors the page.
+- Color every fill and stroke through a custom property the surrounding document's stylesheet defines, never a literal hex value, so the figure re-colors on the switch that re-colors the page
 - Give the drawing an accessible name: `role="img"` with `aria-label` for one short line, or `aria-labelledby` pointing at a `<title>` element inside it for a longer one.

package/claude/skills/draft-figure/references/hand-drawn.md

@@ -12,7 +12,9 @@ description: Authoring a freehand SVG, its color and accessibility audit, and th
 - Author the SVG by hand: plain shapes and lines authored directly in the markup.
 - Follow the `## Color and accessibility` section of `${CLAUDE_SKILL_DIR}/references/figures.md` for every fill, stroke, and accessible name.
 
-There is no external render to verify a freehand drawing against before it is written. The check here is the stroke-and-fill audit above and a read of the markup against what the subject means to show, done once rather than looped. Hand-placed coordinates can drift out of line where a layout engine would not, so a freehand figure bound for a rendered page also takes the in-page capture below.
+There is no external render to verify a freehand drawing against before it is written. The check is the stroke-and-fill audit above and one read of the markup against what the subject means to show, done once rather than looped.
+
+Hand-placed coordinates can drift out of line where a layout engine would not, so a freehand figure bound for a rendered page also takes the in-page capture below.
 
 ## Capture in the page
 

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

@@ -9,8 +9,11 @@ description: The hand-drawn render config, the SVG and PNG pair, the hex rewrite
 
 ## Draft the fence
 
-- Draft the fence against `${CLAUDE_SKILL_DIR}/references/mermaid.md` for direction, node and edge budgets, `accTitle` and `accDescr`, and quoted labels. Do not work the layout or the budgets from memory.
-- Read every node and subgraph label against the banned characters `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` lists. The audit hook skips every line inside a fence, so a label carrying a banned character passes silently while the same character in the caption is caught. Reading the labels is the only gate they have. A colon works as a replacement inside a label.
+Draft the fence against `${CLAUDE_SKILL_DIR}/references/mermaid.md` for direction, node and edge budgets, `accTitle` and `accDescr`, and quoted labels. Do not work the layout or the budgets from memory.
+
+- Read every node and subgraph label against the banned characters `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` lists
+- The audit hook skips every line inside a fence, so a banned character in a label passes silently while the same one in the caption is caught. Reading the labels is their only gate.
+- A colon works as a replacement inside a label
 
 ## Render
 
@@ -25,9 +28,9 @@ bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/f
 bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/figures/<slug>.png -c .canon/tmp/figures/<slug>.json
 ```
 
-Render both formats in one pass. The SVG is what ships inside the `<figure>`, and the PNG is what the read-back below judges, since an SVG's markup carries no recoverable spatial meaning.
+Render both formats in one pass. The SVG ships inside the `<figure>`, and the PNG is what the read-back below judges, since an SVG's markup carries no recoverable spatial meaning.
 
-Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
+- Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cli ...` otherwise
 
 Before the first render in a project, say what is about to block:
 
@@ -42,14 +45,21 @@ Rewrite every stroke, fill, and text color the renderer wrote as a literal hex v
 ## Clipped titles
 
 - Expect a group title or a long label to clip once the destination shows it in the hand font, since the renderer sized its box in a fallback face.
-- When the in-page check shows a clipped title, add a `<style>` inside the SVG, scoped to that SVG's own id, that sets `overflow: visible` on the clipped label's `foreignObject` and centers the label within it, so the wider text spills past both edges evenly. The style hides the mismatch for a title and does nothing for a node label crowding its box, which takes a shorter label instead.
+- When the in-page check shows a clipped title, add a `<style>` inside the SVG, scoped to that SVG's own id
+- The style sets `overflow: visible` on the clipped label's `foreignObject` and centers the label within it, so the wider text spills past both edges evenly
+- It does nothing for a node label crowding its box, which takes a shorter label instead
 
 ## Fonts
 
-Check whether the project ran `canon design css --figures`. The figure and figcaption styling ships unconditionally either way, but that flag alone embeds the Virgil and Excalifont font files. Without it, the figure falls back to the browser's own generic `cursive` face rather than the intended hand-drawn font, and the output names that gap when the flag was not passed.
+Check whether the project ran `canon design css --figures`. The figure and figcaption styling ships either way, but that flag alone embeds the Virgil and Excalifont font files.
+
+Without it, the figure falls back to the browser's generic `cursive` face rather than the hand-drawn font, and the output names that gap.
 
 ## Read the render back
 
-- Read the rendered PNG and judge it against what the figure means to say, applying the verification properties in the mermaid standard. A source satisfying every rule there can still render as a picture asserting something false, so the image is what gets judged.
-- Fix the Mermaid source and re-render on a defect. Stop after two correction passes. When a defect survives, keep the figure and name the defect in the output rather than reporting a false verification.
-- When the render fails for any reason, no browser engine, no network, no package manager, continue to the confirm step and name the skipped check. A missing renderer degrades the loop rather than failing it.
+Read the rendered PNG and judge it against what the figure means to say, applying the verification properties in the mermaid standard. A source satisfying every rule there can still render as a picture asserting something false, so the image is what gets judged.
+
+- Fix the Mermaid source and re-render on a defect, stopping after two correction passes
+- When a defect survives, keep the figure and name the defect in the output rather than reporting a false verification
+- When the render fails for any reason, such as no browser engine, network, or package manager, continue to the confirm step and name the skipped check
+- A missing renderer degrades the loop rather than failing it

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

@@ -9,7 +9,7 @@ Applies to every Mermaid fence, wherever it is written. A fence sits inside a do
 
 ## Scope
 
-Governs the Mermaid attribute wherever a fence is written, naming no path because an attribute standard governs a drawing rather than a document type: direction and layout, node and edge budgets, the accessibility fields, how punctuation reaches a label, and how a rendered diagram is verified. It carries no template, since a fence has no document shape of its own and sits inside one another standard sets.
+Governs the Mermaid attribute wherever a fence is written, being direction and layout, node and edge budgets, the accessibility fields, how punctuation reaches a label, and how a rendered diagram is verified. It names no path and carries no template, since it governs a drawing rather than a document type.
 
 Does not govern:
 
@@ -31,17 +31,21 @@ A diagram failing these is non-conforming even when it satisfies every shape rul
 
 ## Layout
 
-- 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.
+- Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction when it links outward, as an architecture diagram normally does, so top-bottom is a declaration, not 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
 
+A row or a bundle asserts something about the system, so each is drawn only where it is true.
+
 - 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
 
+A label names a node, and the paragraph below the diagram carries the detail.
+
 - 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.
@@ -51,12 +55,13 @@ A diagram failing these is non-conforming even when it satisfies every shape rul
 - Hold a diagram to roughly 5 to 10 nodes. Split it past 15.
 - Watch edge count harder than node count. It binds first, and a diagram whose edges outnumber its nodes is already too dense to read.
 - Treat a diagram that cannot be described in one sentence as two diagrams.
-- Warn rather than refuse on a budget, and name the split that would fix it. These numbers come from published Mermaid practice rather than from a measurement against a corpus, so a hard refusal on them will be wrong sometimes and unarguable when it is.
+- Warn rather than refuse on a budget, and name the split that would fix it
+- These numbers come from published Mermaid practice rather than a measurement, so a hard refusal on them would be wrong sometimes and unarguable when it is
 
 ## Labels
 
-- Apply the punctuation bans in `markdown.md` to node and subgraph labels. A label is not prose, so a check scoped to prose does not reach it, and reading the labels before shipping is the only gate they have.
-- Treat the prose around a fence and the text inside it as two surfaces. The paragraphs are prose and follow `markdown.md` and the `write-human` skill. The fenced block is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
+- Apply the punctuation bans in `markdown.md` to node and subgraph labels. A check scoped to prose does not reach a label, so reading the labels before shipping is their only gate.
+- Treat the prose around a fence and the text inside it as two surfaces. The paragraphs follow `markdown.md` and the `write-human` skill, and a prose check does not reach the fenced block.
 
 ## Accessibility
 

package/claude/skills/draft-ready/references/ready.md

@@ -5,9 +5,13 @@ description: Folder layout, ordinal naming, the overview frontmatter, the thin-p
 
 # Ready reference
 
-Applies to a ready folder at `.canon/ready/<nn>-<slug>/`. A warm session that has already written a skill, a rule, or another finished file uses it to hand the exact text to the worker that ships it, since a plan only describes a change and a cold worker reading a description writes the file again from scratch. The folder holds the finished files themselves, laid out at their destination paths, so the worker's job is to copy rather than to author.
+Applies to a ready folder at `.canon/ready/<nn>-<slug>/`. A warm session that has already written a finished file uses it to hand the exact text to the worker that ships it, since a cold worker reading a plan's description writes the file again from scratch.
 
-The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and protect nothing against a folder deleted before anyone has pushed. That is why the archive step below is a move rather than a cleanup.
+The folder holds the finished files at their destination paths, so the worker copies rather than authors. It is gitignored, which is why the archive step below is a move rather than a cleanup.
+
+- Where a records remote is configured, `canon records push` and `canon records pull` protect it against the machine being lost
+- Where none is, they refuse with `no-remote`
+- Neither protects a folder deleted before anyone has pushed
 
 ## Contents
 
@@ -23,9 +27,7 @@ The folder is gitignored, and backed wherever a records remote is configured: `c
 
 ## Scope
 
-The `draft-ready` skill owns the procedure that writes a ready folder, and this standard owns the shape it writes to.
-
-Governs a ready folder under `.canon/ready/<nn>-<slug>/`: folder layout, ordinal naming, the overview's frontmatter, what the mirrored tree holds, the thin-plan contract that ships it, and the lifecycle from the live folder to the archive.
+The `draft-ready` skill owns the procedure, and this standard owns the shape. It governs a ready folder under `.canon/ready/<nn>-<slug>/`, being its layout, ordinal naming, the overview's frontmatter, what the mirrored tree holds, the thin-plan contract that ships it, and the lifecycle from the live folder to the archive.
 
 Does not govern:
 
@@ -49,8 +51,9 @@ A ready folder failing these is non-conforming even when it satisfies every shap
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug matching the plan's own slug.
-- The ordinal marks a folder per handoff, opened once by the warm session that writes it. It runs on its own sequence, separate from groundwork and intake's shared one, since a ready folder is not a measurement track.
-- With no folder holding an entry yet, the first one opened takes `01`. Read the highest existing `.canon/ready/<nn>-*/` folder, including the archive, and take the next integer.
+- The ordinal marks a folder per handoff, opened once by the warm session that writes it
+- It runs on its own sequence, separate from groundwork and intake's shared one, since a ready folder is not a measurement track
+- The first folder opened takes `01`. After that, read the highest existing `.canon/ready/<nn>-*/` folder, including the archive, and take the next integer.
 - Never renumber an existing folder. The ordinal is the order it opened, and the pull request that shipped it cites the folder by that name.
 
 ## 00-overview.md
@@ -76,29 +79,33 @@ Below the frontmatter, state in prose what the worker still owns beyond copying
 
 ## The mirrored tree
 
-- Every other file in the folder sits at the same relative path its destination has in the project, so `standards/ready.md` inside the destination tree sits at `<nn>-<slug>/standards/ready.md` inside the ready folder. <!-- canon-allow-reference: the example shows a target tree, where the standard sits under standards/ -->
-- Carry no file the destination tree would not carry. A ready folder is a source for `git mv`-shaped copies, not a scratch pad for the warm session's own notes. Anything else belongs in the plan or in the pull request body.
-- Write each file exactly as it should land. The worker copies verbatim and edits only what the gate or the overview's own list requires, so a placeholder or a half-finished passage ships as written.
+Every other file in the folder sits at the same relative path its destination has in the project.
+
+- For example, `standards/ready.md` in the destination tree sits at `<nn>-<slug>/standards/ready.md` in the ready folder <!-- canon-allow-reference: a target tree -->
+- Carry no file the destination tree would not carry. The folder is a source for `git mv`-shaped copies, never a scratch pad, and anything else goes in the plan or the pull request body.
+- Write each file exactly as it should land. The worker copies verbatim and edits only what the gate or the overview's list requires, so a placeholder ships as written.
 
 ## The thin-plan contract
 
 - A ready folder ships through an ordinary task row and a plan at `.canon/plans/feature-<slug>.md`, per `plan.md`. No new plan shape exists for it.
 - Name the ready folder in the plan's `**Constraints:**`, stating that the folder's files are the verbatim source for the paths the plan's `**Files to touch:**` lists.
-- List every destination path in `**Files to touch:**`, matching `00-overview.md`'s `destinations` field. A path the plan omits is invisible to `plan-reach`'s collision check, so a mismatch between the two lists is a defect in the plan rather than a variant the standard permits.
-- Keep the plan itself thin. Its `**Files to touch:**` entries may point at the ready folder's own copy for the reason behind each file rather than restating it, since the overview and the files already carry the detail a plan would otherwise duplicate.
+- List every destination path in `**Files to touch:**`, matching `00-overview.md`'s `destinations` field
+- A path the plan omits is invisible to `plan-reach`'s collision check, so a mismatch between the two lists is a defect in the plan, not a variant
+- Keep the plan thin. Its `**Files to touch:**` entries may point at the folder's copy for the reason behind each file, since the overview and the files carry that detail.
 
 ## Lifecycle
 
 - Write the ready folder in the same session that writes the files it carries. A folder assembled later from memory is a plan with extra steps, not a handoff.
-- Leave the move to `canon tasks archive`, which carries the folder to `.canon/ready/archive/<nn>-<slug>/` with its plan when the task that shipped it archives, and retargets the task's `Ready:` line. A plan another live task still cites keeps its folder.
+- Leave the move to `canon tasks archive`, which carries the folder to `.canon/ready/archive/<nn>-<slug>/` with its plan when the shipping task archives, retargeting its `Ready:` line
+- A plan another live task still cites keeps its folder
 - Never delete a ready folder. The archived copy sits beside the merged pull request as the exact text that shipped, the way an archived plan sits beside the reasoning that produced it.
 
 ## Anti-patterns
 
-- **The folder with an undeclared destination.** A file the plan's `**Files to touch:**` does not list passes the collision check unseen, and a second track can write the same path without either side finding out.
+- **The folder with an undeclared destination.** A file the plan's `**Files to touch:**` omits passes the collision check unseen, so a second track can write the same path with neither side finding out.
 - **The rewritten copy.** A worker that reads the folder's files as inspiration and writes its own version loses the exact text the handoff exists to carry.
 - **The folder as scratch.** Notes, alternates, or draft passages left in the folder beside the real files leave the worker guessing which is the source.
-- **The folder left live after shipping.** A ready folder the archive verb did not move reads as unshipped work to the next session that lists the live folder. The verb skips one whose task carries no `Ready:` line and cites no folder path in its plan.
+- **The folder left live after shipping.** An unmoved folder reads as unshipped work to the next session listing it. The verb skips one whose task has no `Ready:` line and whose plan cites no folder.
 
 ## Template
 

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

@@ -9,12 +9,17 @@ description: What branch naming is for, the gaps it closes, and where the family
 
 Without this skill, a branch name is invented once per session. The type prefix drifts from what the history already carries, the name runs past the width a pull request list renders, and a rename lands on a branch that already exists on the remote, which detaches every open pull request pointing at it.
 
+A session standing on `main` has no route either. The `git.md` rule sends every git operation through a `git-*` skill, and the only one for branches stopped on `Cannot rename a protected branch`, so the first act of any feature, creating its branch, had no skill to go through.
+
 ## Must
 
 - Read the branch format reference before generating, so the type vocabulary and the length limit come from one source
-- Derive the name from the commits ahead of main when the invocation carries no description
+- Create the branch on `main` or `master` and rename it anywhere else, so one skill covers both ends of a branch's start
+- Derive the name from the commits ahead of main when a rename carries no description
+- Take a created name from `canon tasks plan-branch` when the invocation names a plan, so the skill and the dispatch gate hold one derivation
 - Resolve whether the branch exists on the remote before proposing a rename, since the hazard is invisible from local state
-- Show the name and its length against the limit before renaming
+- Read the remote itself with `git ls-remote` before creating, since `origin/<name>` sees only the last fetch
+- Show the name and its length against the limit before renaming or creating
 - Execute immediately after the preview. The tool permission dialog is the confirmation gate.
 
 ## Must not
@@ -22,17 +27,23 @@ Without this skill, a branch name is invented once per session. The type prefix
 - Rename `main` or `master`
 - Rename when the current name already conforms. The skill is chained, so a conforming name has to pass through rather than churn the branch.
 - Rename a branch that exists on the remote. Local rename plus force push is not the same operation and it breaks the pull request.
+- Create a branch from anywhere but `main` or `master`, or create one whose name exists locally or on the remote
+- Invent a name when the plan verb refuses, since a name the skill calls non-conforming strands the rename at ship
+- Fetch or stash while creating
 - Emit anything after the result line
 
 ## Guards
 
-- On a protected branch: stop and say the branch is protected
-- Name already conforms: stop with a success marker, not a failure, since a chained caller continues past it
-- No commits and no description: stop and name both missing inputs
-- Branch exists on the remote: stop and route to the surface that preserves the pull request link
+- Create with no plan and no name: stop and name both missing inputs
+- Create with a name breaking the branch standard: stop and name the cap
+- Create with a name existing locally or on the remote: stop and say which
+- Rename name already conforms: stop with a success marker, not a failure, since a chained caller continues past it
+- Rename with no commits and no description: stop and name both missing inputs
+- Rename of a branch existing on the remote: stop and route to the surface that preserves the pull request link
 
 ## Out of scope
 
 - The commit message, which `git-commit` owns
 - Pushing and opening the pull request, which `git-pr` owns. That skill reads a conforming name as a precondition and refuses without one, so this skill runs first.
 - Splitting a branch whose commits span concerns, which `git-split` owns
+- Entering a worktree, which `session-worktree` owns and which names its own branch

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

@@ -1,6 +1,6 @@
 ---
 name: git-branch
-description: Generates and validates conventional branch names. Use for any branch naming or renaming, such as when asked to "name this branch".
+description: Generates and validates conventional branch names, creating the branch from main or master and renaming it anywhere else. Use for any branch naming, creating, or renaming, such as when asked to "name this branch" or "create the branch for this feature".
 metadata:
   family: ship
 ---
@@ -13,7 +13,64 @@ Before generating a branch name, read:
 
 Follow it exactly.
 
-## Context
+Run `git branch --show-current` to pick the mode. On `main` or `master` the skill creates a branch, and anywhere else it renames the current one.
+
+## Create mode
+
+### Name
+
+Take the name from the invocation. An argument ending in `.md` or resolving under `.canon/plans/` is a plan, and anything else is a branch name, since a name always carries a `<type>/` segment.
+
+- For a plan, run `canon tasks plan-branch <plan> --json` and take the record's `branch`. The verb fixes the type at `feat`, so a plan never yields another type.
+- When the verb refuses or the record carries `conforms: false`, stop and relay its reason. Never invent a name in its place.
+- For a name, check it against the whole Format section of `branch.md`, including the description word bound and the no-repeated-type rule, as the rename guard does.
+
+### Context
+
+Run these in parallel once the name is known:
+
+- `git show-ref --verify --quiet "refs/heads/<name>" && echo "LOCAL_EXISTS" || echo "LOCAL_FREE"`
+- `git ls-remote --exit-code --heads origin "<name>" 2>/dev/null; echo "REMOTE_EXIT=$?"`
+
+Exit 0 on the remote read is a collision. Exit 2, or a repository with no `origin`, is no collision. The check reads the remote itself, never `origin/<name>`, which sees only the last fetch. The skill does not fetch.
+
+### Guards
+
+Each guard stops before any ref moves.
+
+- If the invocation carries no plan and no name, stop: `❌ No plan or branch name to create from.`
+- If the name breaks `branch.md`, stop and name the cap it broke: `❌ <name> breaks the branch standard: <cap>.`
+- If the name exists locally, stop: `❌ Branch <name> already exists locally.`
+- If the name exists on the remote, stop: `❌ Branch <name> already exists on origin.`
+
+### Preview
+
+Output the preview first.
+
+- **Current:** <main_or_master>
+- **Creating:** <name>
+- **Length:** <count>/50
+- **Source:** <plan | name>
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Final command
+
+The branch starts at the current tip, and uncommitted changes carry onto it. The skill stashes nothing.
+
+```bash
+git switch -c <name>
+```
+
+### After execution
+
+Respond with exactly one line and add no other text:
+
+`✅ Created: <name>`
+
+## Rename mode
+
+### Context
 
 Run these commands in parallel to gather git context:
 
@@ -21,14 +78,13 @@ Run these commands in parallel to gather git context:
 - `git rev-parse --verify "origin/$(git branch --show-current)" 2>/dev/null && echo "EXISTS" || echo "LOCAL_ONLY"`
 - `git log main..HEAD --oneline 2>/dev/null || echo "NO_COMMITS"`
 
-## Guards
+### Guards
+
+A conforming name passes through, so a chained caller continues past it.
 
-- If already on main or master, stop: `❌ Cannot rename a protected branch.`
 - If branch name already follows conventions, stop: `✅ Branch name already follows conventions.`
 - If no commits and no args provided, stop: `❌ No commits or description to derive a branch name from.`
 
-## Response format
-
 ### Preview
 
 Output the preview first.
@@ -55,7 +111,7 @@ Only output if LOCAL_ONLY:
 git branch -m <current> <suggested>
 ```
 
-## After execution
+### After execution
 
 Respond with exactly one line and add no other text:
 

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

@@ -25,11 +25,17 @@ Does not govern:
 
 ### Description content
 
+The description names the change, and 2 words stays the target.
+
 - 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`)
 
-The upper bound reads 4 rather than 3 for every branch, whoever named it. It was widened so that a branch taking its description from a planning document's own filename stops being renamed at ship, since a rename there is a third derivation and parts the branch from the filename that later tooling reads back to find the document. Nothing can tell such a name from any other, so the wider bound holds for all of them and 2 words stays the target.
+### Why the bound reads 4
+
+The upper bound reads 4 for every branch, whoever named it, so a branch taking its description from a planning document's filename is not renamed at ship. A rename there is a third derivation, and it parts the branch from the filename later tooling reads back to find the document.
+
+Nothing can tell such a name from any other, so the wider bound holds for all of them.
 
 ## Types
 
@@ -51,6 +57,8 @@ The upper bound reads 4 rather than 3 for every branch, whoever named it. It was
 
 ### Correct
 
+Each line names its reason after the `#`.
+
 ```plaintext
 feat/jwt-expiration                    # clear feature scope
 fix/AUTH-123-connection-pool           # includes ticket ID
@@ -59,6 +67,8 @@ refactor/remove-deprecated-endpoints   # clear refactor intent
 
 ### Incorrect
 
+Each line names its fault after the `#`.
+
 ```plaintext
 feature/auth_stuff                                        # wrong type + underscore
 feat/feature-add-login                                    # duplicates type in description

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

@@ -16,11 +16,20 @@ Does not govern:
 
 ## The transform
 
-Run `git branch --show-current`. Drop a leading segment naming one of the types `branch.md` defines when a further segment follows it, then replace every remaining `/` with `-`. The result is `<slug>`. Anything reading a branch-derived name uses this transform, so two surfaces cannot spell it differently.
+Run `git branch --show-current`. Drop a leading segment naming one of the types `branch.md` defines when a further segment follows it, then replace every remaining `/` with `-`. The result is `<slug>`, and anything reading a branch-derived name uses this transform, so two surfaces cannot spell it differently.
 
-The type comes off because a plan takes its slug from the concern it covers and the branch executing that plan carries the same slug behind a type prefix. Keeping the prefix sends every surface that finds a plan from a branch name looking for `feat-jwt-expiration`, which no plan is filed under. A first segment matching no type stays, so `spike/parser` still yields `spike-parser`.
+### Why the type comes off
 
-A surface that persists output to a shared folder carries the slug in the filename, which is what keeps parallel worktrees from overwriting each other's output. Two branches differing only in type collapse onto one slug. That collision reaches the worktree directory as well, since it takes its name from the same string, so the branch is not where it would first surface.
+A plan takes its slug from the concern it covers, and the branch executing it carries the same slug behind a type prefix. Keeping the prefix sends every surface that finds a plan from a branch name looking for `feat-jwt-expiration`, which no plan is filed under.
+
+- A first segment matching no type stays, so `spike/parser` still yields `spike-parser`
+
+### Slugs in shared folders
+
+A surface persisting output to a shared folder carries the slug in the filename, which keeps parallel worktrees from overwriting each other's output.
+
+- Two branches differing only in type collapse onto one slug
+- That collision reaches the worktree directory too, since it takes its name from the same string, so the branch is not where it first surfaces
 
 ## An empty result
 
@@ -32,8 +41,11 @@ The empty result is a detached HEAD, and the surface picks one of three response
 
 ## Changing the transform
 
-A change here moves what the transform produces, and every declaration asserting the old output keeps asserting it. Nothing reports those, because a fixture carrying an old filename names neither this file nor the surface that reads it, so a diff over the change reaches none of them. Dropping the type segment is the change that proved it: four fixtures and three scenario scripts kept the type-carrying spelling, one surfaced as a red arm months later, and the other six were found by deriving from the rule.
+A change here moves what the transform produces, and every declaration asserting the old output keeps asserting it. A fixture carrying an old filename names neither this file nor the surface reading it, so a diff over the change reaches none of them.
+
+Run `canon gov superseded <old> <new>` in the same change, with the old output and the new one as the two arguments. The value is the only key both sides carry, and the sweep reads the whole tracked tree rather than a path someone predicted.
 
-Run `canon gov superseded <old> <new>` in the same change, with the old output and the new one as the two arguments. The value is the only key both sides carry, and the sweep reads the whole tracked tree rather than a path someone predicted. Its output is a reading rather than a verdict, since a string appears for reasons unrelated to any convention, and a declaration disagreeing on purpose carries a `canon-allow-superseded: <reason>` marker on its own line or the one above.
+- Its output is a reading rather than a verdict, since a string appears for reasons unrelated to any convention
+- A declaration disagreeing on purpose carries a `canon-allow-superseded: <reason>` marker on its own line or the one above
 
 The sweep sees a value and nothing else. A prose reference that went stale without carrying it, such as a passage citing the wrong standard for the transform, is reached by reading rather than by any key.