@erclx/canon 5.38.0 → 5.40.0

package/docs/agents/install-and-sync.md

@@ -1,246 +1,136 @@
 ---
 title: Install and sync
-description: What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
+description: What each install and sync verb writes, refuses, or leaves alone, the drift report and its seven side sections, the rule detection record, and version skew states
 ---
 
 # Install and sync
 
-The behavior notes behind the verbs listed in `commands.md`. Each one records what the verb writes, what it refuses, and what it deliberately leaves alone.
-
-## Domain sync
-
-`canon gov sync` updates only rules already present under
-`.claude/rules/canon/` and never adds new ones. That wrapper marks the
-toolkit-owned half of the tree, and it is the whole of what the walk reaches:
-`.claude/rules/project/` sits outside it by location and is never read,
-matched, or reported on, which is how project-authored rules survive. It also
-removes a stale `.claude/GOV.md` from the retired build. Use
-`canon gov install` to add rules.
-
-Everything under `.claude/rules/canon/` belongs to the toolkit, so a rule
-there that the toolkit no longer ships is deleted on sync, edited or not. That
-is how a retired rule stops loading in a target. A renamed rule
-the toolkit declares in `governance/renames.toml` moves instead: the sync
-installs the rule under its new name and deletes the old file, whether or not
-the target's stamp records a stack. Local edits to the old file are not
-carried, and the sync says so. The sync lists each change by path before it
-applies, and the target's git diff is the record afterwards. `canon sync
---check` lists the same file as `retired` or `renamed` before any sync runs.
-
-A rule that only routed a path to a standard now names the skill that owns
-the guidance. The tasks, plan, context, and skill rules are hand-written at
-`canon/` and `claude/skill.md`. A held copy of each syncs in place, and the
-groundwork, intake, session, design, readme, and rule copies are deleted as
-retired. The markdown rule is hand-written at `writing/markdown.md` and names
-the `markdown-craft` skill, and `800-prose` retires.
-
-A project's own rules belong under `.claude/rules/project/`, where a slug
-the toolkit also ships collides with nothing, and a rule placed under `canon/`
-instead is lost on the next sync.
-
-A sync never deletes a rule that a newer canon release installed. The stamp
-records the newest release that synced governance, and an older binary holds
-every rule it finds no source for, naming both releases and asking for an
-upgrade, rather than deleting what it cannot recognize.
-
-A renamed rule loses its old file and gains nothing under the new name unless
-the target's stamp records the stack it installed, in which case the new name
-shows as `missing` and `canon gov install <stack>` adds it.
-
-Design's own orphans are the target's overrides and are meant to stay where
-they are, so `canon design sync` deletes nothing it finds no source for.
-
-`canon design install` copies one toolkit-owned file to
-`.claude/design/base.css` and creates no override. A project overrides a value
-by writing `.claude/design/project/` itself, which `canon design sync` never
-touches, because that subfolder is project-authored by location the way
-`.claude/rules/project/` is. An override named exactly like the shipped file is
-still the project's.
-
-A project's faces sit in that subfolder too, under `fonts/` with plain
-`@font-face` rules in `fonts.css`. `canon design fonts add <file> --family <name>`
-copies a `woff2`, `woff`, `ttf`, or `otf` face in and appends its rule
-(`--weight`, `--style`, `--json`), refusing bytes that disagree with the
-extension as `invalid-font`. `fonts list --json` emits one row per rule, with a
-`problem` where the file is missing or lies outside the subfolder.
-
-The override ships absent rather than empty. An empty file is one the project
-did not ask for and did not write, the reconciliation already handles a missing
-side, and an empty override invites a target to fill it before it has an
-opinion.
-
-Nothing arrives on a project that has not run `canon design install`. The
-domain is detected by that folder existing, so `canon sync` skips it entirely on
-a target that never installed it, and the unstamped line at the end of
-`canon sync --check` stays quiet about it for the same reason. Governance is
-named there when it is absent and design is not, because a managed project
-without governance has yet to install what every project carries, while one
-without design chose that.
-
-When the target's install recorded a stack, `canon gov sync` also reports a
-rule that stack lists and `.claude/rules/canon/` does not hold, as a `missing`
-entry carrying no change. This is what makes a target whose recorded sync point
-postdates a rule joining its stack still see that rule: the report reads the
-target's current entitlement against its current tree rather than diffing
-from an anchor a later sync could advance past the rule's own commit. A
-target whose install predates the recorded chain falls back to the same
-rule-folder-inference `newRules` uses in `canon sync --check`.
-
-## Tooling diff and sync
-
-`canon tooling diff <stack> [target]` is the read-only comparison, and a session asking what differs reaches for it by default. It writes nothing and exits 1 when anything differs and 0 when nothing does, so it gates CI. `--json` adds the scan record on stdout with `ok: true`, and the frame goes to stderr. A refusal such as an unknown stack, an excluded stack, or a toolkit-root target still exits 1 and answers `{ ok: false, reason, message }`, so a caller branches on the record and reads a typo'd stack name as a refusal rather than as drift.
-
-The record carries a `withheld` array beside `configs`, each entry `{ rel, stack, present }`. It fills only when the target sits below its git root: every `.github/` config or seed moves there rather than into `configs` or `seeds`, and none of them counts toward the exit, since GitHub never reads a workflow outside the root. `present` marks a copy an earlier sync already left in the subfolder, which the sync reports and never deletes. At a root, and for a target outside any repository, `withheld` is empty.
-
-`canon tooling sync <stack> [target] --check` reports the same list and always exits 0. It stays for scripts that already call it. `sync` itself writes only under `--write`, and a headless run with neither flag reports and exits 1.
-
-## Install guards
-
-`canon gov install` requires its first argument under
-`CANON_NON_INTERACTIVE=1`. It used to fall back to an interactive picker that
-resolved to its first option headlessly, so a call with no stack installed
-whichever stack sorted first. It now reports the valid names on stderr and
-exits 1.
-
-Every documented agent path already passes the argument, including
-`canon init`. The confirm-then-apply prompt after it still resolves to `Yes`
-headlessly, so a call that names its stack is unchanged.
-
-`--add` with no stack installs the named rules into the one positional, or the
-current directory, and keeps the recorded chain. Pass `./node` to force a target
-named like a stack. [Rule detection](gov-detect.md) proposes the names.
-
-`canon gov install` also refuses the toolkit root as a target. It resolves the
-target before anything else, so a path that does not exist fails rather than
-being scaffolded.
-
-A target still on the flat installed-rule layout from an older release reports
-"No governance surfaces found in target" from `canon gov sync` and exits 0,
-since sync reads only the current wrapped destination. `canon gov install`
-against that same target writes a second, wrapped copy beside the flat one
-rather than reading or clearing it, so the target ends up holding both, and
-Claude Code loads both copies of an edited rule at session start. Run `canon
-migrate rule-layout` first to move a target off the flat layout, which reports
-what it would move and applies it under `--write`.
-
-## Governance regen
-
-`canon gov regen` is the one governance verb that runs against the toolkit root,
-because the `.claude/rules/` it writes there is produced output rather than an
-operator's working copy. It reads the stack recorded in `internal/governance.toml`
-into `.claude/rules/canon/`, installs anything under `internal/rules/` into a
-separate `.claude/rules/internal/`, and clears both destinations first so a
-rule the record stopped naming disappears. `internal/` is what this repository
-alone carries: no `canon gov install` or `canon gov sync` target ever writes it,
-since a target has no rule source of its own that ships nowhere.
-
-It takes `--root <path>` and defaults to the toolkit root, prints nothing on success, and
-reports the reason on stderr with exit 1 when the record names a stack or rule
-that does not resolve. The Consumed copies stage of `bun run check` calls it and
-asserts both the generated rule folders and the consumed copy are committed.
+What each verb writes, refuses, and leaves alone. `canon --help` lists flags.
+
+## Bootstrap
+
+`canon init [path]` installs up to five core domains and reports each independently. A failed domain does not abort the run, which finishes the rest and exits 1 naming the failures.
+
+Any flag skips the confirmation prompt, but the `base` default of `--stack` does not count, so a bare `canon init` still prompts. `--skip` takes `wiki`, `governance`, and `records`, and warns on any other value.
+
+## Governance install
+
+- `canon gov install <stack> [target]` needs the stack under `CANON_NON_INTERACTIVE=1`, else lists the valid names on stderr and exits 1
+- `--yes` answers the install confirm with no TTY and no env var. Without it, a headless call refuses and the message names `--yes`. It does not pick a stack.
+- It refuses the toolkit root and a missing path
+- `--add <rules>` with no stack installs into the one positional, or the current directory, keeping the recorded chain. Pass `./node` for a target named like a stack.
+
+A flat installed-rule layout makes `gov sync` report "No governance surfaces found in target" and exit 0, and `gov install` write a second, wrapped copy. Run `canon migrate rule-layout` first.
+
+## Governance sync
+
+`canon gov sync [target]` updates what `.claude/rules/canon/` holds and adds nothing. `.claude/rules/project/` is never read, so put project rules there.
+
+- A rule the toolkit no longer ships is deleted, edited or not
+- A rule renamed in `governance/renames.toml` moves, and its local edits are dropped
+- A rule the recorded stack lists and the tree lacks reports as `missing` with no change
+- A retired `.claude/GOV.md` is removed
+- A binary older than the stamp holds every rule it has no source for and asks for an upgrade
+
+After a rename the new name shows as `missing` when the stamp records a stack, and `gov install <stack>` adds it.
+
+`canon gov regen [--root <path>]` runs against the toolkit root alone. It rewrites `.claude/rules/canon/` and `.claude/rules/internal/` from `internal/`, and exits 1 when the record names something that does not resolve.
+
+## Rule detection
+
+`canon gov detect [target] [--stack <stack>] [--json]` proposes opt-in rules and writes nothing, from `governance/detect.toml` evidence keyed by rule basename.
+
+- `deps` match package names in `package.json`, `pyproject.toml`, `go.mod`, and `composer.json`
+- `files` are globs matched against git-listed paths and their folders, to depth two. Install what the operator keeps with `canon gov install --add <rules> <target>`.
+
+```json
+{
+  "target": "",
+  "stack": "node",
+  "proposals": [
+    {
+      "rule": "react",
+      "evidence": [{ "kind": "dep", "match": "react", "path": "package.json" }]
+    }
+  ]
+}
+```
+
+- `kind` is `dep` or `file`, and `stack` is null without `--stack`, which drops rules that stack resolves
+- A glob without a wildcard is also tested on disk, an unparseable manifest contributes nothing, and outside git the walk skips `.git`, `node_modules`, `vendor`, and `.venv`
+- It exits 0 on any readable target and 1 for a missing target or an unresolved stack
+
+## Tooling
+
+- `canon tooling diff <stack> [target]` is the read-only comparison, exiting 1 on any difference
+- A `--json` refusal answers `{ ok: false, reason, message }`, so branch on the record
+- `withheld` entries are `{ rel, stack, present }`, hold every `.github/` file below the git root, and count toward no exit
+- `present` marks a copy an earlier sync left, which is reported and never deleted
+- `canon tooling sync <stack> [target]` writes only under `--write`. `--check` reports and exits 0, and a headless run with neither flag exits 1.
+
+`canon tooling inject` and `prune-gitignore` apply one stack with no scan or prompt, and the latter prints the number removed on stdout. Use `sync` unless scripting provisioning, and pass `--nested` inside an open frame.
+
+## Design
+
+- `canon design install` copies `base.css` to `.claude/design/` and creates no override
+- Project overrides live in `.claude/design/project/`, which `design sync` never touches
+- `canon design fonts add <file> --family <name>` copies a `woff2`, `woff`, `ttf`, or `otf` face into `project/fonts/` with its `fonts.css` rule, and refuses mismatched bytes as `invalid-font`
+- `fonts list --json` flags a missing or out-of-folder file as a `problem`
+- `canon sync` skips the domain where `design install` never ran
 
 ## Whole-project sync
 
-`canon sync` runs every installed domain sync, then offers to commit the result
-and open a pull request. Under `CANON_NON_INTERACTIVE=1` it applies the domain
-syncs and then refuses the git workflow, reporting the branch and commit it
-would have created and exiting 0. Nothing is staged, committed, or pushed
-headlessly.
-
-Run it interactively to reach the commit and pull request options.
-It also refuses a target whose working tree is dirty, so commit or stash first.
-
-## Drift reporting
-
-`canon sync --check` reports drift and writes nothing, so it needs no clean tree
-and is safe to run at any time. Each file is classified as `stale` when it still
-matches what the toolkit installed, `customized` when the project edited it,
-`stranded` when it sits at a path the toolkit no longer installs to, `orphaned`
-when the project authored it, or `drifted` when no stamp covers it. Governance
-also reports `missing`, for a rule the target's recorded stack lists that its
-tree does not hold at all, `retired`, for a rule under
-`.claude/rules/canon/` the toolkit no longer ships, which the next sync
-deletes, and `renamed`, for one the toolkit ships under a new name, which the
-next sync moves. A `retired` or `renamed` file counts toward `--exit-code`,
-since one sync clears it.
-
-Use `--json` for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
-and missing files are both excluded from that exit code: a project-authored
-rule never converges, and a sync that added a missing one silently changes
-what the project is governed by, which stays a separate command an operator
-chooses to run. Attribution reads `canon/config/config.json` first, which every
-install and sync now writes, and falls back to `.claude/canon/config.json` for
-a target that has not moved.
-
-A target installed before stamping shipped has no such file, and neither does
-that fallback do anything to migrate it. A target stamped before the file
-moved into `.claude/canon/` still carries it at the retired
-`.claude/canon.json`, and `canon sync --check` reads that path when the current
-one is absent, reporting it rather than moving it. Only a target carrying
-neither path falls back to the toolkit's own git history.
-Installed content matching any
-version that history ever published proves the file is untouched, so it reports
-`stale` naming the commit it came from, and content matching no published
-version stays `drifted`. A toolkit reached outside a git clone, which is what a
-registry install is, cannot run that fallback and reports
-`historyUnavailable` alongside the unattributed files.
-
-Each domain carries its own toolkit anchor in that file, so syncing one domain
-never advances the revision another measures from, and each reports the upstream
-commits touching its own source path. The `covers` field names the domains a
-target has actually stamped, so a domain that was never stamped is legible
-rather than reading as a clean one.
-
-### Tooling
-
-Tooling records the stack chain an install resolved rather than per-file hashes,
-since `src/tooling/` runs its own inject machinery and has no walk to attribute.
-The chain is ordered nearest stack first, which is what a `--skip` run needs:
-recording the leaf alone would send the next report measuring against a layer the
-target deliberately does not carry. The report loads exactly those stacks, scans
-them the way `canon tooling diff` would, and counts what differs per category
-under `tooling.counts`.
-
-`measured` is the field the section exists for. A target carrying no chain
-reports `measured: false`, which separates tooling nobody has ever looked at from
-tooling that is current. Both produce zero changes otherwise. Every target
-installed before the record shipped starts unmeasured and leaves on its next
-`canon tooling sync`, since backfilling would mean inferring the chain from
-installed files, which is the guess the record replaces.
-
-A workspace root records nothing, because each package resolves its own chain and
-one written at the root would be that same guess. Run the check against a package
-to measure it. Tooling never counts toward `--exit-code`, on the grounds seeds
-are already excluded on, since it reports golden configs a project is expected to
-edit and a job counting those stays red with no remedy.
-
-### Surfaces reported beside the domains
-
-Seven sections sit outside the per-domain scan, because each names something
-that walk cannot see: `seeds`, `superseded`, `unmigrated`, `unmovedSurfaces`,
-`newSkills`, `newRules`, and `reverse`. None of them produces a change, and no sync command
-applies any of them. What each reports, the managed-target gate they share, and
-which count toward `--exit-code` are in `drift-surfaces.md`.
+`canon sync [path]` runs every installed domain sync, then offers a commit and pull request. Headlessly it applies the syncs, refuses the git workflow, reports what it would have made, and exits 0. It refuses a dirty working tree.
 
-## Bootstrap
+## Drift report
+
+`canon sync --check` writes nothing and needs no clean tree. `--json` emits the record, `--exit-code` fails CI.
+
+| State        | Meaning                                                            |
+| ------------ | ------------------------------------------------------------------ |
+| `stale`      | Still matches what the toolkit installed                           |
+| `customized` | The project edited it                                              |
+| `stranded`   | Sits at a path the toolkit no longer installs to                   |
+| `orphaned`   | The project authored it                                            |
+| `drifted`    | No stamp covers it                                                 |
+| `missing`    | Governance only. The recorded stack lists it and the tree lacks it |
+| `retired`    | Governance only. The toolkit no longer ships it                    |
+| `renamed`    | Governance only. The toolkit ships it under a new name             |
+
+`retired` and `renamed` count toward `--exit-code`. `orphaned` and `missing` do not.
+
+- Attribution reads `canon/config/config.json`, then `.claude/canon/config.json`, then the retired `.claude/canon.json`, and moves none
+- With none it matches the toolkit's git history, where a published version is `stale` and anything else `drifted`. A registry install has none and reports `historyUnavailable`.
+- `covers` names the domains the target stamped, and each domain keeps its own anchor
+- Tooling records its stack chain, nearest first, and never counts toward `--exit-code`
+- `tooling.measured: false` means none was recorded. It clears on the next `canon tooling sync`. A workspace root records nothing, so run the check against a package.
+
+## Side sections
+
+Seven sections sit outside the per-domain scan, and no sync applies them. Each returns empty when `managed` is false. A managed target holds `.claude/`, a `CLAUDE.md`, or a root-layout domain, and an unmanaged one is routed to `canon init`.
+
+| Section           | Reports                                                                                 | Exit |
+| ----------------- | --------------------------------------------------------------------------------------- | ---- |
+| `seeds`           | Each seed as `matching`, `stale`, `drifted`, or `missing`. Merge an edited one by hand. | No   |
+| `superseded`      | A file a newer seed folder replaced, as `replacedBy`. Never deleted.                    | No   |
+| `unmigrated`      | A domain at its old root, with `rootPath`, `installPath`, and a count                   | Yes  |
+| `unmovedSurfaces` | A surface at its `.claude/` spelling, as `rel` and `movesTo`                            | No   |
+| `newRules`        | A rule the recorded stack lists and the tree lacks                                      | No   |
+| `newSkills`       | A plugin skill the target has not seen. Needs no command.                               | No   |
+| `reverse`         | `unclaimed` folders the toolkit once shipped                                            | No   |
+
+The Exit column marks what counts toward `--exit-code`. `canon migrate surface-roots` closes `unmovedSurfaces`, and `canon gov install` closes `newRules`. A `reverse` entry is attributed `dropped`, `project`, or `unattributed`.
+
+`newRules` and `newSkills` come back empty on a shallow clone or registry install, which is unmeasured rather than clean.
+
+## Version skew
+
+`canon sync --check` and `canon claude skills drift` report the installed version against the newest published one in `skew.state`. The report never changes an exit code, so branch on the field.
+
+| State     | Meaning                                              |
+| --------- | ---------------------------------------------------- |
+| `behind`  | Names `canon upgrade` as the remedy                  |
+| `current` | Installed matches published                          |
+| `unknown` | Carries the reason the registry could not be reached |
 
-`canon init` installs up to five core domains and reports each one independently. A
-domain that fails does not abort the run, so the command finishes the rest and
-exits 1 naming the failures. Passing any flag skips the confirmation prompt,
-which is what makes it scriptable.
-
-`--stack` defaults to `base`, and the default
-does not read as a passed flag, so a bare `canon init` installs governance and
-still prompts. `--skip` takes `wiki`, `governance`, and `records`, and warns
-without aborting on any other value. Records has nothing to run non-interactively,
-since the private backup repository does not exist yet at scaffold time, so its
-step only prints the one-time setup reminder and `--skip records` silences it.
-
-## Unguarded tooling primitives
-
-`canon tooling inject` and `canon tooling prune-gitignore` are the unguarded
-primitives beneath `sync`. They apply one stack with no scan and no prompt, and
-they deliberately skip the check that rejects `claude`, which is how `canon
-claude` drives its own stack through them. Use `sync` unless you are scripting
-provisioning. Both frame their own output, so pass `--nested` when calling from
-inside an already-open frame.
+`canon upgrade --json` adds `pending`, where the checkout holds a release npm does not serve yet. `checkout` names it, `message` starts `CLI stays at`, and the exit is 0.

package/docs/agents/markdown-audit.md

@@ -1,126 +1,84 @@
 ---
 title: Markdown audit
-description: Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
+description: Running the markdown audit over any path, each finding it reports with whether it gates, the six density limits, the advisory measures, the exit codes, and where the audit runs
+kind: reference
 ---
 
 # Markdown audit
 
-`canon markdown audit [path...]` reports any markdown file against the `markdown-craft` skill's `markdown.md` reference. That reference governs a file rather than a folder, so this resolves no folder and requires no `index.md`, which is what puts `.claude/rules/` and `governance/` in reach. Folder-shaped findings stay in `canon context audit`, described in `context-audit.md`.
+`canon markdown audit [path...]` reports any markdown file against the `markdown-craft` skill's `markdown.md`. It resolves no folder and needs no `index.md`, so `.claude/rules/` and `governance/` are in reach. Folder-shaped findings belong to `canon context audit`, in `context-audit.md`.
 
 ```bash
 canon markdown audit
 canon markdown audit --json
 canon markdown audit .claude/rules governance
