@erclx/canon 5.38.0 → 5.39.0

package/claude/skills/context-fold/references/context.md

@@ -22,7 +22,7 @@ Applies to per-domain narrative entries under `canon/context/`. Skip for `index.
 
 ## Scope
 
-Governs per-domain narrative entries under `canon/context/`: their structure, the decisions and gotchas they carry, and what they leave to the code.
+Governs the structure of per-domain narrative entries under `canon/context/`, the folders and traps they carry, and what they leave to the code.
 
 Does not govern:
 
@@ -33,19 +33,20 @@ Does not govern:
 
 ## Organizing principle
 
-Weight the entry toward what cannot be re-derived from the repo. That single rule sorts every section below.
+Weight the entry toward what a session cannot cheaply re-derive from the repo, and keep it true of the repository today. That single rule sorts every section below.
 
-- Folder structure is re-derivable with `ls`. Cheap to regenerate, expensive to maintain by hand. Cap it hard.
-- Command surfaces are re-derivable with `--help` and already live in the CLI reference under `docs/`. Duplicating flag lists creates a second source of truth that drifts.
-- Decisions and gotchas cannot be re-derived at any price. They are the reason the folder exists.
+- A folder list is re-derivable with `ls`, so Layout spends its words on what each working folder does rather than on naming it
+- Command surfaces are re-derivable with `--help` and already live in the CLI reference under `docs/`, so a copied flag list is a second source of truth that drifts
+- How the domain reached its shape is in git and the pull request that changed it, so the entry carries no decisions and no history
+- A trap the code does not self-document costs a session a failed run to find, so it earns a line
 
 ## What a working entry looks like
 
 An entry works when a session can read it and answer three questions without opening source:
 
-- Where do things live in this domain?
-- Why are they that way?
-- How do I add one more of what this domain holds?
+- What does this domain own, and where does its boundary sit?
+- What does each folder in it do now?
+- Which trap would I hit working here?
 
 An entry that fails these is non-conforming regardless of whether it satisfies every section and ordering rule below. Shape is the means. These three questions are the test.
 
@@ -58,25 +59,32 @@ Both fields feed `canon/context/index.md` when regenerated.
 
 ## The closed set
 
-An entry carries four H2 sections and no other, in this order: `Overview`, `Layout`, `Decisions`, `Gotchas`. `canon context audit` reports any other H2 and `--gate` fails it. A topic of the domain's own, such as `Cache` or `Workflow`, is an H3 under one of the four, which is where a reader scanning the entry looks for it.
+An entry carries three H2 sections and no other, being `Overview`, `Layout`, and `Gotchas` in that order. `canon context audit` reports any other H2 and `--gate` fails it.
 
-- `## Overview`: two to four lines. What the domain owns and where its boundary sits. Required.
-- `## Layout`: one line per folder in owns-X form, folders only and never files. Required, and omitted where the domain owns no paths in the repo, as with a domain covering external tools. Inventing a line to satisfy the heading is the padding banned below.
-- `## Decisions`: non-obvious choices and the reasoning behind them, each as an H3 or a bullet. The highest-value section in the folder and the one most often missing. A decision resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence naming the harm the decision prevents, and a decision resting on the project's own code takes none.
-- `## Gotchas`: workarounds, things tried and rejected, and invariants the code does not self-document, such as shape constraints, skip rules, and header semantics. Use `## Decisions` when the reader needs the reasoning rather than the invariant itself.
+- `## Overview`: two to four lines on what the domain owns and where its boundary sits. Required.
+- `## Layout`: the folders the domain owns, described below. Required unless the domain owns no paths, as with one covering external tools, since an invented line is padding.
+- `## Gotchas`: at most five one-line bullets, each a trap true today. No H3, no paragraph, and no history. Omit the section when the domain has no trap.
 
-Include `Decisions` and `Gotchas` whenever the domain has content for them, and never pad an entry with an empty heading.
+`## Decisions` is retired. The audit reports one everywhere and gates it under a folder rebuilt to this shape, alongside the Gotchas and Layout caps below.
 
-### Where an extra topic goes
+### Layout
 
