@erclx/canon 5.38.0 → 5.39.0

package/docs/agents/context-audit-checks.md

@@ -19,10 +19,28 @@ It reports rather than gates by default, the closer call because a missing secti
 
 ### The closed set
 
-The same section also reports an H2 outside the folder's closed set. A context entry allows `Overview`, `Layout`, `Decisions`, and `Gotchas` and no other H2, so a topic of the domain's own sits one level down as an H3. The finding is per entry rather than per folder, since an extra heading is a fact about the file carrying it. Fenced blocks are skipped, a stub seed is skipped, and only H2 is read, so where an H3 sits is not audited. It gates under `--gate` alone, like a missing section.
+The section also reports an H2 outside the closed set. A context entry allows `Overview`, `Layout`, and `Gotchas` and no other H2. The finding is per entry, since an extra heading is a fact about the file carrying it, and it gates under `--gate` alone. Fenced blocks and stub seeds are skipped, and a retired `Decisions` H2 goes to the shape check.
 
 The record carries it as a top-level `extraSections` array of `{ rel, headings }`, and the set itself as `checkpoints.allowedSectionsByFolder`, keyed on the folder name the way `requiredSectionsByFolder` is. Both are additive.
 
+### The section shape
+
+The Shape section reports where a context entry breaks the shape inside its sections. Each finding carries a line and one of eight kinds.
+
+- `retired-section`: a `## Decisions` H2
+- `gotcha-count`, `gotcha-heading`, `gotcha-paragraph`: a `Gotchas` section past five bullets, holding a heading, or holding a paragraph
+- `layout-heading`: a Layout H3 titled neither a code-spanned path nor `Other folders`
+- `layout-bullets`, `layout-paragraphs`: a folder H3 past five bullets or past its one-paragraph lead
+- `layout-depth`: any heading below H3 under `Layout`
+
+Bullets count at any indent and across any paragraph, so a list split by a bold label counts as one. A line continuing a list item belongs to the item. `Other folders` is exempt from both folder caps.
+
+### Where the shape gates
+
+A shape finding gates under `--gate` only for an entry under a prefix that `SHAPE_GATED_FOLDERS` in `src/context/shape-gated.ts` lists, read from the repository root. Every other entry reports and never fails a push. A seed tree is matched by its toolkit path, such as `tooling/base/seeds/`.
+
+The record carries a top-level `shapeFindings` array of `{ rel, gated, issues }`, and each entry carries its own `shape` list. The caps sit under `checkpoints` as `gotchaCap`, `layoutBulletCap`, and `layoutParagraphCap`, beside `retiredSectionsByFolder` and `shapeGatedFolders`. All are additive.
+
 ## Reference form
 
 The reference-form check reports an entry naming a sibling entry by bare filename where `claude/skills/context-fold/references/context.md` asks for the path it sits at. A bare name resolves against whichever folder its reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A path is checkable, which is what makes the form rule worth measuring at all: once a reference spells its path, the citation gate resolves it and a split that moves the file fails the push.

package/docs/agents/context-audit.md

@@ -23,7 +23,7 @@ canon context audit tooling/base/seeds --gate
 | `--json`           | Add a machine-readable record on stdout, keeping the frame                |
 | `--folder <list>`  | Comma-separated folder names (default: the three below)                   |
 | `--citations-only` | Run the gating citation check alone, printing nothing when it passes      |
-| `--gate`           | Fail on a missing required section, an off-set H2, or index drift as well |
+| `--gate`           | Fail on a missing section, an off-set H2, gated shape break, or drift too |
 
 `--citations-only` and `--gate` refuse together. The first runs the citation check alone, so the two findings the second adds are never measured, and a run honoring both would exit clean on a file short a required section.
 
@@ -43,7 +43,7 @@ Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating find
 
 Entry length, reference form, table, provenance, the record's claim classification, and every word figure no record caps print and return `0` under every mode, because each is a judgment or a weight read alongside one, and failing a push on either would make the check something to route around.
 
-Required-section, off-set H2, and index findings sit between the two. Both are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
+Required-section, off-set H2, and index findings sit between the two. Both are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. A section shape break, such as a `## Decisions` H2 or a sixth gotcha, gates under `--gate` only in a shape-gated folder. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
 
 ## The seed gate
 

package/docs/agents/driver.md

