@erclx/canon 4.126.0 → 5.1.0

package/src/tasks/archive.ts

@@ -47,6 +47,7 @@ export const ARCHIVE_REFUSALS = [
   'no-outcomes',
   'open-outcomes',
   'earlier-slice',
+  'pending-branch',
   'bad-input',
 ] as const
 
@@ -251,6 +252,22 @@ export function readPullRequest(text: string): readonly number[] {
   return match[1].split(',').map((entry) => Number(entry.trim().slice(1)))
 }
 
+/**
+ * Reads the `Pending branch:` line `canon tasks outcome` writes when a branch
+ * ticks an outcome ahead of its own pull request number reaching the task.
+ * `canon tasks pull-request` clears each branch as it records, so a name left
+ * here is a slice whose number the `Pull request:` line cannot list yet.
+ */
+export function readPendingBranches(text: string): readonly string[] {
+  const match = /^Pending branch:(.*)$/m.exec(text)
+  if (!match) return []
+
+  return match[1]
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+}
+
 /** A markdown link on a `Plan:` line, its target captured. */
 const PLAN_LINK_PATTERN = /\[[^\]]*\]\(([^)]+)\)/g
 
@@ -860,6 +877,19 @@ export async function archiveTask(
     )
   }
 
+  // A branch ticks its outcome before `git-pr` appends its number, so in that
+  // window the number above reads as last while it is not. The stem selector
+  // skips this check the way it skips the one above, since a hand archive is
+  // the route out of a pending branch that was abandoned.
+  const pending = readPendingBranches(text)
+  if (selector.kind === 'pull-request' && pending.length > 0) {
+    return refuse(
+      'pending-branch',
+      `${stem} still waits on ${pending.join(', ')}, which closed an outcome before its own pull request was recorded, so the task closes when that pull request merges.`,
+      pending,
+    )
+  }
+
   const { open, closed, cut } = readOutcomes(text)
 
   if (open.length > 0) {

package/src/tasks/record.ts

@@ -10,6 +10,7 @@ import {
   OUTCOME_PATTERN,
   planLine,
   planLineIndex,
+  readPendingBranches,
   readPlanTargets,
   readPullRequest,
   tasksDir,
@@ -63,6 +64,8 @@ export interface PullRequestRecorded {
   readonly path: string
   readonly number: number
   readonly action: LineAction
+  /** Branches still on the `Pending branch:` line after this write. */
+  readonly pending: readonly string[]
 }
 
 export type PullRequestOutcome = PullRequestRecorded | RecordRefused
@@ -85,6 +88,8 @@ export interface OutcomesClosed {
   readonly path: string
   readonly closed: readonly string[]
   readonly alreadyClosed: readonly string[]
+  /** Branches on the `Pending branch:` line after this write. */
+  readonly pending: readonly string[]
 }
 
 export type CloseOutcome = OutcomesClosed | RecordRefused
@@ -146,16 +151,77 @@ export function writePullRequestLine(
   return { text: lines.join('\n'), action: 'added' }
 }
 
-function lastOriginLine(lines: readonly string[]): number | undefined {
+function lastOriginLine(
+  lines: readonly string[],
+  prefixes: readonly string[] = ORIGIN_PREFIXES,
+): number | undefined {
   let found: number | undefined
 
   for (const [index, line] of lines.entries()) {
-    if (ORIGIN_PREFIXES.some((prefix) => line.startsWith(prefix))) found = index
+    if (prefixes.some((prefix) => line.startsWith(prefix))) found = index
   }
 
   return found
 }
 
+const PENDING_PREFIX = 'Pending branch:'
+
+/**
+ * Names a branch on the `Pending branch:` line, which holds the task open
+ * against a merge-time archive until that branch's own number is recorded. The
+ * line sits under `Pull request:` when one exists, since a later slice ticks
+ * after an earlier slice's number is already listed.
+ */
+export function writePendingBranch(
+  text: string,
+  branch: string,
+): { readonly text: string; readonly changed: boolean } {
+  const lines = text.split('\n')
+  const existing = lines.findIndex((entry) => entry.startsWith(PENDING_PREFIX))
+
+  if (existing !== -1) {
+    const pending = readPendingBranches(lines[existing])
+    if (pending.includes(branch)) return { text, changed: false }
+    lines[existing] = `${PENDING_PREFIX} ${[...pending, branch].join(', ')}`
+    return { text: lines.join('\n'), changed: true }
+  }
+
+  const line = `${PENDING_PREFIX} ${branch}`
+  const anchor = lastOriginLine(lines, [...ORIGIN_PREFIXES, 'Pull request:'])
+  if (anchor !== undefined) {
+    lines.splice(anchor + 1, 0, line)
+    return { text: lines.join('\n'), changed: true }
+  }
+
+  const heading = lines.findIndex((entry) => entry.startsWith('# '))
+  if (heading === -1) return { text: `${line}\n${text}`, changed: true }
+
+  lines.splice(heading + 1, 0, '', line)
+  return { text: lines.join('\n'), changed: true }
+}
+
+/** Drops a branch from the `Pending branch:` line, and the line once it is empty. */
+export function clearPendingBranch(
+  text: string,
+  branch: string,
+): { readonly text: string; readonly changed: boolean } {
+  const lines = text.split('\n')
+  const existing = lines.findIndex((entry) => entry.startsWith(PENDING_PREFIX))
+  if (existing === -1) return { text, changed: false }
+
+  const pending = readPendingBranches(lines[existing])
+  if (!pending.includes(branch)) return { text, changed: false }
+
+  const rest = pending.filter((entry) => entry !== branch)
+  if (rest.length > 0) {
+    lines[existing] = `${PENDING_PREFIX} ${rest.join(', ')}`
+  } else {
+    lines.splice(existing, 1)
+  }
+
+  return { text: lines.join('\n'), changed: true }
+}
+
 export type PlanLineWrite =
   | {
       readonly ok: true
@@ -330,24 +396,43 @@ async function openTask(
  * this from a linked worktree, where an in-place edit through the file-editing
  * tools is refused and a shell stream editor is banned, so the write has to
  * resolve the board root in-process.
+ *
+ * `branches` names the recording branch and every name it carried before a
+ * rename, since `git-ship` renames a branch after `context-fold` has already
+ * written the marker under the old name. Each comes off the `Pending branch:`
+ * line even when the number was already listed, so a rerun repairs a stale
+ * marker.
  */
 export async function recordPullRequest(
   root: string,
   selector: RecordSelector,
   number: number,
+  branches: readonly string[] = [],
 ): Promise<PullRequestOutcome> {
   const opened = await openTask(root, selector)
   if ('ok' in opened) return opened
 
   const { stem, path } = opened
-  const { text, action } = writePullRequestLine(
-    await readFile(path, 'utf8'),
-    number,
-  )
+  const numbered = writePullRequestLine(await readFile(path, 'utf8'), number)
+  let text = numbered.text
+  let isCleared = false
+
+  for (const branch of branches) {
+    const cleared = clearPendingBranch(text, branch)
+    text = cleared.text
+    isCleared ||= cleared.changed
+  }
 
-  if (action !== 'unchanged') await writeFile(path, text)
+  if (numbered.action !== 'unchanged' || isCleared) await writeFile(path, text)
 
-  return { ok: true, stem, path, number, action }
+  return {
+    ok: true,
+    stem,
+    path,
+    number,
+    action: numbered.action,
+    pending: readPendingBranches(text),
+  }
 }
 
 /**
@@ -399,11 +484,17 @@ export async function recordPlan(
  * 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.
+ *
+ * A `branch` that ticks at least one new box goes on the `Pending branch:`
+ * line, so the merge of an earlier slice cannot archive the task in the window
+ * before this branch's own number is recorded. A rerun that ticks nothing adds
+ * no marker, since its branch has already recorded or is already listed.
  */
 export async function closeOutcomes(
   root: string,
   selector: RecordSelector,
   positions: readonly number[],
+  branch?: string,
 ): Promise<CloseOutcome> {
   const opened = await openTask(root, selector)
   if ('ok' in opened) return opened
@@ -427,7 +518,12 @@ export async function closeOutcomes(
     )
   }
 
-  if (result.closed.length > 0) await writeFile(path, result.text)
+  const text =
+    result.closed.length > 0 && branch
+      ? writePendingBranch(result.text, branch).text
+      : result.text
+
+  if (result.closed.length > 0) await writeFile(path, text)
 
   return {
     ok: true,
@@ -435,5 +531,6 @@ export async function closeOutcomes(
     path,
     closed: result.closed,
     alreadyClosed: result.alreadyClosed,
+    pending: readPendingBranches(text),
   }
 }

package/standards/commit.md

@@ -17,7 +17,7 @@ Does not govern:
 
 ## Format
 
-- Structure: `<type>(<scope>): <subject>`
+- Structure: `<type>(<scope>): <subject>`, with `!` before the colon for a breaking change
 - Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
 - Subject: 72 characters maximum, no trailing period
 

package/standards/context.md

@@ -111,6 +111,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
 - Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.
 - Split into a folder (`canon/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
+- Group whole single-file entries of two or more small domains into one folder when they share a kind, such as small feature domains that each own a verb. Each entry still covers one domain, and the folder's generated `index.md` carries a `subtitle` naming the kind. It names an entry to start with only when that entry frames the others. A grouping folder is not a split, so no entry inside it is a sub-area of another.
+- Name an entry inside a split or grouping folder per the `codebase-layout` skill, which never repeats the folder's name as the entry's stem or prefix.
 - Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
 - Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and turns a one-line edit into a whole-file rewrite that conflicts with any sibling branch. This is what forced the split above.
 

package/standards/docs.md

@@ -72,6 +72,7 @@ A page failing these is non-conforming even when it satisfies every shape rule b
 - Move every page carrying that value. A shelf split across two depths is harder to scan than either arrangement taken whole.
 - Give the subfolder a catalog page of its own, so the parent lists one entry where it listed several. The parent lists a subfolder as a folder rather than as a member of the shelf it replaced, so nothing on that page restores the grouping.
 - Retarget every link into a moved page in the same change. A link resolving nowhere is what the move costs, and nothing else reports it.
+- Name a moved page per the `codebase-layout` skill, which drops the prefix the subfolder now states.
 
 ## Template
 

package/standards/index.md

@@ -34,7 +34,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Skill requirement reference](skill-requirement.md): Shape and content rules for the REQUIREMENT.md beside a skill
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
-- [Snippet reference](snippets.md): Snippet reference and authoring conventions
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [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

package/standards/pr.md

@@ -20,7 +20,7 @@ Does not govern:
 
 ## Title
 
-- Format: `<type>(<scope>): <subject>`
+- Format: `<type>(<scope>): <subject>`, with `!` before the colon for a breaking change
 - Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
 - Length: 72 characters maximum
 

package/standards/skill.md

@@ -17,7 +17,6 @@ Does not govern:
 
 - What a `REQUIREMENT.md` must answer, its sections, and its template: `skill-requirement.md`
 - Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
-- Single-purpose chat prompts carrying no frontmatter, references, or scripts: `snippets.md`
 - Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
 - Punctuation, formatting, and word choice in a skill body: `markdown.md`
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
@@ -128,7 +127,7 @@ allowed-tools: <tools required>
 
 - Avoid flags that dispatch between alternate flows. The model misreads them and runs the vanilla path. Dry-run-style toggles are fine. For alternate flows, prefer a separate skill or manual invocation of two skills in sequence.
 - When a skill should fire from multiple callers, rely on description matching with strong trigger phrases. Do not hardcode `Skill` calls in sibling skills that could trigger it naturally.
-- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do. Where a pause carries external timing, error-surfacing, or judgment weight, prefer a snippet or explicit per-step confirmation.
+- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do. Where a pause carries external timing, error-surfacing, or judgment weight, prefer explicit per-step confirmation.
 
 ### Output and tuning
 

package/standards/tasks.md

@@ -72,7 +72,7 @@ Add no third heading. Status stays inline on an outcome rather than becoming an
 
 Size the outcomes so one pull request closes all of them, and split the task before handing it off rather than after. A task closes whole or not at all, so outcomes spanning two pull requests leave the board showing in-progress work no branch carries.
 
-A sliced task is the one allowed exception: a task the operator decided to ship across several pull requests on purpose, one slice each. Its `Pull request:` line lists every slice, so the board records which merged work covered which outcomes, and it closes whole when the last slice's merge finds every outcome ticked.
+A sliced task is the one allowed exception: a task the operator decided to ship across several pull requests on purpose, one slice each. Its `Pull request:` line lists every slice, so the board records which merged work covered which outcomes, and it closes whole when the last slice's merge finds every outcome ticked and no slice left pending.
 
 Prefix the H1 with the `vX.Y:` phase label, then a short title whose form depends on the task type:
 
@@ -134,7 +134,7 @@ One plan per task. A plan cited by two tasks is a misfile rather than a shape to
 
 `Pull request:` records which pull requests carry the task's work, each as a bare `#NNN` the way `Issue:` does. It lists every pull request that shipped part of the task, oldest first and separated by commas, as in `Pull request: #NNN, #NNN`, and a task shipped whole lists one. It is not an origin, so a task without one is well-formed. `git-pr` appends to it when a pull request opens.
 
-The line is what lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any number the line lists and archives it only on the last. One pull request, one task: two tasks naming the same number refuse to archive rather than both moving.
+The line is what lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any number the line lists and archives it only on the last. One pull request, one task: two tasks naming the same number refuse to archive rather than both moving. `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number, since `canon tasks outcome` writes it and `canon tasks pull-request` clears it.
 
 ## What goes in
 

package/standards/wiki.md

@@ -37,7 +37,8 @@ A page failing either is non-conforming even when it satisfies every shape rule
 
 ## Naming
 
-- Name a page with a `claude-` prefix before the kebab subject.
+- Name a page by its kebab subject alone. The vendor folder it sits in already names the vendor, so a prefix repeats the folder.
+- The `codebase-layout` skill carries the same rule for every folder in a project, beyond the wiki.
 
 ## Sourcing
 

package/tooling/base/reference.md

@@ -4,7 +4,7 @@
 
 The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and one maintenance script. Every other stack extends it, so a decision made here is one every stack inherits.
 
-A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs target-scenarios` carries the recipe.
+A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs scenarios` carries the recipe.
 
 ## What ships as golden configs
 
@@ -97,4 +97,4 @@ Sticky negative knowledge. Do not relearn.
 
 `bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatters could not fix. The pull request workflow calls `check:format`, `check:spell`, and `check:shell` directly, and those three are the gate.
 
-`scripts/verify.sh`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs target-projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.
+`scripts/verify.sh`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.

package/tooling/claude/reference.md

@@ -82,7 +82,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`, `Snippets`, `Tasks`, `Memory`. Each section groups rules that share a surface so skills can detect, extend, or skip by heading.
+- 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.
 - 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.
 

package/claude/skills/create-snippet/REQUIREMENT.md

@@ -1,39 +0,0 @@
----
-name: create-snippet
-description: Why a snippet needs its shape read from the reference and its write surface resolved before anything is drafted
----
-
-# Create snippet requirement
-
-## Gap
-
-Without this skill, a snippet is drafted the way any other markdown file is drafted, so it arrives carrying frontmatter, headings, and a fill-in placeholder. None of the invocation channels strip those. Typing `>slug` in a chat inserts the scaffolding verbatim, and the file that was meant to be one instruction reads as a document.
-
-The write surface is the second failure. The toolkit authors at `snippets/` and a target project may still hold a stale `.claude/snippets/` copy from before that domain's install channel retired, so a session picks whichever folder it noticed first. A toolkit snippet written into the consumed copy fails the drift assertion that regenerates that folder. A snippet written there in a target project is correct and looks identical, which is why the surface has to be resolved from what the project has rather than guessed.
-
-Inside the project surface, a third failure sits one level deeper. A project-authored snippet sharing a name with a toolkit one used to be indistinguishable from it, back when `canon snippets sync` walked that folder and could not tell which side owned the file. That verb retired with the domain's install channel, so nothing reads ownership by location there any more, but the `project/` subfolder still separates the two by eye, which is worth keeping even with no sync left to protect from.
-
-## Must
-
-- Read the bundled snippet reference before drafting, since the shape rules are what the invocation channels depend on
-- Resolve the write surface from which snippet folder the project has, rather than from whichever one the session noticed first
-- On the project surface, write under its `project/` subfolder, keeping a project-authored file visually apart from a toolkit-installed one
-- Confirm the slug and the full body with the user before writing
-- Emit the written path in full, so the terminal can resolve it
-- State what the resolved surface implies after writing, since a root file needs the consumed copy regenerated and a project-local one needs copying to the toolkit to ship
-
-## Must not
-
-- Restate the snippet authoring conventions in the body, which the bundled reference owns and which would drift from it
-- Write a standard, which answers to a different authoring contract
-
-## Guards
-
-- Neither snippet folder exists: stop, since there is nowhere for the snippet to live
-
-## Out of scope
-
-- Editing a snippet that already exists
-- A standard, which `create-standard` owns
-- Installing and syncing the snippets the toolkit ships, which the `canon snippets` commands own
-- What a snippet is and how it is invoked, which the bundled snippet reference states

package/claude/skills/create-snippet/SKILL.md

@@ -1,30 +0,0 @@
----
-name: create-snippet
-description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to "create a snippet", add a snippet, write a reusable prompt, or make a new snippet. Do NOT use to edit an existing snippet.
----
-
-# Create snippet
-
-Creates one snippet file. Read these files in parallel:
-
-- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: punctuation and formatting for all generated text
-- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
-- `${CLAUDE_SKILL_DIR}/../../standards/snippets.md`: authoring conventions, invocation channels, use patterns
-
-## Guards
-
-- If neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
-
-## Steps
-
-1. Resolve the write surface: `snippets/` at the root if present, which is the toolkit's own authoring source. Otherwise `.claude/snippets/`, a stale copy a target project holds from before its install channel retired.
-2. Draft the content from the user's description. The snippet reference governs structure, invocation, and authoring conventions.
-3. Confirm the slug and full content with the user before writing
-4. Write the file. On the root surface: `<surface>/<category>/<slug>.md`, or `<surface>/<slug>.md` when the snippet takes no category. On the `.claude/` surface: the same shape nested one level deeper under `project/`, a convention kept for its own sake now that nothing syncs that folder.
-
-## After writing
-
-Emit the full path on its own line.
-
-- Root surface: this is the toolkit's authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/`.
-- `.claude/` surface: the file is project-local, under `.claude/snippets/project/`. Remind the user to copy it to the toolkit repo, under `snippets/<category>/<name>.md`, if it should ship to every project.

package/scripts/snippets/create.sh

@@ -1,156 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-trap close_timeline EXIT
-
-SNIPPETS_SOURCE="$PROJECT_ROOT/snippets"
-
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} canon snippets create"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  Creates a new snippet: prompts for category and name, writes the file."
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}"
-  echo -e "${GREY}└${NC}"
-  exit 0
-}
-
-list_categories() {
-  echo "base (root, no prefix)"
-  find "$SNIPPETS_SOURCE" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort
-  echo "new category"
-}
-
-slug_error() {
-  local slug="$1"
-  local path="$2"
-  if [ -z "$slug" ]; then
-    echo "name cannot be empty"
-    return
-  fi
-  if [[ ! "$slug" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
-    echo "kebab-case only (e.g. my-snippet)"
-    return
-  fi
-  if [ -f "$path" ]; then
-    echo "file already exists: $path"
-    return
-  fi
-  echo ""
-}
-
-ask_new_category() {
-  while true; do
-    ask "Category name?" "CATEGORY_INPUT"
-    if [ -z "$CATEGORY_INPUT" ]; then
-      log_warn "Category name cannot be empty"
-      continue
-    fi
-    if [[ ! "$CATEGORY_INPUT" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
-      log_warn "Invalid category: kebab-case only (e.g. my-category)"
-      continue
-    fi
-    if [ -d "$SNIPPETS_SOURCE/$CATEGORY_INPUT" ]; then
-      log_warn "Category '$CATEGORY_INPUT' already exists"
-      continue
-    fi
-    CATEGORY_NAME="$CATEGORY_INPUT"
-    break
-  done
-}
-
-ask_name() {
-  local category="$1"
-  local is_base="$2"
-  local label
-  local error
-
-  label="Snippet name?"
-
-  while true; do
-    ask "$label" "NAME_INPUT"
-    local dest_path
-    if [ "$is_base" = "true" ]; then
-      dest_path="$SNIPPETS_SOURCE/$NAME_INPUT.md"
-    else
-      dest_path="$SNIPPETS_SOURCE/$category/$NAME_INPUT.md"
-    fi
-    error=$(slug_error "$NAME_INPUT" "$dest_path")
-    if [ -z "$error" ]; then
-      NAME="$NAME_INPUT"
-      break
-    fi
-    log_warn "Invalid name: $error"
-  done
-}
-
-cmd_create() {
-  local categories=()
-  mapfile -t categories < <(list_categories)
-
-  select_option "Category?" "${categories[@]}"
-  local selected="$SELECTED_OPTION"
-
-  local category
-  local is_base="false"
-
-  if [ "$selected" = "base (root, no prefix)" ]; then
-    is_base="true"
-    category="base"
-  elif [ "$selected" = "new category" ]; then
-    ask_new_category
-    category="$CATEGORY_NAME"
-  else
-    category="$selected"
-  fi
-
-  ask_name "$category" "$is_base"
-  local name="$NAME"
-
-  local dest_path
-  local install_path
-  if [ "$is_base" = "true" ]; then
-    dest_path="$SNIPPETS_SOURCE/$name.md"
-    install_path="snippets/$name"
-  else
-    dest_path="$SNIPPETS_SOURCE/$category/$name.md"
-    install_path="snippets/$category/$name"
-  fi
-
-  log_info "Installs as: @${install_path}"
-
-  log_step "Creating file"
-
-  if [ "$is_base" = "false" ]; then
-    mkdir -p "$SNIPPETS_SOURCE/$category"
-  fi
-
-  printf '<!-- TODO: write %s prompt -->\n' "$slug" >"$dest_path"
-
-  if [ "$is_base" = "true" ]; then
-    log_add "snippets/$name.md"
-  else
-    log_add "snippets/$category/$name.md"
-  fi
-}
-
-main() {
-  if [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
-    show_help
-  fi
-
-  cmd_create
-
-  trap - EXIT
-  echo -e "${GREY}└${NC}\n"
-  echo -e "${GREEN}✓ Snippet created${NC}"
-}
-
-main "$@"

package/snippets/align.md

@@ -1,12 +0,0 @@
-Check alignment before acting, not after. State three lines, then proceed.
-
-- Outcome: what will be true when this is done
-- Scope: what this deliberately does not touch
-- Assumption: the one inference that would change the work if it is wrong
-
-Act without waiting, unless being wrong about the assumption wastes the work rather than costing an edit.
-
-- Three lines, not three paragraphs
-- Name the inference you are least sure of, not the safest one
-- Do not ask what the request already answers
-- Silence is agreement

package/snippets/claude/decision-memo.md

@@ -1,39 +0,0 @@
-Produce a decision memo for a research or should-we question. This is the decision-heavy counterpart to `plan-feature`, which plans a build. Write one file per independent concern under `.canon/plans/feature-<slug>.md`, or answer inline when the plan is small. Use the same plans folder as `plan-feature`.
-
-Read the current state from the code and docs before recommending. Do not assume it.
-
-Output this shape per memo:
-
-```markdown
-# <slug title>
-
-<the question in one or two lines>
-
-## Summary
-
-- <goal in one line>
-- <deliverables in one line>
-- <key tradeoff in one line>
-
-## Finding
-
-<what the current state actually is, from reading the code and docs>
-
-## Item A: <decision>
-
-**Current state.** <what exists today>
-
-**Recommendation.** <the pick, with the tradeoff in one sentence>
-
-**Options.** <the real alternatives, only when the choice is the user's to make>
-
-**Feasibility.** <what is not buildable as asked and why, omit when all options are buildable>
-
-**Questions.**
-
-1. <question>
-   - Suggested: <best-practice default derived from context>
-   - Answer:
-```
-
-Repeat the `## Item` block per decision. Keep chat to the file pointer plus the questions. Recommend, do not enumerate, unless the user's preference is the deciding factor.