-- A command surface goes under `## Layout` as an H3, only when the domain has one, and only as a list of what each verb does. Flags and JSON shapes stay in the CLI reference under `docs/`, linked rather than restated.
-- The procedure for the domain's most common task goes under `## Layout` as an H3 such as `### Adding a <thing>`, since most sessions arrive asking how to add one more of the thing the domain holds.
-- Implementation detail that the one-line owns-X form cannot carry moves to `## Decisions` or `## Gotchas`.
+Layout gives each folder doing real work its own H3, titled with the folder path in a code span, such as ``### `src/design/` ``.
+
+- Open the H3 with a lead of one short paragraph stating what the folder does
+- Follow it with at most five bullets on what the folder does now
+- Put every trivial folder under `### Other folders` as a one-line bullet in owns-X form
+- Name folders only, never files, and write no decisions and no history under any H3
+- Write no heading below H3 under `## Layout`
+
+The audit reports a Layout H3 titled neither a path nor `Other folders`, a folder H3 holding a second paragraph or a sixth bullet, and any H4 under Layout. Bullets count at any indent and across any paragraph, so a list split by a bold label still counts as one list.
 
 ### Ordering and headings
 
-- Name a heading for its subject as it stands (`### Cache`), never for the event that shaped it (`### The cache was the untested part, and the test moved it`). A heading is what a scan reads, so a narrating heading turns the table of contents into a changelog.
-- Entries get read top-down and often partially, so irreducible content sits above recoverable content.
+Entries get read top-down and often partially, so the boundary sits above the folders and the folders above the traps.
+
+- Name a heading for its subject as it stands, never for the event that shaped it, since a heading is what a scan reads
+- A narrating heading such as `### The cache was the untested part, and the test moved it` turns the table of contents into a changelog
 
 ## The development entry
 
@@ -86,60 +94,77 @@ Only the `development` entry carries this section, as an H3 under `## Layout`. I
 
 ## What goes in
 
-- Per-domain narrative on how the code is structured and why
-- Decisions that constrain the domain, whether or not their reasoning touches another one. A decision lives in the entry of the domain it constrains.
-- Constraints, gotchas, things tried and rejected
-- Domain-specific conventions that do not fit a `paths:`-scoped rule
+- What the domain owns and where its boundary sits
+- What each working folder does now
+- Traps a session would hit, being shape constraints, skip rules, header semantics, and invariants the code does not self-document
 
 ### Figures and references
 
-- A measured figure, closed with a trailing `Measured at <short-sha> on <YYYY-MM-DD>.` naming a commit rather than a pull request number or a branch. Carry one anchor per figure and rewrite it in place when the number is re-read, whether or not it moved. An absent anchor reads as unchecked.
-- A reference to another entry, spelled as the path that entry sits at rather than as its bare filename. A bare name resolves against whichever folder the reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A reference to a seed, a standard, or a file the project owns elsewhere keeps the form its own surface uses.
+A measured figure and a reference to another entry each take a form that keeps them checkable.
+
+- Close a measured figure with `Measured at <short-sha> on <YYYY-MM-DD>.`, naming a commit rather than a pull request number or a branch
+- Carry one anchor per figure and rewrite it in place whenever the number is re-read, whether or not it moved, since an absent anchor reads as unchecked
+- Spell a reference to another entry as the path that entry sits at, never as its bare filename
+- A bare name resolves against whichever folder the reader is in, so a domain splitting into subfolders strands every inbound reference silently
+- A reference to a seed, a standard, or a file the project owns elsewhere keeps the form its own surface uses
 
 ## What does not go in
 
-- Exhaustive file trees with a description per file. Name folders and their responsibility under `## Layout` instead.
+- Exhaustive file trees with a description per file. Describe the folder under its Layout H3 instead.
 - Restated `--help` output, flag tables, or JSON shapes.
 - A catalog a `list` command already returns. Link the command instead, so the entry cannot drift from it.
-- Function-level documentation for implementation modules. Read the code. The exception is the public surface of a shared utility module, where the entry is how a session finds an existing helper instead of duplicating it.
+- Function-level documentation for implementation modules. The exception is a shared utility module's public surface, where the entry is how a session finds a helper rather than duplicating it.
 
 ### Elsewhere
 
+Some content belongs to another surface entirely.
+
 - Rules. Those go in `.claude/rules/<scope>.md` with a `paths:` glob.
-- Tutorials or human onboarding. Those go in `docs/` if a public audience exists.
+- Tutorials or human onboarding, which go in `docs/` if a public audience exists
 - Generated content (API references). Generate, do not write by hand.
 - Anything already in `canon/REQUIREMENTS.md`.
 
-### History and results
+### History and decisions
 
-- The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
-- A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
-- The route to a decision: the rounds of candidates, the tuning steps a threshold passed through, the review pass that caught a miss. State the decision, what lost, and why, once and in the present tense. Cut the route. Git and the change that introduced it keep it.
-- Measured results a generated file already carries. Point at the file instead of copying the figure, so a re-run cannot leave the entry behind.
+An entry describes the repository as it stands, so the route that reached it lives in git and the change that introduced it.
+
+- A decision and its rejected alternative, which the pull request carrying the change records
+- The history of how the domain reached its current shape. A change number, release label, or date attached to a change goes wherever the project tracks work.
+- The route to a choice, being the rounds of candidates, the tuning steps a threshold passed through, and the review pass that caught a miss
+- Measured results a generated file already carries. Point at the file instead, so a re-run cannot leave the entry behind.
 
 ## Length
 
