@erclx/canon 5.22.0 → 5.24.0

package/src/gate/stages.ts

@@ -10,6 +10,7 @@ import {
   auditSet,
   captureStamps,
   clientCommandCitations,
+  designProse,
   documentCeiling,
   folderEchoedNames,
   markdownBans,
@@ -234,7 +235,9 @@ export const STAGES: readonly Stage[] = [
     // from `src/design/tokens.ts`, the base stylesheet from
     // `src/design/neutral.ts`, and none is edited by hand. Four artifacts
     // from two token sources is the cost of the token move, and a render step that has to run is only safe while something fails
-    // when it did not, which is this.
+    // when it did not, which is this. The record and the worked example are
+    // then counted against the prose budget, which the drift asserts cannot
+    // see since a regenerated paragraph agrees with its source.
     id: 'design',
     label: 'Design',
     checks: [
@@ -277,6 +280,7 @@ export const STAGES: readonly Stage[] = [
         failure:
           'The tab icon drifted from the token source. Run bun run check and commit web/public/favicon.svg.',
       },
+      { kind: 'measure', measure: designProse },
     ],
     success: 'Design source clean',
   },

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/design.md

@@ -33,10 +33,20 @@ Does not govern:
 
 ## Format
 
-- Use tables for token systems, one row per token. Use short bullets for component rules, one decision per line.
+- Use tables for token systems, one row per token. Write every other rule as a short bullet, one decision per line, within `## Prose budget`.
 - Plain English over technical notation. If a section could be removed and the developer would still build correctly from wireframes and code alone, remove it.
 - Keep table headers and role names intact so the render tooling can parse the token tables.
 
+## Prose budget
+
+The record is a lookup, so its prose stays short enough to scan beside the tables. Why a value was chosen belongs in the project's context entry for design, never here.
+
+- Personality: one paragraph of at most 60 words
+- Any other section: at most 3 rules beside its table, each at most 25 words. A bullet is one rule, and so is a paragraph.
+- The lead before the first section: at most 40 words
+
+Headings and table rows are never counted, and a section holding a table and no rules is within budget. A bullet wrapping over several lines counts as one rule, and a nested bullet counts as its own.
+
 ## The uncertainty tag
 
 A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
@@ -93,9 +103,9 @@ The column headers are the strings the renderer parses, read by exact key, so th
 
 ## Motion
 
-<whether motion is used at all, and if so the default duration and easing>
+- <whether motion is used at all, and if so the default duration and easing>
 
 ## Iconography
 
-<style, source library, and whether custom icons are allowed>
+- <style, source library, and whether custom icons are allowed>
 ```

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/hooks/scratch-guard.sh

@@ -57,5 +57,5 @@ marker="$marker_dir/$key"
 mkdir -p "$marker_dir"
 : >"$marker"
 
-msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, or .claude/.tmp/<slug>/ where the project carries no .canon/ root, not system temp. See the Scratch rule (604-scratch, under canon/ in your installed governance rules).'
+msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, not system temp. See the Scratch rule (604-scratch, under canon/ in your installed governance rules).'
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

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