@erclx/canon 5.35.0 → 5.37.0

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

@@ -13,10 +13,7 @@ Applies to per-domain narrative entries under `canon/context/`. Skip for `index.
 - [Organizing principle](#organizing-principle)
 - [What a working entry looks like](#what-a-working-entry-looks-like)
 - [Frontmatter](#frontmatter)
-- [Required sections](#required-sections)
-- [Expected sections](#expected-sections)
-- [Optional sections](#optional-sections)
-- [Ordering](#ordering)
+- [The closed set](#the-closed-set)
 - [The development entry](#the-development-entry)
 - [What goes in](#what-goes-in)
 - [What does not go in](#what-does-not-go-in)
@@ -59,40 +56,33 @@ An entry that fails these is non-conforming regardless of whether it satisfies e
 
 Both fields feed `canon/context/index.md` when regenerated.
 
-## Required sections
+## The closed set
 
-- `## Overview`: two to four lines. What the domain owns and where its boundary sits.
-- `## Layout`: one line per folder in owns-X form. Folders only, never files.
-  - Form: ``- `scripts/lib/` owns shared bash functions sourced by domain scripts``. Do not list every file under that folder with a description each.
-  - Implementation detail moves to `## Decisions`, `## Hidden contracts`, or `## Gotchas`.
-  - Omit the section when 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.
+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.
 
-## Expected sections
+- `## 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.
 
-Include whenever the domain has content for them. Never pad an entry with an empty heading.
+Include `Decisions` and `Gotchas` whenever the domain has content for them, and never pad an entry with an empty heading.
 
-- `## Decisions`: non-obvious choices and the reasoning behind them. 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, scar tissue worth preserving.
+### Where an extra topic goes
 
-## Optional sections
+- 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`.
 
-Pick by what the domain is. Add domain-specific headings as needed.
+### Ordering and headings
 
-- `## CLI`: the command surface, 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.
-- `## Workflow` or `## Adding a <thing>`: the procedure for the domain's most common task. Most sessions arrive asking how to add one more of the thing the domain holds.
-- `## Hidden contracts`: invariants the code does not self-document (shape constraints, skip rules, header semantics). Use `## Decisions` when the reader needs the reasoning rather than the invariant itself.
-
-## Ordering
-
-- Order sections `Overview`, `Layout`, `Decisions`, `Gotchas`, then everything else.
-- 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.
+- 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.
 
 ## The development entry
 
-Only the `development` entry carries this section. It is not a general-purpose heading for other domains.
+Only the `development` entry carries this section, as an H3 under `## Layout`. It is not a general-purpose heading for other domains.
 
-- `## Scripts`: a table of run commands (command plus purpose). The single discoverable surface for how to run the project. Keep run commands here, not scattered across `CLAUDE.md`.
+- `### Scripts`: a table of run commands (command plus purpose). The single discoverable surface for how to run the project. Keep run commands here, not scattered across `CLAUDE.md`.
 
 ## What goes in
 
@@ -100,6 +90,9 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - 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
+
+### 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.
 
@@ -109,10 +102,16 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - 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.
+
+### Elsewhere
+
 - 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.
 - Generated content (API references). Generate, do not write by hand.
 - Anything already in `canon/REQUIREMENTS.md`.
+
+### History and results
+
 - 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.
@@ -122,9 +121,15 @@ Only the `development` entry carries this section. It is not a general-purpose h
 
 - 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` or `## CLI` section instead.
+- Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` section or an H3 under it instead.
+
+### 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.
+
+### 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.
@@ -157,16 +162,25 @@ never the reverse.
 
 ## Decisions
 
-- Validation happens at the route boundary using a schema library. Services trust their inputs.
-- Pagination uses opaque cursor tokens, never offset+limit. Cursor format stays opaque to clients.
+### Validation at the route boundary
+
+Validation happens at the route boundary using a schema library. Services trust their inputs.
+
+### Opaque pagination cursors
+
+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.
 
 ## Gotchas
 
-- The `/health` endpoint skips auth middleware. Liveness probes from the orchestrator do not carry tokens.
-- Database connection pool caps at 50. Concurrent requests over that block until a connection frees.
+### 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.
 
-## Hidden contracts
+### Handlers never wrap their return
 
-- Route handlers return a plain object. The serializer wraps it in `{ data, meta }`. Handlers never wrap manually.
-- Cursor tokens are base64-encoded JSON of `{ id, sort }`. Any handler that issues a cursor must use the shared encoder.
+Route handlers return a plain object, and the serializer wraps it in `{ data, meta }`.
 ```

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