-- Aim for one entry per domain. Length is a symptom, not the defect, and the one hard cap is the whole-document ceiling `markdown.md` states.
-- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. The 150 is a diagnostic checkpoint and never gates. Rendered lines count as `markdown.md` defines them.
-- Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` section or an H3 under it instead.
+- Aim for one entry per domain. The section shape and the density limits `markdown.md` states bound the size, and the one hard cap is the whole-document ceiling it states.
+- Past roughly 150 rendered lines, check whether the entry still covers one domain, has filled with content `ls` or `--help` reproduces, or has accumulated its own history
+- Fix whichever is true rather than trimming. The 150 is a diagnostic checkpoint that never gates, counted in rendered lines as `markdown.md` defines them.
 
 ### Retiring and rewriting
 
-- Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
-- Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.
+An entry states the repository that stands, so a bullet changes when its subject does.
+
+- Edit a bullet that went untrue in place, and never append the correction beside it, since two bullets on one subject leave a reader to work out which is current
+- Retire a gotcha once its trap is gone, rather than narrating what fixed it
+- Drop a folder's H3 when the folder is removed, and move it when the folder moves
 
 ### Splitting and naming
 
-- Split into a folder (`canon/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
-- Group whole single-file entries of two or more small domains into one folder when they share a kind, such as small feature domains that each own a verb. Each entry still covers one domain, and the folder's generated `index.md` carries a `subtitle` naming the kind. It names an entry to start with only when that entry frames the others. A grouping folder is not a split, so no entry inside it is a sub-area of another.
-- Name an entry inside a split or grouping folder per the `codebase-layout` skill, which never repeats the folder's name as the entry's stem or prefix.
-- Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
-- Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and turns a one-line edit into a whole-file rewrite that conflicts with any sibling branch. This is what forced the split above.
+A domain outgrowing the ceiling splits into a folder, and small domains of one kind group into one.
+
+- Keep one entry per domain, and split into a folder (`canon/context/<domain>/<sub-area>.md`) only when the rebuilt entry passes the 300-line ceiling `markdown.md` states, never on a count of sub-areas
+- Group the single-file entries of two or more small domains into one folder when they share a kind, such as small feature domains that each own a verb
+- A grouping folder is not a split, so each entry in it covers one domain. Its generated `index.md` carries a `subtitle` naming the kind, and an entry to start with only when one frames the others.
+- Name an entry inside either folder per the `codebase-layout` skill, which never repeats the folder's name as the entry's stem or prefix
+- Keep a split domain's `index.md` generated, since regen rewrites its body. The domain's own overview and layout go in a sibling file, which the `subtitle` names.
+
+Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and conflicts with any sibling branch.
 
 ## Examples
 
 ### Template
 
+Each working folder takes an H3 with a one-paragraph lead and at most five bullets, and the rest sit under `### Other folders`.
+
 ```markdown
 ---
 title: API
@@ -156,31 +181,21 @@ never the reverse.
 
 ## Layout
 
-- `src/routes/` owns the HTTP layer and request parsing
-- `src/services/` owns business logic with no HTTP concerns
-- `src/db/` owns persistence and schema migrations
-
-## Decisions
+### `src/routes/`
 
-### Validation at the route boundary
+Parses each request, validates it against its schema, and calls one service.
 
-Validation happens at the route boundary using a schema library. Services trust their inputs.
+- Validation runs at the route boundary, so a service trusts its inputs
+- Every handler issuing a cursor uses the shared encoder
+- A handler returns a plain object, and the serializer wraps it in `{ data, meta }`
 
-### Opaque pagination cursors
+### Other folders
 
-Pagination uses opaque cursor tokens, never offset+limit. Cursor format stays opaque to clients, which is why any handler that issues a cursor uses the shared encoder.
+- `src/services/` owns business logic with no HTTP concerns
+- `src/db/` owns persistence and schema migrations
 
 ## Gotchas
 
-### The health endpoint skips auth
-
-The `/health` endpoint skips auth middleware. Liveness probes from the orchestrator do not carry tokens.
-
-### The connection pool caps at 50
-
-Concurrent requests over that block until a connection frees.
-
-### Handlers never wrap their return
-
-Route handlers return a plain object, and the serializer wraps it in `{ data, meta }`.
+- The `/health` endpoint skips auth, since liveness probes carry no token
+- The connection pool caps at 50, and a request past it blocks until one frees
 ```

