@erclx/canon 5.37.0 → 5.38.0

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

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

package/claude/skills/auto-ship/SKILL.md

@@ -50,7 +50,7 @@ Check for a `**Files to touch:**` or `## Files to touch` marker per `${CLAUDE_SK
 
 Read `<plan>` at the main worktree root. This file is the scope for this run.
 
-Its sections and its answer contract are fixed by `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop. When this run decides against that suggestion, rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+Its sections and its answer contract are fixed by `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop. When this run decides against that suggestion, rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, opening with the bold source-and-date label that `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
 
 ## Step 2: implement
 

package/claude/skills/backlog-triage/SKILL.md

@@ -112,7 +112,7 @@ Take the task stem from the item heading. Every verdict leaves the folder slug o
 - **keep**: append the `## Findings` line naming what reproduced. The backlog line stays.
 - **promote**: move the backlog line to the bottom of `## Needs a plan` in `.canon/tasks/priority.md`, with a `Waiting on` cell stating what cleared and ending in `last`, then append the `## Findings` line.
 
-Write the `## Findings` line as `- <YYYY-MM-DD>, backlog triage <slug>: <verdict>, <evidence>`. It is the last write on every verdict with a task file behind it, since Step 1 reads it as applied and a line written ahead of a refused move would mark a row done that never moved.
+Write the `## Findings` line as `- **<YYYY-MM-DD>, backlog triage <slug>:** <verdict>, <evidence>`, the bold label form `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes. It is the last write on every verdict with a task file behind it, since Step 1 reads it as applied and a line written ahead of a refused move would mark a row done that never moved.
 
 Before any promote, check the roster the way `task-board` step 4 does: a live session in this repository whose name starts with `orchestrator-` and whose `sessionId` is not this one. When one is found, write the `## Findings` line but not `priority.md` or `backlog.md`, and message that session with the row and its cell so it places the row itself.
 

package/claude/skills/build-in-slices/SKILL.md

@@ -40,7 +40,7 @@ Leave the build passing at every commit. A slice that cannot pass on its own is
 
 A defect outside the plan that turns up mid-build is a finding, not a slice. Fixing it on this branch widens a diff the plan scoped and hides the fix inside an unrelated review.
 
-- Write it in one line under the open task's `## Findings`, naming the file and what is wrong, when the build is closing a task.
+- Write it in one line under the open task's `## Findings`, naming the file and what is wrong, when the build is closing a task. Open the line with the bold source-and-date label from `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`.
 - Carry it in the handover message instead when no task exists, and never create a file to hold it.
 - Leave the file as it is, even when the fix is one line.
 - Fix it here only when the plan's own change cannot pass without it, and then say so in the commit that does.

package/claude/skills/git-issue/references/issue.md

@@ -53,17 +53,18 @@ Does not govern:
 ### Feedback
 
 - One `## Toolkit feedback` wrapper holds every field as a nested `###` heading. A flat `##` field is not recognized.
-  | Field | Holds |
-  | --- | --- |
-  | `### From project` (optional) | the reporting project's name or kind. |
-  | `### Surface` (required) | the toolkit surface and its type, and the specific file or name when known. |
-  | `### Observed` (required) | the observed behavior. |
-  | `### Expected` (optional) | the expected behavior, or `unclear`. |
-  | `### Repro` (optional) | repro details, or `none`. |
-  | `### Proposed fix` (required) | a proposed fix, or `open` when the session settled on no direction. |
+
+  | Field                            | Holds                                                                                                                        |
+  | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+  | `### From project` (optional)    | the reporting project's name or kind.                                                                                        |
+  | `### Surface` (required)         | the toolkit surface and its type, and the specific file or name when known.                                                  |
+  | `### Observed` (required)        | the observed behavior.                                                                                                       |
+  | `### Expected` (optional)        | the expected behavior, or `unclear`.                                                                                         |
+  | `### Repro` (optional)           | repro details, or `none`.                                                                                                    |
+  | `### Proposed fix` (required)    | a proposed fix, or `open` when the session settled on no direction.                                                          |
   | `### Suggested shape` (optional) | the template, output, or field list the change should take, inside a `<details>` block. Omit the heading when there is none. |
