@erclx/canon 4.107.0 → 4.108.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.107.0",
+  "version": "4.108.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -0,0 +1,46 @@
+---
+name: document-health
+description: What the document health check is for, the gap it closes, and why it reports three axes rather than one number
+---
+
+# Document health requirement
+
+## 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.
+
+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.
+
+## 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
+
+## 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.
+- 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
+
+## Out of scope
+
+- Whether a document exists or holds its required sections, which is the structural question `target-check` answers across six domains
+- Conformance of changed markdown to the authoring standards declaring jurisdiction over its paths, which is `standards-audit`. That skill is diff-scoped and standard-declared, taking a changed file and reporting which stated rule it breaks with a line number. This one is corpus-scoped and reads rot in documents nobody changed, which is the case a diff-scoped audit never reaches. The two sit beside each other rather than one absorbing the other.
+- Rewriting a stale claim once this run has named it, which is `markdown-propose`
+- 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.

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

@@ -0,0 +1,88 @@
+---
+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`.
+---
+
+# Document health
+
+Reports which documents have rotted rather than which are missing. `target-check` answers whether a project's documents exist and hold the right kind of content, and this answers whether the ones that exist still earn their place. It reports and never repairs, matching the structural check beside it.
+
+Three axes carry the report. Two answer from a verb and the third answers from a reading, which it says rather than hiding. `${CLAUDE_SKILL_DIR}/references/axes.md` holds what each axis measures, the checkpoint it reads against, and where a finding routes. This body holds the order, the guards, and the report shape.
+
+## Guards
+
+- `canon` absent from the path: stop. `❌ canon is not on PATH, so neither measured axis can be read.`
+- `git ls-files '*.md'` listing nothing: stop. `❌ No tracked markdown here, so there is no corpus to read.`
+- Run every command under `CANON_NON_INTERACTIVE=1` and prompt at no point. A caller reaching this from a rollout wave has nobody present to answer.
+- Branch on each record's own fields rather than on an exit status. An operator's shell profile may wrap `canon` in a function whose status comes from a trailing command, which reports every refusal as success.
+- Repair nothing, write no file in the project, and open no pull request. Whoever read the report decides what to fix.
+
+## Step 1: scope the corpus
+
+Take the documents the project hand-authors, defaulting to every tracked markdown file the two measured verbs reach. Narrow to a path the caller named when one was given, and say which scope the run took.
+
+Drop what nobody hand-authors before reporting a finding against it: a generated `index.md`, a file under a gitignored folder, and a bundled reference a generator copied out to its consumers. A finding against a copy names a file an author cannot fix, since the next regeneration overwrites it.
+
+## Step 2: read the two measured axes
+
+Run these from the project root, in parallel:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon markdown audit --json
+CANON_NON_INTERACTIVE=1 canon context audit --json
+```
+
+The first answers length, carrying the bullet, paragraph, and depth checkpoints and the per-file weights read against them. The second answers placement for the folders it resolves, carrying entry length, reference form, and index drift.
+
+Then read which classifier would run, and deepen placement with the verdicts per section:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon context classifier show
+CANON_NON_INTERACTIVE=1 canon context classify sweep --json
+```
+
+The first names the backend, the model, and the source that decided both. Report which layer answered, since a project with the model layer off reads from the regex layer alone and the sweep says nothing about which one it used.
+
+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.
+
+### 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.
+
+`canon context audit` refuses with `reason: "no-folders"` in a project whose folders resolve to nothing, which is the ordinary shape where the layout differs from the one the verb looks for. That refusal is the honest answer rather than a failure, and reading it as an empty finding set reports a healthy corpus for documents nothing looked at.
+
+A narrower read is not an unread one. The sweep running on its regex layer alone still answered, so it is reported with the layer named rather than as an axis nothing reached.
+
+## Step 3: read the staleness axis
+
+No verb answers whether a document still describes the tree it was written about. Read each document against the surfaces it names and report where the two have parted, taking the file paths, commands, and counts it states as the claims to test.
+
+Mark every staleness finding as a reading. It is this session's judgment rather than a measurement, and a report that sets it beside two verb-backed axes without marking it implies evidence the axis does not carry.
+
+## 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.
+
+The three classes are what keep the axes apart:
+
+- `measured`: a verb returned a number read against a stated checkpoint
+- `classified`: a verb returned a verdict carrying its own confidence
+- `read`: this session's judgment, backed by no verb
+
+Emit no verdict across the three. Two answer from verbs and one answers from a reading, so a roll-up is a figure that lies about the third. Emit no score across the documents either, for the same reason one level up.
+
+## Output
+
+Lead with the table, then one detail block per document carrying a finding:
+
+```markdown
+Document health: `<scope>`, <n> documents read.
+
+| Document         | Length              | Placement           | Staleness        |
+| ---------------- | ------------------- | ------------------- | ---------------- |
+| `path/to/doc.md` | ok / heavy / unread | ok / moved / unread | ok / stale / n/a |
+
+Length and placement are measured. Staleness is a reading.
+```
+
+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

@@ -0,0 +1,78 @@
+---
+title: Document health axes
+description: What each axis measures, the verb behind it, the evidence class it carries, and where a finding routes
+---
+
+# Document health axes
+
+One section per axis. Each states what it measures, the verb that answers it, the evidence class the answer carries, and the surface a finding routes to.
+
+The skill body holds the order, the guards, and the report shape. This holds the detail a run dereferences once it has a finding to place.
+
+## Length
+
+**Measures:** whether a document, or a passage inside it, has grown past what a reader takes in one pass.
+
+**Verb:** `canon markdown audit --json`.
+
+**Evidence class:** `measured`.
+
+The record carries the checkpoints it read against under `checkpoints` and the per-file weights under `entries`. Read both from the record rather than from a number stated here, since the CLI moves a checkpoint on its own cadence and a copy of one goes stale in place.
+
+Four weights answer this axis, each naming a different shape of overgrowth:
+
+- `heavyBullets`: a top-level bullet past the character checkpoint, which is a paragraph wearing a dash
+- `heavyParagraphs`: a paragraph past the sentence or character checkpoint
+- `longestRun`, against `longestRunLine`: unbroken rendered lines between headings, which is the depth checkpoint
+- `cadence`, carrying `measured`, `flat`, and `repeating`: sentence-length spread and repeated openers
+
+Weight is a judgment a reader settles rather than a defect, which the verb states for itself and which this axis carries forward. A finding here is an argument for a split or a trim rather than a rule broken.
+
+**Routes to:** a split of the document, or a move of the overgrown passage to the surface that owns it. Where the project states what a given document may hold, that statement decides whether the passage belongs in it at all, and the finding routes there rather than to a trim.
+
+**Caveat:** the cadence numbers are drawn from prose a person reads straight through. Terse reference prose sits below that range correctly, so a flat paragraph in a table-heavy or bullet-heavy file is not a finding.
+
+## Placement
+
+**Measures:** whether a document's content sits in the file that owns it, and whether the catalogs pointing at it still resolve.
+
+**Verbs:** `canon context audit --json` for the structural half, `canon context classify sweep --json` for the per-section verdicts.
+
+**Evidence class:** `measured` for the audit's findings, `classified` for the sweep's verdicts.
+
+The audit answers required sections, entry length, citation resolution, reference form, catalog tables, provenance, and index drift. A citation resolving to nothing is a fact and gates. Entry length, reference form, table shape, and provenance are judgments under every flag.
+
+The sweep classifies each section as keep, replace or rewrite, history, or move. A `move` verdict is the placement finding proper, naming content sitting in the wrong document. Each verdict carries its own confidence, which is why the class is `classified` rather than `measured`, and 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.
+
+**Caveat:** both verbs resolve their folders by surface root rather than by a path written into them, so a project whose layout differs from the one they look for resolves nothing. The audit says so, refusing with `reason: "no-folders"` and naming the folders it looked for. Report that refusal as an unread axis. The sweep degrades differently: with the model layer off it answers from its regex layer alone, which is a narrower read rather than a refusal, so say which layer answered.
+
+## Staleness
+
+**Measures:** whether a document still describes the tree it was written about.
+
+**Verb:** none.
+
+**Evidence class:** `read`.
+
+This is the axis the operator names first and the one nothing measures. A document goes stale by the tree moving under it rather than by anything changing in the document, so no property of the file answers it and a timestamp answers a different question. A file untouched for a year beside code untouched for a year is current, and one edited yesterday against a refactor from this morning is stale.
+
+Read each document against the surfaces it names. Four claim shapes are testable without leaving the project:
+
+- A file or folder path the document states, against whether it resolves
+- A command or verb the document names, against whether it exists and carries the flags shown
+- A count the document states over a tree, against the tree
+- A cross-reference to another document, against what that document now says
+
+A claim resting on none of the four is unverifiable from here. Report it as unread rather than as passing, which is the same rule the measured axes take when a verb refuses.
+
+**Routes to:** the skill that rewrites a stale claim against an answer, rather than a direct edit from here. A document health run reports and never repairs.
+
+**Caveat:** a reading is the weakest evidence in the report and the most consequential finding in it, which is the tension this axis ships with. Marking the class is what keeps the two facts together in the reader's hands.
+
+## Why the three stay apart
+
+The axes are not equally actionable and a report flattening them implies they are. A length finding is a number against a checkpoint, a placement finding is a verdict carrying a confidence, and a staleness finding is a judgment with nothing behind it. Each is worth reporting and each is worth a different response, so the class travels beside the state on every row rather than being stated once in a preamble a reader skims.
+
+Shipping staleness on weaker evidence than the other two is the trade taken deliberately. Cutting it would leave the report answering the two questions that were never the operator's complaint.

package/docs/workflow/ai-workflow.md

@@ -240,6 +240,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | ------------------------ | --------------------------------------------------------------------------------------- |
 | `canon:review-branch`    | On the local branch diff, before anything is pushed                                     |
 | `canon:standards-audit`  | When changed markdown has to answer to the authoring standards                          |
+| `canon:document-health`  | When the documents themselves have to answer for length, placement, and staleness       |
 | `canon:markdown-propose` | When a markdown claim needs rewriting and the change should wait for an answer per file |
 | `canon:ux-audit`         | To read UI source for missing states, edge cases, and inconsistencies                   |
 | `canon:ux-measure`       | To start the interface and measure paint, processor, and layout cost                    |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.107.0",
+  "version": "4.108.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/workflow.ts

@@ -117,6 +117,16 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Check whether the markdown I changed violates any authoring standards.',
     expect: 'standards-audit',
   },
+  // Rot across documents nobody changed is what separates this from
+  // `standards-audit`, which is diff-scoped and reports a stated rule broken on
+  // a given line. It is also not `target-check`, which asks whether a document
+  // exists and holds its sections rather than whether it still describes the
+  // tree.
+  {
+    prompt:
+      'Which of our docs have gone stale, grown too long, or ended up in the wrong file?',
+    expect: 'document-health',
+  },
   {
     prompt: 'Open a new entry on the task board for this piece of work.',
     expect: 'task-board',