@erclx/canon 4.3.0 → 4.5.0

package/src/tasks/answers.ts

@@ -0,0 +1,202 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+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 = 'plans'
+const TASKS = 'tasks'
+const ARCHIVE = 'archive'
+
+/**
+ * The suggestion the plan standard fixes for a question that turns on the
+ * operator's preference rather than on a technical default. Every other
+ * suggestion is accepted by a blank slot, so only this phrase over an empty
+ * `- Answer:` is a stop.
+ */
+const OPERATOR_CALL = 'needs your call'
+
+const SUGGESTED_PREFIX = '- Suggested:'
+const ANSWER_PREFIX = '- Answer:'
+
+export const ANSWER_REFUSALS = ['no-plan', 'archived', 'bad-input'] as const
+
+export type AnswerRefusal = (typeof ANSWER_REFUSALS)[number]
+
+export interface AnswersRefused {
+  readonly ok: false
+  readonly reason: AnswerRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+/**
+ * One question the dispatch has to hand back. It carries the label rather than
+ * contributing to a count, since a dispatcher that refuses a row without naming
+ * the slot has nothing to give the operator.
+ */
+export interface OpenQuestion {
+  readonly label: string
+  readonly why: string
+}
+
+export interface PlanAnswers {
+  readonly ok: true
+  readonly plan: string
+  readonly launchable: boolean
+  readonly open: readonly OpenQuestion[]
+}
+
+export type AnswersOutcome = PlanAnswers | AnswersRefused
+
+/**
+ * The spellings a caller reaches a plan by, in the order they are tried. A bare
+ * slug names the live folder outright, and a path is resolved against the
+ * project root and against the board directory both.
+ *
+ * The second base is the one a dispatcher actually has to hand. A board row
+ * writes its `Plan:` link relative to `.claude/tasks/`, so the href reads
+ * `../plans/feature-<slug>.md`, and resolving that against the root alone lands
+ * a directory above the repository and refuses a plan that exists.
+ *
+ * `resolveLivePlan` reads a task's own line against the same two bases and is
+ * not this function. It tries the board first and tests containment under the
+ * live plans folder, where this tries the root first and tests nothing, so the
+ * two agree on the spellings a board writes and part company outside them.
+ * Sharing the bases is what makes a board link resolve for both, and the
+ * archive exclusion in `planAnswers` is stated separately for that reason.
+ *
+ * Root order is what keeps the documented forms unchanged. A reference that
+ * resolves from the root is taken there, and the board base is reached only by
+ * a path the root could not answer.
+ */
+export function planCandidates(root: string, reference: string): string[] {
+  if (reference.includes('/') || reference.endsWith('.md')) {
+    if (isAbsolute(reference)) return [reference]
+
+    return [
+      resolve(root, reference),
+      resolve(recordDir(root, TASKS), reference),
+    ]
+  }
+
+  const slug = reference.startsWith('feature-')
+    ? reference.slice('feature-'.length)
+    : reference
+
+  return [recordDir(root, PLANS, `feature-${slug}.md`)]
+}
+
+function suggestionOf(body: readonly string[]): string | undefined {
+  const line = body.find((entry) => entry.startsWith(SUGGESTED_PREFIX))
+
+  return line?.slice(SUGGESTED_PREFIX.length).trim()
+}
+
+/**
+ * An absent `- Answer:` line reads the same as a blank one here. The slot being
+ * missing is a conformance defect `canon tasks validate` already names, and a
+ * gate that answered it differently would refuse a row for a reason the
+ * validator has already reported.
+ */
+function isAnswered(body: readonly string[]): boolean {
+  const line = body.find((entry) => entry.startsWith(ANSWER_PREFIX))
+  if (line === undefined) return false
+
+  return line.slice(ANSWER_PREFIX.length).trim().length > 0
+}
+
+/**
+ * The standard writes the reason behind a comma and the corpus also writes it
+ * behind a full stop, so both separators come off. Reporting the phrase with
+ * whatever punctuation followed it hands the operator a stray mark where the
+ * reason should start.
+ */
+function reasonOf(suggested: string): string {
+  const rest = suggested.slice(OPERATOR_CALL.length).replace(/^[,.;:\s]+/, '')
+
+  return rest.length > 0 ? rest : 'no reason stated'
+}
+
+/**
+ * A question carrying no suggestion at all is also a stop at execution, and it
+ * is not read here. `checkQuestionContract` reports it as `suggestion-missing`
+ * and the runbook dispatches a row whose plan is already verified, so testing
+ * it again would put one rule in two places that ship on different cadences.
+ */
+function openQuestions(lines: readonly string[]): OpenQuestion[] {
+  const open: OpenQuestion[] = []
+
+  for (const question of readQuestions(lines)) {
+    const suggested = suggestionOf(question.body)
+    if (!suggested?.toLowerCase().startsWith(OPERATOR_CALL)) continue
+    if (isAnswered(question.body)) continue
+
+    open.push({ label: question.label, why: reasonOf(suggested) })
+  }
+
+  return open
+}
+
+/**
+ * Answers whether a plan is launchable, which is whether it still waits on the
+ * operator for a call only they can make. It reads the question block through
+ * the same `readQuestions` the plan validator runs, so the gate and the
+ * conformance check cannot drift into disagreeing about what a question is.
+ *
+ * It reports and never writes. Holding the row, naming the slot, and reaching
+ * the operator belong to the dispatcher, which is where the decision already
+ * sits.
+ */
+export async function planAnswers(
+  root: string,
+  reference: string,
+): Promise<AnswersOutcome> {
+  if (reference.trim().length === 0) {
+    return refuse('bad-input', 'No plan named. Pass a plan path or its slug.')
+  }
+
+  const candidates = planCandidates(root, reference)
+  const path = candidates.find((candidate) => existsSync(candidate))
+
+  if (!path) {
+    // Naming every base keeps a task-relative link from reporting the one place
+    // it does not resolve, since `relative` hands that spelling straight back.
+    const looked = candidates.map((entry) => relative(root, entry)).join(' or ')
+
+    return refuse('no-plan', `No plan at ${looked}.`, [reference])
+  }
+
+  // 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.
+  // 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.`,
+      [reference],
+    )
+  }
+
+  const sections = splitPlanSections(await readFile(path, 'utf8'))
+  const open = openQuestions(sections.get('Questions') ?? [])
+
+  return {
+    ok: true,
+    plan: relative(root, path),
+    launchable: open.length === 0,
+    open,
+  }
+}
+
+function refuse(
+  reason: AnswerRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): AnswersRefused {
+  return { ok: false, reason, message, detail }
+}

package/src/tasks/archive.ts

@@ -1,12 +1,13 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
-import { join, relative, resolve, sep } from 'node:path'
+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
@@ -76,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])\] ?(.*)$/
@@ -180,14 +181,6 @@ function isRowFor(line: string, target: string): boolean {
   return first !== undefined && first.includes(target)
 }
 
-/**
- * Tests containment rather than a string prefix, so a sibling whose name merely
- * extends the folder's is not read as being inside it.
- */
-function isUnder(path: string, dir: string): boolean {
-  return path === dir || path.startsWith(`${dir}${sep}`)
-}
-
 /**
  * Resolves the `Plan:` target against the board and against the project root
  * both, which is how `claude-docs` reads the same line. It accepts `../plans/x.md`
@@ -208,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
 }
 
@@ -315,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: [] }
@@ -331,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