-canon markdown audit docs/agents/commands.md
+canon markdown audit docs/agents/install-and-sync.md
 canon markdown audit 'docs/**/*.md'
 ```
 
-| Option   | Behavior                                                   |
-| -------- | ---------------------------------------------------------- |
-| `--json` | Add a machine-readable record on stdout, keeping the frame |
+An argument is a file, a directory, or a glob, taken against the corpus git lists. A bare run measures every tracked or untracked-and-not-ignored file. An explicit file is taken as given, so a gitignored draft can be measured, and an argument matching nothing is named on the scope line.
 
-## Scope
+## Output
 
-An argument is a file, a directory, or a glob. A directory narrows to everything under it and a glob narrows by match, both against the corpus git lists, which is what keeps `node_modules/` and the gitignored session-scratch folders out without naming either. An explicit file path is taken as given, so a gitignored draft can be measured before it is committed. Quote a glob the shell would expand first.
+The ban set and checkpoints ship in `src/markdown/bans.ts` and `src/markdown/structure.ts`. `markdown.md` states each rule and the `write-human` skill states the cadence numbers, so move a number in both places in one change.
 
-A bare run measures every markdown file git lists, tracked plus untracked-and-not-ignored, so a file added on this branch is in scope on the branch that adds it. An argument matching no markdown file is named on the scope line rather than passed over, since a run measuring the paths that did resolve otherwise reads as a pass over one it never opened.
+| Finding         | Reports                                                                              | Gates                     |
+| --------------- | ------------------------------------------------------------------------------------ | ------------------------- |
+| Bans            | The two characters `markdown.md` bans, outside frontmatter, fences, spans, and links | Always                    |
+| Links           | A relative link resolving to nothing on disk                                         | Always                    |
+| Density         | The six limits below, under `density`                                                | On a `GATED_PATHS` prefix |
+| Reference shape | A `kind: reference` page breaking its shape, under `referenceShape`                  | On a `GATED_PATHS` prefix |
+| Colons          | A colon followed by more text in a prose line, under `colons`                        | Never                     |
+| Heading case    | A capital after the first word of a heading or `title`, under `headingCase`          | Never                     |
 
-## Where the rules come from
+A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, and `See also` as H2s, each at most once and in that order. It takes no H3 and no table headed `Flag` or `Option`. An unmarked page is never measured.
 
-The ban set and all ten checkpoints ship with the `canon` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same set whether or not it installed the plugin, and no file has to resolve for a run to mean something.
+| Density limit       | Finding                                                    |
+| ------------------- | ---------------------------------------------------------- |
+| Paragraph length    | A prose paragraph past 350 characters                      |
+| Paragraphs in a row | More than 2 paragraphs with nothing else between them      |
+| Bullet length       | A top-level bullet past 200 characters                     |
+| Bullets in a row    | More than 5 plain top-level bullets                        |
+| Heading depth       | Any heading past H3                                        |
+| H3 opening          | An H3 whose first block is neither a paragraph nor a table |
 
-Seven of the ten are stated in `markdown.md` and the three cadence numbers are stated in the `write-human` skill. That split is the content boundary rather than an accident: `markdown.md` carries the enforced rules a scan can decide, and the skill carries the rhythm rules a ban list cannot express. A cadence number moved in the skill and left in the code drifts the same way, so move both.
+- A paragraph under a list item counts toward that bullet, never as a paragraph
+- A table, fence, list, heading, or bold section marker ends a run of paragraphs
+- A run whose every item opens with a bold label or a link is exempt, and numbered items never count
+- Only context entries, docs, skill bodies and references, tooling seeds and stack references, the wiki, `README.md`, and `CONTRIBUTING.md` take a finding
+- A bullet run gates everywhere those paths sit, and the rest gates under `GATED_PATHS` in `src/markdown/scope.ts`. Outside a canon checkout nothing gates.
 
-Reading them out of the reference per run was the original design. It put a parser contract on a document authored for people, and the reference had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
+Five measures report and never set the exit code on their own.
 
-`markdown.md` still states every ban and every checkpoint, and a reader follows it rather than the code. Nothing compares the two, so a number moved in one place and left in the other drifts silently. Move both in the same change.
+| Measure    | Reports                                                                              | Gate or report                         |
+| ---------- | ------------------------------------------------------------------------------------ | -------------------------------------- |
+| Bullets    | A bullet past 200 characters                                                         | Gates through the density length       |
+| Paragraphs | A paragraph past 4 sentences or 350 characters                                       | Gates through the density length       |
+| Cadence    | 3 or more sentences with a spread of 5 words or under, or a word opening more than 2 | Reports                                |
+| Depth      | A run past about 40 rendered lines at 80 columns                                     | Reports                                |
+| Length     | A document past 300 rendered lines, unless it carries `canon-length-exempt`          | Reports, and the gate owns the verdict |
 
-The set is closed rather than extensible, so a project cannot add a term by editing a file. It holds the two characters alone, since a character is the one class a literal match settles. The set once carried 13 words and 6 British spellings as well. The words moved to the `write-human` skill as guidance, because a word ban catches the token and misses the habit, and `just`, `allows`, and `very` carry honest uses no literal match separates. Spelling is left to the author, with American spelling carried as guidance in `markdown-craft`.
+| Code | Meaning                                                            |
+| ---- | ------------------------------------------------------------------ |
+| `0`  | No gating finding                                                  |
+| `1`  | Refused, with the reason on stderr                                 |
+| `2`  | A ban, a dead link, or a gating density or reference shape finding |
+| `3`  | The shipped ban set is empty, so nothing was measured              |
 
-A set shipped empty is reported rather than passed. It finds nothing and would exit clean, which reports a corpus nobody checked as a corpus carrying no violation, so the run names the empty set and exits `3`. The set ships with the package, so a defect in the build is the only cause left.
+Rewrite the sentence on a ban hit rather than swapping the token. A code span clears the report only where the token is an identifier under discussion.
 
-## What each check reports
+The audit runs in four places:
 
-### Bans
+- `.claude/hooks/standards-audit.sh` after each markdown edit, handing back every finding
+- The `Markdown` stage of `canon gate run`, over the whole corpus
+- `scripts/verify.ts` in a scaffolded project, excluding `CHANGELOG.md` and skipping with a logged line when no `canon` is on `PATH`
+- The seeded hook in a target
 
-One closed set reports a hit: the characters `markdown.md` bans under `## Punctuation`.
+## Refusals
 
