@erclx/canon 5.45.0 → 5.46.0

package/claude/skills/design-identity/REQUIREMENT.md

@@ -7,34 +7,28 @@ description: Why the mark and the card are one pick rather than two, and where t
 
 ## Gap
 
-Without this skill, a session asked for a logo and a social card either invents shapes with nothing behind them, or drafts the mark and the card as two separate decisions that can land on shapes that do not compose, which is the failure the task filing this skill measured by hand on every project it touched. A search across every shipped skill and standard found zero hits for `logo`, `og:image`, `og-image`, or Open Graph, so nothing in the catalog reached either output.
+Without this skill, a session asked for a logo and a social card invents shapes with nothing behind them, or drafts the mark and the card as two decisions that land on shapes that do not compose. Nothing else in the catalog reaches a logo or an Open Graph image.
 
-A session building this without a shared loop restates `pick-by-eye`'s render, hand-off, pick, and loop mechanics from scratch, which drifts from the shipped one with nothing comparing the two copies. It also guesses at the icon size sequence and the output folder rather than reading what the project already declares, and it produces one raster per size through a separate render call per size, which multiplies capture invocations for no reason `canon capture` cannot already batch.
+A session building this alone restates the render-and-pick loop from scratch, where it drifts from the shipped one. It guesses the icon sizes and the output folder rather than reading what the project declares, and it renders each size through its own capture call.
 
 ## Must
 
-- Detect the icon size sequence from the project's own HTML head or manifest before falling back to the stated default set
-- Detect the write folder from the project's own static-asset convention before falling back to the project root, and announce which one decided it
-- Draft every arm already composed inside the card frame, so one pick settles the mark's shape and its composition together
-- Follow `pick-by-eye`'s Steps 2 through 5 for the render, hand-off, pick, and loop, rather than restating them
-- Write the final mark as its own SVG source, not baked into a raster only
-- Render every final size and the card in one capture call, by sharing one selector class across pages, each declared at half its target dimension to land on the literal size once the render engine's fixed 2x scale factor is applied
+- The icon size sequence and the write folder come from the project's own head, manifest, or static-asset convention before a stated default, and the run names which one decided
+- Every arm is drafted inside the card frame, so one pick settles the mark's shape and its composition together
+- The render, hand-off, pick, and loop follow `pick-by-eye` rather than a copy of it
+- The final mark lands as its own SVG source, not only baked into a raster
+- Every final size and the card render in one capture call, each landing at its literal target size
 
 ## Must not
 
-- Restate `pick-by-eye`'s render, hand-off, pick, or loop mechanics
-- Add a `## Logo` section to `claude/skills/canvas-board/references/design.md`'s fixed section set. `src/design/parse.ts` reads a fixed key set, and no outcome behind this skill asks for a schema change.
-- Modify `pick-by-eye`, `canon capture`, or `canon design render`. This skill composes all three and extending any of them is a separate change.
-- Assume this skill's own invocation frequency needs no check. Whether anything reaches for it beyond an operator typing its name has no answer at creation time, so a review pass some months in should read that back rather than take it on faith.
-
-## Guards
-
-- `canon` not on PATH: stop, since the render loop and the finalize step both need it
-- Fires on a direct request only. A run offering a logo to a project that never asked for one spends a render nobody wanted.
+- Draft a mark the operator did not ask for, or mutate an existing logo file, which is a plain edit
+- Add a logo section to the design document's fixed section set, which its parser reads as a fixed key set
+- Modify `pick-by-eye`, `canon capture`, or `canon design render`, which this skill composes
+- Be taken as reached by more than an operator typing its name, which a later review reads back rather than assumes
 
 ## Out of scope
 
-- Wiring the produced files into a project's own HTML head or manifest, which is a separate edit this skill leaves for the operator to make against their own markup
-- Recording the mark's construction rules in `claude/skills/canvas-board/references/design.md`, which the task's own constraint keeps out of the fixed section set
-- Mutating an existing logo file directly, which is a direct edit rather than a skill
+- The render, hand-off, pick, and loop mechanics, which `pick-by-eye` owns
+- Carrying a picked direction into the design document, which `canvas-board` owns
 - Auditing an implemented UI against its tokens, which `ux-audit` owns
+- Wiring the produced files into the project's head or manifest, which the operator owns

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

@@ -7,70 +7,29 @@ description: Why a design round needs a stated layer ordering and a taste catalo
 
 ## Gap
 
-Without this skill, a design round has no vocabulary to declare what it is varying and no standard of quality once it has. Both halves failed together and each is measured.
+Without this skill, a design round cannot declare what it varies. Rounds change palette on a page whose defect sits at composition, and nothing visibly changes. An instruction to name the layer has no catalog behind it, so it gets skipped. Sections are judged alone, and a redesign renames what something outside depends on.
 