package/claude/skills/create-rule/SKILL.md

@@ -7,7 +7,9 @@ metadata:
 
 # Create rule
 
-Author a project-local governance rule. The rule lives in the target project, not the toolkit, so `canon gov sync` never overwrites it: the sync engine orphans anything under `.claude/rules/project/` by location, before it ever checks the rule's name against the toolkit catalog. A rule written anywhere else under `.claude/rules/` survives the sync too, and the report offers it the path under the project subfolder it would take.
+Author a project-local governance rule. The rule lives in the target project, not the toolkit, so `canon gov sync` never overwrites it.
+
+The sync engine orphans anything under `.claude/rules/project/` by location, before checking its name against the toolkit catalog. A rule elsewhere under `.claude/rules/` survives too, and the report offers it the path under the project subfolder.
 
 ## Guards
 
@@ -49,9 +51,11 @@ A rule's filename is its slug alone, a one-to-three-word kebab topic with no num
 
 Read `${CLAUDE_SKILL_DIR}/references/rule.md` for frontmatter, body shape, and voice before writing the body. Do not work the shape from memory.
 
-Write `.claude/rules/project/<subdir>/<slug>.md`. Preview the resolved path, subdir, slug, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
+Write `.claude/rules/project/<subdir>/<slug>.md`. Preview the resolved path, subdir, slug, and frontmatter, then write immediately, since the tool permission dialog is the confirmation gate.
 
-Frontmatter carries the Claude shape. Path-scoped rules emit one `paths:` entry per glob. Always-on rules omit `paths:` entirely.
+- Frontmatter carries the Claude shape
+- Path-scoped rules emit one `paths:` entry per glob
+- Always-on rules omit `paths:` entirely
 
 ```markdown
 ---

package/claude/skills/create-skill/SKILL.md

@@ -12,7 +12,7 @@ Read these files in parallel:
 - `${CLAUDE_SKILL_DIR}/references/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
 - `${CLAUDE_SKILL_DIR}/references/skill-requirement.md`: what `REQUIREMENT.md` must answer, its sections, and its template
 - `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites another skill's reference
-- `${CLAUDE_SKILL_DIR}/references/skill-disclosure.md`: the rules that bind a skill of any size, being where each reference is named, the contents block, the trigger and guard that stay in the body, and what moves to `references/`
+- `${CLAUDE_SKILL_DIR}/references/skill-disclosure.md`: where each reference is named, the contents block, the trigger and guard that stay in the body, and what moves to `references/`
 
 ### Writing standards
 
@@ -32,17 +32,37 @@ Read these in the same pass:
 
 ## Steps
 
-1. Answer three questions in writing before drafting anything. Tell the user and stop if a rule, a verb, or an existing skill already reaches this moment, or if the body carries no procedure a session would get wrong from first principles. A non-interactive run stops on both too, reporting which question failed and writing no folder:
+1. Answer three questions in writing before drafting anything.
    - Does a rule, a verb, or an existing skill already reach this moment? A folder that only wraps something already reachable duplicates it rather than adding to the catalog.
    - Does the body carry a procedure a session would get wrong from first principles? A one-line wrapper around a single command needs no skill.
    - Will anything invoke it other than the author typing its name? Carry this one into the drafted `REQUIREMENT.md`'s `Must not` section as a review criterion instead, since nothing can answer it before the skill has run.
+   - Tell the user and stop when the first answer is yes or the second is no. A non-interactive run stops on both too, reporting which question failed and writing no folder.
 2. Draft the full `SKILL.md` from the user's description, stating the current rule alone. An incident and the date it happened belong in the requirement's `Gap`, not in the body or a reference.
-3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the requirement standard states. Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
-4. Confirm the skill name and both files with the user before writing, when a person can answer. Skip the confirmation when `CANON_NON_INTERACTIVE=1` is set or another skill's run invoked this one, such as `auto-ship` or a dispatched worker. Then put the three Step 1 answers and the two drafted paths in the output and continue to Step 5, since a question nobody reads parks the chain.
-5. Resolve the root, then write `<root>/<name>/SKILL.md` and `<root>/<name>/REQUIREMENT.md`. The root is `.claude/skills/` in a target project. Where the project root holds `claude/.claude-plugin/plugin.json`, which is the toolkit's own checkout, the name decides: an `internal-*` skill goes under `.claude/skills/` and every other skill goes under `claude/skills/`, since the plugin ships that tree.
-6. Run `canon claude skills audit --json` and read `findings.datedProvenance` for rows under `<root>/<name>/`. Move each row's incident into `REQUIREMENT.md` under `Gap`, cut the date from the file the row names, and re-run until no row names the folder.
+3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the requirement standard states.
+   - Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
+4. Confirm the skill name and both files with the user before writing, when a person can answer.
+   - Skip the confirmation when `CANON_NON_INTERACTIVE=1` is set or another skill's run invoked this one, such as `auto-ship` or a dispatched worker.
+   - Then put the three Step 1 answers and the two drafted paths in the output and continue to Step 5, since a question nobody reads parks the chain.
+
+### Write and check
+
+Steps 5 to 7 write the folder and check what landed before the run reports.
+
+5. Resolve the root, then write `<root>/<name>/SKILL.md` and `<root>/<name>/REQUIREMENT.md`.
+   - The root is `.claude/skills/` in a target project.
+   - Where the project root holds `claude/.claude-plugin/plugin.json`, which is the toolkit's own checkout, an `internal-*` skill goes under `.claude/skills/` and every other skill under `claude/skills/`, since the plugin ships that tree.
+6. Run `canon claude skills audit --json` and read `findings.datedProvenance` for rows under `<root>/<name>/`.
+   - Move each row's incident into `REQUIREMENT.md` under `Gap`, cut the date from the file the row names, and re-run until no row names the folder.
    - When `canon` does not resolve or its record carries no `datedProvenance` key, say the check did not run rather than reporting the skill clean.
+7. Run `canon markdown audit <root>/<name>/` over the new body and any references, and fix every ban and density finding it reports.
+   - Re-run it until it reports none, since every file in the folder is this run's draft.
+   - When `canon` does not resolve, say the audit did not run rather than reporting the folder clean.
 
 Every skill carries a requirement. A skill created without one is a gap someone closes in a later sweep, and the sweep has to reconstruct what the skill was for from the body it already shipped.
 
-The two-question check has a shipped precedent. A pull request dropped `git-stash` for wrapping a single git command that needed no skill body, and `release-changelog` for being low-frequency and invoked by no other skill. The first is question one, and the second is question three read back after the fact, which is why it stays a review criterion rather than something this skill can gate on.
+The two-question check has a shipped precedent:
+
+- A pull request dropped `git-stash` for wrapping a single git command that needed no skill body, which is question one
+- It dropped `release-changelog` for being low-frequency and invoked by no other skill, which is question three read back after the fact
+
+That is why the third question stays a review criterion rather than something this skill can gate on.

package/claude/skills/create-skill/references/skill-reference.md

@@ -47,31 +47,44 @@ A reference failing these questions is non-conforming even when it satisfies eve
 
 ### Declaring scope
 
+A reference that specifies shape exhaustively and jurisdiction nowhere cannot refuse a rule, so the rule with no obvious owner lands in whichever reference sits nearest.
+
 - Govern one document type per reference, or one attribute across every document. Split unrelated conventions into separate files.
-- Open with a `## Scope` section stating what the reference governs and what it does not, placed above the shape rules. A reference that specifies shape exhaustively and jurisdiction nowhere cannot refuse a rule, so the rule with no obvious owner lands in whichever reference sits nearest.
+- Open with a `## Scope` section stating what the reference governs and what it does not, placed above the shape rules
 - Write it as one line naming the artifact or attribute and where it applies, then a `Does not govern:` list. Give each entry the excluded concern and the owner it goes to.
 