-  | `### Why` (optional) | the reasons for the fix, one bullet each. Omit the heading when there are none. |
-  | `### Links` (optional) | the issues, pull requests, or documents the report cites, one per line. Omit the heading when there are none. |
+  | `### Why` (optional)             | the reasons for the fix, one bullet each. Omit the heading when there are none.                                              |
+  | `### Links` (optional)           | the issues, pull requests, or documents the report cites, one per line. Omit the heading when there are none.                |
 
 - A required field is refused when present but empty. Write the fallback literal for From project, Expected, and Repro rather than leaving one blank.
 

package/claude/skills/markdown-craft/references/markdown.md

@@ -42,6 +42,7 @@ Does not govern:
 - H1 for document title, H2 for main sections, H3 for subsections
 - Use sentence case for all headings (H1, H2, H3). The audit reports a heading or a frontmatter `title` with a capitalized word after the first, and a proper noun it reports stays as it is.
 - Proper nouns and product names retain their casing in headings
+- Shape a record as H2 per section and H3 per item a reader looks up by name, with a few bullets or prose under each H3. Use a table only for a fixed-shape set.
 
 ### Seams
 
@@ -67,11 +68,11 @@ Does not govern:
 
 - Use prose by default. Reserve bullets for discrete, unrelated items.
 - Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
-- Past roughly 700 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. A paragraph written as two long sentences satisfies the sentence cap above and still asks the reader to hold too much at once. This number sits well above the bullet checkpoint because a paragraph is read straight through and a bullet is scanned. A paragraph a branch adds or grows past it fails the push in a context entry through the `paragraph-growth` gate stage, and an unchanged long paragraph passes. Elsewhere it is the audit's warning and no more.
+- Past roughly 700 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. Two long sentences satisfy the sentence cap and still overload the reader. This number sits well above the bullet checkpoint because a paragraph is read straight through and a bullet is scanned. A paragraph a branch adds or grows past it fails the push in a context entry through the `paragraph-growth` gate stage, and an unchanged long paragraph passes. Elsewhere it is the audit's warning and no more.
 
 ### Bullets
 
-- Keep bullets tight. Past roughly 250 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, the overflow belongs in prose. A bullet a branch adds or grows past it fails the push in a context entry through the `paragraph-growth` gate stage, and an unchanged one passes until edited. Elsewhere it is the audit's warning and no more. The number is a checkpoint rather than a cap, and a bullet reading well past it means the number is wrong rather than the rule.
+- Keep bullets tight. Past roughly 250 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, the overflow belongs in prose. A bullet a branch adds or grows past it fails the push in a context entry through the `paragraph-growth` gate stage, and an unchanged one passes until edited. Elsewhere it is the audit's warning and no more. The number is a checkpoint rather than a cap.
 - Keep a run of consecutive top-level bullets to 5 or fewer under one heading, and fold a longer one into prose, an H3 per item, or a split at the seam. A blank line, a continuation, and a nested item do not break the run, and a paragraph or heading does. The audit reports a longer run and the `bullet-stacks` gate stage fails it.
 - Leave a run whose every item opens with a bold label or a link as it is, since each item names its own subject. A task box (`[ ]`) is not a link, so a checklist counts as plain bullets. Numbered items do not count toward the cap. Governance rules and `REQUIREMENT.md` sit outside it, since a rule is one imperative per bullet.
 - Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.

package/claude/skills/plan-groundwork/references/groundwork.md

@@ -33,8 +33,8 @@ Governs a groundwork track under `.canon/groundwork/<nn>-<slug>/`: folder layout
 Does not govern:
 
 - **`groundwork-spikes.md`**: `08-spikes.md`, what each spike records, and the folders holding what a spike produced
-- **`intake.md`**: A dump of many findings filed by domain, each carrying its own verdict
-- **`plan.md`**: the feature plan a closed track feeds, and the contract its answer slots keep
+- **`intake.md`**: A dump of many findings filed by domain, each with a verdict
+- **`plan.md`**: the feature plan a closed track feeds, and its answer contract
 - **`tasks.md`**: the task file a closing track writes, and the origin line pointing back at the folder
 - **the `write-human` skill**: voice, rhythm, and sentence construction
 - **`markdown.md`**: headings, punctuation, word choice, and file references