-The failure was measured on a real page. Four `pick-by-eye` rounds ran against one landing page in a single working session, and three changed nothing the operator could see. Each varied a property at Surface, being palette, figure treatment, heading separation and underline reach, against a page whose defect sat at composition.
-
-The instruction against that already existed. `pick-by-eye` Step 1 says to name the layer and Step 2 says a palette cannot be picked ahead of a composition. All four rounds skipped both, and nothing reported it. A session told to name a layer has no catalog to name from, so the rule had nothing behind it.
-
-The second half is the output itself. A model with no stated direction draws the population average of its training data, which produces interfaces that satisfy every craft rule and still read templated.
-
-Prose is already governed in two halves and design is governed in neither. The character bans ship as data a command reads, and the shapes no closed word set can match needed a skill of their own, because each is a pattern rather than a token. `claude/skills/canvas-board/references/design.md` governs the shape of a project's design document and is silent on whether its values are any good.
-
-Importing an external catalog wholesale fails on what those catalogs turn out to carry. The largest is 1,206 lines in one file, pinned to one framework, one styling library and one animation package, and it scopes itself out of dashboards, data tables and multi-step product UI. A second bans default fonts by name and prescribes a component library.
-
-A session handed either one unfiltered adopts a stack the project does not use, or silently ignores the item. No later reader can tell which happened, which is why the adopted-and-declined record exists.
+The output has no standard of quality either. A model with no stated direction draws the population average, which satisfies every craft rule and still reads templated. The external catalogs are pinned to one stack, so a session handed one adopts a stack the project does not use or silently drops the item.
 
 ## Must
 
-- Require a declared read in the output before any candidate is authored, naming the kind, the audience, the overriding constraint and the layer, since a layer named privately is a layer nobody can check
-- Enumerate the layers in settle order, so an instruction to name one has a catalog behind it
-- State that a round varies one layer, and that a complaint is worked at the lowest layer it reaches rather than the cheapest one to change
-- Carry grey-boxing as the operational form of the ordering rule, since removing the higher layers from view is what makes a lower one judgeable
-- Cite the correctness floor rather than restating it. `copy`, `a11y`, `keyboard`, `forms` and `ux-completeness` already carry accessibility, keyboard, forms, states and rendered copy on the rendered paths, and a second copy here drifts with nothing comparing the two.
-- Hold in the body what every design moment pays for, being the read, the layers, the ordering, grey-boxing and the locks, and defer everything a single moment needs.
-- State what has to stay constant across a whole surface, since coherence is a property of the whole and each of those is broken one section at a time.
-- Detect the mode before reading anything when a surface already exists, and name what cannot change silently, since a slug, a field name or an analytics event breaks something outside the surface.
-- Carry a final filter the session runs against its own output, with every item tracing to a rule stated here, since an unenforced rule and an unchecked one fail the same way.
-- Name the machine defaults as a catalog of shapes with replacements, held behind a stated trigger so a round that needs none pays no read
-- Record which external patterns were adopted, which declined, and the measurement behind each, so a later session extends the position instead of re-deriving it
-- Stay general-purpose across kinds, naming what a kind optimizes for rather than which packages to install
-- Say when a read names a kind the references do not cover, rather than inventing guidance for it
-
-## What earns a place
-
-A rule belongs in this skill only when all four hold. Three of the four reject most design advice, which is the point: a criterion admitting everything is not a criterion.
-
-1. **An unguided model gets it wrong.** The model already knows a control needs padding, so writing that down costs a read and buys nothing. It does not know to avoid three equal cards. Only the second kind earns a line.
-2. **Nothing else owns it.** A `ui` rule, a standard, or a sibling skill owning the topic makes this a pointer rather than a rule.
-3. **It is judgment rather than a threshold.** A contrast ratio has a number and belongs to the floor. Whether a palette reads cheap has no number and belongs here.
-4. **One line states it, and something could violate that line.** "Use whitespace intentionally" fails, since nothing could break it. "No three consecutive image-and-text splits" passes, since it can be counted.
-
-A rule failing any of the four is recorded as considered and declined rather than argued again, in `references/adopted.md`, under the reference where it would have gone.
+- A declared read naming the kind, the audience, the constraint, the layer, and an existing surface's mode lands in the output before any candidate
+- The layers settle in a stated order, a round varies one, a complaint is worked at the lowest layer it reaches, and grey-boxing is announced
+- What stays constant across a whole surface is named, and so is what cannot change silently on one that already exists
+- The machine defaults are a catalog of shapes with replacements, read on a stated trigger, and a final filter traces each item to a stated rule
+- A record names which external patterns were adopted and which declined, and an uncovered kind gets the body's rules and a stated absence
 
 ## Must not
 
