@erclx/canon 4.3.0 → 4.5.0

package/scripts/core/check-ignore-parity.sh

@@ -117,11 +117,17 @@ for entry in "${shipped[@]}"; do
 done
 
 # Claude-scoped patterns this repository ignores that the manifest does not
-# ship. Scoped to `.claude/` because the manifest is the claude stack and says
-# nothing about `node_modules/` or `.env`.
+# ship. Scoped to the two record roots because the manifest is the claude stack
+# and says nothing about `node_modules/` or `.env`.
+#
+# `.canon` is read as a bare root as well as a prefix, since it is one line
+# covering a whole tree where `.claude/` is thirteen lines naming folders inside
+# a root that also holds tracked content. Leaving it out is what would let a new
+# entry sit outside the only stage comparing the two lists, which is the
+# direction that goes silently blind.
 for pattern in "${ignored[@]}"; do
   case "$pattern" in
-  .claude/*) ;;
+  .claude/* | .canon | .canon/*) ;;
   *) continue ;;
   esac
   contains "$pattern" "${shipped[@]}" && continue

package/scripts/lib/sandbox-dispatch.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+
+# The bound on a nested background dispatch, and the recording behind it.
+#
+# An arm invoked without the narration its fixture states dispatched a real
+# `claude --bg` session against the machine's own process table, and nothing in
+# the harness noticed. `snapshot_tree` reads the sandbox and `snapshot_root`
+# reads four scratch directories, and a dispatched session writes into none of
+# them, so the escape watch reported clean throughout and was right to. The run
+# spent real cost until a person found it, and `SIGTERM` alone did not end it.
+#
+# Three mechanisms sit here rather than in `scripts/sandbox/run.sh`, which is the
+# only caller. Each is reachable from a test that never launches a session:
+# `src/sandbox-dispatch.test.ts` drives the shim against a stub binary and the
+# reap against a `sleep`, where proving either through `run.sh` would mean
+# spawning the thing the bound exists to prevent.
+
+# The prevention. Writes a `claude` that refuses a background dispatch by flag
+# name and delegates everything else, for `run.sh` to place first on the PATH of
+# the session it spawns.
+#
+# The real binary is baked into the file rather than passed through the
+# environment. An env var carrying it would sit in the spawned session's own
+# environment, which hands any arm the exact string that walks around the shim.
+#
+# It names itself in its refusal. No arm shells to `claude` today, and one
+# written tomorrow would meet this and read it as the harness being broken
+# unless the text says which layer refused and why.
+#
+# It is not the whole bound. A dispatch reaching the binary by an absolute path
+# never resolves through PATH at all, which is what `reap_process_group`
+# backstops.
+install_dispatch_shim() {
+  local dir="$1"
+  local real="$2"
+
+  cat >"$dir/claude" <<SHIM
+#!/usr/bin/env bash
+# Generated by install_dispatch_shim in scripts/lib/sandbox-dispatch.sh.
+for arg in "\$@"; do
+  case "\$arg" in
+  --bg | --background)
+    echo "canon sandbox harness: refusing \$arg. A sandbox run may not dispatch a background session, so this shim stands first on PATH in place of the real claude binary. Drive the refusal the fixture asks for, or run this outside the harness." >&2
+    exit 64
+    ;;
+  esac
+done
+exec "$real" "\$@"
+SHIM
+
+  chmod +x "$dir/claude"
+}
+
+# True while any process still carries this group id. Reads the whole table
+# rather than `ps -g`, which selects by session on some builds and reports an
+# empty group as a clean exit either way.
+process_group_alive() {
+  ps -eo pgid= 2>/dev/null | tr -d ' ' | grep -qx "$1"
+}
+
+# The backstop. Signals a process group `run.sh` created, escalating rather than
+# sending one signal and reporting success, since the dispatch that produced this
+# row took two signals to reap.
+#
+# Prints its outcome and always exits zero. Every caller runs under `set -e`, and
+# a survivor is something to report rather than a reason to abandon the verdict
+# the run already took.
+#
+# The group has to be one the run created, and the refusal below is what makes
+# that property travel with the function rather than living in one caller.
+# `run.sh` reads the harness group once and reports `inherited` when the session
+# failed to lead a group of its own, which is a diagnosis; this is the floor
+# under it, and under every caller after it, because the cost of getting the
+# argument wrong is the operator's own shell.
+#
+# What it cannot reach is a dispatch that called `setsid` on its way out, which
+# leaves the group before this reads it. That is the half the shim covers.
+reap_process_group() {
+  local pgid="$1"
+
+  if [ "$pgid" = "$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ')" ]; then
+    printf 'refused-own-group\n'
+    return 0
+  fi
+
+  if ! process_group_alive "$pgid"; then
+    printf 'clear\n'
+    return 0
+  fi
+
+  kill -TERM -"$pgid" 2>/dev/null || true
+  wait_for_group_exit "$pgid"
+
+  if ! process_group_alive "$pgid"; then
+    printf 'reaped-term\n'
+    return 0
+  fi
+
+  kill -KILL -"$pgid" 2>/dev/null || true
+  wait_for_group_exit "$pgid"
+
+  if process_group_alive "$pgid"; then
+    printf 'survived\n'
+  else
+    printf 'reaped-kill\n'
+  fi
+  return 0
+}
+
+# Five seconds per signal. A shorter window reports a survivor for a process
+# that was already exiting, and a longer one stalls a run whose verdict is
+# already taken.
+wait_for_group_exit() {
+  local pgid="$1"
+  local waited=0
+
+  while [ "$waited" -lt 20 ] && process_group_alive "$pgid"; do
+    sleep 0.25
+    waited=$((waited + 1))
+  done
+}
+
+# The client's own session registry, which is the only surface a nested dispatch
+# leaves a trace on that this harness can read. It is client-owned and carries no
+# contract, so a client that stops writing a record per session breaks the
+# detection silently. That is why what reads it reports rather than asserts.
+sessions_dir() {
+  printf '%s/sessions\n' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+}
+
+# Set whenever the registry directory existed at snapshot time. An absent
+# registry produces the same empty manifest a quiet run does, and the two mean
+# opposite things, so the report carries this rather than letting an unwatched
+# run read as a clean one. Same distinction `escape_watched` draws in `run.sh`,
+# which is also the only reader, hence the exemption on the write below.
+sessions_watched=0
+
+# Record names only, never hashes. A live session rewrites its own record on
+# every status change, so a content manifest would name every session running
+# beside this one, which is the noise the escape watch was already narrowed to
+# avoid. A record that appears between the two snapshots is a session that
+# started during the run, and that is the whole question.
+snapshot_sessions() {
+  local manifest="$1"
+  local dir
+  dir="$(sessions_dir)"
+
+  : >"$manifest"
+  [ -d "$dir" ] || return 0
+  # shellcheck disable=SC2034
+  sessions_watched=1
+
+  find "$dir" -maxdepth 1 -type f -name '*.json' 2>/dev/null |
+    sed 's|.*/||' | sort >"$manifest"
+  return 0
+}
+
+# The new side alone, unlike `writes_between`. A record that vanished is a
+# session that ended and a record that changed is one that was already running,
+# and neither is a dispatch this run made.
+sessions_between() {
+  comm -13 "$1" "$2"
+}
+
+# Turns a record name into a line a person can act on. The file can be gone by
+# the time this reads it, since a session that started and exited inside the run
+# takes its record with it, so an unreadable record still reports its name rather
+# than dropping out of the list.
+#
+# One record is one line. The name is written by whatever peer claimed the
+# session, so a newline inside it would split one record across two entries in a
+# list every reader takes as one line each.
+describe_session() {
+  local record desc
+  record="$(sessions_dir)/$1"
+
+  desc="$(jq -r '"\(.name // "unnamed") in \(.cwd // "an unrecorded directory")"
+    | gsub("\\s+"; " ")' "$record" 2>/dev/null || true)"
+  [ -z "$desc" ] && desc="record already gone"
+
+  printf '%s: %s\n' "$1" "$desc"
+}

package/src/audits/baseline.ts

@@ -15,7 +15,7 @@ import type { AuditResult } from '@/audits/catalog'
  * that installs the CLI. A baseline in the package would hand a target this
  * repository's counts to measure its own tree against.
  */
-export const BASELINE_REL = join('.claude', 'audits', 'baseline.json')
+export const BASELINE_REL = join('.claude', 'canon', 'baseline.json')
 
 export interface Baseline {
   /** The day the record was taken, as `YYYY-MM-DD`. */

package/src/claude/cases/misc.ts

@@ -24,4 +24,8 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: "This test just started failing and I don't know why yet.",
     expect: 'systematic-debugging',
   },
+  {
+    prompt: 'Does our github about text still match what the readme says?',
+    expect: 'repo-metadata',
+  },
 ]