@@ -42,9 +42,9 @@ Does not govern:
 
 ## Folder name
 
-- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug.
-- The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
-- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in one atomic act, so two sessions opening at once never share a number. The two kinds share one creation-order line.
+- Name the folder `<nn>-<slug>`, a two-digit ordinal and a kebab-case slug.
+- The ordinal marks a folder per track, opened once and worked over time, unlike a file addressed by name, one with its own sorting prefix, or one overwritten on purpose.
+- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in one atomic act, so two sessions opening at once never share a number. The two kinds share one order.
 - With neither folder holding an entry, the first one opened takes `01`, whatever number a track's own files start at.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 
@@ -53,17 +53,17 @@ Does not govern:
 A track works when a session that has never seen it re-enters from the folder alone and can answer each of these:
 
 - Which single question is being measured, and why is it running now?
-- What is the current state, measured during this pass rather than carried in from an earlier one?
-- Which questions are still open, where does the evidence point, and what would overturn that?
+- What is the current state, measured this pass rather than carried in?
+- Which questions are open, where is the evidence, and what overturns it?
 - What was decided, and what was considered and dropped?
 
-A track failing these is non-conforming even when it satisfies every shape rule below.
+A track failing these is non-conforming even when it meets every shape rule.
 
 ## Frontmatter and dating
 
 - `title` (required): the track subject in sentence case
 - `description` (required): one line naming what the track measures
-- `date` (required, `README.md` only): the day the folder opened, as `YYYY-MM-DD`
+- `date` (required, `README.md` only): the day it opened, as `YYYY-MM-DD`
 
 Carry the opening date as a frontmatter field rather than a sentence in the body, since nothing that walks the folder reads prose. Date the folder once rather than every file, because a per-file date goes stale on the first edit. The checkable half is the commit each measurement was taken against, which the file holding that measurement names.
 
@@ -90,13 +90,13 @@ Orients. Holds no findings.
 
 - A one-line definition of the investigation
 - A `## Why` section stating why the track is running now
-- A file-map table of filename and what it holds, kept current as files are added or retired
+- A file-map table of filename and what it holds, kept current
 - A `## Method` section splitting internal sources from external ones, naming which were used and which were not yet done, and listing under a leads heading any external source found but not opened
 
 ### Closing sections and phase
 
 - A `## Prior art` section
-- A `## Source citation` section stating the rule below, so a returning session picks it up from the folder
+- A `## Source citation` section stating the rule below, so a returning session finds it in the folder
 - The phase stated out loud in the first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
 
 Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. Without one, a later reader cannot tell a fetched page from recall. A source found and not read is listed as a lead and is never cited, since a link to a page nobody opened is worse than no link. Listing it stops a later pass re-searching for it.
@@ -109,23 +109,19 @@ Facts before opinion. Verified measurement only, taken during this pass.
 
 - Never carry a figure from a previous session without re-measuring, since every number built on a stale one is quietly wrong.
 - Mark an inference as an inference where one is unavoidable.
-- Measure only what an open question needs. A number with no question attached is the mechanism by which the groundwork becomes the work.
+- Measure only what an open question needs. A number with no question attached is how the groundwork becomes the work.
 
 ## 00-scope.md
 
-Written when the subject is large enough to run away. Holds constraints, risks, the open question list, and the downstream surfaces a decision would touch. A small track skips it.
+Written when the subject is large enough to run away. Holds constraints, risks, the open questions, and what a decision would touch. A small track skips it.
 
 ## 06-decision.md
 
-Closes the folder. Everything above it is input.
+Closes the folder. Everything above it is input. Write it from the skeleton under `## Template`, with an H3 per dropped alternative.
 
-- The problem stated once
-- The goal
-- The items to do
-- What was considered and dropped
-- `## Revisit when`: the "Overturned by" line of each lean that became the decision, carried over as written. A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section.
+`## Revisit when` carries the "Overturned by" line of each lean that became the decision, as written. A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section.
 
-The dropped list is what stops a future session re-proposing something already rejected.
+The dropped list stops a future session re-proposing a rejected idea.
 
 ## 07-next-session.md
 
