@erclx/canon 5.57.0 → 5.58.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [5.58.0](https://github.com/erclx/canon/compare/v5.57.0...v5.58.0) (2026-10-24)
+
+
+### Features
+
+* **governance:** widen design-taste paths to component files ([#2645](https://github.com/erclx/canon/issues/2645)) ([01b1445](https://github.com/erclx/canon/commit/01b144514eced1150c90b18acc78f0be33990a23))
+* **rules:** route interface changes to api-design ([#2647](https://github.com/erclx/canon/issues/2647)) ([09a073c](https://github.com/erclx/canon/commit/09a073ca38324a399de5c2c2e702fbcede6bb38c))
+* **skills:** offer a restructure before document-repair rewrites ([#2648](https://github.com/erclx/canon/issues/2648)) ([7c2776a](https://github.com/erclx/canon/commit/7c2776a95b86a6626c44e399056b9eaa22418d65))
+
+
+### Bug Fixes
+
+* **context:** count table rows toward no folder paragraph ([#2646](https://github.com/erclx/canon/issues/2646)) ([a99b020](https://github.com/erclx/canon/commit/a99b02064105b81bc3a4f6e4820c73198942785e))
+
 ## [5.57.0](https://github.com/erclx/canon/compare/v5.56.0...v5.57.0) (2026-10-24)
 
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.57.0",
+  "version": "5.58.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -71,7 +71,7 @@ An entry carries three H2 sections and no other, being `Overview`, `Layout`, and
 
 Layout gives each folder doing real work its own H3, titled with the folder path in a code span, such as ``### `src/design/` ``.
 
-- Open the H3 with a one-paragraph lead stating what the folder does, then at most five bullets on what it does now
+- Open the H3 with a one-paragraph lead stating what the folder does, then at most five bullets on what it does now. A table after the lead counts toward neither, with one sentence to lead the bullets
 - Put every trivial folder under `### Other folders` as a one-line bullet in owns-X form
 - Name folders only, never files, and write no decisions and no history under any H3
 - Give each folder under the code roots one H3 or `Other folders` line, since a second entry may cite it but never claims it

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

@@ -13,8 +13,8 @@ Length, placement, and staleness answer to different evidence, and one list hand
 
 ## Must
 
-- 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
+- Report per document across the length, placement, and staleness axes, marking each finding with its evidence class, read through the verb owning each measurement and its record's checkpoints
+- Propose a split or an owner as a structure line for each overgrown entry and doubled or unnamed coverage finding, with the headings and the reason
 - 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

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

@@ -47,6 +47,12 @@ The first names the backend, the model, and the source that decided both. Report
 
 Take the checkpoints from the record each verb returns rather than from a number written here. A checkpoint the CLI moves reaches this report with no edit, and a number held in this body goes stale on its own cadence.
 
+### The structure line
+
+The context audit record already carries what a restructure needs, so the placement axis gains a structure line per area folder and runs no further verb. `${CLAUDE_SKILL_DIR}/references/axes.md` holds how to read `length` and `coverage` into a proposed split or owner.
+
+Emit the line only for a folder with an entry past the line checkpoint whose Layout headings group into two or more domains, or with a doubled or unnamed coverage finding. A folder with neither gets no line, and `document-repair` goes straight to its rewrite.
+
 ### An unread axis is not a healthy one
 
 A refusal, an absent key, and a subcommand the project's binary does not carry each leave an axis unread. Report it as unread against the documents it would have covered, name the read that could not be taken, and name the cause.
@@ -106,4 +112,12 @@ When Step 3 read the canonical records, add one reminder line per doc the verb r
 
 Write `reviewed value is not a date: <value>` for a doc carrying `invalidReviewed`, and `no release tags to count` in place of the count when `tagged` is false. Name the unread cause instead when the verb refused or the binary carries no `canonical` kind.
 
+Under the table, add one structure line per area folder that earned one, naming the entry and the split, or the finding and its owner:
+
+```markdown
+Structure `canon/context/surfaces/`: `cli.md` (300 lines) splits into `cli.md` taking <headings> and `cli-<domain>.md` taking <headings>, because <reason>.
+```
+
+The line is a proposal for the operator, with the headings each entry takes and why. Health applies nothing, and `document-repair` offers the proposal before it rewrites.
+
 Keep the evidence line under the table on every run. A table read without it flattens a judgment into a measurement, which is the one shape the three classes exist to prevent.

package/claude/skills/document-health/references/axes.md

@@ -54,6 +54,18 @@ The sweep classifies each section as keep, replace or rewrite, history, or move.
 - A low-confidence `move` is a prompt to look rather than an instruction to cut
 - **Routes to:** the document the verdict names as the owner. Where the move crosses a tier rather than a file, the project's own content-ownership rules decide the destination.
 
+### The structure line
+
+The audit record's `length` array lists each entry past the line checkpoint, and `coverage.findings` lists the `doubled` and `unnamed` ones. The structure line reads both, so it carries the `measured` class for the finding and `read` for the proposal built on it.
+
+- **Overgrown entry:** read its `causes` in `length` first, since `history: yes` points at cutting provenance and one domain at a trim, so neither earns a split
+- **Split:** group the Layout headings by domain, one new entry per group beyond the first, naming each entry's headings and one reason
+- **Domain boundaries:** no verb measures one, so state the grouping as a judgment.
+- **Doubled coverage:** two entries describe one source area. Propose the one that owns it, from which entry already holds the area's traps, and the other points at it.
+- **Unnamed coverage:** no entry names the area. Propose an owner among the existing entries before a new one, since a new entry is the larger change.
+
+A proposal names headings and a reason, so an operator judges a concrete split. A split nobody can act on names none of those.
+
 ### When a verb resolves nothing
 
 Both verbs resolve their folders by surface root rather than by a path written into them, so a project laid out differently resolves nothing. The two degrade differently.

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

@@ -15,14 +15,19 @@ A folder repaired by hand also drifts back, since a target gates nothing until a
 
 - 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
+- A rewrite keeps every stated reason, command, and path the original carried, and leaves a context entry no more shape findings than it started with
 - The body names the verbs and states no limit number
 - A requirement gates by its own path, never through a folder prefix
 
+## Restructure first
+
+An overgrown context folder is offered the restructure `document-health` proposes before any rewrite, and the restructure applies only on the operator's word.
+
 ## Must not
 
 - Edit `canon/config/markdown.toml` by hand
 - Report a folder gated that the verb refused
+- Reach zero density findings by growing the context shape findings
 - Change what a document claims to pass the audit
 - Be reachable only by its name, since `document-health` names it for every length finding
 

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

@@ -18,6 +18,15 @@ The CLI holds every number. `canon markdown audit` measures, and `canon markdown
 - `gated add` refusing with `canon-checkout`: stop. Canon's own checkout gates through a constant in its source, which a code change edits.
 - Branch on each record's own fields rather than on an exit status a shell wrapper can flatten. A call with no terminal on stdin already runs headless, so no command takes a prefix.
 
+## Step 0: offer the restructure
+
+Restructure an overgrown context folder before rewriting it, so the effort is spent once. Run this step only when `canon/context/` is a candidate, meaning it is not yet listed in `canon/config/markdown.toml`, and skip it silently otherwise.
+
+- Take the structure line `document-health` reports for each area folder, or read it from `canon context audit --json` the way that skill does
+- A folder with no overgrown entry and no doubled or unnamed coverage finding has no line, so go straight to Step 1 with no prompt
+- Show the operator each proposal and ask before applying it, since a split moves files other entries cite. Re-run the audit afterward to confirm the citations still resolve.
+- Take a declined proposal as a decision and rewrite the entry as it stands
+
 ## Step 1: read the audit
 
 Run the audit over the whole tree and take the density and reference shape findings from its record:
@@ -26,6 +35,12 @@ Run the audit over the whole tree and take the density and reference shape findi
 canon markdown audit --json
 ```
 
+When `canon/context/` is a candidate, read the context shape beside it and keep each entry's `shapeFindings` issues as the baseline Step 3 holds the rewrite to:
+
+```bash
+canon context 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.
@@ -46,6 +61,12 @@ 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.
 
+### Hold the context shape
+
+For a file under a folder the context audit resolves, also re-run `canon context audit --json` and compare the entry's `shapeFindings` issues with the baseline. A density fix that splits a Layout paragraph into several can grow `layout-paragraphs`.
+
+A rewrite leaving the entry with more shape issues than it started with is not done. Undo it, or fold the split into a table or a linked page, and report the entry as stopped when neither reaches the baseline. Zero density findings reached by growing shape findings only moves the failure.
+
 ## Step 4: gate the folder
 
 ```bash

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

@@ -84,7 +84,7 @@ What this skill adds on top of the standard:
 Every `- Suggested:` line takes senior judgment, picking the best option in one line with its reason or main tradeoff, and naming alternatives only when they change the pick.
 
 - Suggest a real default when best practice, the codebase, or prior context points to one
-- Load `canon:codebase-layout` before `## Files to touch` when an entry names a path that does not exist yet, and give each new path its placement reason. Report it if it does not resolve.
+- Before `## Files to touch`, load `canon:codebase-layout` for a new path (its reason) and `canon:api-design` for a changed verb, flag, output, record shape, or endpoint. Report either if missing.
 - Fill `## Design references` with the `canon/design/<surface>/` folder for each surface a UI file in `## Files to touch` renders, and write `None identified.` in a project with no folder
 - Write `## Verification` as one bullet per outcome naming the test or command that proves it
 - Write `## Review focus` as the inputs or states that would break the change, carrying the risk you understood to the executor and the reviewer

package/docs/agents/context-audit.md

@@ -46,7 +46,7 @@ The shape kinds are `retired-section`, `gotcha-count`, `gotcha-heading`, `gotcha
 
 - A `## Decisions` H2, or a `Gotchas` section past five bullets or holding a heading or paragraph
 - A `Layout` H3 titled neither a code-spanned path nor `Other folders`, or a heading below H3 under `Layout`
-- A folder H3 past five bullets or its one-paragraph lead
+- A folder H3 past five bullets or its one-paragraph lead, where table rows and the sentence leading the bullets after a table count toward neither
 
 The development entry may carry a `Scripts` H3 exempt from both folder caps. `SHAPE_GATED_FOLDERS` lives in `src/context/shape-gated.ts`.
 

package/governance/rules/code/routing.md

@@ -1,5 +1,5 @@
 ---
-description: Routes code placement and shape decisions to the skills that carry them, and library calls to the official docs
+description: Routes code placement, shape, and interface decisions to the skills that carry them, and library calls to the official docs
 ---
 
 # Code standards
@@ -12,6 +12,10 @@ description: Routes code placement and shape decisions to the skills that carry
 
 - Load the `canon:code-craft` skill before deciding the shape of a new function, class, or module, and report it rather than proceeding silently when it does not resolve.
 
+## Interfaces
+
+- Load `canon:api-design` before shaping a public function, flag or output, record format, endpoint, or caller-handled error, and report it rather than proceeding silently when it does not resolve.
+
 ## Libraries
 
 - Before calling a library API the codebase does not already use, fetch the official docs for the installed version and match the call to them, since recall of an API goes stale.

package/governance/rules/ui/design-taste.md

@@ -1,6 +1,10 @@
 ---
 description: Route edits that decide how a surface looks to the design-taste skill for the layer ordering, the coherence locks, and the defaults a model reaches for
 paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
   - '**/*.css'
   - '**/*.scss'
   - 'canon/DESIGN.md'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.57.0",
+  "version": "5.58.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/context/audit.ts

@@ -616,8 +616,16 @@ function shapeIssues(
   let inItem = false
   let inParagraph = false
   let afterBlank = false
+  let afterTable = false
+  let deferred = false
+
+  const settleDeferred = (): void => {
+    if (deferred && folder) folder.paragraphs++
+    deferred = false
+  }
 
   const closeFolder = (): void => {
+    settleDeferred()
     if (folder && !exempt.has(folder.text)) {
       if (folder.paragraphs > LAYOUT_PARAGRAPH_CAP) {
         issues.push({
@@ -661,6 +669,7 @@ function shapeIssues(
       inItem = false
       inParagraph = false
       afterBlank = false
+      afterTable = false
 
       if (level <= 2) {
         closeFolder()
@@ -697,11 +706,22 @@ function shapeIssues(
       inItem = true
       inParagraph = false
       afterBlank = false
+      afterTable = false
+      deferred = false
       if (gotchas) gotchas.bullets++
       if (folder) folder.bullets++
       continue
     }
 
+    if (folder && TABLE_ROW.test(line.text)) {
+      settleDeferred()
+      inItem = false
+      inParagraph = false
+      afterBlank = false
+      afterTable = true
+      continue
+    }
+
     const continues = inItem && (!afterBlank || INDENTED.test(line.text))
     afterBlank = false
     if (continues) continue
@@ -717,7 +737,12 @@ function shapeIssues(
         text: line.text.trim(),
       })
     }
-    if (folder) folder.paragraphs++
+    if (folder) {
+      settleDeferred()
+      if (afterTable) deferred = true
+      else folder.paragraphs++
+    }
+    afterTable = false
   }
 
   closeFolder()