-#### The path and owners
+### The path and owners
+
+The scope line names the governed path, and each exclusion names its owner.
+
+- Name an owner in the same `references/` folder by bare filename, and one in another skill by its sibling path, `../<skill>/references/<name>.md`
+- Name the surface instead where the owner is one, such as a coding rule, a project policy, or the code
+- Put the governed path in backticks inside the first sentence of that line, anchored deep enough to resolve from a project root, since a bare folder name matches a same-named folder elsewhere
+- A path held back until a later sentence sits beside every other path the statement mentions, including the ones it excludes
+- Say in that same sentence when the reference governs an attribute, since an attribute has no path to name and the silence reads as an omission unless the sentence claims it
 
-- Name an owner in the same `references/` folder by bare filename and one in another skill by its sibling path, `../<skill>/references/<name>.md`. Name the surface instead where the owner is one, such as a coding rule, a project policy, or the code.
-- Put the governed path in backticks inside the first sentence of that line, anchored deep enough to resolve from a project root. A bare folder name matches a same-named folder elsewhere in the tree, and a path held back until a later sentence sits beside every other path the statement mentions, including the ones it excludes.
-- Say in that same sentence when the reference governs an attribute rather than a document type. An attribute is written across every document and has no path to name, so the silence reads as an omission unless the sentence claims it.
-- Cut an entry that names no owner at all. It is either excluding something nothing was going to claim, or it is a content exclusion, which the rule below sends to the shape rules instead.
+Cut an entry that names no owner at all. It is either excluding something nothing was going to claim, or it is a content exclusion, which the rule below sends to the shape rules instead.
 
