@erclx/canon 5.22.0 → 5.23.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.22.0",
+  "version": "5.23.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -26,7 +26,7 @@ CANON_NON_INTERACTIVE=1 canon sync --check . --json
 CANON_NON_INTERACTIVE=1 canon context audit --json
 ```
 
-The first answers five domains from one read, being `skew`, `domains`, `seeds`, `tooling`, and the layout fields `unmigrated`, `superseded`, and `reverse`. The second deepens a domain that first read only counts.
+The first answers five domains from one read, being `skew`, `domains`, `seeds`, `tooling`, and the layout fields `unmigrated`, `superseded`, `unmovedSurfaces`, and `reverse`. The second deepens a domain that first read only counts.
 
 Then run `CANON_NON_INTERACTIVE=1 canon records validate <kind> --json` once per record folder the target carries, taking `<kind>` from what is present under the record root rather than from a list held here.
 
@@ -76,14 +76,14 @@ Lead with the table, then one detail block per domain that is not current:
 ```markdown
 Target check: `<path>`, against canon `<version>`.
 
-| Domain           | State                     | Evidence                          |
-| ---------------- | ------------------------- | --------------------------------- |
-| Toolkit version  | current / behind / unread | `skew.installed` against `latest` |
-| `canon/` folder  | current / behind / unread | what the layout fields named      |
-| Governance rules | current / behind / unread | the per-state counts              |
-| Tooling          | current / behind / unread | what a sync would change          |
-| Seeds            | current / behind / unread | the per-state counts              |
-| Claude harness   | unchecked                 | no verb reads it                  |
+| Domain           | State                     | Evidence                                       |
+| ---------------- | ------------------------- | ---------------------------------------------- |
+| Toolkit version  | current / behind / unread | `skew.installed` against `latest`              |
+| `canon/` folder  | current / behind / unread | the layout fields, including `unmovedSurfaces` |
+| Governance rules | current / behind / unread | the per-state counts                           |
+| Tooling          | current / behind / unread | what a sync would change                       |
+| Seeds            | current / behind / unread | the per-state counts                           |
+| Claude harness   | unchecked                 | no verb reads it                               |
 
 No overall verdict. The harness row is unchecked rather than passing.
 ```

package/claude/skills/target-check/references/domains.md

@@ -21,19 +21,25 @@ This domain is first because it conditions the other five. A target a release be
 
 ## 2. The `canon/` folder
 
-Read three fields off the same report, then two verbs:
+Read four fields off the same report, then two verbs:
 
 - `unmigrated`: a domain still at the root layout with nothing under `.claude/`. The most urgent finding, because such a domain reports no drift of its own while being entirely behind.
 - `superseded`: a file a newer seed folder replaced. No command moves it, since the content is the project's own.
+- `unmovedSurfaces`: a surface held only at its `.claude/` spelling, each entry carrying `rel` and `movesTo`. Every other field reads clean for such a target, and the report's drift status ignores it by design, so read the array itself rather than an exit status.
 - `reverse`: `unclaimed` names folders at roots the toolkit stopped shipping, each with an `attribution` of `dropped`, `unattributed`, or `project`.
 - `canon context audit --json`: required sections, entry length, citations, and index drift across the context folder.
 - `canon records validate <kind> --json`, once per record folder the target carries.
 
-- Current: `unmigrated` and `superseded` both empty, `reverse.unclaimed` carrying nothing outside `project` attribution, and both verbs finding nothing.
-- Behind: any of those carrying an entry. Name the entry and its attribution.
-- Unread: `historyUnavailable` set on `reverse`, a `reverse` key the report does not carry at all, or either verb refusing. A missing `reverse` key is a binary predating the field rather than a target with nothing unclaimed.
+- Current: `unmigrated`, `superseded`, and `unmovedSurfaces` all empty, `reverse.unclaimed` carrying nothing outside `project` attribution, and both verbs finding nothing.
+- Behind: any of those carrying an entry. Name the entry and its attribution, and for `unmovedSurfaces` each `rel` with its `movesTo`.
+- Unread: `historyUnavailable` set on `reverse`, a `reverse` or `unmovedSurfaces` key the report does not carry at all, or either verb refusing. A missing key is a binary predating the field rather than a target with nothing to report, so name the installed version beside it.
 
-Routes by finding. `unmigrated` routes to a relocation the user runs, since no command moves it. `superseded` routes to a split the user makes, since no command moves the content and no skill proposes it. An `unclaimed` folder carrying `project` attribution routes nowhere, since history proved the project owns it.
+Routes by finding.
+
+- `unmovedSurfaces` routes to `canon migrate surface-roots`, which only reports its plan until `--write` is passed. Name the verb with each entry's `rel` and `movesTo`, and run neither form.
+- `unmigrated` routes to a relocation the user runs, since no command moves it.
+- `superseded` routes to a split the user makes, since no command moves the content and no skill proposes it.
+- An `unclaimed` folder carrying `project` attribution routes nowhere, since history proved the project owns it.
 
 ## 3. Governance rules
 

package/docs/agents/architecture-record.md

@@ -19,7 +19,7 @@ What the derivation costs where it does apply is that the ceiling rises when a d
 
 The decision word check counts each decision's prose against the cap the record states in a clause of the form `at most 150 words a decision`. The count runs below the `###` heading with fenced lines dropped, so neither the heading nor a template block inside a decision counts, and the report and the gate read the same number. The JSON record carries the clause as `architecture.wordCap`, and the audit catalog counts the decisions past it as `recordOverWords`, absent where the record states no clause.
 