@@ -100,4 +100,4 @@ An unreachable page refuses rather than returning an empty report, since nothing
 
 The browser binary installs separately from the package, once, with `bunx playwright install chromium`. The command ships to targets like `demo`, `inventory`, and `capture`, because its whole purpose is measuring a page inside someone else's project. It reaches nothing under `src/capture/`, so the two surfaces move independently.
 
-See `commands.md` for where this sits among the browser commands, and `capture.md` for the single-state render it adds an axis to.
+See `canon --help` for where this sits among the browser commands, and `capture.md` for the single-state render it adds an axis to.

package/docs/agents/hooks.md

@@ -1,6 +1,6 @@
 ---
 title: Hooks
-description: Running the post-merge steps through one verb, the order and the child call behind each, the root and working directory each step reads, the skip switches, and the line each record maps to
+description: Running the post-merge steps through one verb, the order and the child call behind each, the root and working directory each step reads, the skip switches, the line each record maps to, and the reply link check
 ---
 
 # Hooks
@@ -38,6 +38,26 @@ The reclaim takes no `--root`. It refuses the worktree its own working directory
 
 Each step is a separate process rather than an in-process call, so the plugin update runs the binary the upgrade just installed. Every child, and every `git` read, runs with the repository variables a hook exports stripped, since `GIT_DIR` beats `-C`.
 
+## Reply links
+
+`canon hooks reply-links` checks that every markdown link in a reply names a file on disk. The `Stop` hook `reply-links.sh` runs it on the closing message of a turn, so a dead link is corrected in the same turn.
+
+```bash
+printf '%s' "$reply" | canon hooks reply-links
+canon hooks reply-links --json < reply.md
+```
+
+| Option          | Behavior                                                                                          |
+| --------------- | ------------------------------------------------------------------------------------------------- |
+| `--root <path>` | Root a relative link resolves against, the main worktree root from `git worktree list` if omitted |
+| `--json`        | Write `{ ok, missing, message }` to stdout. `message` is present only when `ok` is false          |
+
+The reply comes on stdin, and a terminal on stdin is refused. A relative link resolves against the root, an absolute one is checked as written. The check skips placeholders such as `<path>`, globs, URLs, anchors, and any link inside a code span or fence. A `:42`, `:42-50`, or `#L42` tail is stripped before the check.
+
+Each entry in `missing` carries the `destination` as written and the `path` that was checked. A link into `.claude/worktrees/<name>/.canon/` also carries a `suggestion` with the main-root path when that file exists there.
+
+Exit codes: `0` when every link resolves or the reply holds none, `1` when at least one does not. The missing list goes to stderr. The hook turns a finding into exit 2 so the session continues, and exits 1 without blocking when it could not run the check, such as with no `jq` or no `canon` on `PATH`.
+
 ## Skip switches
 
 | Variable                     | Skips                   |

package/docs/agents/index.md