-#### Boundaries
+### Boundaries
 
-- Declare a boundary from both sides. A yield, an exemption, or a handoff stated in one reference alone is never checked against the reference on the other side of it, which is how two files come to claim the same rule or neither does.
-- Separate a jurisdiction exclusion from a content exclusion. The first names a concern another reference owns and belongs in `## Scope`. The second names what does not belong inside the document and stays with the shape rules. Merging them puts a boundary claim where no sibling will read it.
+A yield, an exemption, or a handoff stated in one reference alone is never checked against the reference on the other side, which is how two files come to claim the same rule or neither does.
+
+- Declare a boundary from both sides
+- Separate a jurisdiction exclusion, naming a concern another reference owns, which belongs in `## Scope`, from a content exclusion, which stays with the shape rules
+- Merging the two puts a boundary claim where no sibling will read it
 - Stay silent on a section the reference holds today but should not own. Claiming it makes the scope statement false the moment it moves, and the mismatch is the evidence that moves it.
 
 ### Naming the file
 
-- Name the file for the artifact the scope statement governs, taking the word from the deepest path segment that names the artifact rather than the folder holding it. `plan.md` over `.canon/plans/feature-<slug>.md` and `session.md` over `.canon/tasks/session-<slug>.md` both follow it.
+Name the file for the artifact the scope statement governs, taking the word from the deepest path segment that names the artifact rather than the folder holding it. `plan.md` over `.canon/plans/feature-<slug>.md` and `session.md` over `.canon/tasks/session-<slug>.md` both follow it.
 
 ### Staying inside it
 
-- Name no path, filename, or folder outside the document type the reference governs. A reference reaches projects whose layout is their own, so a path borrowed from the authoring repository is wrong in a target and nothing reports it.
-- State the rule, never the mechanism enforcing it. Hooks, scripts, checks, and skill catalogs are facts about one repository. Name the condition the document must meet and let the enforcing surface name its own case.
+A reference reaches projects whose layout is their own, so what it names holds in any of them.
+
+- Name no path, filename, or folder outside the document type the reference governs, since a path borrowed from the authoring repository is wrong in a target and nothing reports it
+- State the rule, never the mechanism enforcing it, since hooks, scripts, checks, and skill catalogs are facts about one repository
+- Name the condition the document must meet, and let the enforcer name its own case
 - Invent inline examples rather than citing a real file elsewhere in the project. A cited file moves or is deleted and the reference goes stale in silence.
 
 ## Frontmatter
@@ -82,9 +95,10 @@ A reference failing these questions is non-conforming even when it satisfies eve
 
 ## Structure
 
-- Use sentence case for every heading
+- Use sentence case for every heading, and stop at `###`, since `markdown.md` allows no deeper one
 - Flat `##` rule groups for a single-topic reference. Group `##` headers by concern for a multi-topic one.
-- When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
+- When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one per sub-concern, each opening with a lead sentence
+- A flat bullet list under an `##` covers a single sub-concern, and a run past the bullet limit `markdown.md` states is the signal to split it
 - Order groups from the most-used rule down to the edge case
 
 ## Rules
@@ -93,7 +107,7 @@ A reference failing these questions is non-conforming even when it satisfies eve
 - State the forbidden shape rather than enumerating allowed options, so a rule survives new categories
 - Cut any rule that resists a crisp one-line phrasing
 - Do not pad with filler prose. Every line earns its place as a usable reference entry.
-- Close a ban asserting how the model or a tool behaves with one `Revisit when <finding>.` sentence, since that claim can stop holding while the ban reads the same. A style, safety, or consistency ban takes none, and filling one with a condition is padding.
+- Close a ban asserting how the model or a tool behaves with one `Revisit when <finding>.` sentence, since that claim can stop holding. A style, safety, or consistency ban takes none.
 
 ## Success criterion
 
@@ -115,7 +129,8 @@ Answer all four before editing, and carry the answers into wherever the change i
 
 ### What justifies a change
 
-- Change a reference on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
+Change a reference on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y, and a failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
+
 - Park findings wherever the project tracks pending work, or in the reference's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
 - Cite the failing artifact in the change that fixes it, so the next reader can tell which rules were paid for by evidence.
 
@@ -129,17 +144,22 @@ Answer all four before editing, and carry the answers into wherever the change i
 ## Template
 
 - Carry one fenced template of the document the reference governs, so an author copies a shape instead of reconstructing it from prose.