@@ -1,15 +1,13 @@
 ---
 name: create-rule
-description: Why a project-local rule needs a subdir, a number from the band reserved for one, and a scope key that decides when it fires
+description: Why a project-local rule needs a subdir, a slug free in it, and a scope key that decides when it fires
 ---
 
 # Create rule requirement
 
 ## Gap
 
-Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a number free in the target today could be the number a shipped rule landed on tomorrow, and the next install double-booked it, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that half regardless of the number, since the sync engine orphans the file by location before it ever compares names.
-
-Numbering in `900-999` closes the other half. A number scanned against today's toolkit catalog goes stale on the next release, and a reserved band does not.
+Without this skill, a project rule is written straight into the rules folder under a name already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a name free in the target today could be the name a shipped rule landed on tomorrow, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that collision whatever the name, since the sync engine orphans the file by location before it ever compares names, and leaves only a slug taken in the same project subdir to check.
 
 The subdir gets picked by feel, so a UI copy rule lands in the always-on folder and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
 
@@ -18,24 +16,24 @@ The subdir gets picked by feel, so a UI copy rule lands in the always-on folder
 - Resolve what the rule enforces and where it applies, asking only for what the request leaves missing
 - Pick the subdir from the topic and take the folder from that choice
 - Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
-- Take the lowest free number at or above `900`, scanning every project subdir the target holds rather than one
+- Take a slug no rule in the chosen project subdir uses and that equals no subdir name
 - Read the rule standard before writing the body
 - Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
-- Preview the resolved path, subdir, number, and frontmatter, then write without pausing
+- Preview the resolved path, subdir, slug, and frontmatter, then write without pausing
 - Say when the rule loads, since path-scoped and always-on rules behave differently
 
 ## Must not
 
 - Edit a toolkit source rule, which is authored in the toolkit and would be overwritten here
 - Work the body shape or the frontmatter from memory
-- Take a number below `900`, which a later toolkit release can ship into
+- Overwrite a project rule already holding the slug
 - Write more than one topic into a single rule
 
 ## Guards
 
 - No project Claude directory: stop, since there is nowhere for the rule to live
 - The request names no behavior to enforce: stop rather than inventing one
-- The reserved band holds no free number: stop rather than reaching below `900`
+- The topic's slug is taken in the chosen subdir: stop and propose a narrower one
 
 ## Out of scope
 

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

@@ -1,6 +1,6 @@
 ---
 name: create-rule
-description: Scaffolds a project-specific governance rule into `.claude/rules/project/<subdir>/<n>-<slug>.md` with correct frontmatter and a non-colliding number. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
+description: Scaffolds a project-specific governance rule into `.claude/rules/project/<subdir>/<slug>.md` with correct frontmatter and a slug no other rule in that subdir takes. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
 metadata:
   family: generate
 ---
@@ -25,29 +25,31 @@ Resolve both from the request, and ask only for what is missing. Attach a propos
 
 Pick the subdir from the topic. It sits under `.claude/rules/project/` and names the rule's domain:
 
-- `code/`: code placement, errors, naming, testing.
-- `lang/`: one programming language.
-- `framework/`: one framework.
-- `lib/`: one library or tool.
-- `ui/`: UI copy, accessibility, forms.
-- `claude/`: session conduct and `.claude/` authoring surfaces.
-- `canon/`: the toolkit workflow and its record folders.
-- `tooling/`: dev setup, such as CI workflows, dependencies, and config.
-- `writing/`: prose and document shape.
+| Subdir        | Holds                                                      |
+| ------------- | ---------------------------------------------------------- |
+| `code/`:      | code placement, errors, naming, testing.                   |
+| `lang/`:      | one programming language.                                  |
+| `framework/`: | one framework.                                             |
+| `lib/`:       | one library or tool.                                       |
+| `ui/`:        | UI copy, accessibility, forms.                             |
+| `claude/`:    | session conduct and `.claude/` authoring surfaces.         |
+| `canon/`:     | the toolkit workflow and its record folders.               |
+| `tooling/`:   | dev setup, such as CI workflows, dependencies, and config. |
+| `writing/`:   | prose and document shape.                                  |
 