-- Name a framework, a styling library, an animation package, a component library or an icon set as a default. A rule that survives only inside one stack is not a taste rule.
-- Ship a frozen corpus of palettes, font pairings or product examples. A copy becomes a file some sync reconciles forever, and a traced reference is current by construction where a frozen one is not.
-- Restate the banned characters, which `markdown.md` states and `canon markdown audit` gates from package data
-- Express intensity as a numeric scale. A session picks a middle value and reports compliance, which satisfies the rule and decides nothing.
-- Claim the reported failure is closed. Nothing measures whether a round follows these rules, so this skill states them and the measurement is owed separately.
-- Duplicate a rule a surface already states for itself, such as slide layout or terminal color, where pointing at that surface is the whole of the correct answer
-- Be reached only by an author typing its name. `claude/skills/create-skill/references/skill.md` makes this a review criterion rather than a check, since nothing answers it before the skill has run. The intended non-author caller is the declared read in `pick-by-eye`'s output. A round producing no read, with this skill never loaded, is the evidence that the description's triggers are too weak.
-
-## Guards
-
-- A kind with no per-kind guidance gets the body's rules and a stated absence, never invented guidance
-- A grey-boxed set is announced as grey-boxed, since an unannounced grey page reads as unfinished work rather than as the question being asked
-- Accessibility and the state set outrank an aesthetic preference wherever the two collide, rather than being traded against it
+- Name a framework, a library, or an icon set as a default, or ship a frozen corpus of palettes, pairings, or examples
+- Admit a rule an unguided model already gets right, another surface owns, a threshold settles, or no single line could violate
+- Restate the correctness floor or the banned characters, or trade accessibility and the state set against an aesthetic preference
+- Express intensity as a numeric scale, or claim a round follows these rules when nothing measures it
+- Be reached only by an author typing its name, since `pick-by-eye`'s declared read is the intended caller
 
 ## Out of scope
 
-- Accessibility, ARIA and alt text, which `a11y` owns on every rendered path, and keyboard interaction, which `keyboard` owns
-- State coverage, empty and loading treatment, destructive confirmation and truncation, which `ux-completeness` owns
-- Validation timing, error placement and save blocking, which `forms` owns
-- Rendered copy casing, button labels and error wording, which `copy` owns
-- The candidate loop, the arm set, the render and the pick, which `pick-by-eye` owns and which this skill is loaded alongside rather than inside
-- The shape of the project's design document, its sections and its role tables, which `claude/skills/canvas-board/references/design.md` governs
-- Prose on the surface being designed, which `write-human` and `markdown.md` govern between them
-- Measuring whether finished output followed these rules, which needs a check this skill does not carry and which no command reaches while a render is an image rather than a parse
+- Accessibility, keyboard interaction, state coverage, forms, and rendered copy, which the `a11y`, `keyboard`, `ux-completeness`, `forms`, and `copy` rules own
+- The candidate loop and the pick, which `pick-by-eye` owns
+- The shape of the project's design document, which `canvas-board`'s design reference governs
+- Prose on the surface being designed, which `write-human` and `markdown-craft` own

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

@@ -7,37 +7,28 @@ description: Scope boundary for consumer-facing prose against the agent-facing d
 
 ## Gap
 
-Without this skill, a rename or a dropped flag ships with the README still describing the old surface. Nothing fails, because no test reads prose, so the doc stays wrong until a person hits it.
+A rename or a dropped flag ships with the README still describing the old surface, and no test reads prose. Rewriting whole files churns sections the change never reached. A doc edited earlier in the session passes file-level classification while a later change leaves a section stale.
 
-Three failures belong to the sync itself rather than to the drift. A session that syncs by rewriting whole files churns sections the change never reached, which costs the reviewer the ability to tell the sync from the feature. A doc edited earlier in the same session reads as current while a later change leaves one of its sections stale, so file-level classification passes where section-level would not. And a hardcoded doc list never checks the file someone added after the list was written.
-
-The trigger is a failure of its own. "Sync the docs" names either corpus to the person saying it, so a description claiming the bare phrase takes the request meant for the planning surface its sibling owns, and the run rewrites a README nobody asked about while the `.claude/` docs it was called for stay stale.
-
-The quiet one is the baseline. A diff resolved against a bare local ref equals HEAD on `main` and on a branch before its first commit, so every committed change drops out of the set. The skill then reports nothing to sync, which reads as a clean result rather than as an admission that it could not see the work.
+"Sync the docs" names either corpus, so a bare description takes a request meant for its sibling. A diff resolved against a bare local ref equals HEAD on `main`, so the skill reports nothing to sync and reads as clean. A hardcoded doc list misses a file added later.
 
 ## Must
 
