@erclx/canon 4.120.0 → 4.122.0

package/src/tasks/record.ts

@@ -353,7 +353,7 @@ export async function recordPlan(
 }
 
 /**
- * Marks the named outcomes `[x]` in place. `docs-fold` runs this against a
+ * Marks the named outcomes `[x]` in place. `context-fold` runs this against a
  * board it can read and cannot edit from a linked worktree, and the positions
  * come from the read it already made.
  */

package/src/tasks/validate.ts

@@ -7,6 +7,7 @@ import {
   isReservedStem,
   readOutcomes,
   readPlanTarget,
+  readPlanTargets,
   readPullRequest,
   resolveLivePlan,
   tasksDir,
@@ -41,6 +42,7 @@ export const FINDING_KINDS = [
   'plan-mismatched',
   'plan-parked',
   'plan-absent',
+  'plan-several',
   'task-unresolved',
   'row-duplicated',
   'row-misshapen',
@@ -563,7 +565,7 @@ async function listTaskStems(dir: string): Promise<string[]> {
 
 /**
  * Resolves a pointer against the board and against the project root both, the
- * way `docs-fold` reads the same line. A fragment is dropped first, since an
+ * way `context-fold` reads the same line. A fragment is dropped first, since an
  * anchor is part of the link and never part of the path.
  */
 function resolves(target: string, dir: string, root: string): boolean {
@@ -728,8 +730,12 @@ async function planDisagreement(
   const file = join(dir, `${row.stem}.md`)
   if (!existsSync(file)) return undefined
 
-  const target = readPlanTarget(await readFile(file, 'utf8'))
+  const text = await readFile(file, 'utf8')
+  const target = readPlanTarget(text)
   if (!target) {
+    const several = severalPlans(text, 'Run now', subject)
+    if (several) return several
+
     return {
       kind: 'plan-uncited',
       group: 'Run now',
@@ -787,7 +793,13 @@ async function groupClaimFinding(
   const file = join(dir, `${row.stem}.md`)
   if (!existsSync(file)) return undefined
 
-  const target = readPlanTarget(await readFile(file, 'utf8'))
+  const text = await readFile(file, 'utf8')
+  const target = readPlanTarget(text)
+  if (!target) {
+    const several = severalPlans(text, row.group, row.stem)
+    if (several) return several
+  }
+
   const live = target ? resolveLivePlan(target, dir, root) : undefined
   const hasLivePlan = live !== undefined && existsSync(live)
 
@@ -814,6 +826,27 @@ async function groupClaimFinding(
   return undefined
 }
 
+/**
+ * Reports a `Plan:` line linking more than one plan. `readPlanTarget` reads
+ * such a line as naming nothing, so without this a caller would report the
+ * line as absent when it is there and breaks the one-plan rule instead.
+ */
+function severalPlans(
+  text: string,
+  group: Finding['group'],
+  subject: string,
+): Finding | undefined {
+  const targets = readPlanTargets(text)
+  if (targets.length < 2) return undefined
+
+  return {
+    kind: 'plan-several',
+    group,
+    subject,
+    message: `cites ${targets.length} plans on its Plan: line (${targets.join(', ')}). One task names one plan, so split the task or drop the extra links.`,
+  }
+}
+
 /**
  * Where a plan pointer lands, resolved against the board and against the
  * project root the way the archive resolves the same line. Neither base

package/standards/docs.md

@@ -19,7 +19,7 @@ Does not govern:
 - 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`
+- Punctuation and formatting: `markdown.md`
 
 ## What a working docs page looks like
 

package/standards/index.md

@@ -19,7 +19,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [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
-- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
+- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Mermaid reference](mermaid.md): Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
 - [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive

package/standards/markdown.md

@@ -1,6 +1,6 @@
 ---
 title: Markdown reference
-description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
+description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
 ---
 
 # Markdown reference
@@ -9,11 +9,11 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 
 ## Scope
 
-Governs what a check can decide about a markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, file references, the closed-set word and spelling bans, what prose may claim about its sources, and the wording of a catalog title and description. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because these rules are written across every document and have no shape of their own.
+Governs what a check can decide about a markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, file references, the spelling convention, what prose may claim about its sources, and the wording of a catalog title and description. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because these rules are written across every document and have no shape of their own.
 
 The two frontmatter fields it reaches are `title` and `description`. They are named here rather than in the statement above, since a backticked token in a scope statement's first sentence is published as the standard's jurisdiction.
 
-The split with the voice guidance is what reads the rule rather than what the rule covers. Every ban below ships as data `canon markdown audit` and the installed audit hook both read, so a violation is measured on every run. Cadence, rhythm, and information density are judgments a reader settles, and those travel in the `canon:write-human` skill, which a markdown edit routes to.
+The split with the voice guidance is what reads the rule rather than what the rule covers. The character bans ship as data `canon markdown audit` and the installed audit hook both read, so a violation is measured on every run. Word choice, cadence, rhythm, and information density are judgments a reader settles, and those travel in the `canon:write-human` skill, which a markdown edit routes to.
 
 Does not govern:
 
@@ -71,9 +71,7 @@ Does not govern:
 
 ## Language
 
-- Use American English spelling. Prefer `-ize` over `-ise`, `-or` over `-our`, `-er` over `-re` (`organize`, `analyze`, `summarize`, `recognize`, `behavior`, `color`, `center`)
-- Do not use marketing buzzwords (`seamless`, `robust`, `powerful`, `revolutionary`, `enhanced`, `allows`, `leverage`)
-- Do not use vague qualifiers (`simply`, `just`, `easily`, `quickly`, `very`, `really`)
+- Use American English spelling
 - Open a sentence with its subject and action, not filler (`Note that`, `Basically`), a hollow connective (`That being said`, `It's worth noting`), or a gerund windup (`Leveraging the API...`). Substantive transitions that carry a real relationship are fine.
 - Do not use the negative parallelism pattern (`It's not X, it's Y`, `not because X, but because Y`)
 - Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
@@ -84,7 +82,7 @@ Does not govern:
 - Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
 - Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
 
-The word bans and the character bans sit under one file because one command reads both. `canon markdown audit` ships them as package data, so a project that installed no standards is measured the same as one that did, and this section states them for a reader rather than for the parser.
+One command reads the character bans under `## Punctuation`. `canon markdown audit` ships them as package data, so a project that installed no standards is measured the same as one that did, and this file states them for a reader rather than for the parser. The spelling line above states a convention and ships no set, so a project's spell checker is what enforces it.
 
 ## Frontmatter descriptions
 

package/standards/memory.md

@@ -56,19 +56,21 @@ Write no entry for a fact another surface already owns. A fact about a domain be
 
 ## Frontmatter
 
-Every entry carries all three fields.
+Every entry carries the three required fields, and a reviewed entry carries a fourth.
 
 ```yaml
 ---
 title: A scope glob wide enough for a correct run can be wide enough for every wrong one
 description: Omit a declaration key whose only passing value admits the whole tree
 category: Project
+reviewed: 2026-09-26
 ---
 ```
 
 - `title` (required): the rule stated as a line a reader can act on, in sentence case.
 - `description` (required): one line naming what the entry settles, so a reader scanning the catalog decides whether to open it.
 - `category` (required): the type in sentence case, which is what groups the catalog.
+- `reviewed` (optional): the `YYYY-MM-DD` date a review last read the entry and kept it. A review writes it and capture never does, so an entry without the field has never been reviewed. A rewrite of the entry carries the field through untouched, since dropping it sends a kept entry back to the front of the queue.
 
 Never write the filename stem as the `title`. The stem is a slug, and an entry titled with it reads as an unwritten file in every catalog that renders the field.
 
@@ -103,6 +105,16 @@ Link a related entry as `[[name]]`, where `name` is the target's filename stem w
 
 The catalog is generated from sibling frontmatter rather than authored. Never hand-edit it, since the next regeneration discards whatever was added by hand.
 
+## Reading
+
+Nothing loads the pen into every session, and that is the design. An entry reaches a reader through one of three paths:
+
+- A review reads the pen in batches, taking entries in the order `canon records stale memory` reports: due entries first, those citing a path the tree no longer holds ahead of the rest, then the longest unreviewed.
+- A resuming session reads the entries matching the task it picks up.
+- Capture reads the catalog to find an existing entry on the same topic before writing a new one.
+
+An entry none of the three reaches is one the pen holds for a review to promote or retire.
+
 ## Collecting a review receipt
 
 A review of the pen writes a receipt recording what it proposed per entry and what was decided. The receipt is collected once every item on it has resolved, and it is held while any item is still pending, since a pending item is decision state the next round reads back.

package/standards/pr.md

@@ -16,7 +16,7 @@ Does not govern:
 - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
 - Whether a quoted label, a gitignored record path, or a link to one Claude Code session may appear in a title or body, which `canon labels scan` fails on: `publish.md`
 - Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
-- Punctuation, formatting, and banned words in pull request prose: `markdown.md`
+- Punctuation and formatting in pull request prose: `markdown.md`
 
 ## Title
 

package/standards/publish.md

@@ -26,7 +26,7 @@ Scope every check below by destination. Text published to a remote takes all of
 
 ## Banned characters
 
-`markdown.md` holds the character bans and the banned words alike. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
+`markdown.md` holds the character bans. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
 
 Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.
 

package/standards/readme.md

@@ -5,7 +5,7 @@ description: Readme voice, structure, and content conventions
 
 # Readme reference
 
-Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the spelling rules, banned words, punctuation, and formatting in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no buzzwords.
+Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as does the word-choice guidance that travels with them, and so do the punctuation and formatting in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no marketing words.
 
 The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
 
@@ -16,7 +16,7 @@ Governs every `README.md`: voice, heading structure, required and optional secti
 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
+- 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`
 

package/standards/tasks.md

@@ -51,7 +51,7 @@ The handoff takes one file per session for the reason a task does. A single shar
 
 The catalog is the one reader that filters nothing, so it carries a row per sibling alongside the tasks. That is what a folder catalog is for, and the handoffs are what make it worth stating: a board accumulates one row per session that ever wrote one, with nothing pruning them. Anything reading the catalog as the backlog therefore does its own filtering, and a reader that takes every row as a task reports the handoffs as queued work.
 
-The `task-board` skill creates and archives task files, and the archive carries the task's plan with it. `docs-fold` marks outcomes `[x]` in an existing file. Neither does the other's job.
+The `task-board` skill creates and archives task files, and the archive carries the task's plan with it. `context-fold` marks outcomes `[x]` in an existing file. Neither does the other's job.
 
 ## Ordering
 

package/tooling/astro/reference.md

@@ -58,7 +58,7 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``. <!-- audit-ignore-citations: canon/context/ci.md -->
 
 ## Social card route
 

package/tooling/base/configs/.husky/post-merge

@@ -7,7 +7,7 @@
 # to hand a worker. This is the only event that lands after a merge.
 #
 # Candidates rather than closed tasks, because an all-`[x]` board entry does not
-# mean the work merged. `docs-fold` marks outcomes on the branch as step 1 of
+# mean the work merged. `context-fold` marks outcomes on the branch as step 1 of
 # the ship chain, so a task can read closed while its pull request is still open
 # or already abandoned. The board is gitignored and an archived task has nothing
 # to recover it, so `task-board` confirms the work is on `main` before moving

package/tooling/base/configs/scripts/verify.sh

@@ -48,14 +48,14 @@ check_markdown_bans() {
 
   case "$code" in
   0)
-    log_info "No banned character, word, or spelling"
+    log_info "No banned character"
     ;;
   1)
     log_info "Skipped: canon markdown audit refused and measured nothing."
     ;;
   2)
     echo "$output" | pipe_output
-    log_error "Markdown prose carries a banned character, word, or spelling, or a relative link resolves to nothing on disk"
+    log_error "Markdown prose carries a banned character, or a relative link resolves to nothing on disk"
     ;;
   3)
     echo "$output" | pipe_output

package/tooling/base/seeds/canon/context/development.md

@@ -34,4 +34,4 @@ All `.sh` files live under `scripts/`. Do not place shell scripts outside `scrip
 
 - `pre-commit` runs `lint-staged` (prettier, cspell, shfmt, shellcheck on staged files).
 - `commit-msg` runs `commitlint` against the conventional commit format.
-- `pre-push` runs `bun run check`. When a markdown-bans audit tool is on PATH, it also gates on banned characters, words, and spellings across every tracked markdown file except `CHANGELOG.md`. After pushing, run `git status`. If files changed, commit the diff as `style(<scope>):` and push again.
+- `pre-push` runs `bun run check`. When a markdown-bans audit tool is on PATH, it also gates on banned characters across every tracked markdown file except `CHANGELOG.md`. After pushing, run `git status`. If files changed, commit the diff as `style(<scope>):` and push again.

package/tooling/claude/reference.md

@@ -25,7 +25,7 @@ canon/
 .canon/
 ├── tasks/             ← seeded. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
 ├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
-├── plans/             ← execution detail for multi-step tasks. `feature-*.md` entries swept by docs-fold into `archive/`.
+├── plans/             ← execution detail for multi-step tasks. `feature-*.md` entries swept by context-fold into `archive/`.
 ├── review/            ← one subfolder per producer. `branch/` for review-branch, `feedback/` for canon feedback, `memory/` for memory-review with its own `archive/`, `design/` for canon design render.
 ├── tmp/               ← ephemeral scratch space, safe to delete without loss
 └── memory/            ← session facts no context entry owns. `index.md` regenerated by a hook.

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -28,12 +28,11 @@ esac
 
 [ -f "$file" ] || exit 0
 
-# The audit verb owns the ban sets, so this hook carries no copy of them. The
-# awk this replaces parsed the word bans out of the project's own standards,
-# hardcoded the em-dash and semicolon, and reached none of the spellings, so a
-# British spelling passed at edit time and a corpus check caught it later with
-# nothing in between explaining the difference. A ban class added to the verb
-# now reaches this hook without an edit here.
+# The audit verb owns the ban set, so this hook carries no copy of it. The awk
+# this replaces parsed its bans out of the project's own standards and
+# hardcoded the rest, so edit time and a later corpus check could disagree with
+# nothing in between explaining the difference. A ban added to the verb now
+# reaches this hook without an edit here.
 #
 # The verb resolves its own paths under the cwd, so the project root is named
 # rather than inherited. The payload carries an absolute file path, which is

package/tooling/go/reference.md

@@ -57,4 +57,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `go vet ./...` passes ``. Add a Lint row whose assertion reads: `` `golangci-lint run` passes ``. Add a Tests row whose assertion reads: `` `go test -race ./...` exits 0 ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `go vet ./...` passes ``. Add a Lint row whose assertion reads: `` `golangci-lint run` passes ``. Add a Tests row whose assertion reads: `` `go test -race ./...` exits 0 ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/nextjs/reference.md

@@ -50,4 +50,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `next typegen && tsc --noEmit` passes ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `next typegen && tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/php/reference.md

@@ -71,4 +71,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `phpstan analyse` passes ``. Add a Lint row whose assertion reads: `` `php-cs-fixer check` passes ``. Add a Tests row whose assertion reads: `` `phpunit` exits 0 ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `phpstan analyse` passes ``. Add a Lint row whose assertion reads: `` `php-cs-fixer check` passes ``. Add a Tests row whose assertion reads: `` `phpunit` exits 0 ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/python/reference.md

@@ -62,4 +62,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `mypy .` passes ``. Add a Lint row whose assertion reads: `` `ruff check` and `ruff format --check` pass ``. Add a Tests row whose assertion reads: `` `pytest` exits 0 ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `mypy .` passes ``. Add a Lint row whose assertion reads: `` `ruff check` and `ruff format --check` pass ``. Add a Tests row whose assertion reads: `` `pytest` exits 0 ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/vite-react/reference.md

@@ -52,4 +52,4 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `tsc --noEmit` passes ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/ci.md -->

package/tooling/web/reference.md

@@ -84,7 +84,7 @@ Sticky negative knowledge. Do not relearn.
 
 ## CI docs (extend)
 
-Extend `canon/context/ci.md` so the `## Checks` table reflects the web jobs.
+Extend `canon/context/ci.md` so the `## Checks` table reflects the web jobs. <!-- audit-ignore-citations: canon/context/ci.md -->
 
 Append rows: