@erclx/canon 5.30.0 → 5.32.0

package/src/upstream/releases.ts

@@ -0,0 +1,170 @@
+import { $ } from 'bun'
+import { gitEnv } from '@/git/env'
+import { compareVersions } from '@/upstream/cursor'
+
+const RELEASES_URL =
+  'https://api.github.com/repos/anthropics/claude-code/releases'
+const PER_PAGE = 100
+const MAX_PAGES = 10
+
+/** The subset of a GitHub release the digest reads. */
+export interface Release {
+  readonly tag_name: string
+  readonly published_at: string
+  readonly body: string | null
+  readonly draft?: boolean
+}
+
+export interface ReleaseLine {
+  readonly version: string
+  readonly date: string
+  readonly text: string
+}
+
+export type FetchFailure = 'rate-limited' | 'network' | 'http'
+
+export type PageResult =
+  | { readonly ok: true; readonly releases: readonly Release[] }
+  | {
+      readonly ok: false
+      readonly reason: FetchFailure
+      readonly message: string
+    }
+
+/** Page numbers start at 1. A page past the feed's end comes back empty. */
+export type PageFetcher = (page: number) => Promise<PageResult>
+
+export type Walk =
+  | { readonly kind: 'reached'; readonly releases: readonly Release[] }
+  | { readonly kind: 'cursor-missing'; readonly cursor: string }
+  | {
+      readonly kind: 'failed'
+      readonly reason: FetchFailure
+      readonly message: string
+    }
+
+// Ported from the groundwork's mechanical-drop script. The first group anchors on the line
+// start, the rest match anywhere because the surface they name can sit mid-line.
+const DROP =
+  /^(Fixed|\[VSCode\]|\[Claude Tag\]|\[Code Review\]|Windows:|Self-hosted)|apps gateway|managed setting|OpenTelemetry|Bedrock|Vertex|screen reader/i
+const KEEP = /^(Added|Changed|Removed|Improved|Deprecated)/
+const BULLET = /^\s*[-*] (.*)$/gm
+const DIFFERENCE_LINE = /^(\[[^\]]+\] )?(Changed|Removed|Deprecated)/
+const BACKTICKED = /`([^`]{3,60})`/g
+const DISTINCTIVE = /[-/.A-Z]/
+
+export function versionOf(tag: string): string {
+  return tag.replace(/^v/, '')
+}
+
+export function keepLines(release: Release): ReleaseLine[] {
+  const version = versionOf(release.tag_name)
+  const date = release.published_at.slice(0, 10)
+
+  return [...(release.body ?? '').matchAll(BULLET)]
+    .map((match) => match[1] ?? '')
+    .filter((text) => KEEP.test(text) && !DROP.test(text))
+    .map((text) => ({ version, date, text }))
+}
+
+export function extractIdentifiers(text: string): string[] {
+  if (!DIFFERENCE_LINE.test(text)) return []
+
+  return [...text.matchAll(BACKTICKED)]
+    .map((match) => match[1] ?? '')
+    .filter((name) => DISTINCTIVE.test(name))
+}
+
+/**
+ * Collects the releases newer than the cursor, newest first.
+ *
+ * The walk stops at the first release whose version is not newer than the
+ * cursor, wherever it sits, so a range crossing a page boundary is read whole
+ * and a cursor naming a version the feed never carried, as 2.1.256 is not,
+ * still bounds the range. A feed that ends with every release newer than the
+ * cursor reports `cursor-missing` instead of returning all of it.
+ */
+export async function walkReleases(
+  cursor: string,
+  fetchPage: PageFetcher,
+  perPage: number = PER_PAGE,
+): Promise<Walk> {
+  const collected: Release[] = []
+
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const result = await fetchPage(page)
+    if (!result.ok) {
+      return { kind: 'failed', reason: result.reason, message: result.message }
+    }
+
+    for (const release of result.releases) {
+      if (release.draft) continue
+      if (compareVersions(versionOf(release.tag_name), cursor) <= 0) {
+        return { kind: 'reached', releases: collected }
+      }
+      collected.push(release)
+    }
+
+    if (result.releases.length < perPage) break
+  }
+
+  return { kind: 'cursor-missing', cursor }
+}
+
+export function githubPageFetcher(
+  env: Record<string, string | undefined> = process.env,
+  signal?: AbortSignal,
+): PageFetcher {
+  const token = env.GH_TOKEN ?? env.GITHUB_TOKEN
+  const headers: Record<string, string> = {
+    Accept: 'application/vnd.github+json',
+    'User-Agent': 'canon-upstream',
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  }
+
+  return async (page) => {
+    try {
+      const response = await fetch(
+        `${RELEASES_URL}?per_page=${PER_PAGE}&page=${page}`,
+        { headers, signal },
+      )
+      if (response.status === 403 || response.status === 429) {
+        return {
+          ok: false,
+          reason: 'rate-limited',
+          message:
+            'GitHub refused the request. Set GH_TOKEN or GITHUB_TOKEN to lift the hourly limit.',
+        }
+      }
+      if (!response.ok) {
+        return {
+          ok: false,
+          reason: 'http',
+          message: `GitHub answered ${response.status} for page ${page}.`,
+        }
+      }
+
+      return { ok: true, releases: (await response.json()) as Release[] }
+    } catch {
+      return {
+        ok: false,
+        reason: 'network',
+        message: 'The releases feed could not be reached.',
+      }
+    }
+  }
+}
+
+/** The tracked files naming an identifier, as a hint for where to look. */
+export async function grepHint(
+  root: string,
+  identifier: string,
+): Promise<string[]> {
+  const result =
+    await $`git -C ${root} grep -l -F -e ${identifier} -- . ':!wiki'`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+
+  return result.stdout.toString().split('\n').filter(Boolean)
+}

package/standards/context.md

@@ -18,10 +18,8 @@ Governs per-domain narrative entries under `canon/context/`: their structure, th
 
 Does not govern:
 
-- Decisions filling a stack, delivery, boundary, layout, or build-principle slot, and system-wide risks: `architecture.md`
 - Product scope, goals, and non-goals: `requirements.md`
 - Path-scoped coding rules: `rule.md`
-- Wireframes, which answer layout questions an entry hands off: `wireframes.md`
 - Figures and architecture views, which answer structure questions an entry hands off: the `draft-figure` skill
 - The consumer-facing reference under `docs/`, whose reader is operating the project without the source open: `docs.md`
 
@@ -88,10 +86,10 @@ Only the `development` entry carries this section. It is not a general-purpose h
 ## What goes in
 
 - Per-domain narrative on how the code is structured and why
-- Decisions that constrain the domain, whether or not their reasoning touches another one. This is a decision's default home, and `canon/ARCHITECTURE.md` takes only a decision that fills one of the slots its standard names.
+- Decisions that constrain the domain, whether or not their reasoning touches another one. A decision lives in the entry of the domain it constrains.
 - Constraints, gotchas, things tried and rejected
 - Domain-specific conventions that do not fit a `paths:`-scoped rule
-- A measured figure, anchored the way `architecture.md` states under `## Verification anchors`, so an entry and the architecture record date a number the same way.
+- A measured figure, closed with a trailing `Measured at <short-sha> on <YYYY-MM-DD>.` naming a commit rather than a pull request number or a branch. Carry one anchor per figure and rewrite it in place when the number is re-read, whether or not it moved. An absent anchor reads as unchecked.
 - A reference to another entry, spelled as the path that entry sits at rather than as its bare filename. A bare name resolves against whichever folder the reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A reference to a seed, a standard, or a file the project owns elsewhere keeps the form its own surface uses.
 
 ## What does not go in
@@ -103,7 +101,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Rules. Those go in `.claude/rules/<scope>.md` with a `paths:` glob.
 - Tutorials or human onboarding. Those go in `docs/` if a public audience exists.
 - Generated content (API references). Generate, do not write by hand.
-- Anything already in `canon/REQUIREMENTS.md` or `canon/ARCHITECTURE.md`.
+- Anything already in `canon/REQUIREMENTS.md`.
 - The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
 - A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
 - The route to a decision: the rounds of candidates, the tuning steps a threshold passed through, the review pass that caught a miss. State the decision, what lost, and why, once and in the present tense. Cut the route. Git and the change that introduced it keep it.

package/standards/design.md

@@ -15,13 +15,12 @@ Governs the visual-intent document at `canon/DESIGN.md`: tokens described as int
 
 Does not govern:
 
-- Screen layout, on-screen copy, and interaction intent: `wireframes.md`
 - Per-domain implementation narrative: `context.md`
 
 ## What goes in
 
 - A token's exact value, anchored to the surface it was read from and tagged per `## The uncertainty tag` when unconfirmed. Fall back to intent language ("mid gray, muted text") only where no source exists yet to anchor from.
-- Layout constraints and sizing rules not obvious from wireframes
+- Layout constraints and sizing rules not obvious from the tokens and the code
 - Visual rules a developer could get wrong without guidance
 - Non-obvious omissions ("no motion", "no custom icons") that prevent scope creep
 
