@erclx/canon 4.19.2 → 4.20.0

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

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

package/claude/skills/claude-teach/references/lesson-craft.md

@@ -35,6 +35,15 @@ Every element competes with the material for attention.
 - Do not animate anything the learner did not trigger
 - Prefer whitespace over rules and boxes to separate sections
 
+## Diagrams
+
+A diagram earns its place when a relationship, a boundary, a path, a before-and-after, is the point of the passage rather than decoration for it. Most passages do not clear that bar, and a lesson reaching for a diagram on every section is the failure the neighboring `## Restraint` section already guards against. When prose or a list already carries that point, leave it there.
+
+- Wrap it in a `<figure>` holding an inline `<svg>` and a `<figcaption>` that names what to take from the diagram rather than what it shows. Let the figure run wider than the prose column, since a diagram cramped to the reading measure loses the labels it needs.
+- Draw it by hand, as plain shapes and lines authored directly in the markup, not exported from a diagramming tool.
+- Color every fill and stroke through a custom property the workspace's own stylesheet defines, never a literal hex value, which is the same rule that stylesheet's opening comment already states for every rule added under it. The diagram then re-colors itself on the same switch that re-colors the page.
+- Give the `<svg>` an accessible name: `role="img"` with `aria-label` for one short line, or `aria-labelledby` pointing at a `<title>` element inside it for a longer one.
+
 ## Quiz construction
 
 The quiz is the retrieval, so a leak in its construction turns it into a reading test.

package/claude/skills/docs-sync/SKILL.md

@@ -10,6 +10,7 @@ Read these files in parallel:
 - `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
 - The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 - `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: README structure, required sections, and content rules
+- `${CLAUDE_SKILL_DIR}/../../standards/docs.md`: the reader a page under `docs/` serves, its frontmatter, structure, and what it links out rather than carrying
 
 ## Diff baseline
 

package/docs/agents/commands.md

@@ -51,7 +51,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon migrate record-tree`   | Repoint the old-root citations inside the records themselves, scoped to the live folders and reporting every line without `--write` (`--root`, `--json`)              |
 | `canon sessions list`         | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
 | `canon worktrees list`        | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
-| `canon worktrees reclaim`     | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run`                                                                |
+| `canon worktrees reclaim`     | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run` (`--json`)                                                     |
 | `canon comments scan`         | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |
 | `canon context audit`         | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                             |
 | `canon markdown audit`        | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                                |

package/docs/agents/index.md

@@ -45,4 +45,4 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
 - [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
-- [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, removing the ones that are, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
+- [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, removing the ones that are, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes

package/docs/agents/worktrees.md

@@ -1,6 +1,6 @@
 ---
 title: Worktrees
-description: Reporting which worktrees are reclaimable, removing the ones that are, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
+description: Reporting which worktrees are reclaimable, removing the ones that are, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
 ---
 
 # Worktrees
@@ -31,11 +31,13 @@ An exit code says nothing about a call made from a session, since a shell profil
 ```bash
 canon worktrees reclaim --dry-run
 canon worktrees reclaim
