@erclx/canon 5.36.0 → 5.38.0

package/docs/agents/drift-surfaces.md

@@ -101,7 +101,7 @@ rule on the far side of a window a later sync moved past it. The per-file
 rule the chain lists reaches both surfaces the same way.
 
 A target stamped before governance recorded a chain falls back to the older
-band-inference read below. The measurement there anchors on governance's own
+rule-folder-inference read below. The measurement there anchors on governance's own
 stamp rather than on the oldest anchor across domains, since rules are
 domain-scoped and a shared anchor would let another domain's sync move the
 revision rules are measured from. A target carrying no chain and no governance anchor
@@ -124,16 +124,16 @@ their own language and testing rules, and every other rule is opt-in, so an
 unfiltered list would tell a base consumer about rules it can never receive and
 train the reader to skip the section.
 
-The filter accepts a band on either of two grounds. A folder holding a rule the
+The filter accepts a rule folder on either of two grounds. A folder holding a rule the
 base stack resolves to is entitled to every target, read through the stack file so
-a rule added to base later needs no code change. Every other band is read off the folders the
+a rule added to base later needs no code change. Every other rule folder is read off the folders the
 target already carries, which is the fallback's only evidence of what a target
-was entitled to before it recorded a chain. One band can be reached by more than
+was entitled to before it recorded a chain. One rule folder can be reached by more than
 one stack, so the test over-reports inside a folder the target holds, which
 costs a line where under-reporting would cost the section its point.
 
 A rule the target already holds is dropped by name. That is what keeps a rule the
-toolkit moved between band folders out of the list, since a rename reaches this
+toolkit moved between rule folders out of the list, since a rename reaches this
 read as an addition and only the name tells the two apart.
 
 This closes the dangling-citation case as a side effect rather than checking for

package/docs/agents/gate.md

@@ -9,16 +9,15 @@ description: Running the gate this repository verifies a branch with, what the s
 
 ```bash
 canon gate run
-canon gate run --all --no-write
+canon gate run --all
 canon gate run --json
 ```
 
-| Option       | Behavior                                                                      |
-| ------------ | ----------------------------------------------------------------------------- |
-| `--all`      | Run every stage instead of scoping shell, types, and tests to the changed set |
-| `--no-write` | Check formatting instead of applying it, which is what a merge gate wants     |
-| `--nested`   | Suppress the outer frame when a calling script has already opened one         |
-| `--json`     | Add a machine-readable record on stdout                                       |
+| Option     | Behavior                                                                      |
+| ---------- | ----------------------------------------------------------------------------- |
+| `--all`    | Run every stage instead of scoping shell, types, and tests to the changed set |
+| `--nested` | Suppress the outer frame when a calling script has already opened one         |
+| `--json`   | Add a machine-readable record on stdout                                       |
 
 ## What the command owns and what it runs
 

package/docs/agents/index.md

