@erclx/canon 4.4.0 → 4.6.0

package/src/records/validate.ts

@@ -3,6 +3,10 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { linesOutsideFences } from '@/markdown/scan'
+import {
+  recordDir as resolveRecordDir,
+  recordDirs as resolveRecordDirs,
+} from '@/record-root'
 import {
   TEACH_GLOSSARY,
   TEACH_MISSION,
@@ -25,22 +29,22 @@ export const RECORD_KINDS = [
 export type RecordKind = (typeof RECORD_KINDS)[number]
 
 /**
- * The folders each kind reads, in precedence order.
+ * The folders standards reads, in precedence order.
  *
- * Standards carry two because the corpus authors at the project root and
- * installs under `.claude/`. The authoring root wins where both exist, since the
+ * It carries two because the corpus authors at the project root and installs
+ * under `.claude/`. The authoring root wins where both exist, since the
  * installed tree is a generated copy here and a finding fixed there is
  * overwritten by the next regen. A project that consumed the corpus holds only
  * the second, so one order serves both.
+ *
+ * Every other kind is a session record and takes the record roots instead,
+ * resolved by `@/record-root`. Standards is the one kind that is tracked, so it
+ * does not move and spells its own two candidates here.
  */
-const FOLDERS_BY_KIND: Readonly<Record<RecordKind, readonly string[]>> = {
-  plans: [join('.claude', 'plans')],
-  groundwork: [join('.claude', 'groundwork')],
-  intake: [join('.claude', 'intake')],
-  memory: [join('.claude', 'memory')],
-  standards: ['standards', join('.claude', 'standards')],
-  teach: [join('.claude', 'teach')],
-}
+const STANDARDS_FOLDERS: readonly string[] = [
+  'standards',
+  join('.claude', 'standards'),
+]
 
 /**
  * `unknown-kind` is raised at the argument boundary rather than by the walk, and
@@ -107,17 +111,31 @@ export type ValidateOutcome = ValidateReport | ValidateRefused
 
 /** Every folder a kind would accept, whether or not it is on disk. */
 export function recordDirs(root: string, kind: RecordKind): string[] {
-  return FOLDERS_BY_KIND[kind].map((folder) => join(root, folder))
+  if (kind === 'standards') {
+    return STANDARDS_FOLDERS.map((folder) => join(root, folder))
+  }
+
+  return resolveRecordDirs(root, kind)
 }
 
 /**
- * The folder a kind reads. The first candidate on disk wins, and the first
- * candidate stands in when none exists, so a refusal and a test fixture both
- * name the location the kind prefers.
+ * The folder a kind reads. The first candidate on disk wins, and the creation
+ * default stands in when none exists, so a refusal and a test fixture both name
+ * the location the kind would be written to.
+ *
+ * The default is where this parts company with `dirs[0]`, which the record
+ * kinds can no longer take: their first candidate is the root the move lands at
+ * and nothing creates there yet, so a fallback reading it would name a folder no
+ * verb would ever write. Standards has no such split, since it is tracked and
+ * its first candidate is where it is authored.
  */
 export function recordsDir(root: string, kind: RecordKind): string {
-  const dirs = recordDirs(root, kind)
-  return dirs.find((dir) => existsSync(dir)) ?? dirs[0]
+  if (kind === 'standards') {
+    const dirs = recordDirs(root, kind)
+    return dirs.find((dir) => existsSync(dir)) ?? dirs[0]
+  }
+
+  return resolveRecordDir(root, kind)
 }
 
 export function isRecordKind(value: string): value is RecordKind {

package/src/tasks/answers.ts

@@ -1,12 +1,13 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { isAbsolute, join, relative, resolve } from 'node:path'
+import { isAbsolute, relative, resolve } from 'node:path'
 import { isUnder } from '@/paths'
+import { recordDir, recordDirs } from '@/record-root'
 import { readQuestions, splitPlanSections } from '@/records/validate'
 
-const PLANS_DIR = join('.claude', 'plans')
-const PLANS_ARCHIVE_DIR = join(PLANS_DIR, 'archive')
-const TASKS_DIR = join('.claude', 'tasks')
+const PLANS = 'plans'
+const TASKS = 'tasks'
+const ARCHIVE = 'archive'
 
 /**
  * The suggestion the plan standard fixes for a question that turns on the
@@ -74,14 +75,17 @@ export function planCandidates(root: string, reference: string): string[] {
   if (reference.includes('/') || reference.endsWith('.md')) {
     if (isAbsolute(reference)) return [reference]
 
-    return [resolve(root, reference), resolve(join(root, TASKS_DIR), reference)]
+    return [
+      resolve(root, reference),
+      resolve(recordDir(root, TASKS), reference),
+    ]
   }
 
   const slug = reference.startsWith('feature-')
     ? reference.slice('feature-'.length)
     : reference
 
-  return [join(root, PLANS_DIR, `feature-${slug}.md`)]
+  return [recordDir(root, PLANS, `feature-${slug}.md`)]
 }
 
 function suggestionOf(body: readonly string[]): string | undefined {
@@ -167,7 +171,10 @@ export async function planAnswers(
   // An archived plan answers every question and would report as launchable, so
   // the name would clear a dispatch that `claude-autoship` Step 1 then refuses
   // as already-shipped work. Catching it here is a step earlier than the worker.
-  if (isUnder(path, join(root, PLANS_ARCHIVE_DIR))) {
+  // Both roots, for the reason `resolveLivePlan` carries: the reference is a
+  // string a caller wrote, and one spelling the root this tree has since left is
+  // still a path into the archive.
+  if (recordDirs(root, PLANS, ARCHIVE).some((dir) => isUnder(path, dir))) {
     return refuse(
       'archived',
       `${relative(root, path)} sits in the plans archive, so it describes work that already shipped.`,

package/src/tasks/archive.ts

@@ -3,11 +3,11 @@ import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { join, relative, resolve } from 'node:path'
 import { regenOne } from '@/indexes/regen'
 import { isUnder } from '@/paths'
+import { recordDir, recordDirs } from '@/record-root'
 
-const TASKS_DIR = join('.claude', 'tasks')
-const ARCHIVE_DIR = join(TASKS_DIR, 'archive')
-const PLANS_DIR = join('.claude', 'plans')
-const PLANS_ARCHIVE_DIR = join(PLANS_DIR, 'archive')
+const TASKS = 'tasks'
+const PLANS = 'plans'
+const ARCHIVE = 'archive'
 
 /**
  * Siblings that sit on the board without being tasks: the generated index, the
@@ -77,11 +77,11 @@ export interface TaskOutcomes {
 }
 
 export function tasksDir(root: string): string {
-  return join(root, TASKS_DIR)
+  return recordDir(root, TASKS)
 }
 
 export function archiveDir(root: string): string {
-  return join(root, ARCHIVE_DIR)
+  return recordDir(root, TASKS, ARCHIVE)
 }
 
 export const OUTCOME_PATTERN = /^- \[([ xX])\] ?(.*)$/
@@ -201,15 +201,20 @@ export function resolveLivePlan(
   dir: string,
   root: string,
 ): string | undefined {
-  const plans = join(root, PLANS_DIR)
-  const archive = join(root, PLANS_ARCHIVE_DIR)
+  // Both roots are tested rather than the one this tree resolves at, since a
+  // task's line is a string somebody wrote and a path spelling the root the tree
+  // has since left is still a path into the plans folder. Reading it as outside
+  // would report a shipped plan as still live.
+  const plans = recordDirs(root, PLANS)
+  const archives = recordDirs(root, PLANS, ARCHIVE)
+  const live = (path: string): boolean =>
+    plans.some((dir) => isUnder(path, dir)) &&
+    !archives.some((dir) => isUnder(path, dir))
   const fromBoard = resolve(dir, target)
   const fromRoot = resolve(root, target)
 
-  if (isUnder(fromBoard, plans) && !isUnder(fromBoard, archive)) {
-    return fromBoard
-  }
-  if (isUnder(fromRoot, plans) && !isUnder(fromRoot, archive)) return fromRoot
+  if (live(fromBoard)) return fromBoard
+  if (live(fromRoot)) return fromRoot
   return undefined
 }
 
@@ -308,7 +313,12 @@ export async function planCitations(
 
   const live = resolveLivePlan(target, dir, root)
   if (!live) {
-    const location = resolvesUnder(target, dir, root, PLANS_ARCHIVE_DIR)
+    const location = resolvesUnder(
+      target,
+      dir,
+      root,
+      recordDirs(root, PLANS, ARCHIVE),
+    )
       ? 'archived'
       : 'outside'
     return { ok: true, stem, target, location, citedBy: [] }
@@ -324,21 +334,21 @@ export async function planCitations(
 }
 
 /**
- * Runs the two-spelling resolution `resolveLivePlan` applies against a folder
- * other than the live one, so an archived plan is read as archived whichever
- * root the task wrote its path against.
+ * Runs the two-base resolution `resolveLivePlan` applies against folders other
+ * than the live ones, so an archived plan is read as archived whichever base the
+ * task wrote its path against and whichever record root it spelled.
  */
 function resolvesUnder(
   target: string,
   dir: string,
   root: string,
-  folder: string,
+  dirs: readonly string[],
 ): boolean {
-  const resolved = join(root, folder)
+  const fromBoard = resolve(dir, target)
+  const fromRoot = resolve(root, target)
 
-  return (
-    isUnder(resolve(dir, target), resolved) ||
-    isUnder(resolve(root, target), resolved)
+  return dirs.some(
+    (resolved) => isUnder(fromBoard, resolved) || isUnder(fromRoot, resolved),
   )
 }
 

package/src/teach/workspace.ts

@@ -3,6 +3,7 @@ import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { type BodyLine, bodyLines } from '@/markdown/scan'
+import { recordDir } from '@/record-root'
 
 export const TEACH_REFUSALS = [
   'no-teach',
@@ -173,7 +174,7 @@ export function refuse(
  * this takes one and never reads the working directory.
  */
 export function teachDir(root: string): string {
-  return join(root, '.claude', 'teach')
+  return recordDir(root, 'teach')
 }
 
 async function listSlugs(dir: string): Promise<string[]> {

package/tooling/claude/manifest.toml

@@ -11,4 +11,4 @@ scaffold = ""
 # scripts/core/check-ignore-parity.sh, which also holds the two `.claude/` paths
 # this array deliberately omits and the reason each stays out.
 [gitignore]
-"# Claude" = [".claude/.records.git/", ".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/proposals/", ".claude/review/", ".claude/worktrees/", ".claude/tasks/", ".claude/teach/"]
+"# Claude" = [".canon/", ".claude/.records.git/", ".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/proposals/", ".claude/review/", ".claude/worktrees/", ".claude/tasks/", ".claude/teach/"]

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

@@ -40,7 +40,14 @@ done
 
 session=$(printf '%s' "$input" | jq -r '.session_id // "none"')
 key=$(printf '%s__%s' "$session" "$index" | tr -c 'A-Za-z0-9' '_')
-marker_dir="${CLAUDE_PROJECT_DIR:-.}/.claude/.tmp/index-reminder"
+# The marker is scratch, so it follows the scratch folder to whichever record
+# root the project carries rather than creating a second one beside it.
+project="${CLAUDE_PROJECT_DIR:-.}"
+if [ -d "$project/.canon" ]; then
+  marker_dir="$project/.canon/tmp/index-reminder"
+else
+  marker_dir="$project/.claude/.tmp/index-reminder"
+fi
 marker="$marker_dir/$key"
 [ -f "$marker" ] && exit 0
 mkdir -p "$marker_dir"

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

@@ -25,31 +25,48 @@ esac
 file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
 [ -n "$file_path" ] || exit 0
 
+# Both record roots, since a project the move has reached keeps its memory pen
+# under `.canon/` and a guard fixed at the old spelling stops matching with
+# nothing said. The index then goes stale while every save reports success.
 case "$file_path" in
-*/.claude/memory/*.md) ;;
+*/.claude/memory/*.md | */.canon/memory/*.md) ;;
 *) exit 0 ;;
 esac
 
 case "$file_path" in
-*/.claude/memory/index.md) exit 0 ;;
+*/.claude/memory/index.md | */.canon/memory/index.md) exit 0 ;;
 esac
 
+# The walk-up boundary has to come from the path, not from the session. Shared
+# scratch resolves at the main worktree root, so a session inside a linked
+# worktree passes a path that sits outside its own project directory and the
+# default boundary would reject it.
+#
+# The index this would have rebuilt is read out of the same branch, so both
+# messages below name the file that actually went stale rather than one root's
+# spelling of it.
+case "$file_path" in
+*/.canon/memory/*)
+  root="${file_path%/.canon/memory/*}"
+  index=".canon/memory/index.md"
+  ;;
+*)
+  root="${file_path%/.claude/memory/*}"
+  index=".claude/memory/index.md"
+  ;;
+esac
+[ -n "$root" ] || exit 0
+
 # Report a missing CLI rather than exiting quietly. The path guard above already
 # scopes this to a memory-file edit, so the message only fires where the stale
 # index it warns about is the actual outcome.
 if ! command -v canon >/dev/null 2>&1; then
-  jq -nc --arg msg 'canon is not on PATH, so .claude/memory/index.md was not regenerated and is now stale. Install the toolkit CLI or run canon indexes regen by hand.' \
+  msg="canon is not on PATH, so $index was not regenerated and is now stale. Install the toolkit CLI or run canon indexes regen by hand."
+  jq -nc --arg msg "$msg" \
     '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
   exit 0
 fi
 
-# The walk-up boundary has to come from the path, not from the session. Shared
-# scratch resolves at the main worktree root, so a session inside a linked
-# worktree passes a path that sits outside its own project directory and the
-# default boundary would reject it.
-root="${file_path%/.claude/memory/*}"
-[ -n "$root" ] || exit 0
-
 # `--no-stage` because a hook has no business touching the index. On a project
 # whose memory folder is not gitignored, the default auto-stage would silently
 # add memory files to whatever commit is being assembled.
@@ -62,7 +79,7 @@ output=$(canon indexes regen --no-stage --root "$root" "$file_path" 2>&1) && exi
 errors=$(printf '%s\n' "$output" | grep '^ERROR: ' | head -5)
 [ -n "$errors" ] || errors="$output"
 
-msg="Memory index regen failed, so .claude/memory/index.md is now stale. Fix the frontmatter and save again. $errors"
+msg="Memory index regen failed, so $index is now stale. Fix the frontmatter and save again. $errors"
 jq -nc --arg msg "$msg" \
   '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
 exit 0

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

@@ -18,8 +18,12 @@ esac
 file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
 [ -n "$file_path" ] || exit 0
 
+# Both record roots, and the scratch folder loses its leading dot under the new
+# one, since inside a dotted root the dot hides nothing already hidden. A guard
+# fixed at the old spelling warns on every correct scratch write in a project
+# the move has reached.
 case "$file_path" in
-*/.claude/.tmp/*) exit 0 ;;
+*/.claude/.tmp/* | */.canon/tmp/*) exit 0 ;;
 esac
 
 # A project whose own root sits under a path carrying a tmp segment is not
@@ -42,11 +46,16 @@ esac
 
 session=$(printf '%s' "$input" | jq -r '.session_id // "none"')
 key=$(printf '%s' "$session" | tr -c 'A-Za-z0-9' '_')
-marker_dir="${CLAUDE_PROJECT_DIR:-.}/.claude/.tmp/scratch-guard"
+project="${CLAUDE_PROJECT_DIR:-.}"
+if [ -d "$project/.canon" ]; then
+  marker_dir="$project/.canon/tmp/scratch-guard"
+else
+  marker_dir="$project/.claude/.tmp/scratch-guard"
+fi
 marker="$marker_dir/$key"
 [ -f "$marker" ] && exit 0
 mkdir -p "$marker_dir"
 : >"$marker"
 
-msg='Temporary file write outside .claude/.tmp/. Write temp files to .claude/.tmp/<slug>/ in the project root, not system temp. See the Scratch rule in CLAUDE.md.'
+msg='Temporary file write outside the project scratch folder. Write temp files to .claude/.tmp/<slug>/ in the project root, or .canon/tmp/<slug>/ where the project carries that root, not system temp. See the Scratch rule in CLAUDE.md.'
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

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

@@ -18,8 +18,12 @@ case "$file" in
 *) exit 0 ;;
 esac
 
+# Four 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 ;;
 esac
 
 [ -f "$file" ] || exit 0

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

@@ -25,8 +25,11 @@ esac
 file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
 [ -n "$file_path" ] || exit 0
 
+# Both record roots, since a project the move has reached keeps its board under
+# `.canon/` and a guard fixed at the old spelling stops matching with nothing
+# said. The index then goes stale while every save reports success.
 case "$file_path" in
-*/.claude/tasks/*.md) ;;
+*/.claude/tasks/*.md | */.canon/tasks/*.md) ;;
 *) exit 0 ;;
 esac
 
@@ -35,24 +38,39 @@ esac
 # a regen fired on one would rebuild the index the archive was taken out of.
 case "$file_path" in
 */.claude/tasks/index.md | */.claude/tasks/archive/*) exit 0 ;;
+*/.canon/tasks/index.md | */.canon/tasks/archive/*) exit 0 ;;
 esac
 
+# The walk-up boundary has to come from the path, not from the session. Shared
+# scratch resolves at the main worktree root, so a session inside a linked
+# worktree passes a path that sits outside its own project directory and the
+# default boundary would reject it.
+#
+# The index this would have rebuilt is read out of the same branch, so both
+# messages below name the file that actually went stale rather than one root's
+# spelling of it.
+case "$file_path" in
+*/.canon/tasks/*)
+  root="${file_path%/.canon/tasks/*}"
+  index=".canon/tasks/index.md"
+  ;;
+*)
+  root="${file_path%/.claude/tasks/*}"
+  index=".claude/tasks/index.md"
+  ;;
+esac
+[ -n "$root" ] || exit 0
+
 # Report a missing CLI rather than exiting quietly. The path guard above already
 # scopes this to a task-file edit, so the message only fires where the stale
 # index it warns about is the actual outcome.
 if ! command -v canon >/dev/null 2>&1; then
-  jq -nc --arg msg 'canon is not on PATH, so .claude/tasks/index.md was not regenerated and is now stale. Install the toolkit CLI or run canon indexes regen by hand.' \
+  msg="canon is not on PATH, so $index was not regenerated and is now stale. Install the toolkit CLI or run canon indexes regen by hand."
+  jq -nc --arg msg "$msg" \
     '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
   exit 0
 fi
 
-# The walk-up boundary has to come from the path, not from the session. Shared
-# scratch resolves at the main worktree root, so a session inside a linked
-# worktree passes a path that sits outside its own project directory and the
-# default boundary would reject it.
-root="${file_path%/.claude/tasks/*}"
-[ -n "$root" ] || exit 0
-
 # `--no-stage` because a hook has no business touching the index. On a project
 # whose board is not gitignored, the default auto-stage would silently add task
 # files to whatever commit is being assembled.
@@ -65,7 +83,7 @@ output=$(canon indexes regen --no-stage --root "$root" "$file_path" 2>&1) && exi
 errors=$(printf '%s\n' "$output" | grep '^ERROR: ' | head -5)
 [ -n "$errors" ] || errors="$output"
 
-msg="Task index regen failed, so .claude/tasks/index.md is now stale. Fix the frontmatter and save again. $errors"
+msg="Task index regen failed, so $index is now stale. Fix the frontmatter and save again. $errors"
 jq -nc --arg msg "$msg" \
   '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
 exit 0