package/src/cli.ts

@@ -37,6 +37,7 @@ import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
 import { register as autoship } from '@/commands/autoship'
 import { register as pr } from '@/commands/pr'
+import { register as repo } from '@/commands/repo'
 import { register as census } from '@/commands/census'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
@@ -86,6 +87,7 @@ function showHelp(): void {
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
     `${GREY}│${NC}    autoship [cmd]     ${GREY}# Decide whether a changed set needs the review pass (classify)${NC}`,
     `${GREY}│${NC}    pr [cmd]           ${GREY}# Read a pull request body against its own diff (key-changes)${NC}`,
+    `${GREY}│${NC}    repo [cmd]         ${GREY}# This repository's own remote metadata (metadata propose, apply)${NC}`,
     `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    gate [cmd]         ${GREY}# Run the merge gate stage by stage (run)${NC}`,
@@ -135,6 +137,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon secrets scan --json`,
     `${GREY}│${NC}    canon deps audit --json`,
     `${GREY}│${NC}    canon labels audit --json`,
+    `${GREY}│${NC}    canon repo metadata propose --json`,
     `${GREY}│${NC}    canon census --json`,
     `${GREY}│${NC}    canon audits run --json`,
     `${GREY}│${NC}    canon gate run --all --no-write`,
@@ -192,6 +195,7 @@ deps(program)
 labels(program)
 autoship(program)
 pr(program)
+repo(program)
 census(program)
 audits(program)
 gate(program)

package/src/commands/claude.ts

@@ -51,6 +51,7 @@ import {
 import { copyPreservingMode } from '@/copy'
 import { execScript } from '@/exec'
 import { PROJECT_ROOT } from '@/project-root'
+import { recordDir } from '@/record-root'
 import { isDirectory, resolveTarget } from '@/target'
 import { injectGitignore, pruneGitignore } from '@/tooling/inject'
 import {
@@ -491,13 +492,18 @@ async function runSync(target: string): Promise<number> {
   const resolved = resolveTarget(target, PROJECT_ROOT)
   if (typeof resolved === 'number') return resolved
 
+  // A record folder resolves at either root, so a migrated target is reported as
+  // seeded rather than sent to `canon claude init` to re-create records it
+  // already holds. The three seeded files and `wireframes` are tracked and stay
+  // at `.claude/`, which the resolver answers for them anyway, since nothing
+  // ever creates a second root copy for a name that does not move.
   logStep('Seeded')
   for (const name of SEEDED_FILES) {
     if (existsSync(join(resolved, '.claude', name))) logInfo(name)
     else logWarn(`${name} missing. Run \`canon claude init\``)
   }
   for (const name of SEEDED_DIRS) {
-    if (isDirectory(join(resolved, '.claude', name))) logInfo(`${name}/`)
+    if (isDirectory(recordDir(resolved, name))) logInfo(`${name}/`)
     else logWarn(`${name}/ missing. Run \`canon claude init\``)
   }
 