-The risk bullet check counts every list item under `## Risks / open questions`, nested ones included, against a clause of the form `at most 6 risk bullets`, since a nested bullet is weight the reader pays for like any other. Both clauses can share the entry cap's sentence, and each gates only a record stating it, for the reason the cap does. A record stating a risk cap and carrying no Risks section is reported as absent rather than passed as zero bullets. The JSON record carries the clause as `architecture.riskCap` and the count as `architecture.risksBullets`, and the audit catalog counts a section past its cap as `recordOverRisks`, absent where the record states no clause.
+The risk bullet check counts every list item under `## Risks / open questions`, nested ones included, against a clause of the form `at most 6 risk bullets`, since a nested bullet is weight the reader pays for like any other. Both clauses can share the entry cap's sentence, and each gates only a record stating it, for the reason the cap does. The record `canon claude init` seeds into a new project states all three caps in that one sentence, so a new project gates on them from its first decision, and a project that installed earlier keeps whatever its own record states. A record stating a risk cap and carrying no Risks section is reported as absent rather than passed as zero bullets. The JSON record carries the clause as `architecture.riskCap` and the count as `architecture.risksBullets`, and the audit catalog counts a section past its cap as `recordOverRisks`, absent where the record states no clause.
 
 The coverage report classifies each decision as carrying a countable claim, a structural invariant, or neither, then reports each testable entry against whether it names a check that exists. A countable claim carries a figure a run could recompute, and an invariant quantifies over a named tree closely enough that a walk could falsify it. A check is a `scripts/**.sh` path the entry spells that is on disk, or a `canon` invocation matching a registered audit, so coverage reads the entry rather than the tree and a claim some check happens to cover without the entry saying so reads as unchecked.
 
@@ -33,4 +33,4 @@ The `## Risks / open questions` section is weighed the same way, reported apart
 
 ## The requirements record
 
-The audit reads `canon/REQUIREMENTS.md` under its own step and counts every word below the frontmatter against the cap the record states in a clause of the form `This record holds at most 600 words.` The cap is the record's own, so a record stating none is measured and never gated, and a project with no record is reported as out of scope. The JSON record carries the reading as `requirements`, null where the project carries no record and absent under `--citations-only`, and the audit catalog counts a record past its cap as `requirementsOverWords`.
+The audit reads `canon/REQUIREMENTS.md` under its own step and counts every word below the frontmatter against the cap the record states in a clause of the form `This record holds at most 600 words.` The cap is the record's own, so a record stating none is measured and never gated, and a project with no record is reported as out of scope. The seeded record states the 600-word cap. The JSON record carries the reading as `requirements`, null where the project carries no record and absent under `--citations-only`, and the audit catalog counts a record past its cap as `requirementsOverWords`.

package/docs/agents/index.md

@@ -62,7 +62,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
 - [Tasks archive](tasks-archive.md): Archiving a shipped task by stem or pull request, declining one decided against, the refusal reasons each carries, and how the plan and ready folder move with the task
 - [Tasks plans](tasks-plans.md): The five verbs that read or write a task's plan, being where it sits and who cites it, whether it waits on the operator, the branch it derives, what a branch reached against what it declared, and writing its Plan line