-Frontmatter, fenced blocks, inline code spans, and link destinations are excluded. Without the code-span exclusion each reference would report its own backticked examples, and without the link exclusion a semicolon in a query string would report as prose no rewrite can fix.
+- `no-git` or `no-markdown`: no corpus can be built, and the gate reads it as unmeasured
 
-Word choice stays unmeasured and the report says so on every run. Single words travel in the `write-human` skill as guidance a reader applies. A multi-word ban escapes the harvest by width, whether it carries a placeholder standing in for the rest of the sentence or spells the phrase out in full, and every rule under `## Voice` is a judgment. The bans `## Language` states over what a sentence may claim are patterns of the multi-word kind by construction, since a literal match over a pattern reports the compliant text and reaches none of the violations. A report listing hits without naming those would read as a verdict on the whole reference.
+## See also
 
-### Links
-
-A relative link's destination resolves against the filesystem, over the same corpus the ban scan reads. A destination is skipped rather than resolved when it is empty, opens with a URL scheme, opens with `#` as a same-file anchor, opens with `/` as a root-absolute reference, or carries `<` as a template placeholder such as `<slug>` or `<name>`. What remains is split on its first `#`, decoded, and resolved against the linking file's own folder, and a destination resolving to nothing on disk reports.
-
-The placeholder exemption is the one live case the corpus needs. Every current instance is a genuine illustration rather than a literal path, and a marker-based override is available for the day a real one needs an exception instead.
-
-### Colons and heading case
-
-Two advisory measures report beside the bans and never fail a run.
-
-The colon measure reports a colon followed by more text in a prose line, outside the label position. A list item's first colon, a bold or code span label, a line-final colon, a time, a URL, and anything inside a code span or a link are left alone. A heading, a table row, and a fenced line are skipped. Each finding carries the line, the column, the line's text, and the word before the colon as `lead` under `colons` in the `--json` entry.
-
-The heading-case measure reports a heading or a frontmatter `title` with a capitalized word after its first, outside code spans and all-caps tokens, under `headingCase`. A proper noun reports as well and is left as it is.
-
-`CHANGELOG.md` is exempt from both, since the release tool writes its headings.
-
-### Weight, cadence, and length
-
-Bullet and paragraph weight, bullet stacks, run depth, the two cadence numbers, and the document length ceiling are each a judgment a reader settles rather than a fact a scan settles. What each measures, the samples behind its checkpoint, and why none of them gates are in `markdown-audit-weight.md`.
-
-## Exit codes
-
-Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code. A bullet stack, a run of more than 5 plain bullets, reports the same way, and the `bullet-stacks` stage in `canon gate run` owns its verdict. Length reports the same way, since the audit also runs on a plan kept out of version control, and the Document ceiling stage in `canon gate run` owns that verdict instead.
-
-`3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `canon gate run` is right to report it as unmeasured rather than as a pass. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
-
-`2` rather than `1` for the gate keeps a measurement that succeeded and found something distinct from the audit declining to measure at all. A caller reading one as the other sends a reader hunting a defect that does not exist, which is the distinction `canon context audit` and the gate's own seed stage already draw between the same two codes.
-
-A banned character is a fact rather than a judgment, which is the test that admits it to a gate. What held it back was that gating on day one against a corpus never checked mechanically fails loudly on work nobody has had a chance to fix. The order was to land the verb reporting, measure the corpus once, fix what it finds, and turn the gate on as its own change, and the gate is the last of the four.
-
-Of the five measures a first full reading took, the ban count is the only one a gate should ever read.
-
-The ban half reached zero, which was the precondition the gate waited on, and it was re-measured against the same corpus at the moment the gate landed. Three sweep slices then took the structural half, and the corpus reports 1 heavy bullet and 22 heavy paragraphs across 6 files on 2026-08-06, every one on a ground the triage record holds as exempt.
-
-Depth is the one measure no slice triaged, so its figure moved with the sweep rather than with the corpus. The break rule widened to bold section markers on 2026-08-28 and again to the colon-less ones the same day, and each drop came with no edit to any file, so the 41 above reads against a rule the command no longer runs. Read all four structural counts from a run rather than from this paragraph.
-
-### What a hit asks of an author
-
-Rewrite the sentence rather than swapping the banned token for a near-synonym. The rule is about the sense the token carries, so a swap that keeps the sense clears the report without clearing the violation.
-
-A code span clears the report too, since the ban scan walks around one, and it is the answer only where the token is genuinely an identifier under discussion. `## Code and identifiers` in `markdown.md` reserves the span for commands, API names, file paths, and identifiers, so backticking a quoted utterance spends one rule to satisfy another and leaves the corpus no cleaner.
-
-A hit the closed set could not separate from correct prose was the case with no third option while the set still carried words. The temporal `just` reported as the vague qualifier it happened to spell, and rewriting the sentence is what the toolkit settled on over building an exemption path, since an exemption landing in the verb and not the edit hook leaves the line failing where an author actually meets it. That class is part of why the words left the gate.
-
-### Where the rules are enforced
-
-Four surfaces apply the ban set and all four go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, the `Markdown bans` stage in `canon gate run` runs it across the whole corpus before this repository's own push, and the same-named stage in the one verify runner every stack shares, `scripts/verify.ts`, runs it across a scaffolded project's tracked markdown before its own push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
-
-The seed copy moved onto the verb when the sets became data, since its awk had nothing left to parse. It resolves one runner where the toolkit copy resolves two, looking for no checkout source, and a machine carrying no `canon` gets a report naming the binary to install rather than a silent pass. The Seed independence stage of `bun run check` scopes its walk to markdown and leaves the seed hooks outside it, which its own comment records as deliberate.
-
-The target push stage reads the same exit codes `canon gate run`'s own stage reads: 0 passes, 1 is a refusal logged as a skip, 2 is a finding, and 3 is a shipped-empty ban set. It skips and logs rather than failing when no `canon` binary is on the machine's PATH, since a scaffolded project is not guaranteed the toolkit is installed, and its skip line names the install command.
-
-The target push stage excludes `CHANGELOG.md`, unlike every other surface here. A changelog a generator builds from commit subjects carries prose nobody wrote against the ban set, where this repository's own passes only because `release-please` builds it from subjects sessions already wrote to the rule. The stage passes an explicit file list rather than the bare invocation the other surfaces use, so a corpus with no file left once the changelog is set aside reads as a pass rather than falling back to the whole tree.
-
-The hook prefers a checkout's own `src/cli.ts` over a globally installed binary, so it and the push stage read one build. A published binary lags a branch by whatever has not been released, which would put a ban kind added on the branch into the push and not into the edit. It reads its findings out of the `--json` record rather than off the exit code, so an older binary still reports where the fallback applies. It reads `bans.emptySets` out of the same record, so a set the verb shipped empty reaches the author as a check narrowed to what it could measure rather than as a clean pass.
-
-It also relays the two advisory measures from the same record. A heading finding reports for the whole file, and a colon finding reports only where the word before the colon and the colon appear in the text the write carried, so an edit is never asked to answer for a colon it left untouched.
-
-That field replaced `bans.missingStandards`, which answered a standard resolving under none of three roots. The set ships with the package now, so the state it named cannot occur and the narrowed check has one cause left, a defect in the build. The hook keeps reading a field either way, since a reader cannot tell a narrowed check from a clean one without it.
-
-Both hooks answer an absent record as well. A completed run always writes the record and a refusal writes none, so an empty one means the verb declined to measure rather than measured and found nothing. The verb needs a git repository to build its corpus and refuses without one, which is a project the seeded hook can be installed into, and reading the findings alone reported that as a clean file.
-
-A machine with neither runner still blocks no edit, and it says so rather than exiting clean. The push stage holds either way. An edit nobody checked and an edit carrying no violation are one silence to a reader, so the enforcement a machine lacks is reported rather than inferred.
-
-The stage measures the whole corpus rather than the changed files. A `Do not use` bullet added to a reference bans a token retroactively, and no file in the push that adds the bullet was edited.
-
-## What it does not cover
-
-The verb reads the `markdown-craft` skill's reference and the `write-human` cadence numbers and nothing else. The references the `git-pr`, `git-branch`, and `git-commit` skills own, `publish.md`, `slug.md`, and `versioning.md`, govern an attribute of other artifacts, and none of them is implemented here.
-
-`publish.md` describes a scan applying the same punctuation bans to finished text on its way out. No code implemented that scan before this command, so nothing is duplicated, and a later surface should call this verb rather than build a second one.
-
-That reference's cross-reference rule is out of reach rather than merely unimplemented. It resolves by destination, bare where the destination auto-links a pull request or issue number and backticked where it does not, so this verb sees only the half where the backticked form is correct. A check here would report every compliant reference in the tree and reach none of the published text that goes wrong, which is why the rule holds on reading alone.
-
-The list-density rule at `claude/skills/markdown-craft/references/markdown.md` is out of scope on purpose, since it carries no number and what a density figure should measure is still open.
+- `context-audit.md`: the folder-shaped findings
+- `audits.md`: the aggregate that runs this audit