@erclx/canon 4.6.1 → 4.8.0

package/tooling/claude/reference.md

@@ -9,49 +9,62 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 ```plaintext
 .claude/
 ├── CLAUDE.md          ← seeded. Project context and rules, auto-loaded by Claude Code each session
-├── tasks/             ← seeded then gitignored. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
 ├── REQUIREMENTS.md    ← seeded. Project goals, non-goals, MVP scope
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
-├── 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.
 ├── GOV.md             ← retired. Removed by `canon gov sync` if present from a prior install
 ├── settings.json      ← seeded. Project-level Claude Code config (PreToolUse and PostToolUse hooks). User-level config installed separately via `canon claude setup`.
-├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs into `archive/`.
-├── review/            ← gitignored, one subfolder per producer. `branch/` for claude-review, `feedback/` for canon feedback, `memory/` for claude-memory-review with its own `archive/`, `design/` for canon design render.
-├── .tmp/              ← ephemeral scratch space, gitignored
-└── memory/            ← session facts no context entry owns, gitignored. `index.md` regenerated by a hook.
+└── worktrees/         ← gitignored. Where EnterWorktree creates a linked worktree, which is why it did not move.
+
+.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 claude-docs into `archive/`.
+├── review/            ← one subfolder per producer. `branch/` for claude-review, `feedback/` for canon feedback, `memory/` for claude-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.
 ```
 
+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.
+
+## Moving the records to `.canon/`
+
+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.
+
+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.
+
 ## Upgrading from a single-file board
 
-A project installed before the board became a folder still holds `.claude/TASKS.md`. Nothing migrates it. `canon claude init` seeds an empty `.claude/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.
+A project installed before the board became a folder still holds `.claude/TASKS.md`. Nothing migrates it. `canon claude init` seeds an empty `.canon/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.
 
 Convert by hand, once per project:
 
-1. Split each `###` block into `.claude/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the tasks standard requires, which `canon standards tasks` prints. Compare each new file against the block it came from rather than checking that every block landed somewhere.
-2. Run `canon indexes regen --no-stage --root . .claude/tasks/<any-task>.md` to build the catalog.
-3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.claude/tasks/`.
+1. Split each `###` block into `.canon/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the tasks standard requires, which `canon standards tasks` prints. Compare each new file against the block it came from rather than checking that every block landed somewhere.
+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 `.claude/memory/MEMORY.md`, and its entries still carry `name` and `type` frontmatter. Nothing migrates it. `claude-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.
+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. `claude-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 . .claude/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
+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.
 
 ## Upgrading from a single-file diagram set
 
-A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.claude/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
+A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.canon/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
 
 ## Gitignore
 
-- `# Claude`: `.claude/.records.git/`, `.claude/.tmp/`, `.claude/groundwork/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`, `.claude/teach/`
+- `# Claude`: `.canon/`, `.claude/worktrees/`
 
-Each entry is a top-level record folder, and an archive sits inside the folder it archives, so one line covers a record and everything it retires.
+The first entry covers the whole record root, so a record folder added later needs no line here and no sync. The second is the carve-out, since the harness creates a worktree under `.claude/` and requires its target to sit there.
 
 ## CLI
 

package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh

@@ -27,19 +27,19 @@ case "$file_path" in
 esac
 
 # A project whose own root sits under a path carrying a tmp segment is not
-# writing to system temp, and the bare pattern below trips the guard on every
-# source file it holds. Anchor on the project root before the pattern match.
-#
-# This gives up one case on purpose: a write to <project>/tmp/ is a genuine
-# scratch violation that no longer warns. The false positive fires on every
-# source write in an affected project, so the trade favors the anchor.
+# writing to system temp, and the bare pattern below would trip on every source
+# file it holds. The project root is stripped before the match rather than
+# exiting on it, so the segments the patterns look for are the ones the write
+# adds. Exiting on any path under the project gives up <project>/tmp/ as well,
+# which is a genuine violation this still warns on.
+matched=$file_path
 if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
   case "$file_path" in
-  "$CLAUDE_PROJECT_DIR"/*) exit 0 ;;
+  "$CLAUDE_PROJECT_DIR"/*) matched=${file_path#"$CLAUDE_PROJECT_DIR"} ;;
   esac
 fi
 
-case "$file_path" in
+case "$matched" in
 */tmp/* | *\\tmp\\* | */Temp/* | *\\Temp\\* | */var/folders/*) ;;
 *) exit 0 ;;
 esac