-- Name the corpus in every trigger phrase, so a request naming neither reaches one skill of the pair rather than either
-- Resolve one merge base, prefer the remote ref over the local one, and reuse it everywhere the skill reads the diff
-- Say so in the output when the baseline degrades, rather than reporting a clean pass off a set it could not build
-- Discover the doc set by glob at run time
-- Classify and rewrite at section level, so a partly stale file is partly rewritten
-- Mark a section stale only when the diff changes what a caller sees, since a page rewritten on every internal change starts carrying the reasons behind it
-- Write immediately after the preview, since the tool permission dialog is the confirmation gate
+- Name the corpus in every trigger phrase
+- Resolve one merge base, prefer the remote ref over the local, and reuse it wherever the diff is read
+- Say so in the output when the baseline degrades, rather than reporting a clean pass
+- Discover the doc set by glob at run time, and classify and rewrite at section level
+- Mark a section stale only when the diff changes what a caller sees, and write right after the preview
 
 ## Must not
 
 - Touch a section the change does not reach
-- Rewrite a doc to match the diff when the doc records an intent the diff departed from. That is a finding rather than a sync.
-
-## Guards
-
-- No committed change and no working-tree change stops the skill before it reads any doc
+- Rewrite a doc to match the diff when the doc records an intent the diff departed from
+- Read docs when there is no committed or working-tree change
 
 ## Out of scope
 
-- The context entries: `context-fold`, which runs ahead of this skill in the ship chain and resolves the same baseline. The task board: `task-complete`, which runs between the two. The split is by audience, so a file's location decides which skill owns it rather than its subject.
-- The requirements record: `document-health` reads it when asked
-- `CLAUDE.md` and the installed seed docs, which an operator reconciles by hand against the toolkit source
-- Changelog entries, which release tooling generates from commit messages
-- Whether the prose conforms to its standards. `canon markdown audit` reports violations and fixes none, and this skill writes prose it does not audit.
+- The context entries, which `context-fold` owns, and the task board, which `task-complete` owns
+- The requirements record, which `document-health` owns
+- `CLAUDE.md` and the installed seed docs, which an operator reconciles by hand
+- Changelog entries, which release tooling generates
+- Whether the prose conforms to its standards, which `canon markdown audit` reports

package/claude/skills/document-health/REQUIREMENT.md

@@ -7,42 +7,28 @@ description: What the document health check is for, the gap it closes, and why i
 
 ## Gap
 
-Without this skill, a project learns which documents are missing and never learns which have rotted. `target-check` reports per domain what a target holds against what the toolkit ships, and every one of its domains asks a structural question: does the file exist, does it hold the required sections, do the bytes match what shipped. A document that exists, holds every section, and describes a tree that moved six months ago passes every one of them.
+A project learns which documents are missing and never which have rotted. `target-check` asks structural questions, and a document that exists, holds its sections, and matches what shipped can still describe a tree that moved long ago.
 
-The second half of the gap is the axes being read as one thing. Length, placement, and staleness answer to different evidence, and a run that reports them in one undifferentiated list hands the reader a judgment wearing the authority of a measurement. The operator's own complaint was staleness, which is the axis with nothing behind it, so the flattening runs in the direction that overstates the weakest finding.
-
-The third is silence on an unread axis. Both measured verbs resolve their folders by surface root, so a project whose layout differs resolves nothing and the verb refuses. A run reading that refusal as an empty finding set reports a healthy corpus for documents nothing looked at.
+Length, placement, and staleness answer to different evidence, and one list hands the reader a judgment wearing a measurement's authority. A verb that refuses on an unfamiliar layout reads as an empty set, so a healthy corpus is reported for documents nothing looked at.
 
 ## Must
 
-- Report per document across three named axes, so a reader can tell which question a finding answers
-- Read length and placement through the verb that already owns each measurement, rather than re-deriving either by hand
-- Mark every finding with its evidence class, so a judgment is never read as a measurement
-- Ship the staleness axis, and mark it as a reading rather than cutting it for lacking a verb
-- Report a refusal, an absent key, and a missing subcommand as an unread axis, naming the cause
-- Say which layer answered the classifier sweep, since its model layer being off narrows the read without refusing it
-- Take every checkpoint from the record the verb returns rather than from a number written into the skill
-- Run standalone, and stay callable from the structural check rather than reachable only through it
-- Read the requirements record for identity drift when the scope reaches it, and print one reminder line from `canon records stale canonical`, since the fold never writes it, so nothing else reads it whole
+- Report per document across the length, placement, and staleness axes, marking each finding with its evidence class
+- Read length and placement through the verb owning each measurement, and take every checkpoint from the record the verb returns
+- Ship the staleness axis as a reading rather than cutting it for lacking a verb
+- Report a refusal, an absent key, or a missing subcommand as an unread axis naming the cause, and say which layer answered the classifier sweep
+- Run standalone, read the requirements record for identity drift when the scope reaches it, and print the `canon records stale canonical` reminder
 
 ## Must not
 