@@ -141,8 +137,8 @@ Every open question carries a lean, wherever it appears. A bare numbered list ha
    - Overturned by: <the finding that would change it>
 ```
 
-- Pair every lean with what would overturn it. A lean with no falsifier is an opinion.
-- On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse than an admission.
+- Pair every lean with what would overturn it. A lean with no falsifier is opinion.
+- On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse.
 - Mark each question open or answered, and repeat the open ones at the end of the file they belong to. That gives the decision file its agenda for free.
 
 A lean is weaker than a plan's suggestion: it records the current read on an open question, not a decision to accept at execution time.
@@ -155,13 +151,15 @@ A lean is weaker than a plan's suggestion: it records the current read on an ope
 
 ## Anti-patterns
 
-- **The groundwork becomes the work.** Gathering expands until the measuring costs more than the change it justifies. Cap it, and drop any thread with no question attached.
+- **The groundwork becomes the work.** Gathering expands until the measuring costs more than the change it justifies. Cap it, and drop any thread with no question.
 - **Deciding by omission.** Closing a track while an unresolved question quietly fails an outcome. Resolve it or record it as knowingly accepted.
 - **Recording a constraint discovered while defending a decision.** Check it against the alternative design first, or a fact about the current shape reads as inherent to the problem.
 - **A plan written before the groundwork.** Every track that has done this had to supersede the plan it wrote.
 
 ## Template
 
+### README.md
+
 ```markdown
 ---
 title: <Track subject>
@@ -195,10 +193,41 @@ Groundwork phase. Nothing here is a feature plan.
 
 ## Prior art
 
-<Earlier plans, folders, or decisions this track supersedes or builds on.>
+### <earlier plan or folder>
+
+<What it decided and how this track supersedes or builds on it. Say not to go looking for it again.>
 
 ## Source citation
 
 Every claim about a source outside the project carries a link. A source found
 and not read is listed as a lead and is never cited.
 ```
+
+### 06-decision.md
+
+```markdown
+---
+title: <Track subject> decision
+description: <one line naming what the track decided>
+---
+
+# <Track subject> decision
+
+## Problem and goal
+
+<The problem stated once, then what done looks like.>
+
+## What to do
+
+1. <item>
+
+## Considered and dropped
+
+### <alternative>
+
+<Why it was dropped, and what would revive it.>
+
+## Revisit when
+
+- <an "Overturned by" line, as written>
+```

package/claude/skills/review-pr/references/post.md

@@ -80,7 +80,7 @@ Keying either half of the opening's threshold on the grade was measured wrong: a
 
 The cost is that the merge decision no longer reads off the heading alone, since an open heading covers a minor as well as a critical. Take it from the counts on the summary line, which is where they already sit. No summary line reports the merge as unblocked under either heading, since a thread reading open cannot also report that nothing blocks it.
 
-A minor the dispatched worker declines is what needs a surface that survives the merge, rather than every minor, since one that gets fixed on the branch needs no durable record. Write a declined minor into the `## Findings` section of the task the branch closes, which is where the queue-refill sweep already routes a finding that changes another task. A declined finding left on the thread alone is lost the moment the pull request merges.
+A minor the dispatched worker declines is what needs a surface that survives the merge, rather than every minor, since one that gets fixed on the branch needs no durable record. Write a declined minor into the `## Findings` section of the task the branch closes, as a line opening with the bold source-and-date label from `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`, which is where the queue-refill sweep already routes a finding that changes another task. A declined finding left on the thread alone is lost the moment the pull request merges.
 
 Read the state off the most recent review comment rather than off the presence of a closed one. A close-out does not close the pull request, so a commit pushed after it gets its own pass, and that pass reopens the review under `## Review` when it raises a finding of any grade.
 

package/claude/skills/role-orchestrator/SKILL.md

@@ -43,7 +43,7 @@ No surface carries cross-version sequencing, so report none. A row's `Waiting on
 
 A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do.
 
-On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It sends the generic half to `canon:session-map`, which writes a session map per `${CLAUDE_SKILL_DIR}/../session-map/references/session.md`, then adds the decisions taken under delegated authority as this role's extension. A lesson about how to work goes to the owning task's Findings. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
+On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It sends the generic half to `canon:session-map`, which writes a session map per `${CLAUDE_SKILL_DIR}/../session-map/references/session.md`, then adds the decisions taken under delegated authority as this role's extension. A lesson about how to work goes to the owning task's Findings, as a bold-labeled line per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
 
 On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work.
 