-## Step 3: pick a free number
+## Step 3: pick a free slug
 
-A project-authored rule numbers in `900-999`, the band reserved for one. `000-899` belongs to the toolkit, so a number free in the target today is one a later release can ship into.
+A rule's filename is its slug alone, a one-to-three-word kebab topic with no number in front. A slug the toolkit ships is no collision, since `canon/` and `project/` install side by side and a sync never reads the second.
 
-- Scan every `.claude/rules/project/<subdir>/` in the target for used prefixes, not only the subdir this rule lands in. The band runs as one sequence across all of them.
-- Take the lowest unused number at or above `900`.
-- Stop and say so if the band is full, rather than reaching below `900`.
+- Take a slug no file in the chosen `.claude/rules/project/<subdir>/` already uses.
+- Never take a slug equal to a subdir name from Step 2, since a stack entry naming that word reads it as the folder.
+- Stop and say so when the topic's natural slug is taken, and propose a narrower one rather than overwriting the file.
 
 ## Step 4: write the rule
 
 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>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, subdir, number, 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. 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.
 
@@ -70,4 +72,4 @@ Title casing is sentence case, with proper nouns keeping their own casing (`# Ty
 
 ## After writing
 
-Emit the full path on its own line: `.claude/rules/project/<subdir>/<n>-<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session.
+Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session.

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

@@ -11,8 +11,7 @@ description: Rule frontmatter, body shape, and voice for .claude/rules files
 - [Scope](#scope)
 - [Whether a skill belongs behind the rule](#whether-a-skill-belongs-behind-the-rule)
 - [Location](#location)
-- [Reserved numbers](#reserved-numbers)
-- [Two sources numbering into one folder](#two-sources-numbering-into-one-folder)
+- [Names](#names)
 - [Frontmatter](#frontmatter)
 - [Body](#body)
 - [Examples](#examples)
@@ -27,7 +26,7 @@ A rule with `paths:` loads on a read or a write of a matching file, inside a lin
 
 ## Scope
 
-Governs governance rules under `.claude/rules/`: their location, numbering, frontmatter, and body shape.
+Governs governance rules under `.claude/rules/`: their location, names, frontmatter, and body shape.
 
 Does not govern:
 
@@ -45,33 +44,22 @@ Write both when both apply. A rule stating the directive and a skill stating how
 
 ## Location
 
-- A toolkit-shipped rule lives at `.claude/rules/canon/<subdirectory>/<n>-<slug>.md`. The wrapper marks the file as toolkit-owned and replaced on sync, so a reader unfamiliar with the numbering convention still knows not to edit it.
+- A toolkit-shipped rule lives at `.claude/rules/canon/<subdirectory>/<slug>.md`. The wrapper marks the file as toolkit-owned and replaced on sync, so a reader still knows not to edit it.
 - Subdirectories group by domain or audience: `code/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`, `canon/`, `tooling/`, `writing/`
-- `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
-- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, a sibling of `canon/` rather than nested inside it, keeping the same subdirectory names
-- This repository's own toolkit-only rules, which never ship to a target, live at `.claude/rules/internal/<subdirectory>/<n>-<slug>.md`, a second sibling of `canon/`. See "Two sources numbering into one folder" below.
-- Give every authored rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
+- `<slug>` is a one-to-three-word kebab topic
+- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<slug>.md`, a sibling of `canon/` rather than nested inside it, keeping the same subdirectory names
+- This repository's own toolkit-only rules, which never ship to a target, live at `.claude/rules/internal/<subdirectory>/<slug>.md`, a second sibling of `canon/`.
 
-## Reserved numbers
+## Names
 
-`000-899` is reserved for a rule set that ships to targets, and the nine subdirectories above divide it at 100 per subdirectory, in the order listed. No band is left over, so a subdirectory a shipped set adds later joins an existing band or takes one a retired subdirectory freed.
+A rule's filename is its slug, with no number in front. Nothing orders rules at load, and the folder already names the domain.
 
-A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met the shipped teach rule, then numbered 561, on its next install, and now reads two numbers differently from everywhere else.
-
-The cost is that a project-authored rule's leading digit stops naming its domain. Its subdirectory names it instead, and install preserves that either way. What a shared band costs is worse: a session that loads two rules reading as one number, with nothing in the folder to say which is which.
+- Keep every basename unique across a rule set, internal rules included, since `canon gov` resolves a stack entry and a rename by basename alone.
+- Never name a rule after a subdirectory. A stack entry naming that word expands to the whole folder, so the rule becomes unreachable on its own.
+- A project-authored rule needs its slug free only inside its own subdirectory under `.claude/rules/project/`. A slug the toolkit ships collides with nothing there, since `canon/` and `project/` install side by side.
 
 `canon gov sync` walks only `.claude/rules/canon/`, so `.claude/rules/project/` sits outside the walk by location and is never matched, read, or reported on. A file under `.claude/rules/canon/` itself that no toolkit source names is still reported orphaned, but with no destination offered: the toolkit cannot tell a rule the project dropped there from one it shipped and later renamed, and a destination nested inside `canon/` would be wrong for the first case regardless, since that folder is toolkit-owned and replaced on sync. Nothing is moved either way, since a rule's installed path is one the project's own rules, skills, and docs may cite.
 
-## Two sources numbering into one folder
-
-The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source, a rule set held back from targets and installed only where it was authored, needs its own division too. This repository is the one place all three sources exist at once, and it divides the third pair two ways at once rather than one: `canon/` and `internal/` separate a shipped rule from an internal one by location, the same way `project/` separates a project-authored one, and within each subdirectory the numbering still divides by source as well, one source taking the top of the band and the other the gaps between the tens.
-
-The numbering half stays because location alone does not carry to a reader who only sees the number, such as one comparing `claude/566-output.md` against a citation written before the rules moved into `canon/`.
-
-The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it. Separating `canon/` from `internal/` by folder removes the filename-collision case specifically, since the two no longer install to the same directory, but the number still carries the source signal for a reader who has only the number in view.
-
-State that division where the rule sources are described, not inside the rules it divides. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
-
 ## Frontmatter
 
 - `description` (required): one line naming what the rule enforces and where
@@ -93,9 +81,15 @@ paths:
 - Use imperative voice for every rule (`Prefix booleans with is`, not `Booleans should be prefixed`)
 - State one rule per bullet as a single directive line
 - State what to do and what not to do. Do not explain the reasoning behind a rule.
+
+### Phrasing
+
 - End the directive line of a ban asserting how the model or a tool behaves with one `Revisit when <finding>.` sentence, which states a condition rather than the reasoning. A style, safety, or consistency ban takes none.
 - Phrase a rule as a ban on the forbidden shape when it could otherwise enumerate allowed options, so it stays stable as categories grow
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+
+### Scope of a rule file
+
 - Keep the file to one topic. A second topic is a second rule file.
 - Do not restate a rule that a sibling rule or `CLAUDE.md` already owns. Point once, never duplicate.
 - Name the current layout only, in a glob and in the body alike. A layout change ships a migration verb, as `canon migrate surface-roots` and `canon migrate records` did, rather than a rule line or a glob that keeps the old spelling loading.

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

@@ -12,11 +12,20 @@ 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-reference.md`, when the skill carries a reference setting the shape of one artifact: its scope, success criterion, frontmatter, and rule phrasing
+- `${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/`
+
+### Writing standards
+
+Read these in the same pass:
+
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for skill body text
-- `${CLAUDE_SKILL_DIR}/references/skill-practice.md`, when the skill carries engineering practice: the closing sections a practice skill owes and the anatomy behind them
 - The `write-human` skill: voice, rhythm, and sentence construction for skill body text
 
+## Further references
+
+- `${CLAUDE_SKILL_DIR}/references/skill-reference.md`, when the skill carries a reference setting the shape of one artifact: its scope, success criterion, frontmatter, and rule phrasing
+- `${CLAUDE_SKILL_DIR}/references/skill-practice.md`, when the skill carries engineering practice: the closing sections a practice skill owes and the anatomy behind them
+
 ## Guards
 
 - If `${CLAUDE_SKILL_DIR}/references/skill.md` is not present, stop: `❌ skill.md standard not found. Reinstall the canon plugin.`

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

@@ -0,0 +1,26 @@
+---
+title: Skill disclosure reference
+description: Keeping a skill body and its references under the ceiling, what moves to references and what stays in the body, and how the body names a reference
+---
+
+# Skill disclosure reference
+
+Applies to the size and split of every `SKILL.md` and every file under a skill's `references/`.
+
+## Rules
+
+- Keep `SKILL.md` and each file under `references/` at or under the 300 rendered line ceiling `markdown.md` sets for a whole document. The ceiling binds procedure as much as reference material.
+- Look at a body once it passes 150 lines. That number prompts a look and gates nothing.
+- Move a catalog, a table of cases, or a format spec running past roughly 15 lines to `references/` at any body length.
+- Below the ceiling, name the branch that skips a block before moving it. A block every run dereferences costs a read and saves nothing.
+
+### Moving a step
+
+- Past the ceiling, move a whole step to a reference, preferring a step a named branch skips. Keep the step heading in the body with one line naming the file to read on reaching it, so the body still shows every step in order.
+- Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
+
+### Contents, triggers, and citations
+
+- Open a file under `references/` running over 100 lines with a `## Contents` H2 of anchor links after its H1 and intro, so a session that reads only the top of the file still sees everything it holds.
+- Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
+- Point one skill at a sibling skill's reference by the form `skill-paths.md` states, `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`, and name the owner rather than copying the file.

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

@@ -43,6 +43,9 @@ A reference shared across skills lives in the `references/` of the skill that ow
 - Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`. The plugin ships the skills side by side, so the sibling path resolves in every install. Name the owner skill rather than copying the file.
 - State the path once per body, at the site that reads the reference. A later mention of a reference the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
 - A guard on a reference's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
+
+### Form and ownership
+
 - Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`, since only the first expands before the body reaches the model.
 - Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in its owner's reference and a citation in each body.
 - Keep the trigger in the body and the procedure in the reference. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the reference cannot know it.

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

@@ -50,10 +50,16 @@ A reference failing these questions is non-conforming even when it satisfies eve
 - 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.
 - 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
+
 - 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.
+
+#### 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.
 - 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.
@@ -125,9 +131,15 @@ Answer all four before editing, and carry the answers into wherever the change i
 - 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.
 - Place the template below the rules it satisfies, under a `## Template` heading or inside the section holding those rules.
+
+### What the template shows
+
 - 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
+
 - 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.
 

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

@@ -30,15 +30,15 @@ Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its siblings
 
 Does not govern:
 
-- What a `REQUIREMENT.md` must answer, its sections, and its template: `skill-requirement.md`
-- A practice skill's closing sections and ledger: `skill-practice.md`
-- Which root a path in a body resolves against, and how a body cites another skill's reference: `skill-paths.md`
-- The jurisdiction, success criterion, and rule phrasing of a reference setting one artifact's shape: `skill-reference.md`
-- Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
-- Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
-- Punctuation, formatting, and word choice in a skill body: `markdown.md`
-- The transform from a branch name to a slug a skill carries in a filename: `slug.md`
-- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the creation-time bullet in the `skill` governance rule
+- **`skill-requirement.md`**: what a `REQUIREMENT.md` must answer, its sections, and its template
+- **`skill-practice.md`**: a practice skill's closing sections and ledger
+- **`skill-paths.md`**: which root a path in a body resolves against, and how a body cites another skill's reference
+- **`skill-reference.md`**: the jurisdiction, success criterion, and rule phrasing of a reference setting one artifact's shape
+- **`rule.md`**: path-scoped coding rules, which load on a file match rather than on a request match
+- **the `write-human` skill**: voice, rhythm, and sentence construction in a skill body
+- **`markdown.md`**: punctuation, formatting, and word choice in a skill body
+- **`slug.md`**: the transform from a branch name to a slug a skill carries in a filename
+- **the `create-skill` skill and the creation-time bullet in the `skill` governance rule**: whether a new skill earns its place, by the three-question test
 
 ## Changing a skill
 
@@ -93,18 +93,21 @@ allowed-tools: <tools required>
 - Create a new skill with its `REQUIREMENT.md` beside it, even where nobody contests its scope. A requirement present for some skills and absent for others cannot be scanned, since an absence reads as a gap rather than as a verdict
 - Name a file sitting directly in the skill folder in capitals and a bundled folder in lowercase, so the parts a reader opens are distinct from the ones a skill loads
 - `EVAL.md` holds prompts and a judging rubric a person runs by hand, since the automated `claude plugin eval` runner is gated in early access
+
+### Folder and file rules
+
 - `SKILL.md` must start with YAML frontmatter between `---` delimiters
 - No `README.md` inside the skill folder
 - No spaces, capitals, or underscores in folder or skill name
 
 ## Frontmatter
 
-- `name` (required): kebab-case, matches folder name, no spaces or capitals
-- `description` (required): what it does + when to use it, under 1024 chars, no XML tags
-- `disable-model-invocation: true`: user-invoked only, Claude will not auto-trigger. Set it on a skill that starts a process the operator owns, never on one reachable by a matched trigger.
-- `allowed-tools`: restrict tool access when the skill is active
-- `metadata`: optional key-value pairs (`author`, `version`, `mcp-server`)
-- `metadata.family` (required on a skill under `claude/skills/`): the skill map group the skill's row sits under, as one key from `families` in `canon claude skills list --json`. A skill under `.claude/skills/` takes none.
+- **`name`** (required): kebab-case, matches folder name, no spaces or capitals
+- **`description`** (required): what it does + when to use it, under 1024 chars, no XML tags
+- **`disable-model-invocation: true`**: user-invoked only, Claude will not auto-trigger. Set it on a skill that starts a process the operator owns, never on one reachable by a matched trigger.
+- **`allowed-tools`**: restrict tool access when the skill is active
+- **`metadata`**: optional key-value pairs (`author`, `version`, `mcp-server`)
+- **`metadata.family`** (required on a skill under `claude/skills/`): the skill map group the skill's row sits under, as one key from `families` in `canon claude skills list --json`. A skill under `.claude/skills/` takes none.
 
 ## Description
 
@@ -120,24 +123,22 @@ allowed-tools: <tools required>
 - Front-load critical instructions
 - Contain only behavioral rules (what to do, what not to do) and pointers to reference docs. Narrative descriptions of what files are or how the system works belong in `docs/`, not in the skill body.
 - State rules, not inventories. Reference docs for lists that change, and phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change.
+
+#### Current rule and grouping
+
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
 - State the current rule only, in the body and in every file under `references/`. The incident and the date that earned a rule go in `REQUIREMENT.md` under `Gap`, or stay in git. A date inside a fence or a code span is example data and stays.
 - Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
+
+#### Examples and density
+
 - Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.
 - Keep a statement only when removing it would change what the agent does, naming a principle as a few-word handle rather than explaining it. Revisit when a run shows the model ignoring a principle named only as a handle.
 
 ### Progressive disclosure
 
-- Keep `SKILL.md` and each file under `references/` at or under the 300 rendered line ceiling `markdown.md` sets for a whole document. The ceiling binds procedure as much as reference material.
-- Look at a body once it passes 150 lines. That number prompts a look and gates nothing.
-- Move a catalog, a table of cases, or a format spec running past roughly 15 lines to `references/` at any body length.
-- Below the ceiling, name the branch that skips a block before moving it. A block every run dereferences costs a read and saves nothing.
-- Past the ceiling, move a whole step to a reference, preferring a step a named branch skips. Keep the step heading in the body with one line naming the file to read on reaching it, so the body still shows every step in order.
-- Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
-- Open a file under `references/` running over 100 lines with a `## Contents` H2 of anchor links after its H1 and intro, so a session that reads only the top of the file still sees everything it holds.
-- Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
-- Point one skill at a sibling skill's reference by the form `skill-paths.md` states, `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`, and name the owner rather than copying the file.
+Keeping a body and its references under the ceiling, what moves to `references/` and what stays, and how a body names a reference are in `skill-disclosure.md`.
 
 ### Reading and running commands
 
@@ -162,7 +163,7 @@ allowed-tools: <tools required>
 
 - Use `scripts/` for operations that must be deterministic or repetitive
 - Ask whether a CLI verb the project already has does the job before writing a script. A verb is already installed and tested, and a script beside it is a second copy that drifts
-- Write a script in TypeScript and run it as `bun ${CLAUDE_SKILL_DIR}/scripts/<name>.ts`. Keep bash for a few lines that start one command
+- Write a script in TypeScript and run it as `bun ${CLAUDE_SKILL_DIR}/scripts/<name>.ts`. Keep bash for a few lines that start one command. The rule governs a new script, so bash kept by decision is no breach and is not ported unasked, such as `review-ui`'s `scripts/pw.sh` as glue and the shell scripts the web tooling stacks ship, whose port was deferred
 - Import no package. A plugin loads from a cache that carries no `node_modules`, so only `node:` built-ins and the CLIs the skill already requires resolve
 - Use XML tags in script output for reliable parsing: `<SECTION>content</SECTION>`
 

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

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

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

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