-- Repair a finding, write a file in the project, or open a pull request. A check that repaired as it read leaves the reader unable to tell a finding from a fix.
-- Emit a verdict across the three axes, or a score across the documents. Two axes answer from verbs and one answers from a reading, so any roll-up is a figure that lies about the third.
-- Report a finding against a file nobody hand-authors. A generated index, a gitignored file, and a copied reference each name a file an author cannot fix.
-- Answer an axis by file inspection where a verb answers it. The verb is the surface under test and a hand-rolled read of the same files is not.
-- Trigger itself, or ask a hook, a gate stage, or CI to trigger the canonical review. The operator settled that it runs only when asked.
-- Read a document's modification time as its staleness. A file untouched beside code untouched is current, and the timestamp answers a different question.
-
-## Guards
-
-- `canon` absent from the path: stop, since neither measured axis can be read
-- No tracked markdown under the working root: stop, since there is no corpus to read
+- Repair a finding, write a file in the project, or open a pull request
+- Emit a verdict or score across the axes, or report a finding against a generated, gitignored, or copied file
+- Answer an axis by file inspection where a verb answers it, or read a modification time as staleness
+- Trigger itself or ask a hook, gate stage, or CI to, and run without `canon` or tracked markdown
 
 ## Out of scope
 
-- Whether a document exists or holds its required sections, which is the structural question `target-check` answers across six domains
-- Banned tokens and structural checkpoints in markdown, which `canon markdown audit` measures from package data. This skill reads rot a ban set cannot state.
-- Rewriting a stale claim once this run has named it, which the operator or the owning skill does
-- Running the toolkit's own checks as one gating set over its own corpus, which is `canon audits run`. That set gates a push and this reports to a reader.
-- Repairing anything an axis names. Each routes to the command or skill that owns it.
+- Whether a document exists or holds its sections, which `target-check` owns
+- Banned tokens and structural checkpoints, which `canon markdown audit` owns
+- Rewriting a stale claim once named, which the operator or the owning skill owns
+- Gating the toolkit's own corpus as one set, which `canon audits run` owns

package/claude/skills/document-health/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: document-health
-description: Reports which of a project's documents have rotted, one section per document, across length, placement, and staleness. Reads each axis through the verb that owns it and marks the evidence class each answer carries. Use when asked to "check document health", "which docs have gone stale", "audit the docs for rot", "are these documents still accurate", "which docs are too long", or after a target check reports the structural side. Do NOT use to repair a finding, which the owning command or skill does, and do NOT use to check whether a document exists or holds the right sections, which is `target-check`.
+description: Reports which of a project's documents have rotted, one section per document, across length, placement, and staleness. Reads each axis through the verb that owns it and marks the evidence class each answer carries. Use when asked to "check document health", "which docs have gone stale", "audit the docs for rot", "are these documents still accurate", "which docs are too long", or after a target check reports the structural side. Do NOT use to repair a finding, which the owning command or skill does, such as `document-repair` for a length finding, and do NOT use to check whether a document exists or holds the right sections, which is `target-check`.
 metadata:
   family: check
 ---
@@ -74,7 +74,7 @@ Nothing triggers this review but a request. A finished review hands the rewrite
 
 ## Step 4: report per document
 
-Give each document its three axes, and give each axis three things: the state, the evidence class, and the command or skill that repairs it. Naming the repair is not running it.
+Give each document its three axes, and give each axis three things: the state, the evidence class, and the command or skill that repairs it. Naming the repair is not running it. A length finding names `document-repair`, which rewrites a folder to zero and gates it.
 
 The three classes are what keep the axes apart:
 

package/claude/skills/document-repair/REQUIREMENT.md

@@ -0,0 +1,32 @@
+---
+name: document-repair
+description: What the repair skill is for, the drift it closes, and why it gates only through the CLI
+---
+
+# Document repair requirement
+
+## Gap
+
+Without this skill, an older project fails the density limits on every file it has not edited since the limits landed, and nothing repairs it. `document-health` reports a length finding and stops, and the edit hook fires only on a file being touched, so an untouched folder stays over the limits.
+
+A folder repaired by hand also drifts back, since a target gates nothing until a folder is listed, and a session listing one by hand can list a folder that still fails.
+
+## Must
+
+- Each batch takes one folder and leaves it at zero findings or reports it ungated
+- A folder gates only through `canon markdown gated add`, which refuses one with a finding left
+- A rewrite keeps every stated reason, command, and path the original carried
+- The body names the verbs and states no limit number
+- A requirement gates by its own path, never through a folder prefix
+
+## Must not
+
+- Edit `canon/config/markdown.toml` by hand
+- Report a folder gated that the verb refused
+- Change what a document claims to pass the audit
+- Be reachable only by its name, since `document-health` names it for every length finding
+
+## Out of scope
+
+- Reporting rot across length, placement, and staleness, which `document-health` owns
+- Whether a document exists or holds its required sections, which `target-check` owns