package/claude/skills/role-orchestrator/references/orchestrator-parked.md

@@ -31,7 +31,7 @@ The blocker cell states what the row waits on, and each kind is tested different
 
 Every measurement this pass takes is a blocker re-test on a row already filed, and it decides whether that row can start rather than how big it is. Sizing a row is the filing boundary `role-orchestrator` states under `## Boundaries`, which leaves the extent and the cause to whoever plans the row.
 
-Write the result into the row. A re-test reported in chat is lost at the next compaction and the next pass measures the same thing again. Rewrite a blocker cell whose test no longer holds, move the row to the group its new state puts it in, and record the measurement in that task's `## Findings` with the date it was taken. `### Writing the board` in `role-orchestrator` owns the method, and `canon tasks validate` runs once the board is rewritten and before the report.
+Write the result into the row. A re-test reported in chat is lost at the next compaction and the next pass measures the same thing again. Rewrite a blocker cell whose test no longer holds, move the row to the group its new state puts it in, and record the measurement in that task's `## Findings` as a line labeled with this session and the date it was taken, per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`. `### Writing the board` in `role-orchestrator` owns the method, and `canon tasks validate` runs once the board is rewritten and before the report.
 
 ## Re-testing a backlog row
 

package/claude/skills/role-planner/SKILL.md

@@ -69,7 +69,7 @@ it.
 
 - Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md`. Both are gitignored, so an overwrite drops a row with no history to recover it from.
 - Never write the task file. The record is the whole output, and a row edited from here changes what the controller reads back as the state of the board.
-- One exception, and it belongs to `plan-groundwork` alone: that skill writes a single task file at close, recording what the track concluded. Its own `## Write scope` states the exception, and this line exists so the rule above does not forbid what that skill requires.
+- One exception, and it belongs to `plan-groundwork` alone: that skill writes a single task file at close, recording what the track concluded. Each finding in it opens with the bold source-and-date label that `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes. Its own `## Write scope` states the exception, and this line exists so the rule above does not forbid what that skill requires.
 - Report what the row got wrong rather than repairing it. A stale count, a moved line, or a path that no longer resolves goes into the record and into the handback, and the controller decides which of the two carries the correction.
 - Leave the cross-feature call alone. Which rows collide, what merges before what, and whether a row should run at all stay with the controller. `priority.md` shows blockers and file sets and is enough to write a confident merge order off a partial picture, which is the failure this boundary exists to prevent.
 

package/claude/skills/role-worker/SKILL.md

@@ -37,7 +37,7 @@ which `auto-ship` Step 2 loads.
 - Copy a ready folder's files verbatim to the paths its plan's constraints name, when the plan's `**Constraints:**` block names one, and edit only what the gate or the overview's own list requires. A rewrite discards the text the handoff exists to carry.
 - Report a draft flag reading ready once, and leave it cleared. The ship chain marks the pull request a draft, and only `canon pr lift` or the operator un-marks it, so a flag reading ready afterwards passed every gate the verb reads or was readied by a person, which GitHub requires before a merge. Re-drafting fights them, and no surface in the tree states a reason to.
 - Leave the lift to the reviewers, who run `canon pr lift` on posting their close, and to the controlling session as the fallback. Refuse an instruction to ready the pull request directly, whoever sends it, since a direct ready skips every gate the verb reads.
-- Rewrite a plan question's `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when this build decides against an unanswered one, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+- Rewrite a plan question's `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when this build decides against an unanswered one, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, opening with the bold source-and-date label that `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
 
 ## The board is read-only
 

package/claude/skills/target-setup/SKILL.md

@@ -99,7 +99,7 @@ Step 2: `canon tooling sync <tooling-stack> --write` installs stack deps, script
 CANON_NON_INTERACTIVE=1 canon tooling sync <tooling-stack> <target> --write
 ```
 
-Monorepo with multiple language roots: run `canon init` once at the repo root so `base` (husky, prettier, commitlint, CI) lands single, then sync each subtree with `--skip base` so the shared layer is not re-dropped. Take the subtree commands from the per-root rows the preview printed rather than picking folders by hand. Detection found each root and its stack, and the two commands below show the shape.
+Monorepo with multiple language roots: run `canon init` once at the repo root so `base` (husky, oxfmt, commitlint, CI) lands single, then sync each subtree with `--skip base` so the shared layer is not re-dropped. Take the subtree commands from the per-root rows the preview printed rather than picking folders by hand. Detection found each root and its stack, and the two commands below show the shape.
 
 ```bash
 CANON_NON_INTERACTIVE=1 canon tooling sync vite-react ./frontend --skip base --write