@@ -34,7 +33,7 @@ Does not govern:
 ## Format
 
 - 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.
+- Plain English over technical notation. If a section could be removed and the developer would still build correctly from the tokens and code alone, remove it.
 - Keep table headers and role names intact so the render tooling can parse the token tables.
 
 ## Prose budget

package/standards/index.md

@@ -7,40 +7,17 @@ subtitle: Reference docs for consistent authoring across the toolkit and target
 
 Reference docs for consistent authoring across the toolkit and target projects.
 
-- [Architecture reference](architecture.md): Shape and content rules for canon/ARCHITECTURE.md
-- [Board reference](board.md): Readiness groups, row cells, and ordering for priority.md, the unordered backlog.md beside it, and the generated index under .canon/tasks/
 - [Branch reference](branch.md): Branch naming format and type conventions
-- [Canvas reference](canvas.md): Page folders, frame files, the layout.json shape, token resolution, and what a frame must not assume on a local design canvas
 - [Commit reference](commit.md): Commit message format and type conventions
 - [Context entry reference](context.md): Shape and content rules for canon/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for canon/DESIGN.md
 - [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
 - [Figure reference](figures.md): When a figure earns its place, the render-first policy for a graph-shaped subject, freehand SVG as the escape hatch, and its wrapping, color, and accessibility rules
-- [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
-- [Groundwork spikes reference](groundwork-spikes.md): What each spike in a track's 08-spikes.md records, the sample rule, and the three folders that hold what a spike produced
-- [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, 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 lifecycle reference](plan-lifecycle.md): When a feature plan is written, where it lives, how it changes mid-flight, and its move to the archive
-- [Plan reference](plan.md): Filename and slug, the required sections, and the suggested-and-answer contract for a feature plan
 - [Pull request reference](pr.md): Pull request title and body conventions
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
-- [Ready reference](ready.md): Folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff
-- [Requirements reference](requirements.md): Shape and content rules for canon/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
-- [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
-- [Skill path reference](skill-paths.md): Which root a file a skill body names resolves against, and how a body cites a standard
-- [Practice skill reference](skill-practice.md): Closing sections and source ledger for a skill carrying engineering practice
-- [Skill requirement reference](skill-requirement.md): Shape and content rules for the REQUIREMENT.md beside a skill
 - [Claude skill reference](skill.md): Skill structure and authoring rules for Claude Code
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
-- [Task decline reference](tasks-decline.md): Where a task decided against moves, the Declined line it carries, and what happens to its plan and board row
-- [Tasks reference](tasks.md): Folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/
-- [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
-- [Wiki reference](wiki.md): Folder split, frontmatter, naming convention, and sourcing for a wiki reference page
-- [Wireframe reference](wireframes.md): Shape and content rules for canon/wireframes/<surface>.md files

package/standards/publish.md

@@ -70,7 +70,7 @@ Qualifying it against `erclx/canon` fixes nothing, because a reader holding only
 
 Write `owner/repo#123` and `owner/repo@abc1234` for a citation of a different, resolvable repository, across every such surface. `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or on the line above.
 
-Choose the number over the sha where the citation names a decided change, since a pull request number resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape `canon/ARCHITECTURE.md` already uses. The choice holds for both spellings this section fixes, the bare form a remote auto-links and the qualified form a cross-repository citation carries.
+Choose the number over the sha where the citation names a decided change, since a pull request number resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape a context entry already uses. The choice holds for both spellings this section fixes, the bare form a remote auto-links and the qualified form a cross-repository citation carries.
 
 A commit message takes the bare form even though it is also read through the log, where nothing links. The remote is what the form is chosen for, since a reader in the log loses only a link that plain text never carried.
 

package/standards/rule.md

@@ -57,7 +57,7 @@ The cost is that a project-authored rule's leading digit stops naming its domain
 
 The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source, a rule set held back from targets and installed only where it was authored, needs its own division too. This repository is the one place all three sources exist at once, and it divides the third pair two ways at once rather than one: `canon/` and `internal/` separate a shipped rule from an internal one by location, the same way `project/` separates a project-authored one, and within each subdirectory the numbering still divides by source as well, one source taking the top of the band and the other the gaps between the tens.
 
-The numbering half stays because location alone does not carry to a reader who only sees the number, such as one comparing `claude/567-planning.md` against a citation written before the rules moved into `canon/`.
+The numbering half stays because location alone does not carry to a reader who only sees the number, such as one comparing `claude/566-output.md` against a citation written before the rules moved into `canon/`.
 
 The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it. Separating `canon/` from `internal/` by folder removes the filename-collision case specifically, since the two no longer install to the same directory, but the number still carries the source signal for a reader who has only the number in view.
 

package/standards/skill.md

@@ -149,7 +149,7 @@ allowed-tools: <tools required>
 ### Output and tuning
 
 - Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
-- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. A `review/` writer names its file `<kind>-<slug>.md` and writes it flat, and an `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared.
+- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. A `review/` writer names its file `<kind>-<slug>.md` and writes it flat, and an `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions, never turning a soft cap hard for aesthetic drift.

package/tooling/base/reference.md

@@ -45,7 +45,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 
 - All shell scripts live in `scripts/`. Do not place a `.sh` file outside it.
 - Dictionaries live in `.cspell/`, hooks in `.husky/`, seeded context docs in `canon/context/`.
-- The `canon/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md`, `canon/REQUIREMENTS.md`, and `canon/ARCHITECTURE.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `canon/context/`. Indexes stay opt-in.
+- The `canon/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md` and `canon/REQUIREMENTS.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `canon/context/`. Indexes stay opt-in.
 
 ## Hooks
 

package/tooling/claude/reference.md

@@ -10,11 +10,9 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 CLAUDE.md              ← seeded. Project context and rules, auto-loaded by Claude Code each session
 
 canon/
-├── REQUIREMENTS.md    ← seeded. Project goals, non-goals, MVP scope
-├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
+├── REQUIREMENTS.md    ← seeded. Project problem, goals, non-goals
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
-├── context/           ← seeded. Per-domain narrative. `index.md` is the discovery anchor.
-└── wireframes/        ← seeded. Per-surface regions and states. `index.md` is the discovery anchor; `<surface>.md` files hold the regions list, the states table, and the behavior bullets.
+└── context/           ← seeded. Per-domain narrative. `index.md` is the discovery anchor.
 
 .claude/
 ├── GOV.md             ← retired. Removed by `canon gov sync` if present from a prior install
@@ -24,9 +22,8 @@ canon/
 .canon/
 ├── tasks/             ← seeded. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
 ├── 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.
+├── review/            ← one subfolder per producer. `branch/` no longer written, `design/` for canon design render.
+└── tmp/               ← ephemeral scratch space, safe to delete without loss
 ```
 
 One ignore entry covers `.canon/` whole, so nothing under it is named separately and nothing tracked may ever land there. A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root.
@@ -35,7 +32,7 @@ One ignore entry covers `.canon/` whole, so nothing under it is named separately
 
 A project installed before the split still holds its records under `.claude/`. `canon migrate records` moves them and repoints every tracked file that cites one, reporting the plan until `--write` is passed.
 
-Run `canon tooling sync claude . --write` first. The verb refuses while the project does not ignore `.canon/`, because every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Until the move runs, this project's records sit at a root the shipped ignore set no longer names, so a `git add -A` in that window picks them up.
+Run `canon tooling sync claude . --write` first. The verb refuses while the project does not ignore `.canon/`, because every folder it relocates is ignored where it stands and landing one under a tracked root commits the task board and the plans. Until the move runs, this project's records sit at a root the shipped ignore set no longer names, so a `git add -A` in that window picks them up.
 
 The verb ships with the change that split the roots and is not in a published release yet, so an installed binary answers `unknown command` until one carries it. Run it out of a canon checkout in the meantime, as `bun src/cli.ts migrate records --root <project> --write`, and read the `ok` field out of `--json` rather than the exit code, which a shell wrapper around `canon` can flatten.
 
@@ -49,16 +46,6 @@ Convert by hand, once per project:
 2. Run `canon indexes regen --no-stage --root . .canon/tasks/<any-task>.md` to build the catalog.
 3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.canon/tasks/`.
 
-## Upgrading a hand-appended memory index
-
-A project installed before the memory folder gained a generated index still holds `.canon/memory/MEMORY.md`, and its entries still carry `name` and `type` frontmatter. Nothing migrates it. `memory-capture` stops appending rows once the new seed lands, so the old file freezes at whatever it held while the folder keeps growing past it.
-
-Convert by hand, once per project:
-
-1. Rewrite each entry's `name` key to `title` and its `type` key to a sentence-case `category`, quoting any `description` that opens with a backtick or a colon so the frontmatter parses.
-2. Replace `MEMORY.md` with an `index.md` carrying `title` and `subtitle` frontmatter and nothing else.
-3. Run `canon indexes regen --no-stage --root . .canon/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
-
 ## Gitignore
 
 - `# Claude`: `.canon/`, `.claude/worktrees/`, `.claude/.tmp/` <!-- canon-keep-record-root -->
@@ -76,8 +63,7 @@ The first entry covers the whole record root, so a record folder added later nee
 ## CLAUDE.md
 
 - Ships as a seed with placeholder project name, description, and key paths. Fill these in after init.
-- Section layout: `Context`, `Indexes`, `Markdown`, `Key paths`, `Spelling`, `Tasks`, `Memory`. Each section groups rules that share a surface so skills can detect, extend, or skip by heading.
-- The memory rules favor signal over volume. Saving only after a second occurrence or an explicit user correction keeps entries focused on patterns worth preventing, not first-occurrence slips. The 3-line cap stops the built-in auto-memory from drifting into narrative writeups that bury the rule underneath the recovery story.
+- Section layout: `Context`, `Commands`, `Key paths`. Each section groups rules that share a surface so skills can detect, extend, or skip by heading.
 - The `Context` section points at `.claude/` state docs one line. `plan-feature` does the parallel read when invoked. The seed intentionally does not re-list every file.
 
 ## Seed docs

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

@@ -53,5 +53,5 @@ marker="$marker_dir/$key"
 mkdir -p "$marker_dir"
 : >"$marker"
 
-msg=$(printf 'An index.md exists at %s. Read it before searching this folder, it catalogs the sibling files faster than a blind search. For a cross-folder answer, run canon indexes list --json or invoke the index-lookup skill.' "$index")
+msg=$(printf 'An index.md exists at %s. Read it before searching this folder, it catalogs the sibling files faster than a blind search. For a cross-folder answer, run canon indexes list --json.' "$index")
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

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

@@ -1,12 +1,12 @@
 #!/usr/bin/env bash
 
-# Regenerates the index.md of a gitignored record folder, `tasks` or `memory`,
-# after a file in it changes.
+# Regenerates the index.md of the gitignored `tasks` record folder after a
+# file in it changes.
 #
-# 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
+# That folder is gitignored, so the whole-repo walk in `bun run check` drops
+# it and never regenerates its 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 either folder.
+# 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`
@@ -31,11 +31,9 @@ file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
 # said. The index then goes stale while every save reports success.
 #
 # 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 index does not render: an archived or declined task, or the index itself.
+# Those exit here, before the regen call. A task under `review/` is
+# indexed, and no other folder is read.
 #
 # 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
@@ -45,8 +43,6 @@ file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
 case "$file_path" in
 */.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
@@ -55,14 +51,6 @@ case "$file_path" in
   folder=tasks
   base=.claude
   ;;
-*/.canon/memory/*.md)
-  folder=memory
-  base=.canon
-  ;;
-*/.claude/memory/*.md)
-  folder=memory
-  base=.claude
-  ;;
 *) exit 0 ;;
 esac
 root="${file_path%/"$base/$folder"/*}"

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

@@ -18,12 +18,12 @@ case "$file" in
 *) exit 0 ;;
 esac
 
-# Four record folders, at either root. A skip list fixed at the old spelling
+# Three record folders, at either root. A skip list fixed at the old spelling
 # audits a project's own session records the moment the move reaches it, which
 # reports findings against prose nobody publishes.
 case "$file" in
-*.claude/.tmp/* | *.claude/memory/* | *.claude/review/* | *.claude/plans/*) exit 0 ;;
-*.canon/tmp/* | *.canon/memory/* | *.canon/review/* | *.canon/plans/*) exit 0 ;;
+*.claude/.tmp/* | *.claude/review/* | *.claude/plans/*) exit 0 ;;
+*.canon/tmp/* | *.canon/review/* | *.canon/plans/*) exit 0 ;;
 esac
 
 [ -f "$file" ] || exit 0

package/tooling/claude/seeds/CLAUDE.md

@@ -4,12 +4,10 @@
 
 ## Context
 
-- Before non-trivial work in a domain read `canon/context/<domain>.md`, and before touching a UI surface read `canon/wireframes/<surface>.md`. Pick which from the index anchors below.
+- Before non-trivial work in a domain read `canon/context/<domain>.md`. Pick which from the index anchor below.
 
 @canon/REQUIREMENTS.md
-@canon/ARCHITECTURE.md
 @canon/context/index.md
-@canon/wireframes/index.md
 
 ## Commands
 

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

@@ -1,18 +1,11 @@
 # Requirements
 
+[One line: the problem and who has it]
+
 Authoring guidance: the requirements standard.
 
 This record holds at most 600 words.
 
-## Problem
-
 ## Goals
 
 ## Non-goals
-
-## MVP features
-
-1. Feature: description
-2. Feature: description
-
-## Constraints

package/tooling/web/configs/e2e/screenshot.ts

@@ -58,7 +58,6 @@ const HOME_SECTIONS: CaptureSection[] = [
   { name: 'dispatch', selector: '#dispatch' },
   { name: 'workers', selector: '#workers' },
   { name: 'gate', selector: '#gate' },
-  { name: 'memory', selector: '#memory' },
   { name: 'evidence', selector: '#evidence' },
   { name: 'loop', selector: '#loop' },
   { name: 'merge', selector: '#merge' },

package/claude/skills/auto-ship/references/review-findings.md

@@ -1,20 +0,0 @@
----
-title: Review findings
-description: How auto-ship Step 7 splits the review receipt's findings by origin, which ones it repairs in place and which stop the chain, and the one-pass bound on the repair
----
-
-# Evaluate the review findings
-
-Step 7 of `auto-ship`. The session reads this file when Step 6 ran review rather than skipping it.
-
-Read `.canon/review/branch-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited.
-
-- **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop or offer the fix as a choice.
-- **It predates this run, critical or should-fix.** Stop: `❌ Review found non-minor issues that predate this run. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
-- **It predates this run, minor only.** Continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
-
-Read origin as causation rather than authorship, so staleness this run induced in a file it never opened is a finding it caused.
-
-Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `❌ A self-introduced finding survived one fix pass. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
-
-This chain owns the receipt's lifetime. The `context-fold` sweep under Step 8 reaches only reports whose branch is gone, so it collects this one a branch later.

package/claude/skills/bash-cli-script/REQUIREMENT.md

@@ -1,43 +0,0 @@
----
-name: bash-cli-script
-description: What a small non-interactive shell wrapper owes its caller, and the 100-line threshold past which the work belongs in TypeScript on Bun
----
-
-# Bash CLI script requirement
-
-## Gap
-
-Without this skill, a wrapper is written with an interactive tool's habits. Progress lines, icons, and color land on stdout, so the script stops composing in a pipe and the caller parses a spinner as data. The failure is invisible in a terminal and total in CI.
-
-The robustness failures are the ones that reach production. Without strict mode a failed stage inside a pipe exits zero and the script reports success on work that did not happen. An unset variable expands to nothing and a path built from it points somewhere nobody meant.
-
-The size failure is the slow one. A shell script that keeps growing past a wrapper's job turns into the long file nobody will touch, and the [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) puts the line at 100: past it, the script is rewritten in a more structured language. Without a stop before generating, a session writes the long script first and the rewrite never happens.
-
-## Must
-
-- Stop before generating when the script will run past 100 lines, and route the work to TypeScript on Bun citing the style guide
-- Stop the same way on a request for prompts or a terminal UI, saying why
-- Open with the strict-mode preamble, so a failed stage stops the script
-- Keep data on stdout and put every log line, progress message, and error on stderr
-- Exit non-zero with actionable context through one error helper
-- Default every variable expansion rather than relying on it being set
-- Guard a command that returns non-zero on a valid empty result
-- Run the validation list before responding
-
-## Must not
-
-- Emit timeline frames, icons, color, or an interactive prompt
-- Put a log or progress line on stdout
-- Comment what the code already states
-- Rewrite an existing long shell file on contact, which is a rewrite decision rather than an edit
-
-## Guards
-
-- A script that will run past 100 lines stops before any of it is written, and the session writes it in TypeScript on Bun instead.
-- A request for prompts, a framed timeline, icons, or color stops with the same route.
-
-## Out of scope
-
-- A tool a person drives through prompts or a terminal UI, which is written in TypeScript on Bun
-- A GitHub Actions workflow file, which `ci-workflow` owns
-- Running, installing, or scheduling what it generates

package/claude/skills/bash-cli-script/SKILL.md

@@ -1,53 +0,0 @@
----
-name: bash-cli-script
-description: Generates a small non-interactive Bash wrapper for automation, CI, and agent-run tasks, with strict mode, logs on stderr, a clean stdout, and explicit exit codes. Stops at 100 lines and routes the work to TypeScript on Bun. Use when asked for "a shell script", "a wrapper script", an automation or CI script, a cron job, or a pipeline helper. Do NOT use for a tool that prompts a person or draws a terminal UI, or for a script that will run past 100 lines. Both are written in TypeScript on Bun.
-metadata:
-  family: generate
----
-
-# Bash CLI script
-
-Generate small non-interactive Bash wrappers for automation, CI, and agent-run workflows. Shell is for small utilities and simple wrappers, and anything larger is written in TypeScript on Bun, which runs a script about as fast as bash starts one.
-
-Load `${CLAUDE_SKILL_DIR}/references/template.md` for the base skeleton. Copy it and keep only what the task needs.
-
-## Guards
-
-- Estimate the script's length before writing any of it. When it will run past 100 lines, stop and write it in TypeScript on Bun instead, saying the threshold is the one the [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) sets: "If you are writing a script that is more than 100 lines long ... you should rewrite it in a more structured language now". Stopping after generating wastes the draft and leaves a long script to argue against.
-- A request for interactive prompts, a framed timeline, icons, or color stops the same way. Say that a tool a person drives is past what a wrapper is for, and offer the TypeScript route rather than generating a script with prompts.
-- Editing an existing shell file already over 100 lines is not a new script. Edit it in place without growing it, and flag it for a rewrite rather than rewriting it on contact.
-
-## Script setup
-
-- Start with `#!/usr/bin/env bash` and `set -euo pipefail`.
-- Do not rely on unset variables. Use `${VAR:-default}`.
-
-## Output contract
-
-- Write data to stdout. Write logs, progress, and errors to stderr.
-- Keep stdout clean so the script composes in a pipe.
-- Do not emit timeline frames, icons, or color.
-
-## Error handling
-
-- Define `die()` that prints an error to stderr and exits non-zero.
-- Include actionable context in error messages.
-- Guard commands that return non-zero on a valid empty result with `|| true`.
-- Set explicit exit codes. Reserve 0 for success.
-- Read a called command's machine-readable record where it emits one. An exit status separates success from failure and never names which failure, so a script routing on the reason reads the record and keeps the exit for the pass-fail decision alone.
-
-## Code style
-
-- Quote variables in expansions and test brackets.
-- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
-- Use 2-space indentation.
-
-## Validation
-
-Before responding, verify:
-
-- The script is 100 lines or fewer.
-- File starts with `#!/usr/bin/env bash` and `set -euo pipefail`.
-- Data goes to stdout, logs and errors go to stderr.
-- No timeline frames, icons, or interactive prompts.
-- Errors exit non-zero with context through `die()`.