-- [Tasks validate](tasks-validate.md): Validating the board against the tree, the seven checks, the untested, claims, and unplaced arrays, the exit codes, and the refusal reasons
+- [Tasks validate](tasks-validate.md): Validating the board against the tree, the seven checks, the untested, claims, wide, and unplaced arrays, the exit codes, and the refusal reasons
 - [Tasks](tasks.md): Claiming the next phase label, recording a pull request number and closing an outcome, listing each task's readiness, and where archiving, the plan verbs, and board validation are described
 - [Teach authoring](teach-authoring.md): Resolving what the next lesson needs before it is written, rendering a lesson body's blocks to HTML, and rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions
 - [Teach](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, viewing one with its chrome refreshed, where the lesson authoring verbs are described, the refusal reasons, and why every write here runs through a verb

package/docs/agents/tasks-validate.md

@@ -1,6 +1,6 @@
 ---
 title: Tasks validate
-description: Validating the board against the tree, the seven checks, the untested, claims, and unplaced arrays, the exit codes, and the refusal reasons
+description: Validating the board against the tree, the seven checks, the untested, claims, wide, and unplaced arrays, the exit codes, and the refusal reasons
 ---
 
 # Tasks validate
@@ -103,7 +103,9 @@ That claim collides with every row a later session writes under the folder, and
 
 The scan reaches `## Run now` and stops, where the collision check stops. A cell in another group describes work nobody has planned, written as a sentence and rewritten once a plan exists, so a claim read off one reports on prose rather than on a file set. A parked folder claim surfaces when its row is promoted, which is when the cell becomes something a dispatcher can act on.
 
-A task file neither surface names lands in a fourth array, on the same reasoning:
+A code span in any cell that the preview cannot break lands in a fourth array, `wide`, with the same `group`, `subject`, and `message` fields. The scan measures a span's longest whitespace-free run and flags one past 60 characters, or a brace-glob at any width. A 57-character span fit the pane and a 78-character one did not, so the limit is a heuristic and the array moves no exit code. A link target is skipped, since only its label renders, and the scan reaches every group, since the overflow it exists for sat under `## Up next`.
+
+A task file neither surface names lands in a fifth array, on the same reasoning:
 
 ```json
 {

package/docs/agents/tasks.md

@@ -118,6 +118,6 @@ canon tasks list --json | jq -r '.tasks[] | select(.readiness == "backlog") | .s
 
 ## Validate
 
-`canon tasks validate` reports what each row of `priority.md` and each line of `backlog.md` claims against what the tree holds. Its seven checks, the three arrays that move no exit code, and the refusals are in `tasks-validate.md`.
+`canon tasks validate` reports what each row of `priority.md` and each line of `backlog.md` claims against what the tree holds. Its seven checks, the four arrays that move no exit code, and the refusals are in `tasks-validate.md`.
 
 For the board format, see `standards/board.md`. For the `Pull request:` line and the archive rules, see `standards/tasks.md`.

package/docs/target/projects.md

@@ -71,7 +71,7 @@ Keep the `## Scripts` table in `canon/context/development.md` current as scripts
 
 Scaffold installs tooling and seeds. It does not fill the planning docs or the design system. Complete those before the first feature session:
 
-1. Fill `canon/REQUIREMENTS.md` and `canon/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
+1. Fill `canon/REQUIREMENTS.md` and `canon/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write. Each seed states its own caps, 12 decisions of at most 150 words and 6 risk bullets for the architecture record and 600 words for the requirements, and `canon context audit` gates on them. Edit a number in the record to loosen it.
 2. For a UI project, invoke `canon:design-extract` to draft `canon/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
 3. Optionally invoke `canon:draft-diagram` to draft entries under `.canon/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
 4. Start the feature loop. See [AI workflow](../workflow/ai-workflow.md) for the per-feature sequence.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.22.0",
+  "version": "5.23.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/commands/tasks.ts

@@ -42,6 +42,7 @@ import {
 import {
   type Finding,
   type FolderClaim,
+  type WideToken,
   type Unplaced,
   type Untested,
   type ValidateOutcome,
@@ -1411,6 +1412,16 @@ function reportValidation(
       for (const claim of outcome.claims) logWarn(describeClaim(claim))
     }
 
+    // The width limit is a heuristic over one preview pane, so a wide token
+    // reports and moves no exit code, and a measure failing on a cell that
+    // fits would teach a reader to skip it.
+    logStep('Wide tokens')
+    if (outcome.wide.length === 0) {
+      logInfo('every code span fits the preview pane')
+    } else {
+      for (const token of outcome.wide) logWarn(describeWide(token))
+    }
+
     // Unplaced is the normal state between a session filing a task and an
     // orchestrator placing its row, so it moves no exit code. It still reports,
     // since it is the only local detector for a row a hand-edit dropped or a
@@ -1436,6 +1447,7 @@ function reportValidation(
         findings: outcome.findings,
         untested: outcome.untested,
         claims: outcome.claims,
+        wide: outcome.wide,
         unplaced: outcome.unplaced,
       })}\n`,
     )
@@ -1457,6 +1469,10 @@ function describeClaim(claim: FolderClaim): string {
   return `${claim.group}: ${claim.subject} ${claim.message}`
 }
 
+function describeWide(token: WideToken): string {
+  return `${token.group}: ${token.subject} ${token.message}`
+}
+
 function describeUnplaced(task: Unplaced): string {
   return `${task.subject} ${task.message}`
 }

package/src/tasks/validate.ts

@@ -89,6 +89,20 @@ export interface FolderClaim {
   readonly message: string
 }
 
+/**
+ * A code span in a board cell that the markdown preview cannot break, so it
+ * pushes the table past the pane and makes it scroll sideways. Either the
+ * longest whitespace-free run is wider than `WIDE_LIMIT`, or the span is a
+ * brace-glob, which is written out as separate paths. The limit is a heuristic
+ * over one pane, which is why it reports beside the findings and moves no exit
+ * code.
+ */
+export interface WideToken {
+  readonly group: BoardGroup
+  readonly subject: string
+  readonly message: string
+}
+
 /**
  * A task file neither surface names. That is the normal state between a
  * session filing it and a live orchestrator placing it, so it reports beside
@@ -124,6 +138,8 @@ export interface BoardRow {
   readonly ordinal: OrdinalWord | 'last' | undefined
   /** Whether a `Waiting on` cell ranks its row against a sibling row or a class of rows, false when the group fixes no such column. */
   readonly ranked: boolean
+  /** Every cell of the row as `splitCells` read it, which the wide-token scan walks. */
+  readonly cells: readonly string[]
 }
 
 export interface ValidateReport {
@@ -135,6 +151,7 @@ export interface ValidateReport {
   readonly findings: readonly Finding[]
   readonly untested: readonly Untested[]
   readonly claims: readonly FolderClaim[]
+  readonly wide: readonly WideToken[]
   readonly unplaced: readonly Unplaced[]
 }
 
@@ -461,6 +478,7 @@ export function readBoard(text: string): {
       waiting,
       ordinal: waiting ? readOrdinal(waiting) : undefined,
       ranked: waiting ? readRank(waiting) : false,
+      cells,
     })
   }
 
@@ -992,6 +1010,52 @@ function checkFolderClaims(
   return claims
 }
 
+/**
+ * The widest the longest unbroken run in a code span may be before a table
+ * scrolls in the preview pane. A 57-character span fit and a 78-character one
+ * did not, so the limit sits at the nearest round number above the first.
+ */
+const WIDE_LIMIT = 60
+
+/**
+ * Reports a code span a table cell cannot wrap. A span breaks only at
+ * whitespace, so the longest whitespace-free run is what is measured, and a
+ * link target is stripped first because only its label renders. Every group is
+ * scanned, since the overflow this exists for happened under `## Up next`,
+ * where the folder-claim scan would not have looked. Prose breaks at spaces
+ * and bare words at hyphens, so only a span is read.
+ */
+function checkWideTokens(rows: readonly BoardRow[]): WideToken[] {
+  const wide: WideToken[] = []
+
+  for (const row of rows) {
+    for (const cell of row.cells) {
+      const spans = cell.replace(/\]\([^)]*\)/g, ']').match(/`[^`]+`/g) ?? []
+
+      for (const span of spans) {
+        const text = span.slice(1, -1)
+        const run = Math.max(...text.split(/\s+/).map((part) => part.length))
+
+        if (/\{[^}]*,[^}]*\}/.test(text)) {
+          wide.push({
+            group: row.group,
+            subject: subjectOf(row),
+            message: `holds the brace-glob ${span}, which renders as one unbroken token. Write it out as separate paths.`,
+          })
+        } else if (run > WIDE_LIMIT) {
+          wide.push({
+            group: row.group,
+            subject: subjectOf(row),
+            message: `holds a ${run}-character token, ${span}, past the ${WIDE_LIMIT} a preview pane fits, so its table scrolls sideways.`,
+          })
+        }
+      }
+    }
+  }
+
+  return wide
+}
+
 /**
  * Reports a task file neither the board nor the backlog names. Under the
  * roster-checked hand-off, filing a task and placing its row are two acts a
@@ -1327,6 +1391,7 @@ export async function validateBoard(
     findings,
     untested: parked.untested,
     claims: checkFolderClaims(rows, root),
+    wide: checkWideTokens(rows),
     unplaced: checkUnplaced(rows, backlog, stems),
   }
 }

package/standards/architecture.md

@@ -88,7 +88,7 @@ Every session pays for this file before any work starts, so a heavy read is a re
   - `This record holds at most <n> decisions.`
   - `at most <n> words a decision`, counting a decision's prose below its heading, fenced lines left out
   - `at most <n> risk bullets`, counting every list item under `## Risks / open questions`, nested ones included
-- The three can share one sentence, such as `This record holds at most 12 decisions, at most 150 words a decision, and at most 6 risk bullets.` Each cap is the record's own, so a record stating none is measured and never gated, and the template states the entry cap alone so the other two are adopted on purpose.
+- The three can share one sentence, such as `This record holds at most 12 decisions, at most 150 words a decision, and at most 6 risk bullets.` Each cap is the record's own, so a record stating none is measured and never gated. The template and the seed a new project installs state all three, and a project loosens one by editing the number in its own record.
 - Set the decision cap near one decision per slot plus a small margin, the word cap near what one trade takes to state, about 150, and the risk cap at what a reader holds in mind at once, about 6.
 - At the decision cap, merge two decisions or retire one before adding another, and name which in the change that does it. Never pack two decisions under one heading, which the count cannot see.
 - At the word cap, cut a decision to the choice, the alternative that lost, the reason, and the revisit sentence. What it sheds is a mechanism or a measurement, which goes to the domain context entry it constrains, never under a second heading.
@@ -106,7 +106,7 @@ The revisit sentence closes the reasoning of every decision. The anchor sentence
 
 ## Overview
 
-This record holds at most 12 decisions. Every decision closes with a revisit sentence.
+This record holds at most 12 decisions, at most 150 words a decision, and at most 6 risk bullets. Every decision closes with a revisit sentence.
 
 ## Key technical decisions
 

package/standards/board.md

@@ -57,6 +57,8 @@ Each group fixes its own columns, which follow from the test above it rather tha
 
 A `Touches` cell is copied from its plan's own list, so it states what the branch sets out to write rather than a bound on it, and a branch outgrows it while the row still reads as it did at dispatch. Correct the cell from the branch rather than from the plan once one is running, since the plan is the prediction that already went stale and only the diff says what was written. `canon tasks plan-reach <plan>` reads that diff against every live plan and every cell in this group, and the row's owner is the one who writes the correction: a worker never edits this board.
 
+A cell holds no code span whose longest unbroken run passes 60 characters, since a span has no break point and a wider one makes its table scroll sideways in the preview. Write a brace-glob out as separate paths for the same reason. `canon tasks validate` reports both in its `wide` array and moves no exit code.
+
 ### Row order
 
 Row position inside `## Needs a plan` is the order those tasks get planned in, top first. The three tests answer whether a task can start, which is mechanical, and none of them answers which task is worth starting, which is a judgment no column holds. Position is where that judgment is recorded, so the top row is the answer to what to plan next and a reader needs no other surface to get it. The other two groups take the same reading, and it costs them little, since a group holding what is already planned is short by construction.

package/standards/requirements.md

@@ -40,7 +40,7 @@ Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, and `## Constra
 
 ## Length
 
-This file loads into every session, so its weight is paid before any work starts. Cap it by stating the clause `This record holds at most <n> words.` in the record itself, where a checker reads it and counts every word below the frontmatter. The cap is the record's own, so a record stating none is measured and never gated. Set it near 600, and at the cap cut a goal or a constraint that no longer changes a decision before adding one.
+This file loads into every session, so its weight is paid before any work starts. Cap it by stating the clause `This record holds at most <n> words.` in the record itself, where a checker reads it and counts every word below the frontmatter. The cap is the record's own, so a record stating none is measured and never gated. The template and the seed a new project installs state it at 600, and a project loosens it by editing the number in its own record. At the cap, cut a goal or a constraint that no longer changes a decision before adding one.
 
 ## Lifecycle
 
@@ -59,6 +59,8 @@ State each entry as an outcome the consumer reaches, never as the mechanism that
 ```markdown
 # Requirements
 
+This record holds at most 600 words.
+
 ## Problem
 
 ## Goals

package/tooling/claude/seeds/.claude/hooks/path-form.sh

@@ -12,8 +12,8 @@
 # its surface, not from this hook or the output rule.
 #
 # The worktree branch comes from the path rather than from `git rev-parse`,
-# the way `tasks-index.sh` and `memory-index.sh` already derive their main
-# root from a path suffix instead of the session. A git call would answer for
+# the way `records-index.sh` already derives its main root from a path suffix
+# instead of the session. A git call would answer for
 # whatever directory the hook's own process happens to run in, which is not
 # necessarily the worktree the write came from.
 

package/tooling/claude/seeds/.claude/hooks/pr-create-log.sh

@@ -39,8 +39,8 @@ url=$(printf '%s' "$stdout" | grep -Eo 'https://github\.com/[^[:space:]]+/pull/[
 # CLAUDE_PROJECT_DIR is the session's own worktree rather than the main root,
 # so a worker building in a linked worktree would log into a folder that dies
 # with the worktree. The log is a denominator across a wave rather than a
-# per-session record, so strip back to the main root the way tasks-index.sh
-# and memory-index.sh already derive theirs, off a path suffix.
+# per-session record, so strip back to the main root the way
+# records-index.sh already derives its own, off a path suffix.
 root="${CLAUDE_PROJECT_DIR:-.}"
 case "$root" in
 */.claude/worktrees/*) root="${root%/.claude/worktrees/*}" ;;

package/tooling/claude/seeds/.claude/hooks/{tasks-index.sh → records-index.sh}

@@ -1,11 +1,12 @@
 #!/usr/bin/env bash
 
-# Regenerates .claude/tasks/index.md after a task file changes.
+# Regenerates the index.md of a gitignored record folder, `tasks` or `memory`,
+# after a file in it changes.
 #
-# The task folder is gitignored, so the whole-repo walk in `bun run check`
-# drops it and never regenerates this index. Naming the file as a positional
+# These folders are gitignored, so the whole-repo walk in `bun run check` drops
+# them and never regenerates their index. Naming the file as a positional
 # argument to `canon indexes regen` below bypasses that filter, which makes this
-# hook the only trigger that reaches the folder.
+# hook the only trigger that reaches either folder.
 
 # Claude Code sends a payload and closes stdin. A bare read with nothing feeding
 # it blocks forever and holds the session open, so the read is bounded. `read`
@@ -25,45 +26,51 @@ esac
 file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
 [ -n "$file_path" ] || exit 0
 
-# Both record roots, since a project the move has reached keeps its board under
+# Both record roots, since a project the move has reached keeps its records under
 # `.canon/` and a guard fixed at the old spelling stops matching with nothing
 # said. The index then goes stale while every save reports success.
-case "$file_path" in
-*/.claude/tasks/*.md | */.canon/tasks/*.md) ;;
-*) exit 0 ;;
-esac
-
-# The board index covers the live folder alone. A shell pattern's wildcard
-# crosses a separator, so the guard above matches an archived or declined task
-# as well, and a regen fired on one would rebuild the index that task was
-# taken out of.
-case "$file_path" in
-*/.claude/tasks/index.md | */.claude/tasks/archive/* | */.claude/tasks/declined/*) exit 0 ;;
-*/.canon/tasks/index.md | */.canon/tasks/archive/* | */.canon/tasks/declined/*) exit 0 ;;
-esac
-
+#
+# A shell `case` `*` crosses `/`, so each arm also matches a file in a subfolder
+# the index does not render: an archived or declined task, a memory receipt, a
+# retired memory entry, or the index itself. Those exit here, before the regen
+# call. The exclusions are per folder, since a task under `review/` is indexed
+# and a memory `declined/` is not special. The arms are ordered tasks first,
+# and no path carries both segments today.
+#
 # The walk-up boundary has to come from the path, not from the session. Shared
 # scratch resolves at the main worktree root, so a session inside a linked
 # worktree passes a path that sits outside its own project directory and the
-# default boundary would reject it.
-#
-# The index this would have rebuilt is read out of the same branch, so both
-# messages below name the file that actually went stale rather than one root's
-# spelling of it.
+# default boundary would reject it. The messages below name the index read out
+# of the same match, so they name the file that actually went stale.
 case "$file_path" in
-*/.canon/tasks/*)
-  root="${file_path%/.canon/tasks/*}"
-  index=".canon/tasks/index.md"
+*/.canon/tasks/index.md | */.canon/tasks/archive/* | */.canon/tasks/declined/*) exit 0 ;;
+*/.claude/tasks/index.md | */.claude/tasks/archive/* | */.claude/tasks/declined/*) exit 0 ;;
+*/.canon/memory/index.md | */.canon/memory/review/* | */.canon/memory/archive/*) exit 0 ;;
+*/.claude/memory/index.md | */.claude/memory/review/* | */.claude/memory/archive/*) exit 0 ;;
+*/.canon/tasks/*.md)
+  folder=tasks
+  base=.canon
+  ;;
+*/.claude/tasks/*.md)
+  folder=tasks
+  base=.claude
   ;;
-*)
-  root="${file_path%/.claude/tasks/*}"
-  index=".claude/tasks/index.md"
+*/.canon/memory/*.md)
+  folder=memory
+  base=.canon
   ;;
+*/.claude/memory/*.md)
+  folder=memory
+  base=.claude
+  ;;
+*) exit 0 ;;
 esac
+root="${file_path%/"$base/$folder"/*}"
+index="$base/$folder/index.md"
 [ -n "$root" ] || exit 0
 
 # Report a missing CLI rather than exiting quietly. The path guard above already
-# scopes this to a task-file edit, so the message only fires where the stale
+# scopes this to a record-file edit, so the message only fires where the stale
 # index it warns about is the actual outcome.
 if ! command -v canon >/dev/null 2>&1; then
   msg="canon is not on PATH, so $index was not regenerated and is now stale. Install the toolkit CLI or run canon indexes regen by hand."
@@ -73,18 +80,18 @@ if ! command -v canon >/dev/null 2>&1; then
 fi
 
 # `--no-stage` because a hook has no business touching the index. On a project
-# whose board is not gitignored, the default auto-stage would silently add task
-# files to whatever commit is being assembled.
+# whose folder is not gitignored, the default auto-stage would silently add
+# record files to whatever commit is being assembled.
 output=$(canon indexes regen --no-stage --root "$root" "$file_path" 2>&1) && exit 0
 
-# Regen failed, which on this folder means a task file is missing `title` or
+# Regen failed, which on these folders means a file is missing `title` or
 # `description`. Report it. Nothing else can: the folder is gitignored, so the
 # whole-repo walk never reaches it and no gate stage will ever fail on a stale
 # index. Staying quiet here is what makes the drift permanent.
 errors=$(printf '%s\n' "$output" | grep '^ERROR: ' | head -5)
 [ -n "$errors" ] || errors="$output"
 
-msg="Task index regen failed, so $index is now stale. Fix the frontmatter and save again. $errors"
+msg="The $folder index regen failed, so $index is now stale. Fix the frontmatter and save again. $errors"
 jq -nc --arg msg "$msg" \
   '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
 exit 0

package/tooling/claude/seeds/.claude/settings.json

@@ -39,11 +39,7 @@
           },
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tasks-index.sh"
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/memory-index.sh"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/records-index.sh"
           },
           {
             "type": "command",

package/tooling/claude/seeds/canon/ARCHITECTURE.md

@@ -4,7 +4,7 @@ Authoring guidance: the architecture standard.
 
 ## Overview
 
-This record holds at most 12 decisions.
+This record holds at most 12 decisions, at most 150 words a decision, and at most 6 risk bullets.
 
 ## Key technical decisions
 

package/tooling/claude/seeds/canon/REQUIREMENTS.md

@@ -2,6 +2,8 @@
 
 Authoring guidance: the requirements standard.
 
+This record holds at most 600 words.
+
 ## Problem
 
 ## Goals

package/tooling/claude/seeds/.claude/hooks/memory-index.sh

@@ -1,95 +0,0 @@
-#!/usr/bin/env bash
-
-# Regenerates .claude/memory/index.md after a memory file changes.
-#
-# The memory folder is gitignored, so the whole-repo walk in `bun run check`
-# drops it and never regenerates this index. Naming the file as a positional
-# argument to `canon indexes regen` below bypasses that filter, which makes this
-# hook the only trigger that reaches the folder.
-
-# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
-# it blocks forever and holds the session open, so the read is bounded. `read`
-# rather than `timeout cat`, which macOS does not ship.
-IFS= read -r -d '' -t 2 input
-[ -n "$input" ] || {
-  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
-  exit 1
-}
-
-tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
-case "$tool" in
-Write | Edit | MultiEdit) ;;
-*) exit 0 ;;
-esac
-
-file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
-[ -n "$file_path" ] || exit 0
-
-# Both record roots, since a project the move has reached keeps its memory pen
-# under `.canon/` and a guard fixed at the old spelling stops matching with
-# nothing said. The index then goes stale while every save reports success.
-case "$file_path" in
-*/.claude/memory/*.md | */.canon/memory/*.md) ;;
-*) exit 0 ;;
-esac
-
-# A shell `case` `*` crosses `/`, so the match above also catches a receipt
-# under memory/review/ or a retired entry under memory/archive/. Neither is
-# a pen entry the index renders, so both exit here before the regen call.
-case "$file_path" in
-*/.claude/memory/review/* | */.canon/memory/review/* | \
-  */.claude/memory/archive/* | */.canon/memory/archive/*)
-  exit 0
-  ;;
-esac
-
-case "$file_path" in
-*/.claude/memory/index.md | */.canon/memory/index.md) exit 0 ;;
-esac
-
-# The walk-up boundary has to come from the path, not from the session. Shared
-# scratch resolves at the main worktree root, so a session inside a linked
-# worktree passes a path that sits outside its own project directory and the
-# default boundary would reject it.
-#
-# The index this would have rebuilt is read out of the same branch, so both
-# messages below name the file that actually went stale rather than one root's
-# spelling of it.
-case "$file_path" in
-*/.canon/memory/*)
-  root="${file_path%/.canon/memory/*}"
-  index=".canon/memory/index.md"
-  ;;
-*)
-  root="${file_path%/.claude/memory/*}"
-  index=".claude/memory/index.md"
-  ;;
-esac
-[ -n "$root" ] || exit 0
-
-# Report a missing CLI rather than exiting quietly. The path guard above already
-# scopes this to a memory-file edit, so the message only fires where the stale
-# index it warns about is the actual outcome.
-if ! command -v canon >/dev/null 2>&1; then
-  msg="canon is not on PATH, so $index was not regenerated and is now stale. Install the toolkit CLI or run canon indexes regen by hand."
-  jq -nc --arg msg "$msg" \
-    '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
-  exit 0
-fi
-
-# `--no-stage` because a hook has no business touching the index. On a project
-# whose memory folder is not gitignored, the default auto-stage would silently
-# add memory files to whatever commit is being assembled.
-output=$(canon indexes regen --no-stage --root "$root" "$file_path" 2>&1) && exit 0
-
-# Regen failed, which on this folder means a memory file is missing `title` or
-# `description`. Report it. Nothing else can: the folder is gitignored, so the
-# whole-repo walk never reaches it and no gate stage will ever fail on a stale
-# index. Staying quiet here is what makes the drift permanent.
-errors=$(printf '%s\n' "$output" | grep '^ERROR: ' | head -5)
-[ -n "$errors" ] || errors="$output"
-
-msg="Memory index regen failed, so $index is now stale. Fix the frontmatter and save again. $errors"
-jq -nc --arg msg "$msg" \
-  '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
-exit 0