@@ -112,11 +112,10 @@ A subtree sync withholds `.github/`, since GitHub reads workflows only at the re
 
 Step 3: post-sync fixups. Golden configs arrive from sync, so no config generation is required. But a few items may need a one-time touch:
 
-- **ESLint version pin.** If `bun create vite` installed `eslint@^10` and the manifest pins `eslint@^9`, sync does not override a present dep. Run `bun add -d eslint@^9` if `bun run lint:fix` fails with `Class extends value undefined`.
 - **File naming.** `bun create vite`'s `App.tsx` violates the `KEBAB_CASE` rule. Rename to `app.tsx` and update the import in `main.tsx`.
 - **Docs.** Run `canon tooling reference <tooling-stack>` and `canon tooling reference web` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
 
-Do not generate ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
+Do not generate oxlint, ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
 
 ## Phase: gov
 
@@ -161,7 +160,7 @@ After the chain, report:
 
 - Domains installed, with a check per domain
 - Tooling stack synced, or skipped. Name the layers pulled via the extends chain.
-- Any post-sync fixups applied (ESLint pin, filename renames)
+- Any post-sync fixups applied (filename renames)
 - `verify` outcome, naming the depth it ran at
 
 ### Outcomes and gaps

package/claude/skills/target-setup/references/verify.md

@@ -58,10 +58,11 @@ exit code is the whole verdict.
 | Order | Script      | Skip if                     |
 | ----- | ----------- | --------------------------- |
 | 1     | `lint:fix`  | absent                      |
-| 2     | `typecheck` | absent                      |
-| 3     | `check`     | absent                      |
-| 4     | `test:run`  | absent, fall back to `test` |
-| 5     | `build`     | absent                      |
+| 2     | `format`    | absent                      |
+| 3     | `typecheck` | absent                      |
+| 4     | `check`     | absent                      |
+| 5     | `test:run`  | absent, fall back to `test` |
+| 6     | `build`     | absent                      |
 
 Do not run composite scripts like `check:full`. Do not run `dev`, `preview`,
 `test:e2e`, `test:ui`, or `screenshot` at this depth. They belong to `deep`
@@ -80,7 +81,7 @@ server, and whether the screenshot harness produces output.
 | 3     | `test:e2e`   | absent  | leaf script: exit code  |
 | 4     | `screenshot` | absent  | leaf script: exit code  |
 
-`deep` runs the four above and not the five leaf scripts, which the default
+`deep` runs the four above and not the six leaf scripts, which the default
 depth already covers. The two sets are disjoint, so running both depths runs
 every declared script exactly once.
 

package/claude/skills/task-board/references/tasks.md

@@ -82,6 +82,8 @@ Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable
 
 Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
 
+Open each finding with a bold label naming its source and date, as in `- **planner, 2026-10-11:** <finding>`, and keep it to a few sentences. Anything longer moves into the plan or the groundwork folder. Outcomes stay a checklist, since the board tools read them by their `- [ ]` line.
+
 Size the outcomes so one pull request closes all of them, and split the task before handing it off rather than after. A task closes whole or not at all, so outcomes spanning two pull requests leave the board showing in-progress work no branch carries.
 
 A sliced task is the one allowed exception: a task the operator decided to ship across several pull requests on purpose, one slice each. Its `Pull request:` line lists every slice, so the board records which merged work covered which outcomes, and it closes whole when the last slice's merge finds every outcome ticked and no slice left pending.
@@ -115,7 +117,7 @@ Why this task exists and what it depends on.
 
 ## Findings
 