package/claude/skills/document-repair/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: document-repair
+description: Rewrites a project's markdown to the density limits one failing folder at a time, re-audits each to zero, and gates it through `canon markdown gated add` so it cannot drift back. Use when asked to "repair the docs", "bring the docs under the limits", "fix the density findings", "gate this folder", or after `document-health` reports a length finding. Do NOT use to report rot without repairing it, which is `document-health`, or to fix a banned character or a dead link alone, which the audit names directly.
+metadata:
+  family: upkeep
+---
+
+# Document repair
+
+Brings an older project's markdown under the density limits one folder at a time and gates each folder as it reaches zero. `document-health` names a length finding and stops, and the edit hook fires only on a file being touched, so a folder nobody edits stays over the limits forever. This skill closes that.
+
+The CLI holds every number. `canon markdown audit` measures, and `canon markdown gated add` refuses a folder with any finding left, so this body names the verbs and restates no limit.
+
+## Guards
+
+- `canon` absent from the path: stop. `❌ canon is not on PATH, so nothing can be measured or gated.`
+- The audit refusing: stop and name its `reason`. A `malformed-config` refusal names the file to fix by hand, since the verb will not append to a file it cannot read.
+- `gated add` refusing with `canon-checkout`: stop. Canon's own checkout gates through a constant in its source, which a code change edits.
+- Run every command under `CANON_NON_INTERACTIVE=1`, and branch on each record's own fields rather than on an exit status a shell wrapper can flatten
+
+## Step 1: read the audit
+
+Run the audit over the whole tree and take the density and reference shape findings from its record:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon markdown audit --json
+```
+
+Take the candidate folders from the order table in `${CLAUDE_SKILL_DIR}/references/batches.md` rather than from the findings, since a clean folder carries no finding and would never be gated. Drop every folder `canon/config/markdown.toml` already lists, since a listed folder already gates.
+
+Sort what is left in two. A candidate the findings never name needs no rewrite, so gate it through Step 4 before the first batch. Group the findings under the rest, which Steps 2 and 3 rewrite.
+
+## Step 2: pick one folder
+
+Take one folder per batch, per `${CLAUDE_SKILL_DIR}/references/batches.md`, which holds the size, the order, and the stop rule. Say which folder this batch takes and how many findings it carries before editing anything.
+
+## Step 3: rewrite to zero
+
+Load `markdown-craft` and `write-human`, then rewrite each failing block by its shape rather than by trimming characters. Split a long paragraph at its seam, put a heading or a table between paragraphs, give a long list H3s, and open each H3 with a sentence or a table.
+
+Re-run the audit on the folder alone after each file:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon markdown audit <prefix> --json
+```
+
+Read `${CLAUDE_SKILL_DIR}/references/batches.md` for what a rewrite may cut. A stated reason survives every rewrite, and the audit reaching zero cannot see one that went missing.
+
+## Step 4: gate the folder
+
+```bash
+CANON_NON_INTERACTIVE=1 canon markdown gated add <prefix> --json
+```
+
+Pass the prefix exactly as the batch named it: a folder with its one trailing slash, such as `docs/`, and a file by its bare path, such as `README.md`. The verb refuses a doubled slash and a slash after a file, since either matches nothing and would gate nothing.
+
+Branch on the record. `action: appended` or `present` means the folder gates now. `reason: findings` means one is left, so return to Step 3 with the paths the record lists. Never edit the config by hand, since the verb is what holds the folder to zero.
+
+### Requirements
+
+A skill's `REQUIREMENT.md` gates only on its own path, never through a folder prefix, so gating `.claude/skills/` leaves each requirement reporting. Gate each one that reaches zero by its path:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon markdown gated add .claude/skills/<name>/REQUIREMENT.md --json
+```
+
+## Output
+
+One line per batch, then the folders left:
+
+```markdown
+✅ Gated `<prefix>`: <n> files rewritten, <m> findings cleared.
+Left: `<prefix>` (<k> findings), `<prefix>` (<k> findings).
+```
+
+Name a folder the batch stopped short on with the findings still open, rather than reporting it gated.

package/claude/skills/document-repair/references/batches.md

@@ -0,0 +1,44 @@
+---
+title: Repair batches
+description: How document-repair sizes and orders a batch, when it stops, and what a rewrite may cut
+---
+
+# Repair batches
+
+`document-repair` reads this at Step 2 to pick a folder and at Step 3 before cutting anything.
+
+## Size
+
+One batch is one folder, gated before the next starts. A folder is the unit `canon markdown gated add` takes, so a batch spanning two leaves one half rewritten and ungated when the session stops.
+
+Split a folder with more findings than one session can rewrite with care into its subfolders, and gate each subfolder by its own prefix.
+
+## Order
+
+Take the folder a reader opens most, then the folder with the fewest findings.
+
+| Order | Folder            | Why                                             |
+| ----- | ----------------- | ----------------------------------------------- |
+| 1     | `README.md`       | The first page anyone reads                     |
+| 2     | `docs/`           | Pages written for a reader rather than an agent |
+| 3     | `canon/context/`  | Read on every session that touches its domain   |
+| 4     | `.claude/skills/` | Loaded on request, so a long body costs a turn  |
+| 5     | The wiki folder   | Orientation pages, read least often             |
+
+Within a tier, a folder close to zero goes first, since it gates the soonest and stops drift there.
+
+## Stop rule
+
+Stop the batch, and report it ungated, when a rewrite would change what a document claims rather than how it says it. That call belongs to the document's owner, so name the file and the block.
+
+Stop the run after the batch in hand when the session's context is running short. A half-rewritten folder is worse than an untouched one, since the next session cannot tell which files were read.
+
+## What a rewrite may cut
+
+A rewrite changes shape and keeps substance.
+
+- Keep every stated reason. A rule without its reason is the cut a reviewer cannot recover from the diff alone.
+- Keep every command, path, and number the document states, unless the tree shows it wrong
+- Cut a sentence restating the one above it, and a list item repeating its heading
+- Move detail to a table or a linked page rather than deleting it
+- Never cut a warning, a refusal condition, or a stated limit to pass the audit

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

@@ -7,17 +7,18 @@ description: Why a pointer answers under the old `draft-and-pick` name, and the
 
 ## Gap
 
-Without this skill, a person typing the old name after the rename to `pick-by-eye` meets an unknown command with nothing naming where the skill went. A target that has not run `canon migrate skill-names` still holds files telling someone to type it, and a live gitignored record written before the rename still names it, since the sweep reads the tracked listing only.
+Without this skill, a person typing the old name after the rename to `pick-by-eye` meets an unknown command that names no successor. A target that has not run `canon migrate skill-names` still tells people to type it, and so does a live gitignored record, which the sweep never reads.
 
 ## Must
 
 - Name `pick-by-eye` as the skill to run, so a typed invocation of the old name reaches the new one in one step
-- Carry `disable-model-invocation: true`, so routing never matches the old description against a request the new skill owns
+- Carry `disable-model-invocation: true`, so routing never matches the old description against a request `pick-by-eye` owns
+- Retire once `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name
 
 ## Must not
 
 - Carry any part of the draft and pick loop, which would give one behavior two bodies that drift apart