@@ -30,7 +30,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [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, run depth, the two cadence numbers, and the length ceiling, with the samples behind each checkpoint and why none of them gates
+- [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

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

@@ -84,7 +84,7 @@ 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
-band-inference `newRules` uses in `canon sync --check`.
+rule-folder-inference `newRules` uses in `canon sync --check`.
 
 ## Tooling diff and sync
 
@@ -137,7 +137,7 @@ 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 band and the consumed copy are committed.
+asserts both the generated rule folders and the consumed copy are committed.
 
 ## Whole-project sync
 

package/docs/agents/markdown-audit-weight.md

@@ -1,13 +1,13 @@
 ---
 title: Markdown audit weight
-description: The structural half 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 why none of them gates
+description: 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 weight
 
 ## Bullets, paragraphs, and depth
 
-Bullet weight and depth are the checks that moved off `canon context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero, either ending in a colon, or holding one whole code span at any width, or running to 20 characters or fewer, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
+Bullet weight and depth are the checks that moved off `canon context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 250 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero, either ending in a colon, or holding one whole code span at any width, or running to 20 characters or fewer, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
 
 Every weight and depth measure counts the text a reader is shown. A link reduces to its anchor text and an autolink drops whole, since no reader is shown either destination. A backticked path stays counted, which is where these measures part from the ban scan `markdown-audit.md` describes: that one blanks a code span so a standard quoting its own banned character does not report itself, and discounting the same span here would under-report a paragraph carrying several. One file holds both span sets and each answers its own question.
 
@@ -17,7 +17,7 @@ The paragraph check measures both halves of one rule. `markdown.md` caps a parag
 
 A sentence boundary closes on terminal punctuation ahead of a capital or a code span. The capital is what keeps a version pin and a decimal from each reading as two sentences, and the code span is admitted beside it because a command name opening a sentence carries no capital to find.
 
-The paragraph weight sits at 700 and the bullet weight at 400. Both shipped at 400, because the paragraph number was borrowed from the bullet rule when the two checks landed together, and each has since been read against a sample of its own. They are separate checkpoints in the standard and separate patterns in the parser, so a read that moves one leaves the other where it is.
+The paragraph weight sits at 700 and the bullet weight at 250. Both shipped at 400, and the bullet number moved to 250 so the audit's warning and the `paragraph-growth` gate stage, which fails a bullet a branch adds or grows past it in a context entry, read one number. The paragraph number was borrowed from the bullet rule when the two checks landed together, and each has since been read against a sample of its own. They are separate checkpoints in the standard and separate patterns in the parser, so a read that moves one leaves the other where it is.
 
 ### The sample behind the paragraph number
 
@@ -46,6 +46,14 @@ That re-sample ran once the scan stopped counting link syntax as prose. Findings
 
 A bullet, a heading, a table row, a blockquote, a blank line, and a fence each end a paragraph, so a heavy bullet is reported by the bullet check alone and never counted twice.
 
+## Bullet stacks
+
+A run of consecutive top-level bullets reports past 5. A blank line, an indented continuation, and a nested item do not break the run, and a paragraph, a heading, or any other column-zero line does. A fenced line is skipped without breaking it. The count is of items rather than weight, so it catches a catalog of short bullets the 250-character checkpoint above passes.
+
+Two shapes are exempt. A run whose every item opens with a bold label or a link names its own subject per item and reads as a table of entries, and a numbered list states an order, so numbered items never count. `CHANGELOG.md` is exempt by name. Governance rules and `REQUIREMENT.md` sit outside the gate stage's scope rather than being exempted here, since a rule is one imperative per bullet.
+
+The audit reports a stack and never fails on one. The `bullet-stacks` stage in `canon gate run` fails the push, for the reason the length ceiling does: the audit also runs on plans and groundwork records kept out of version control.
+
 ## Cadence
 
 Uniform cadence is the failure a ban list cannot express. A ban set states negatives, and fragments, verbless clauses, and sentences that all run one length are each the absence of something, so no word added to a ban list reaches any of them. The shape layer already measured a bullet, a paragraph, and a run, and stopped one level above where that failure lives.

package/docs/agents/markdown-audit.md

@@ -67,11 +67,11 @@ The heading-case measure reports a heading or a frontmatter `title` with a capit
 
 ### Weight, cadence, and length
 
-Bullet and paragraph weight, 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`.
+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. 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.
+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.
 

package/docs/agents/pr-frames.md

@@ -8,7 +8,7 @@ description: How canon pr frames pushes a UI review frame to a never-merged bran
 `canon pr frames` gives a review comment an image it can embed. `review-ui`
 drives a pull request's checklist and captures a frame per box, and a frame
 on the reviewer's disk resolves for nobody else. The verb pushes one frame to
-the `canon-frames` branch and returns a link to its path there.
+the `canon/frames` branch and returns a link to its path there.
 
 ```bash
 canon pr frames 1341 --add frames/3.png --box 3 --head <sha> --pass 20261002T154450Z --json
@@ -19,7 +19,7 @@ canon pr frames --prune 30 --json
 
 ## What it writes
 
-The verb writes `refs/heads/canon-frames` and no other ref. Every call goes
+An add writes `refs/heads/canon/frames` and no other ref. Every call goes
 through the GitHub git data API, being blobs, trees, commits, and that one ref,
 so nothing is checked out, no worktree is entered, and neither `main` nor any
 branch a pull request holds is touched. The branch never merges.
@@ -36,7 +36,7 @@ box therefore writes a new file rather than replacing the image an earlier
 comment shows, which matters when a preview is minted again at one head.
 
 `link` uses the same `blob/<ref>/<path>?raw=true` form as the evidence comment,
-naming the `canon-frames` branch rather than a commit. Every drop rewrites the
+naming the `canon/frames` branch rather than a commit. Every drop rewrites the
 branch, and a link pinned to a commit would stop resolving for every other pull
 request's frames once GitHub collects the commit it names. A path link lives
 exactly as long as its file, so it survives every rewrite that drops another
@@ -97,6 +97,20 @@ than that many days ago, in a single rewrite. It keeps one still open, one
 reopened after closing, one closed exactly the given days ago, and one whose
 state could not be read, listing that last kind under `unread`.
 
+## The legacy branch
+
+Frames lived on `canon-frames` before the rename to `canon/frames`. An add
+never writes it. `--drop` and `--prune` also run against it after the
+current branch, remove only, and delete it once empty. `--prune` drains it
+as its pull requests expire, and `--drop` clears one pull request at once.
+The record carries `legacy: true` when that
+pass changed the ref, and its `removed` list folds both branches in, naming
+a pull request once. A missing or unreadable legacy ref never fails a run
+the current branch finished.
+
+A link minted before the rename points at `blob/canon-frames/...` and keeps
+resolving until its pull request has been closed 30 days or `--drop` runs.
+
 This repository runs `--prune 30` daily from
 `.github/workflows/pr-frames-cleanup.yml`. A frame's file stays on the branch
 until its own pull request has been closed for 30 days, so a link in a review

package/docs/agents/sessions-transfer.md

@@ -67,12 +67,14 @@ The transcript and side folder land under `projects/<encoding>/`, where the enco
 
 Exit codes: `0` the session was placed, `1` refused. The refusal carries one of these reasons:
 
-- `not-a-bundle`: the file is no gzip tarball, carries no manifest at format `1`, or names a path outside its own session, such as one climbing out with `..` or an absolute one
-- `other-repository`: the local `origin` differs from the one the bundle recorded
-- `exists`: the target transcript or side folder is already there, or any other project folder already holds a transcript for the id, which `--resume <id>` could reach first
-- `live-here`: the id is live in the local roster, so a second copy would fork it
-- `write-failed`: a write failed partway for a reason other than a copy appearing, such as a bundle carrying a file where it also needs a folder
-- `no-archive`: the running Bun predates `Bun.Archive`
+| Reason             | Meaning                                                                                                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `not-a-bundle`     | the file is no gzip tarball, carries no manifest at format `1`, or names a path outside its own session, such as one climbing out with `..` or an absolute one    |
+| `other-repository` | the local `origin` differs from the one the bundle recorded                                                                                                       |
+| `exists`           | the target transcript or side folder is already there, or any other project folder already holds a transcript for the id, which `--resume <id>` could reach first |
+| `live-here`        | the id is live in the local roster, so a second copy would fork it                                                                                                |
+| `write-failed`     | a write failed partway for a reason other than a copy appearing, such as a bundle carrying a file where it also needs a folder                                    |
+| `no-archive`       | the running Bun predates `Bun.Archive`                                                                                                                            |
 
 A write that fails partway removes every file this run placed and every folder it created before refusing, so a retry of the same bundle does not refuse on its own leftovers. Any path it could not remove is named in the message. A copy that appears between the existence check and the write refuses as `exists` on the same terms.
 

package/docs/agents/skills-audit.md

@@ -28,14 +28,22 @@ The audit reads the directory it is pointed at, defaulting to the cwd. `canon cl
 
 Each check traces to a line in the standard.
 
-- `REQUIREMENT.md` present in every skill folder
+### Folder and frontmatter
+
 - Frontmatter `name` matching the folder name
 - Frontmatter `description` present
 - `description` under 1024 characters
 - No `README.md` inside a skill folder
 - Folder name in kebab-case
+
+### Requirement and content
+
+- `REQUIREMENT.md` present in every skill folder
 - Each `REQUIREMENT.md` declaring `Gap` and `Must`, matched at any heading level
 - No ISO date in `SKILL.md` or any file under `references/`, reported as `datedProvenance` in the JSON record's `findings`
+
+### Practice, references, and family
+
 - Each listed practice skill closing with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, and each skill on the wider ledger list carrying `references/adopted.md`, reported together as `practiceShape`
 - Each file under `references/` running over 100 lines opening with a `## Contents` H2, reported as `referenceContents`
 - Each skill under `claude/skills/` declaring a `metadata.family` that names a key in `checkpoints.families`, reported as `family`

package/docs/target/projects.md

@@ -57,7 +57,7 @@ The chain is:
 
 - `canon init` installs base tooling, Claude seeds, and governance rules into `.claude/rules/` in the same pass
 - `canon tooling sync <stack> --write` adds stack-specific deps, scripts, and gitignore entries
-- The agent reads `canon tooling reference <stack>` (plus parents) as its audit context, follows it to generate eslint, vitest, playwright configs and the stack's setup script, and extends `canon/context/ci.md` and `canon/context/development.md` per the reference's extend sections <!-- audit-ignore-citations: canon/context/ci.md, canon/context/development.md -->
+- The agent reads `canon tooling reference <stack>` (plus parents) as its audit context, follows it to generate oxlint, vitest, playwright configs and the stack's setup script, and extends `canon/context/ci.md` and `canon/context/development.md` per the reference's extend sections <!-- audit-ignore-citations: canon/context/ci.md, canon/context/development.md -->
 - The `verify` phase runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
 - The `indexes` phase bootstraps the `index.md` system over the project's own documentation folders, confirming candidate folders with the operator rather than running unattended
 

package/docs/target/scenarios.md

@@ -46,10 +46,10 @@ canon tooling sync vite-react ./frontend --skip base --write
 canon tooling sync python ./backend --skip base --write
 ```
 
-`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, commitlint, and CI stay single at the repo root. The one exception is base's verify runner, `scripts/verify.ts` and `scripts/verify.json`, which every subtree still receives so it can verify on its own. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite), and its own stack reference reads through `canon tooling reference <stack>`.
+`--skip base` drops the `base` layer from each subtree sync, so husky, oxfmt, commitlint, and CI stay single at the repo root. The one exception is base's verify runner, `scripts/verify.ts` and `scripts/verify.json`, which every subtree still receives so it can verify on its own. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (oxlint, vitest, tsconfig, vite), and its own stack reference reads through `canon tooling reference <stack>`.
 
 A sync whose target sits below the git root knows it is writing into a subfolder:
 
 - It withholds `.github/`, since GitHub reads workflows only at the repository root, and names each withheld file. Run the subtree from a job in the root workflow instead, with `working-directory` set to the subtree path the sync prints, such as `working-directory: frontend`.
 - It installs no dependencies and adds no scripts to a subtree without a `package.json`. It names what it skipped and ends on `run 'bun init' in <path>, then sync again`.
-- The subtree carries no `check` script, since that lives in the root's base layer, so run `bun scripts/verify.ts` there. It skips the format phases a subtree does not declare, since the root runs them, and still fails on a missing lint, typecheck, or test script, the phases its stack's `scripts/verify.json` requires.
+- The subtree carries no `check` script, since that lives in the root's base layer, so run `bun scripts/verify.ts` there. It skips the format phase a subtree does not declare, since the root runs them, and still fails on a missing lint, typecheck, or test script, the phases its stack's `scripts/verify.json` requires.

package/docs/target/standards-moved.md

@@ -10,23 +10,25 @@ category: Agent surface
 
 Each standard now lives at `references/<name>.md` in the skill that owns it. Load that skill and read the reference it names:
 
-- `task-board`: `board`, `tasks`, `tasks-decline`
-- `context-fold`: `context`
-- `canvas-board`: `canvas`, `design`
-- `docs-sync`: `docs`, `readme`
-- `draft-figure`: `figures`, `mermaid`
-- `create-rule`: `rule`
-- `create-skill`: `skill`, `skill-paths`, `skill-practice`, `skill-requirement`
-- `git-branch`: `branch`, `slug`
-- `git-commit`: `commit`, `versioning`
-- `git-pr`: `pr`, `publish`
-- `markdown-craft`: `markdown`
-- `teach-workspace`: `glossary`, `teach`
-- `plan-groundwork`: `groundwork`, `groundwork-spikes`
-- `plan-intake`: `intake`
-- `plan-feature`: `plan`, `plan-lifecycle`
-- `draft-ready`: `ready`
-- `draft-doc`: `requirements`, `wiki`
-- `session-map`: `session`
+| Skill             | Standards                                                     |
+| ----------------- | ------------------------------------------------------------- |
+| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
+| `context-fold`    | `context`                                                     |
+| `canvas-board`    | `canvas`, `design`                                            |
+| `docs-sync`       | `docs`, `readme`                                              |
+| `draft-figure`    | `figures`, `mermaid`                                          |
+| `create-rule`     | `rule`                                                        |
+| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
+| `git-branch`      | `branch`, `slug`                                              |
+| `git-commit`      | `commit`, `versioning`                                        |
+| `git-pr`          | `pr`, `publish`                                               |
+| `markdown-craft`  | `markdown`                                                    |
+| `teach-workspace` | `glossary`, `teach`                                           |
+| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
+| `plan-intake`     | `intake`                                                      |
+| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
+| `draft-ready`     | `ready`                                                       |
+| `draft-doc`       | `requirements`, `wiki`                                        |
+| `session-map`     | `session`                                                     |
 
 One name moved under a new filename. `standard`, the shape of a standard itself, became `skill-reference.md` in `create-skill`, since the toolkit no longer ships a standards folder to hold one.

package/docs/workflow/ai-workflow.md

@@ -52,6 +52,9 @@ Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full fi
 - When the input is a pile of findings rather than one feature, invoke `canon:plan-intake` first. It files the dump into `.canon/intake/<nn>-<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled.
 - When the backlog has grown past what anyone rereads, invoke `canon:backlog-triage`. It files one item per backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, and once `canon:plan-intake-answer` has taken your answers, a second run applies the approved verdicts through the task verbs.
 - When the current state is unmeasured and more than one approach is live, invoke `canon:plan-groundwork` first. It opens a track folder under `.canon/groundwork/<nn>-<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled.
+
+Then plan and build:
+
 - Invoke `canon:plan-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
 - Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
 - For UI changes, invoke `canon:ui-checklist` to write what a reviewer has to look at and name any behavior shipping without a test

package/docs/workflow/visual-design-workflow.md

@@ -35,9 +35,14 @@ A record generated from a token source carries the values in tables instead, whi
 
 ### Skills
 
+#### Reviewing and measuring
+
 - `canon:ui-checklist` for what a reviewer has to look at after UI changes, and what ships without a test
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
+
+#### Drafting
+
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates as frames on the canvas and taking your pick
 - `canon:canvas-board` for a direction worked out over several turns, drawn as HTML frames you drag, select, and restyle in the browser while the session reads your changes back. Only the pick moves into `canon/DESIGN.md`, since the canvas folder is gitignored
 - `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop. On an Astro project holding the card route scaffold, the card lands as a route the project keeps and is captured through a running server, so it reads the project's real stylesheet rather than typed copies of every color. Everywhere else it ships as a PNG and the run says so.

package/governance/detect.toml

@@ -27,7 +27,12 @@ files = [".github/workflows"]
 
 ["dependencies"]
 deps = []
-files = ["**/package.json", "**/pyproject.toml", "**/go.mod", "**/composer.json"]
+files = [
+  "**/package.json",
+  "**/pyproject.toml",
+  "**/go.mod",
+  "**/composer.json",
+]
 
 ["config-comments"]
 deps = []

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.36.0",
+  "version": "5.38.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -24,15 +24,16 @@
     "access": "public"
   },
   "scripts": {
-    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/ claude/",
-    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/ claude/",
+    "format": "oxfmt . && prettier --write --log-level warn 'web/**/*.astro' && shfmt --write --indent 2 scripts/ tooling/ claude/",
+    "check:format": "oxfmt --check . && prettier --check --log-level warn 'web/**/*.astro' && shfmt --diff --indent 2 scripts/ tooling/ claude/",
     "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
+    "check:lint": "oxlint --disable-nested-config --max-warnings 0",
     "check:types": "tsc --noEmit",
     "check:install": "./scripts/core/install-check.sh",
     "test": "bun --bun vitest run",
     "prepare": "husky",
     "check": "bun src/cli.ts gate run",
-    "check:ci": "bun src/cli.ts gate run --all --no-write",
+    "check:ci": "bun src/cli.ts gate run --all",
     "update": "bun update --interactive && bun run check",
     "clean": "rm -rf node_modules && bun pm cache rm && bun install",
     "bootstrap": "./scripts/core/bootstrap.sh",
@@ -72,6 +73,8 @@
     "happy-dom": "^20.14.5",
     "husky": "^9.1.7",
     "micromatch": "^4.0.8",
+    "oxfmt": "0.72.0",
+    "oxlint": "1.87.0",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
     "prettier-plugin-tailwindcss": "^0.7.2",

package/scripts/core/install-check.sh

@@ -101,7 +101,7 @@ log_step "Assert scaffold"
 # skills rather than installing into a target. The two
 # rule paths stand for the `claude` and `canon` groups `base` takes whole.
 for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" \
-  ".prettierrc" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.ts" \
+  ".oxfmtrc.json" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.ts" \
   ".claude/rules/canon/claude/output.md" ".claude/rules/canon/canon/scratch.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then
     log_error "Missing after canon init: $path"

package/src/cli/help.ts

@@ -130,7 +130,7 @@ const EXAMPLES = [
   'canon labels audit --json',
   'canon census --json',
   'canon audits run --json',
-  'canon gate run --all --no-write',
+  'canon gate run --all',
   'canon upgrade --json',
   'canon upstream fetch --since 2.1.256 --json',
 ]

package/src/commands/claude.ts

@@ -70,7 +70,6 @@ import {
   writeSettings,
 } from '@/claude/settings'
 import { copyPreservingMode } from '@/sync/copy'
-import { execScript } from '@/cli/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import { recordDir } from '@/roots/record'
 import { SURFACE_ENTRIES, surfaceDir } from '@/roots/surface'

package/src/commands/context.ts

@@ -11,11 +11,14 @@ import {
   LENGTH_CHECKPOINT,
   matchesSiblings,
   measureFolders,
+  extraSections,
   missingSections,
   PROVENANCE_FOLDER,
+  ALLOWED_SECTIONS_BY_FOLDER,
   REQUIRED_SECTIONS,
   REQUIRED_SECTIONS_BY_FOLDER,
   requiredSections,
+  type ExtraSectionFinding,
   type SectionFinding,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -640,6 +643,7 @@ async function runAudit(
   const entries = gateOnly ? [] : await measureFolders(root, folders)
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
+  const extras = gateOnly ? [] : extraSections(entries)
   const length = gateOnly ? undefined : lengthFindings(entries)
   // Absent under `--citations-only` and null when the project carries no
   // record. A run that never looked and a project with nothing to look at are
@@ -653,7 +657,7 @@ async function runAudit(
     reportScope(folders, unresolved)
     reportCitations(citations, cited)
     reportReferenceForm(entries, folders)
-    reportSections(sections, folders)
+    reportSections(sections, extras, folders)
     reportLength(length ?? [])
     reportTables(entries)
     reportProvenance(entries, folders)
@@ -691,6 +695,7 @@ async function runAudit(
         // never opened an entry.
         length,
         missingSections: sections,
+        extraSections: extras,
         indexDrift: drift,
         // Null says the run opened the project and found no record, which a
         // target that never wrote one is entitled to. Absent says the run
@@ -705,6 +710,7 @@ async function runAudit(
           // caller that read it first, since removing it would break that
           // caller without an error.
           requiredSectionsByFolder: REQUIRED_SECTIONS_BY_FOLDER,
+          allowedSectionsByFolder: ALLOWED_SECTIONS_BY_FOLDER,
         },
       })}\n`,
     )
@@ -715,6 +721,7 @@ async function runAudit(
     requirementsOverWords:
       requirements !== undefined && isOverWordCap(requirements),
     sections,
+    extraSections: extras,
     drift,
     widened,
   })
@@ -905,6 +912,7 @@ function reportReferenceForm(
  */
 function reportSections(
   missing: readonly SectionFinding[],
+  extras: readonly ExtraSectionFinding[],
   folders: readonly AuditedFolder[],
 ): void {
   logStep('Sections')
@@ -938,13 +946,30 @@ function reportSections(
 
   if (missing.length === 0) {
     logInfo('Every entry declares each required section.')
+  } else {
+    logWarn(`${plural(missing.length, 'path')} short a required section`)
+    pipeOutput(
+      missing
+        .map((found) => `${found.rel}  missing: ${found.missing.join(', ')}`)
+        .join('\n'),
+    )
+  }
+
+  logInfo(
+    `The set is closed: ${Object.entries(ALLOWED_SECTIONS_BY_FOLDER)
+      .map(([name, set]) => `canon/${name}/ allows ${set.join(', ')}`)
+      .join('. ')} as H2. Any other topic is an H3 under one of them.`,
+  )
+
+  if (extras.length === 0) {
+    logInfo('No entry carries an H2 outside the set.')
     return
   }
 
-  logWarn(`${plural(missing.length, 'path')} short a required section`)
+  logWarn(`${plural(extras.length, 'path')} carrying an H2 outside the set`)
   pipeOutput(
-    missing
-      .map((found) => `${found.rel}  missing: ${found.missing.join(', ')}`)
+    extras
+      .map((found) => `${found.rel}  extra: ${found.headings.join(', ')}`)
       .join('\n'),
   )
 }

package/src/commands/gate.ts

@@ -27,7 +27,6 @@ import { repairBareFlag } from '@/worktrees/bare-flag'
 
 interface RunCommandOptions {
   readonly all?: boolean
-  readonly write?: boolean
   readonly nested?: boolean
   readonly json?: boolean
 }
@@ -48,10 +47,6 @@ export function register(program: Command): void {
       '--all',
       'Run every stage instead of scoping shell, types, and tests to changed files',
     )
-    .option(
-      '--no-write',
-      'Check formatting instead of applying it, which is what a merge gate wants',
-    )
     .option(
       '--nested',
       'Suppress the outer frame when another script opened one',
@@ -77,7 +72,7 @@ export function register(program: Command): void {
         '',
         'Examples:',
         '  canon gate run',
-        '  canon gate run --all --no-write',
+        '  canon gate run --all',
         '  canon gate run --json',
         '',
       ].join('\n'),
@@ -92,7 +87,6 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
   const mismatch = checkoutMismatchWarning(process.cwd())
   const emitJson = opts.json ?? false
   const nested = opts.nested ?? false
-  const write = opts.write ?? true
   const run = commandRunner(root)
 
   if (!emitJson && !nested) intro('canon gate run')
@@ -111,7 +105,6 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
     ci: process.env.CI === 'true',
     run,
     cli: cliRunner(root),
-    write,
     changed: changed.scoped ? changed.files : undefined,
     onQueue: (label, holder) => {
       const text = `${label} is waiting for the suite pid ${holder.pid} runs at ${holder.root}`