-- What constrains the task, dated where it matters.
+- **<source>, <YYYY-MM-DD>:** What constrains the task.
 
 > Test strategy: <unit | component | e2e | visual | manual>, what is being verified
 ```

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,7 +46,7 @@ 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:
 

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.37.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,9 +24,10 @@
     "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",
@@ -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/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/pr.ts

@@ -1891,7 +1891,7 @@ async function mapPool<T, R>(
   limit: number,
   task: (input: T) => Promise<R>,
 ): Promise<R[]> {
-  const results: R[] = new Array(inputs.length)
+  const results: R[] = Array.from({ length: inputs.length })
   let next = 0
   const lane = async (): Promise<void> => {
     while (next < inputs.length) {

package/src/commands/records.ts

@@ -17,7 +17,6 @@ import {
   type FolderSize,
   formatBytes,
   GROWTH_WINDOWS,
-  sizedFolders,
   type SizeOutcome,
   sizeRecords,
 } from '@/records/size'

package/src/docs/read.ts

@@ -149,29 +149,23 @@ export function walkEntries(root: string, dir: string): WalkedEntry[] {
   const cwd = join(root, dir)
   if (!existsSync(cwd)) return []
 
-  const files = markdownNames(cwd).map(
-    (name): WalkedEntry => ({
-      name,
-      kind: 'file',
-      rel: join(dir, `${name}.md`),
-    }),
-  )
+  const files = markdownNames(cwd).map((name): WalkedEntry => ({
+    name,
+    kind: 'file',
+    rel: join(dir, `${name}.md`),
+  }))
   const folders = catalogedFolders(cwd)
-  const split = folders.map(
-    (folder): WalkedEntry => ({
-      name: folder,
-      kind: 'folder',
-      rel: join(dir, folder, `${INDEX_TOPIC}.md`),
-    }),
-  )
+  const split = folders.map((folder): WalkedEntry => ({
+    name: folder,
+    kind: 'folder',
+    rel: join(dir, folder, `${INDEX_TOPIC}.md`),
+  }))
   const leaves = folders.flatMap((folder) =>
-    markdownNames(join(cwd, folder)).map(
-      (name): WalkedEntry => ({
-        name,
-        kind: 'leaf',
-        rel: join(dir, folder, `${name}.md`),
-      }),
-    ),
+    markdownNames(join(cwd, folder)).map((name): WalkedEntry => ({
+      name,
+      kind: 'leaf',
+      rel: join(dir, folder, `${name}.md`),
+    })),
   )
 
   return [...files, ...split, ...leaves]

package/src/gate/stages.ts

@@ -544,6 +544,20 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Shell check passed',
   },
+  {
+    id: 'lint',
+    label: 'Lint',
+    // Unscoped, since a full run costs less than spawning the process and a
+    // scope is one more pattern to fall behind the extensions oxlint reads.
+    checks: [
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'check:lint'],
+        failure: 'Lint failed',
+      },
+    ],
+    success: 'Lint passed',
+  },
   {
     id: 'types',
     label: 'Types',

package/src/markdown/structure.ts

@@ -86,7 +86,7 @@ const BLOCKQUOTE = /^\s*>/
  * follows, and the price is that a span opening a fragment mid-paragraph reads
  * as a sentence start.
  */
-const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“(\[]*[A-Z]|`)|\s*$)/g
+const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“([]*[A-Z]|`)|\s*$)/g
 
 /**
  * Checkpoints the structural measures run against.

package/src/sandbox/equivalence.ts

@@ -674,7 +674,7 @@ async function pool<T, R>(
   size: number,
   work: (item: T, index: number) => Promise<R>,
 ): Promise<R[]> {
-  const results: R[] = new Array(items.length)
+  const results: R[] = Array.from({ length: items.length })
   let next = 0
 
   async function lane(): Promise<void> {
@@ -827,14 +827,12 @@ export async function runEquivalence(
     const records: ArmRecord[] = [
       ...offline,
       ...anchored,
-      ...skipped.map(
-        (arm): ArmRecord => ({
-          arm: armKey(arm),
-          state: 'skipped-anchor',
-          differs: [],
-          masked: [],
-        }),
-      ),
+      ...skipped.map((arm): ArmRecord => ({
+        arm: armKey(arm),
+        state: 'skipped-anchor',
+        differs: [],
+        masked: [],
+      })),
     ].sort((x, y) => x.arm.localeCompare(y.arm))
 
     const counts: Record<ArmState, number> = {