-- Retire on a release number. Retire it when `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name, since a release number retires it on a date nothing measured.
+- Retire on a release number, which retires it on a date nothing measured
 
 ## Out of scope
 

package/claude/skills/draft-doc/REQUIREMENT.md

@@ -7,17 +7,18 @@ description: Why a pointer answers under the old `draft-doc` name, and the test
 
 ## Gap
 
-Without this skill, a person typing the old name after the rename to `write-doc` meets an unknown command with nothing naming where the skill went. A target that has not run `canon migrate skill-names` still holds files telling someone to type it, and a live gitignored record written before the rename still names it, since the sweep reads the tracked listing only.
+Without this skill, a person typing the old name after the rename to `write-doc` meets an unknown command that names no successor. A target that has not run `canon migrate skill-names` still tells people to type it, and so does a live gitignored record, which the sweep never reads.
 
 ## Must
 
 - Name `write-doc` as the skill to run, so a typed invocation of the old name reaches the new one in one step
-- Carry `disable-model-invocation: true`, so routing never matches the old description against a request the new skill owns
+- Carry `disable-model-invocation: true`, so routing never matches the old description against a request `write-doc` owns
+- Retire once `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name
 
 ## Must not
 
 - Carry any part of the document draft, which would give one behavior two bodies that drift apart