-- Bind this to a reference governing a document type. An attribute reference governs a scan, a string, or a label rather than a file, so it has no document to template and carries none. State that exemption in the sentence declaring it an attribute reference.
+- Bind this to a reference governing a document type. An attribute reference governs a scan, a string, or a label rather than a file, so it carries none.
+- State that exemption in the sentence declaring it an attribute reference
 - Place the template below the rules it satisfies, under a `## Template` heading or inside the section holding those rules.
 
 ### What the template shows
 
+The template is a skeleton an author fills, never a document of its own.
+
 - Show the skeleton alone: every required section, one placeholder line for what each holds. A full worked document is a second document to maintain.
 - Write placeholders in angle brackets rather than copying a real document. A copied file goes stale, and its backticked filenames read as citations to anything parsing the reference.
 - Switch to a bare word where the fenced language reads `<` as syntax of its own, as Mermaid and HTML do, and say in the line above the fence that the names are placeholders.
 
 ### Load-bearing text
 
+The template is the only place an author learns which strings a consuming tool parses.
+
 - Carry any header, key, or label a consuming tool parses verbatim. The template is the only place an author learns which strings are load-bearing.
 - Treat the template as authoritative where it and the prose disagree. An author copies the block, so a contradiction ships as the block.
 
@@ -178,6 +198,10 @@ A <document type> failing these is non-conforming even when it satisfies every s
 
 ## <Shape rule group>
 
+### <Sub-concern>
+
+<A lead sentence naming what this sub-concern decides.>
+
 - <imperative rule, one concern per bullet>
 
 ## Template

package/claude/skills/decision-escalate/SKILL.md

@@ -15,7 +15,7 @@ One batch is the whole point. A session that asks one question, acts, then asks
 ## Guards
 
 - If nothing is open, stop: `❌ Nothing to escalate. Every open call is one this session can make.`
-- Escalate only a decision whose answer turns on the operator's preference. A judgment call with two or three reasonable options the session can weigh is a pick with the tradeoff stated in one sentence, taken without asking.
+- Escalate only a decision whose answer turns on the operator's preference. A judgment call the session can weigh between two or three options is a pick taken without asking, its tradeoff in a sentence.
 - Escalate only what is open now. A decision already taken this session goes to the artifact that records it rather than back to the operator.
 - Do not act on any decision in the batch before it is answered. Continue the work that depends on none of them.
 - Do not escalate a question the session can answer by reading the repository. Read first, and escalate what the tree does not settle.
@@ -39,11 +39,11 @@ Cap the batch at four. A structured question tool takes four, and a batch past t
 
 ## Step 3: put the batch
 
-Put every question in one turn. Never split the batch across turns and never ask the first while the rest stay unstated.
+Put every question in one turn, never splitting the batch across turns or asking the first while the rest stay unstated. Send the batch through a structured question tool wherever the session runs on one, and write the shape below where it does not. One call carries the whole set, one entry per decision, so the operator answers them together.
 
-Send the batch through a structured question tool wherever the session runs on one, and write the shape below where it does not. What a batch adds is that one call carries the whole set, with one entry per decision, so the operator answers them together instead of one per turn.
+The test is the surface rather than the project's instruction file. A target scaffolded before the rule shipped still reaches the tool, and loses only the option shape `CLAUDE.md` states, which the example below carries.
 
-The test is the surface rather than the project's instruction file. A target scaffolded before the rule shipped still reaches the tool, and what it loses is the option shape `CLAUDE.md` states, which the example below carries instead.
+### The fallback shape
 
 Batch shape on the fallback surface:
 
@@ -69,7 +69,10 @@ An operator who answers some and not others has answered those. Continue on the
 
 Restate each pick in one line, then continue the work.
 