@@ -12,29 +12,26 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Canvas](canvas.md): The canvas server, its content format, and the verbs that list, arrange, fit, select, edit, mark, and capture frames
 - [Capture](capture.md): Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 - [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
-- [Command catalog](commands.md): Every top-level command with its purpose, each domain's subcommands and the page describing them, the browser commands, and the version skew report
 - [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
 - [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, the requirements record's word cap, which folders each check reaches, and what moved to the attribute tier
 - [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
 - [Doc classifier](context-classify.md): Classifying canonical-doc content as keep, replace/rewrite, history, or move in diff and sweep mode, the classifier setting pair, the record shape, and the exit codes
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
-- [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
-- [Drift surfaces](drift-surfaces.md): The seven sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, surfaces at the old root, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
 - [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
 - [Merge gate](gate.md): Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing
-- [Rule detection](gov-detect.md): Proposing opt-in governance rules from a target's dependencies and paths, the evidence file the verb reads, the record it emits, and its exit codes
-- [Hooks](hooks.md): Running the post-merge steps through one verb, the order and the child call behind each, the root and working directory each step reads, the skip switches, and the line each record maps to
-- [Indexes](indexes.md): Flags, exit codes, and JSON shape for canon indexes regen and canon indexes list, plus when regen auto-stages what it rewrote
-- [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
+- [Hooks](hooks.md): Running the post-merge steps through one verb, the order and the child call behind each, the root and working directory each step reads, the skip switches, the line each record maps to, and the reply link check
+- [Indexes](indexes.md): How canon indexes regen and canon indexes list resolve paths, what they stage, and the record and exit codes each emits
+- [Install and sync](install-and-sync.md): 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
 - [Intake](intake.md): Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
 - [Key changes bijection](key-changes.md): Comparing the files a pull request body's Key changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
 - [Label coverage](label-coverage.md): Reading a changed set against the pull request label map, the two tables it matches, how a gap is separated from a decision, and why an absent map is an answer
-- [Markdown audit weight](markdown-audit-weight.md): The structural half of the markdown audit, being bullet and paragraph weight, bullet stacks, run depth, the two cadence numbers, and the length ceiling, with the samples behind each checkpoint and why none of them gates
-- [Markdown audit](markdown-audit.md): 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
-- [Migrate](migrate.md): What each canon migrate verb moves and rewrites, what it refuses, the markers that keep an old spelling, and the idempotence check a second run gives
-- [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
-- [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
+- [Markdown audit density](markdown-audit-density.md): The six layout limits the markdown audit measures, what each one counts, which paths take a finding, and how a folder's gate turns on
+- [Markdown audit weight](markdown-audit-weight.md): The advisory sections of the markdown audit, being bullet and paragraph weight, run depth, the two cadence numbers, and the length ceiling, with the samples behind each checkpoint and which of those numbers gate through density
+- [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, how a reference page opts into its shape check, and why bans, dead links, and density or reference shape on a gated path fail while the rest reports
+- [Migrate](migrate.md): What each canon migrate verb moves, the markers that keep an old spelling, and what each one refuses
+- [Output shape](output-shape.md): The framed output shape every command renders into, the JSON and color modes, the exit discipline, the runtime catalogs, and a headless invocation per domain
+- [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and how canon docs resolves a topic name
 - [The pull request evidence layout](pr-evidence-layout.md): How canon pr evidence groups screenshots into one block per view with a row per width and a column per theme, when a base column appears, where a name outside the form lands, how the commit line links, and when the blocks open
 - [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
 - [The pull request frame store](pr-frames.md): How canon pr frames pushes a UI review frame to a never-merged branch through the GitHub API and returns a branch-path link, which ref it writes, the pass segment that keeps an earlier image fixed, the refusal reasons it names, and how --drop and --prune rewrite the branch so a dropped frame leaves history
@@ -51,7 +48,6 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [Rule citations](rule-citations.md): Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the one form a citation is written in, the shapes that look like citations and are not, the two classes where an absent path is correct, why the glob half reads one corpus, and why this one gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
-- [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions transfer](sessions-transfer.md): Moving a session to another machine, the export bundle and its manifest, placing it with import, the refusal reasons, and what a resume on the target depends on
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and where moving a session to another machine is described
 - [Skill audit](skills-audit.md): Measuring both skill corpora against the skill standards, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
@@ -59,7 +55,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Slides](slides.md): Where a deck folder lives and what it holds, what it declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates
-- [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
+- [Targets](targets.md): The projects this toolkit installed into, where each answer comes from, and the cross-target pull request read
 - [Tasks archive](tasks-archive.md): Archiving a shipped task by stem or pull request, declining one decided against, the refusal reasons each carries, and how the plan and ready folder move with the task
 - [Tasks plans](tasks-plans.md): The five verbs that read or write a task's plan, being where it sits and who cites it, whether it waits on the operator, the branch it derives, what a branch reached against what it declared, and writing its Plan line
 - [Tasks validate](tasks-validate.md): Validating the board against the tree, the seven checks, the five report arrays, the exit codes, and the refusal reasons

package/docs/agents/indexes.md

@@ -1,51 +1,47 @@
 ---
 title: Indexes
-description: Flags, exit codes, and JSON shape for canon indexes regen and canon indexes list, plus when regen auto-stages what it rewrote
+description: How canon indexes regen and canon indexes list resolve paths, what they stage, and the record and exit codes each emits
+kind: reference
 ---
 
 # Indexes
 
-`canon indexes regen` rewrites `index.md` files from sibling frontmatter, so a hand edit to a generated index is lost on the next run. With no positional paths, it walks the current directory. With paths, each resolves by walking up to the nearest indexed ancestor, bounded by `--root`.
+`canon indexes regen [paths…]` rewrites `index.md` files from sibling frontmatter, so a hand edit to a generated index is lost. `canon indexes list [path]` flattens each folder's `title` and `subtitle` plus each sibling's `title` and `description` into one catalog sorted by path.
 
-Duplicates dedupe. The whole-repo walk prunes `.git`, `node_modules`, and anything `.gitignore` covers via `git check-ignore`.
+`regen` takes `--dry-run`, `--json`, `--root <path>` (default the current directory), and `--no-stage`. `list` takes `--json`.
 
-A positional path is not filtered that way, because the walk-up resolves on the filesystem and never consults git. That is the only way to regenerate an index inside a gitignored folder, and it is how `.canon/tasks/` and `.canon/memory/` both stay current.
+- With no paths `regen` walks the current directory, pruning `.git`, `node_modules`, and anything git ignores
+- With paths, each resolves by walking up to the nearest indexed ancestor, bounded by `--root`, without consulting git. That is how `.canon/tasks/` and `.canon/memory/` stay current.
+- A `PostToolUse` hook on `Write|Edit|MultiEdit` drives it, so a shell `mv` fires nothing. Run it after the last move.
 
-Each is driven by a `PostToolUse` hook matching `Write|Edit|MultiEdit`, so a file moved by a shell `mv` fires nothing. A caller that relocates an entry runs the command itself once the last move is done.
+## Output
 
-| Option          | Behavior                                                         |
-| --------------- | ---------------------------------------------------------------- |
-| `--dry-run`     | Report which indexes would change without writing                |
-| `--json`        | Emit a machine-readable record per index on stdout               |
-| `--root <path>` | Walk-up boundary when positional paths are passed (default: CWD) |
-| `--no-stage`    | Skip the auto `git add` on modified indexes                      |
-
-Exit codes: `0` clean, `1` frontmatter error or missing index, `2` drift found in `--dry-run`.
-
-An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `results` array rather than the exit when a skill consumes this, on the write pass as well as the dry run.
-
-When positional paths are passed inside a git repo, modified `index.md` files are staged so lint-staged and Claude `PostToolUse` hooks commit the regenerated catalog. Whole-repo walks never auto-stage, and neither does a path git ignores, since staging one always fails and the warning would fire on every edit.
-
-Skills can parse drift without branching on exit code:
+`regen --json` emits a record per index in `results`, each with an `action`. A dry run reports drift as `would-write`.
 
 ```bash
 canon indexes regen --dry-run --json | jq '.results[] | select(.action == "would-write")'
 ```
 
-## List
+With paths inside a git repo, modified indexes are staged. A whole-repo walk and a git-ignored path never stage.
 
-`canon indexes list [path]` walks every folder index under `path` (default: cwd) and flattens each folder's own `title`/`subtitle` plus every sibling's `title`/`description` into one catalog, sorted by path relative to the walk root.
+`list --json` emits `{ root, entries, errors }`.
 
-| Option   | Behavior                                   |
-| -------- | ------------------------------------------ |
-| `--json` | Emit `{ root, entries, errors }` on stdout |
+- Each entry is `{ path, title, description }`, and an `index.md` row takes its `subtitle` as `description`
+- A folder failing validation lands in `errors`, drops out of `entries`, and prints one `ERROR:` line on stderr
+- Git-ignored folders never appear, so `.canon/tasks/` and `.canon/memory/` are absent
 
-Each entry is `{ path, title, description }`. `path` is relative to the resolved root, and an `index.md` file's own row uses its `subtitle` as `description`.
+## Refusals
 
-A folder failing frontmatter validation lands its message in `errors` and drops out of `entries` rather than failing the whole walk, matching `regen`'s per-folder isolation. Every mode writes one `ERROR:` line per error to stderr.
+Read the record's `results` rather than the exit, on a write pass as well as a dry run.
 
-Exit codes: `0` no errors, `1` root not a directory, or a folder failed frontmatter validation.
+| Verb    | Exit | Means                                                      |
+| ------- | ---- | ---------------------------------------------------------- |
+| `regen` | 0    | Clean                                                      |
+| `regen` | 1    | A frontmatter error or a missing index                     |
+| `regen` | 2    | Drift found under `--dry-run`                              |
+| `list`  | 0    | No errors                                                  |
+| `list`  | 1    | The root is not a directory, or a folder failed validation |
 
-A git-ignored indexed folder, such as `.canon/tasks/` or `.canon/memory/`, never appears in the output. `listIndexes` filters candidates through `git check-ignore` the same way `regen`'s whole-repo walk does, which is the right default for a documentation lookup since those rows are session scratch, but it is a gap against `regen`'s positional-path mode, which bypasses that filter for those two folders.
+## See also
 
-For the system rationale, frontmatter contract, when to adopt, and bootstrap path, see `canon/context/context-model/indexes.md`.
+- `canon docs context-model`: the frontmatter contract and when to adopt indexes