-- Retire on a release number. Retire it when `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name, since a release number retires it on a date nothing measured.
+- Retire on a release number, which retires it on a date nothing measured
 
 ## Out of scope
 

package/claude/skills/draft-figure/REQUIREMENT.md

@@ -7,17 +7,18 @@ description: Why a pointer answers under the old `draft-figure` name, and the te
 
 ## Gap
 
-Without this skill, a person typing the old name after the rename to `draw-figure` meets an unknown command with nothing naming where the skill went. A target that has not run `canon migrate skill-names` still holds files telling someone to type it, and a live gitignored record written before the rename still names it, since the sweep reads the tracked listing only.
+Without this skill, a person typing the old name after the rename to `draw-figure` meets an unknown command that names no successor. A target that has not run `canon migrate skill-names` still tells people to type it, and so does a live gitignored record, which the sweep never reads.
 
 ## Must
 
 - Name `draw-figure` as the skill to run, so a typed invocation of the old name reaches the new one in one step
-- Carry `disable-model-invocation: true`, so routing never matches the old description against a request the new skill owns
+- Carry `disable-model-invocation: true`, so routing never matches the old description against a request `draw-figure` owns
+- Retire once `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name
 
 ## Must not
 
 - Carry any part of the figure draft, which would give one behavior two bodies that drift apart
-- Retire on a release number. Retire it when `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name, since a release number retires it on a date nothing measured.
+- Retire on a release number, which retires it on a date nothing measured
 
 ## Out of scope
 

package/claude/skills/draft-identity/REQUIREMENT.md

@@ -7,17 +7,18 @@ description: Why a pointer answers under the old `draft-identity` name, and the
 
 ## Gap
 
-Without this skill, a person typing the old name after the rename to `design-identity` meets an unknown command with nothing naming where the skill went. A target that has not run `canon migrate skill-names` still holds files telling someone to type it, and a live gitignored record written before the rename still names it, since the sweep reads the tracked listing only.
+Without this skill, a person typing the old name after the rename to `design-identity` meets an unknown command that names no successor. A target that has not run `canon migrate skill-names` still tells people to type it, and so does a live gitignored record, which the sweep never reads.
 
 ## Must
 
 - Name `design-identity` as the skill to run, so a typed invocation of the old name reaches the new one in one step
-- Carry `disable-model-invocation: true`, so routing never matches the old description against a request the new skill owns
+- Carry `disable-model-invocation: true`, so routing never matches the old description against a request `design-identity` owns
+- Retire once `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name
 
 ## Must not
 
 - Carry any part of the logo and social card draft, which would give one behavior two bodies that drift apart
-- Retire on a release number. Retire it when `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name, since a release number retires it on a date nothing measured.
+- Retire on a release number, which retires it on a date nothing measured
 
 ## Out of scope
 

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

@@ -7,17 +7,18 @@ description: Why a pointer answers under the old `draft-ready` name, and the tes
 
 ## Gap
 
-Without this skill, a person typing the old name after the rename to `plan-ready` meets an unknown command with nothing naming where the skill went. A target that has not run `canon migrate skill-names` still holds files telling someone to type it, and a live gitignored record written before the rename still names it, since the sweep reads the tracked listing only.
+Without this skill, a person typing the old name after the rename to `plan-ready` meets an unknown command that names no successor. A target that has not run `canon migrate skill-names` still tells people to type it, and so does a live gitignored record, which the sweep never reads.
 
 ## Must
 
 - Name `plan-ready` as the skill to run, so a typed invocation of the old name reaches the new one in one step
-- Carry `disable-model-invocation: true`, so routing never matches the old description against a request the new skill owns
+- Carry `disable-model-invocation: true`, so routing never matches the old description against a request `plan-ready` owns
+- Retire once `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name
 
 ## Must not
 
 - Carry any part of the ready folder packaging, which would give one behavior two bodies that drift apart
-- Retire on a release number. Retire it when `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name, since a release number retires it on a date nothing measured.
+- Retire on a release number, which retires it on a date nothing measured
 
 ## Out of scope
 

package/claude/skills/draft-screencast/REQUIREMENT.md

@@ -7,17 +7,18 @@ description: Why a pointer answers under the old `draft-screencast` name, and th
 
 ## Gap
 
-Without this skill, a person typing the old name after the rename to `script-screencast` meets an unknown command with nothing naming where the skill went. A target that has not run `canon migrate skill-names` still holds files telling someone to type it, and a live gitignored record written before the rename still names it, since the sweep reads the tracked listing only.
+Without this skill, a person typing the old name after the rename to `script-screencast` meets an unknown command that names no successor. A target that has not run `canon migrate skill-names` still tells people to type it, and so does a live gitignored record, which the sweep never reads.
 
 ## Must
 
 - Name `script-screencast` as the skill to run, so a typed invocation of the old name reaches the new one in one step
-- Carry `disable-model-invocation: true`, so routing never matches the old description against a request the new skill owns
+- Carry `disable-model-invocation: true`, so routing never matches the old description against a request `script-screencast` owns
+- Retire once `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name
 
 ## Must not
 
 - Carry any part of the screencast script draft, which would give one behavior two bodies that drift apart
-- Retire on a release number. Retire it when `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name, since a release number retires it on a date nothing measured.
+- Retire on a release number, which retires it on a date nothing measured
 
 ## Out of scope