+canon worktrees reclaim --json
 ```
 
 | Option      | Behavior                                    |
 | ----------- | ------------------------------------------- |
 | `--dry-run` | Report what would be removed without acting |
+| `--json`    | Add a machine-readable record on stdout     |
 
 Removal sits on the default path rather than behind an apply flag. Report-only is what the `list` verb already did, and what it produced was a hand cleanup: eight directories deleted outside git in one afternoon, each leaving the registration and the branch that `git worktree remove` would have taken with it. A flag a reader has to remember is one nobody passes the first time, and the first time is when the directories are still there.
 
@@ -43,6 +45,18 @@ Each entry unlocks, removes, then deletes its branch, and the sequence is the sa
 
 Exit codes: `0` every reclaimable worktree was removed or there were none, `1` refused or a removal failed. A reading that could not reach the merge state refuses every entry rather than falling back to a default, since that state is the one input deciding whether a branch is safe to delete.
 
+### The record
+
+`--json` writes `{reason, detail, dryRun, reclaimable, removed, failed, pruned, outcomes}` on stdout. `reason` is null unless the whole reading refused, `reclaimable` counts what the verdicts named, `removed` and `failed` split the outcomes, and `pruned` says whether the stale-registration sweep ran. A dry run and a reading that found nothing both report `removed` as 0 and differ on `reclaimable`, which separates a quiet repository from a run asked not to act.
+
+Field order is part of the contract. A shell reads this record with a pattern rather than a parser, so `reason` sits ahead of the free-text `detail`, and the scalar counts sit ahead of `outcomes`, whose per-entry `failedAt` and boolean `removed` match neither digit pattern. Read the record's fields rather than the exit when a skill or a hook consumes this, for the reason the `list` section above gives.
+
+## What calls it
+
+`.husky/post-merge` runs `canon worktrees reclaim --json` on every merge, between the records push and the upgrade block, so a merged branch's worktree goes without a person remembering. `CANON_SKIP_RECLAIM=1` turns that step off.
+
+The hook's call carries no `--root` and no `cd`, unlike the two steps above it. Git runs a hook from the top level of the worktree the pull happened in, and the verb reads its own working directory to refuse that worktree as `current-worktree`, so a root argument would turn the running worktree into an ordinary candidate and let a pull inside a linked worktree delete the ground under itself.
+
 ## What makes a worktree reclaimable
 
 All three hold: its branch has a merged pull request, its working tree is clean, and no live session holds the directory. Each alone has a case where removal loses something, so `refusals` names every failing condition rather than the first.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.19.2",
+  "version": "4.20.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -28,7 +28,7 @@
     "check:spell": "cspell '**' '.*/**' '.*' --no-progress --color --show-context",
     "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/",
-    "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} +",
+    "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:types": "tsc --noEmit",
     "check:install": "./scripts/core/install-check.sh",
     "test": "bun --bun vitest run",

package/src/commands/worktrees.ts

@@ -17,7 +17,11 @@ import {
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
 import { mainWorktreeRoot } from '@/worktree'
-import { removeReclaimable, type RemovalOutcome } from '@/worktrees/remove'
+import {
+  removeReclaimable,
+  type RemovalOutcome,
+  type RemovalReport,
+} from '@/worktrees/remove'
 
 interface ListCommandOptions {
   readonly json?: boolean
@@ -25,8 +29,51 @@ interface ListCommandOptions {
 
 interface ReclaimCommandOptions {
   readonly dryRun?: boolean
+  readonly json?: boolean
+}
+
+/**
+ * What a caller reads instead of the frame.
+ *
+ * `.husky/post-merge` is the first caller that is not a person, and it branches
+ * on a parsed field rather than on the exit code, since a shell profile
+ * wrapping `canon` in a function flattens every status to zero. It reads the
+ * record with a pattern rather than a parser, so every field it branches on is
+ * a number or a fixed word, and `outcomes` sits last so a greedy pattern
+ * anchored on a scalar never reaches into it.
+ */
+export interface ReclaimRecord {
+  readonly reason: Unreadable | null
+  readonly detail: string | null
+  readonly dryRun: boolean
+  readonly reclaimable: number
+  readonly removed: number
+  readonly failed: number
+  readonly pruned: boolean
+  readonly outcomes: readonly RemovalOutcome[]
 }
 
+/** Every value the record carries, in the two shapes a run can end in. */
+export type ReclaimSource =
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: Unreadable
+      readonly detail: string
+      readonly dryRun: boolean
+    }
+  | {
+      readonly kind: 'read'
+      readonly dryRun: boolean
+      readonly reclaimable: number
+      /**
+       * Null when no removal ran at all, which covers a reading that found
+       * nothing reclaimable and a dry run alike. The two differ on
+       * `reclaimable` rather than here, so a caller can tell a quiet repository
+       * from a run that was asked not to act.
+       */
+      readonly removal: RemovalReport | null
+    }
+
 const REFUSALS: Record<Refusal, string> = {
   'main-worktree': 'the main worktree, which is never reclaimable',
   'current-worktree':
@@ -120,6 +167,7 @@ export function register(program: Command): void {
     )
     .helpOption('-h, --help', 'Show this help message')
     .option('--dry-run', 'Report what would be removed without removing it')
+    .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
       [
@@ -148,6 +196,7 @@ export function register(program: Command): void {
         'Examples:',
         '  canon worktrees reclaim --dry-run',
         '  canon worktrees reclaim',
+        '  canon worktrees reclaim --json',
         '',
       ].join('\n'),
     )
@@ -210,6 +259,47 @@ async function runList(opts: ListCommandOptions): Promise<number> {
   return 0
 }
 
+/**
+ * Builds the record from the values a run already holds.
+ *
+ * Separate from the run so the record is testable without a repository, a `gh`
+ * credential, or a directory the test would then have to remove. The counts are
+ * derived from `outcomes` rather than passed in, since two numbers a caller
+ * computes are two numbers a caller can get wrong.
+ */
+export function reclaimRecord(source: ReclaimSource): ReclaimRecord {
+  if (source.kind === 'unreadable') {
+    return {
+      reason: source.reason,
+      detail: source.detail,
+      dryRun: source.dryRun,
+      reclaimable: 0,
+      removed: 0,
+      failed: 0,
+      pruned: false,
+      outcomes: [],
+    }
+  }
+
+  const outcomes = source.removal?.outcomes ?? []
+
+  return {
+    reason: null,
+    detail: null,
+    dryRun: source.dryRun,
+    reclaimable: source.reclaimable,
+    removed: outcomes.filter((outcome) => outcome.removed).length,
+    failed: outcomes.filter((outcome) => !outcome.removed).length,
+    pruned: source.removal?.pruned ?? false,
+    outcomes,
+  }
+}
+
+function emitReclaim(opts: ReclaimCommandOptions, source: ReclaimSource): void {
+  if (opts.json !== true) return
+  process.stdout.write(`${JSON.stringify(reclaimRecord(source))}\n`)
+}
+
 async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
   const dryRun = opts.dryRun ?? false
   const cwd = process.cwd()
@@ -222,6 +312,12 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
   if (report.kind === 'unreadable') {
     reportUnreadable(report)
     outro()
+    emitReclaim(opts, {
+      kind: 'unreadable',
+      reason: report.reason,
+      detail: report.detail,
+      dryRun,
+    })
     return 1
   }
 
@@ -231,6 +327,7 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
   if (reclaimable.length === 0) {
     logInfo('None. Every worktree fails at least one condition.')
     outro()
+    emitReclaim(opts, { kind: 'read', dryRun, reclaimable: 0, removal: null })
     return 0
   }
 
@@ -241,6 +338,12 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
     logStep('Dry run')
     logWarn('Nothing was removed. Run this again without --dry-run to remove.')
     outro()
+    emitReclaim(opts, {
+      kind: 'read',
+      dryRun,
+      reclaimable: reclaimable.length,
+      removal: null,
+    })
     return 0
   }
 
@@ -265,12 +368,16 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
     logWarn(
       `${plural(failed.length, 'worktree')} could not be removed. Read the reason above and clear it by hand.`,
     )
-    outro()
-    return 1
   }
 
   outro()
-  return 0
+  emitReclaim(opts, {
+    kind: 'read',
+    dryRun,
+    reclaimable: reclaimable.length,
+    removal,
+  })
+  return failed.length > 0 ? 1 : 0
 }
 
 /** Names what happened to one entry, with the failing step where it did not close. */

package/src/gate/stages.ts

@@ -410,7 +410,12 @@ export const STAGES: readonly Stage[] = [
   {
     id: 'shell',
     label: 'Shell',
-    scope: /\.sh$|^package\.json$/,
+    // `.husky/` is matched by prefix rather than by extension, since every hook
+    // there carries no extension and the `.sh` half reaches none. Without
+    // it `check:shell` lints those files only on a branch that happened to
+    // touch a `.sh` file or this manifest, which is the gap that let fifty
+    // lines of shell land in a hook with no stage firing on it.
+    scope: /\.sh$|^\.husky\/|^package\.json$/,
     skipped: 'Skipped, no shell changes',
     checks: [
       {

package/standards/context.md

@@ -17,6 +17,7 @@ Does not govern:
 - Product scope, goals, and non-goals: `requirements.md`
 - Path-scoped coding rules: `rule.md`
 - Diagrams and wireframes, which answer structure and layout questions an entry hands off: `diagrams.md` and `wireframes.md`
+- The consumer-facing reference under `docs/`, whose reader is operating the project without the source open: `docs.md`
 
 ## Organizing principle
 

package/standards/docs.md

@@ -0,0 +1,102 @@
+---
+title: Docs reference
+description: Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder
+---
+
+# Docs reference
+
+Applies to each authored reference page under `docs/`. Skip for `index.md` at any depth, which is generated rather than authored.
+
+## Scope
+
+Governs each authored reference page under `docs/`, whose reader is an operator running what the project ships rather than developing it, and an agent reading the page cold from a project that consumes it: the frontmatter a page carries, its structure, what it links out to rather than restating, whether it holds a diagram, and when a category earns a subfolder of its own.
+
+Neither reader has the source open. That is the whole of the distinction from internal narrative, whose reader does, and from the page a project puts at its front door, whose reader has not decided to install anything yet.
+
+Does not govern:
+
+- The page a project puts at its front door, whose reader is deciding whether to commit at all: `readme.md`
+- Per-domain internal narrative written for a reader with the source open: `context.md`
+- The drawing inside a Mermaid fence: `mermaid.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Spelling, banned words, punctuation, and formatting: `markdown.md`
+
+## What a working docs page looks like
+
+A page works when a reader who has never opened the source answers all four from the page alone.
+
+- What is this surface, and when would I reach for it?
+- What do I run or write to use it, spelled exactly enough to copy?
+- What does it refuse, and what does a refusal look like when I hit one?
+- Where do I go for the adjacent surface this page stops at?
+
+A page failing these is non-conforming even when it satisfies every shape rule below. The shape rules are the means. These four questions are the test.
+
+## Frontmatter
+
+- `title` (required): sentence case, naming the surface the page covers rather than the action a reader takes on it
+- `description` (required): one line naming what the page covers, which is what the folder's catalog shows beside the link
+- `category` (conditional): the shelf the page sits on in that catalog
+- Declare `category` on every page in a folder where any page declares one. A grouped catalog writes the declared shelves and nothing else, so a page omitting the field beside a sibling that carries one is absent from the catalog with nothing reporting it.
+- Omit it on every page or on none. A folder where no page declares one lists flat, which is the right shape for a folder whose pages need no shelves.
+- Spell one shelf's value identically on every page sitting there. The grouping reads the literal string, so a second spelling opens a second shelf holding one page.
+
+## Structure
+
+- Open with an H1 matching `title`, then one or two lines saying what the surface is, before any heading
+- Use `##` for major sections and `###` for subsections. Do not nest deeper.
+- Use sentence case for every heading, proper nouns aside
+- Lead with the invocation a reader came for. Background, rationale, and edge cases sit below it.
+- Write a command, a flag, or a field as something copyable, in a code span or a fence, never paraphrased into prose
+
+## Content
+
+- Write for a reader with no access to the source. A sentence that resolves only by opening a file belongs in internal narrative instead.
+- Name the failures a surface produces alongside the path that works. A page documenting success alone sends its reader to the source at the first refusal.
+- Link to the adjacent page rather than restating it. One page owns each surface, and a second copy drifts with nothing comparing the two.
+- Do not restate output a command already prints, such as a full flag table. Name the command that prints it.
+- Do not carry the history of how a surface reached its shape. A page describes the surface as it stands, and the change that moved it is recorded wherever the project tracks work.
+- Do not carry contributor setup or the argument for adopting the project. Both are addressed to a reader who has not installed anything yet.
+
+## Diagrams
+
+- Carry a diagram where the page describes a structure or a path the reader has to hold in their head at once. One per page at most, and none is a correct answer for most pages.
+- Draw it as a Mermaid fence or as a committed image the page references. Neither form is preferred, and the pick belongs to whoever knows which one the page's reader reads it in.
+- Follow `mermaid.md` for the drawing inside a fence. It reaches the drawing and stops at the fence markers, so everything around it stays this file's subject.
+- Do not write the drawing as raw inline markup. A rendering host strips markup outside its own allowlist, so an inline drawing survives a local preview and vanishes on the surface the page is read from.
+- Say beneath the diagram, in prose, what it shows. A reader who cannot see the image gets the same answer from the sentence.
+
+## Splitting the folder
+
+- Move a `category` into a subfolder once its pages stop reading as a list in the catalog and start reading as a section of one. The shelf is the signal, not a file count, and a count invites an argument about the count instead.
+- Move every page carrying that value. A shelf split across two depths is harder to scan than either arrangement taken whole.
+- Give the subfolder a catalog page of its own, so the parent lists one entry where it listed several. The parent lists a subfolder as a folder rather than as a member of the shelf it replaced, so nothing on that page restores the grouping.
+- Retarget every link into a moved page in the same change. A link resolving nowhere is what the move costs, and nothing else reports it.
+
+## Template
+
+```markdown
+---
+title: <Surface>
+description: <one line naming what this page covers>
+category: <the shelf this page sits on, carried by every sibling or by none>
+---
+
+# <Surface>
+
+<One or two lines on what the surface is and when a reader reaches for it.>
+
+## <The invocation>
+
+`<the command or field, spelled to copy>`
+
+<What it does and what it produces.>
+
+## <Refusals>
+
+- `<the condition>`: <what the reader sees, and what to do about it>
+
+## <Adjacent surface>
+
+<Where the reader goes for the thing this page stops at.>
+```

package/standards/index.md

@@ -13,6 +13,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
+- [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder
 - [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
 - [Groundwork reference](groundwork.md): Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval

package/standards/readme.md

@@ -18,6 +18,7 @@ Does not govern:
 - Rhythm and sentence construction in README prose: the `write-human` skill, which yields the voice and keeps the rest
 - Spelling, banned words, punctuation, and formatting in README prose: `markdown.md`, which yields nothing
 - Product scope and goals: `requirements.md`
+- The consumer-facing reference under `docs/`, whose reader has already committed and is operating the project: `docs.md`
 
 ## Voice