package/src/commands/context.ts

@@ -180,7 +180,7 @@ async function runAudit(
   if (folders.length === 0) {
     return refuse(
       'no-folders',
-      `No audited folder found ${named ? 'under .claude/ or the project root' : 'under .claude/'}, since resolving one needs its own index.md file. Looked for: ${names.join(', ')}.`,
+      `No audited folder found ${named ? 'under a record root or the project root' : 'under a record root'}, since resolving one needs its own index.md file. Looked for: ${names.join(', ')}.`,
       gateOnly,
       root,
       opts.json ?? false,
@@ -200,7 +200,7 @@ async function runAudit(
   if (gateOnly && cited.length === 0) {
     return refuse(
       'no-citation-scope',
-      `The citation check spells the .claude/ prefix and no audited folder resolved there. Looked for: ${names.join(', ')}.`,
+      `The citation check spells the record-root prefixes and no audited folder resolved under one. Looked for: ${names.join(', ')}.`,
       gateOnly,
       root,
       opts.json ?? false,
@@ -414,7 +414,7 @@ function reportCitations(
 
   if (cited.length === 0) {
     logInfo(
-      'Out of scope. The pattern spells the .claude/ prefix, and no audited folder resolved there.',
+      'Out of scope. The pattern spells the record-root prefixes, and no audited folder resolved under one.',
     )
     return
   }

package/src/commands/design.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
+import { creationRel } from '@/record-root'
 import { renderDesignDoc } from '@/design/render'
 import { palette } from '@/ui'
 
@@ -13,7 +14,11 @@ export function register(program: Command): void {
     .command('render')
     .description('Render DESIGN.md tokens to HTML and CSS preview')
     .option('-s, --source <path>', 'Source DESIGN.md path', '.claude/DESIGN.md')
-    .option('-o, --out <path>', 'Output directory', '.claude/review/design')
+    .option(
+      '-o, --out <path>',
+      'Output directory',
+      creationRel('review', 'design'),
+    )
     .action((opts: { source: string; out: string }) => {
       const sourcePath = resolve(process.cwd(), opts.source)
       const outDir = resolve(process.cwd(), opts.out)

package/src/commands/feedback.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import type { Command } from 'commander'
 import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
 import { PROJECT_ROOT } from '@/project-root'
+import { creationRel } from '@/record-root'
 import { createGithubIssue } from '@/github'
 import { frameError, frameSuccess, palette } from '@/ui'
 
@@ -39,7 +40,10 @@ function isToolkitSource(): boolean {
  * single ignore entry and the single backed-folder entry it already had.
  */
 function writeLocal(body: string): string {
-  const relativeDir = join('.claude', 'review', 'feedback')
+  // Creation, so the destination is the creation default rather than the
+  // resolved read root. A toolkit checkout that has migrated its records already
+  // carries the folder and resolves the same path either way.
+  const relativeDir = creationRel('review', 'feedback')
   const reviewDir = join(PROJECT_ROOT, relativeDir)
   mkdirSync(reviewDir, { recursive: true })
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`

package/src/commands/gov.ts

@@ -9,6 +9,7 @@ import {
   scanCounts,
 } from '@/counts/scan'
 import { PROJECT_ROOT } from '@/project-root'
+import { creationRel, SCRATCH } from '@/record-root'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
 import { installRules, lookupRules } from '@/gov/install'
@@ -65,7 +66,7 @@ import {
   select,
 } from '@/ui'
 
-const PAYLOAD_REL = join('.claude', '.tmp', 'gov', 'rules.md')
+const PAYLOAD_REL = creationRel(SCRATCH, 'gov', 'rules.md')
 const RULES_REL = join('.claude', 'rules')
 
 interface InstallOptions {