-A pick that changes a written artifact goes into that artifact under the rule its own standard sets. An answer to an open plan question rewrites that question's `- Suggested:` line to the pick and names the operator as its source, leaving the `- Answer:` slot blank, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. The standard bars a session from filling that slot even when the operator supplied the pick, and the blank slot resolves to the rewritten suggestion, so the record carries the operator's decision either way. A pick that settles nothing written stays in the session.
+A pick that changes a written artifact goes into it under the rule its own standard sets, and a pick that settles nothing written stays in the session.
+
+- An answer to an open plan question rewrites its `- Suggested:` line to the pick, naming the operator as source, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`
+- Leave the `- Answer:` slot blank, since the standard bars a session from filling it, and the blank resolves to the rewritten suggestion
 
 Output after the answers land:
 

package/claude/skills/deploy-app/SKILL.md

@@ -14,7 +14,7 @@ Runs the one-time setup a deploy needs before the host can publish on push, stop
 - Never accept an API token as input, in a prompt, an argument, or a file. Verify a secret's presence with `gh secret list` rather than asking for or reading its content.
 - Read every account, org, or project ID from the host CLI's own session or files, never from the operator, and pipe it into `gh secret set` rather than reporting it first.
 - Never reimplement a host CLI call or `gh secret set` as a hand-built HTTP call. Call the tools directly.
-- If the project name is not supplied, derive it from the repository's own name (`basename` of `git remote get-url origin`, stripped of a trailing `.git`) and confirm it in the preview rather than asking first.
+- If the project name is not supplied, derive it as the `basename` of `git remote get-url origin` without a trailing `.git`, and confirm it in the preview rather than asking first
 
 ## Step 1: pick the host
 

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

@@ -7,7 +7,11 @@ metadata:
 
 # Deprecation and migration
 
-A session asked to remove something tends to grep for its name, find nothing it recognizes, and delete it. What it misses calls the thing by a string, a config key, or a copy shipped somewhere the search never looked, and the first anyone hears of it is a break in a place the diff never touched. The reverse failure is as common: a replacement ships, the old path gets a deprecation note, and nobody ever moves the callers, so both live on with no owner. This skill carries the discipline that ends with the old surface gone and every caller working.
+A session asked to remove something tends to grep for its name, find nothing it recognizes, and delete it. What it misses calls the thing by a string, a config key, or a copy the search never reached, and breaks somewhere the diff never touched.
+
+The reverse failure is as common. A replacement ships, the old path gets a deprecation note, and nobody moves the callers, so both live on with no owner. This skill ends with the old surface gone and every caller working.
+
+## When to load
 
 Load it before deleting or replacing anything a caller outside the current change could reach. Skip it for code introduced on the same branch that nothing has shipped against yet.
 
@@ -32,7 +36,7 @@ Answer four questions before writing a deprecation notice, and keep the surface
 The owner of a surface moves its callers, the Churn Rule. Announcing a deprecation and waiting for callers to migrate pushes the work onto everyone downstream, and most of them never do it.
 
 - Migrate every caller you can reach in the repository you own, as part of the deprecation work rather than after it.
-- For a caller you cannot edit, such as another team's code or a published consumer, ship a backward-compatible path or migration notes they can apply, and track them as a caller still on the old surface.
+- For a caller you cannot edit, such as another team's code or a published consumer, ship a compatible path or migration notes, and track it as a caller still on the old surface
 - Never add a feature to the deprecated surface. New behavior goes on the replacement, which gives callers a reason to move.
 
 ## Prove zero consumers before removal
@@ -43,13 +47,13 @@ A clean search for one spelling of the name proves only that this spelling is ab
 - **String references**, such as a handler looked up by name, a command dispatched from a table, a reflection call, or a test fixture naming it.
 - **Configuration**, including build files, CI workflows, environment defaults, and data files that name the surface.
 - **Documentation and examples**, which callers copy from long after the code moves.
-- **Copies outside the repository**, such as a published package, an installed copy in another project, a shipped binary, a script someone runs from their own machine, or a saved request in an API client.
+- **Copies outside the repository**, such as a published package, an installed copy in another project, a shipped binary, a script run from someone's machine, or a saved API client request.
 
 Say which kinds your search could not reach and why, rather than reporting zero. "No callers in this repository, but a published release still exports it" is a finding a reader can act on, since it names where the remaining risk sits. A bare "no callers" is a guess.
 
 ## Bridge with an adapter or a strangler
 
-- **Adapter.** Keep the old interface as a thin layer over the new implementation, so callers keep working while the implementation moves underneath them. The adapter holds no logic of its own and goes once its last caller moves.
+- **Adapter.** Keep the old interface as a thin layer over the new implementation, so callers keep working while it moves underneath. It holds no logic of its own and goes once its last caller moves.
 - **Strangler.** Route callers to the new path a group at a time, leaving the old path serving the rest. The old path is done when it serves nothing, and only then is it removed.
 - Prefer the adapter when the interface stays and the implementation changes. Prefer the strangler when callers have to change how they call.
 
@@ -96,6 +100,8 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 
 ### Behavior and callers
 
+Behavior and callers carry their own signs.
+
 - You are adding behavior to the surface being deprecated.
 - Your report says "no callers" without naming the caller kinds the search could not reach.
 - A caller outside the repository was found and the plan still deletes the original.
@@ -110,6 +116,8 @@ Check each line against what the change produced. A line answering no is fixed o
 
 ### Checks and fallbacks
 
+Hold the checks and the fallbacks to the same test.
+
 - The zero-consumers check covered every caller kind, and the report names the kinds it could not reach.
 - No change both adds the replacement and removes the original.
 - Every fallback left in place states when it goes and who removes it.