@smartmemory/compose 0.3.6-beta → 0.3.8

package/bin/compose.js

@@ -91,7 +91,12 @@ function resolveCwdWithWorkspace(args) {
 // ---------------------------------------------------------------------------
 import { parseTeamFlag } from '../lib/team-flag.js';
 import { loadDeps, checkExternalSkills, printDepReport, buildDepReport, checkExternalBinaries, printBinaryReport, buildBinaryReport } from '../lib/deps.js';
-import { checkLatestVersion } from '../lib/version-check.js';
+import {
+  checkLatestVersion,
+  checkPackageVersion,
+  resolveStratumVersion,
+  formatDriftNudge,
+} from '../lib/version-check.js';
 import { computeHooksStatus, formatHookStatusLines, HOOK_MARKERS } from '../lib/hooks-status.js';
 
 const [,, cmd, ...args] = process.argv
@@ -115,38 +120,10 @@ if (cmd === '--version' || cmd === '-V' || cmd === 'version') {
 }
 
 if (!cmd || cmd === '--help' || cmd === '-h') {
-  console.log('Usage: compose <command>')
-  console.log('')
-  console.log('Commands:')
-  console.log('  start     Start the compose app (UI + API) for this project')
-  console.log('  remote    Manage remote access: pair, list, revoke, status')
-  console.log('  new       Kickoff a product (research, brainstorm, roadmap, scaffold)')
-  console.log('  import    Scan existing project and generate structured analysis')
-  console.log('  feature   Add a single feature (folder, design seed, ROADMAP entry)')
-  console.log('  build     Run a feature through the headless lifecycle')
-  console.log('  fix       Run a bug through the headless bug-fix lifecycle')
-  console.log('  gsd       Per-task fresh-context dispatch from existing blueprint+Boundary Map')
-  console.log('  pipeline  View and edit the build pipeline')
-  console.log('  roadmap            Show roadmap status and next buildable features')
-  console.log('  roadmap generate   Regenerate ROADMAP.md from feature.json files')
-  console.log('  roadmap migrate    Extract ROADMAP.md entries into feature.json files')
-  console.log('  roadmap check      Verify feature.json and ROADMAP.md are in sync')
-  console.log('  roadmap xref-sync  Pull-reconcile feature.json external links to live state')
-  console.log('  roadmap xref-push  Push-write GitHub trackers to match expect= (dry-run; --apply to write)')
-  console.log('  migrate-anon       Promote historical anonymous ROADMAP rows to typed features (interactive)')
-  console.log('  items              List vision items from local state (no server)')
-  console.log('  items show <id>    Show detail for a specific vision item')
-  console.log('  triage    Analyze a feature and recommend build profile')
-  console.log('  qa-scope  Show affected routes from a feature\'s changed files')
-  console.log('  context decisions  Show the build decision log (--feature <FC>, --format text|json)')
-  console.log('  gate list          List pending gates (--item <id>, --status pending|all|resolved)')
-  console.log('  gate resolve <id>  Resolve a gate (--approve|--revise|--kill, --comment <text>)')
-  console.log('  init      Initialize Compose in the current project')
-  console.log('  setup     Install/sync global Compose skills (alias: sync)')
-  console.log('  sync      Re-sync global skills from this install (alias of setup)')
-  console.log('  update    Pull latest compose, reinstall deps, refresh global skill')
-  console.log('  doctor    Check external skill dependencies')
-  console.log('  --version Print compose version, git SHA, and install root')
+  // Rendered from the single command table (lib/cli-commands.js) so --help can
+  // never silently omit a shipped command (COMP-AUDIT-13).
+  const { renderHelp } = await import('../lib/cli-commands.js')
+  console.log(renderHelp())
   process.exit(0)
 }
 
@@ -566,10 +543,24 @@ async function runInit(flags, cwdOverride) {
     }
   }
 
-  // 8. Copy default pipeline specs if absent
+  // 8. Copy default pipeline specs if absent.
+  // COMP-PIPELINE-QUARANTINE follow-up: `bug-fix` belongs in this set. `compose
+  // fix` checks for pipelines/bug-fix.stratum.yaml, runs init when it is absent,
+  // and then fails with "Lifecycle spec not found" because init never copied it —
+  // so the command was unavailable in every fresh workspace independently of the
+  // spec's dialect. Each spec's `<name>.profiles.json` sidecar travels WITH it:
+  // loadPipelineProfiles fails open, so a spec copied without its sidecar runs on
+  // bare defaults and silently drops the tool restrictions it declares.
   const pipelinesDir = join(cwd, 'pipelines')
   mkdirSync(pipelinesDir, { recursive: true })
-  for (const specName of ['build.stratum.yaml', 'build-quick.stratum.yaml', 'new.stratum.yaml', 'plan.stratum.yaml']) {
+  const DEFAULT_PIPELINES = [
+    'build.stratum.yaml',
+    'build-quick.stratum.yaml',
+    'bug-fix.stratum.yaml',
+    'new.stratum.yaml',
+    'plan.stratum.yaml',
+  ]
+  for (const specName of DEFAULT_PIPELINES) {
     const dest = join(pipelinesDir, specName)
     if (!existsSync(dest)) {
       const src = join(PACKAGE_ROOT, 'pipelines', specName)
@@ -578,6 +569,12 @@ async function runInit(flags, cwdOverride) {
         console.log(`Copied default pipeline to ${dest}`)
       }
     }
+    const sidecarName = specName.replace(/\.stratum\.ya?ml$/, '.profiles.json')
+    const sidecarDest = join(pipelinesDir, sidecarName)
+    if (!existsSync(sidecarDest)) {
+      const sidecarSrc = join(PACKAGE_ROOT, 'pipelines', sidecarName)
+      if (existsSync(sidecarSrc)) copyFileSync(sidecarSrc, sidecarDest)
+    }
   }
 
   // 9. Sync all compose-owned skills to detected agents
@@ -738,17 +735,90 @@ async function runUpdate(flags) {
     } else {
       console.log('Stratum MCP wiring already current')
     }
+
+    // Healing .mcp.json only fixes what the NEXT client launch reads. An MCP
+    // server the agent already spawned keeps serving the old Stratum build for
+    // the rest of the session, so an update can look applied while every
+    // stratum_* tool still runs pre-update code. Say so explicitly — this has
+    // bitten us before (stale tool contracts surviving a "successful" upgrade).
+    if (!wiring.skipped) {
+      console.log('')
+      console.log('⚠ Restart your MCP client (e.g. /mcp reconnect, or restart Claude Code)')
+      console.log('  to pick up the new Stratum server — a running one keeps serving the old build.')
+    }
   }
 
   console.log('')
   console.log(`compose updated to v${getPkgVersion()}${style === 'git' ? ` @ ${getGitSha(root) || '?'}` : ''}`)
 }
 
+/** Hard ceiling on how long the update nudge may delay a command. */
+const NUDGE_BUDGET_MS = 4000
+
+/** Stratum is enabled unless this cwd's workspace manifest explicitly opts out.
+ * This deliberately does not use resolveWorkspace(): the nudge runs before
+ * argument parsing, and workspace resolution may print errors and exit. */
+function isStratumCapabilityEnabled() {
+  try {
+    const manifest = join(process.cwd(), '.compose', 'compose.json')
+    const config = JSON.parse(readFileSync(manifest, 'utf-8'))
+    return config?.capabilities?.stratum !== false
+  } catch {
+    // Absent, unreadable, or malformed means "enabled" for compatibility.
+    return true
+  }
+}
+
+/** Print a one-line update nudge at session entry points. NOTIFY ONLY —
+ * this must never mutate an installation. Compose has ~109 lazy `await import()`
+ * sites, so replacing files under a running process would have it load new
+ * modules into an old module graph; safe self-update needs a versioned install
+ * (COMP-UPDATE-VERSIONED-INSTALL), not a check here.
+ *
+ * Swallows everything: a courtesy line may never fail the command it precedes. */
+async function emitDriftNudge() {
+  try {
+    // Only an interactive terminal pays for a registry lookup. Everything else
+    // — a spawned CLI, CI, a script — reads cache and stays silent on a miss.
+    //
+    // This is not an optimization, it is a correctness fix. The nudge sits on
+    // the startup path of init/build/plan, and the test suite alone spawns
+    // `compose init` dozens of times in parallel with a cold HOME. Every one of
+    // those fired a live fetch, and under that concurrency one failed to settle:
+    // node reported "Detected unsettled top-level await" at this call and exited
+    // non-zero, breaking `compose init` itself. A courtesy line must never be
+    // able to do that, and non-interactive callers were never its audience.
+    const cacheOnly = !process.stdout.isTTY
+    const stratumCurrent = isStratumCapabilityEnabled()
+      ? resolveStratumVersion(PACKAGE_ROOT)
+      : null
+    const work = Promise.all([
+      checkPackageVersion('@smartmemory/compose', getPkgVersion(), { cacheOnly }),
+      stratumCurrent
+        ? checkPackageVersion('@smartmemory/stratum', stratumCurrent, { cacheOnly })
+        : Promise.resolve(null),
+    ])
+    // Belt and braces: whatever happens below, this await settles. The timer is
+    // ref'd deliberately — an unref'd one would let the loop drain and reproduce
+    // the very unsettled-await exit this guards against.
+    const [composeInfo, stratumInfo] = await Promise.race([
+      work,
+      new Promise((resolve) => setTimeout(() => resolve([null, null]), NUDGE_BUDGET_MS)),
+    ])
+    for (const line of formatDriftNudge({ compose: composeInfo, stratum: stratumInfo })) {
+      console.log(line)
+    }
+  } catch {
+    // never break the command this is attached to
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Command dispatch
 // ---------------------------------------------------------------------------
 
 if (cmd === 'init') {
+  await emitDriftNudge()
   await runInit(args)
   process.exit(0)
 }
@@ -1148,38 +1218,122 @@ _This is a seed design doc created by \`compose feature\`. The \`compose build\`
   process.exit(0)
 }
 
+if (cmd === 'guard' && ['descriptors', 'sign', 'enrol'].includes(args[0])) {
+  // New signing verbs stay above the canon-guard dispatcher below. They resolve
+  // the target workspace; canon-guard intentionally continues to dogfood this
+  // package root for its own hook state.
+  const sub = args[0]
+  const { root: cwd } = resolveCwdWithWorkspace(args)
+  const { runGuardDescriptors, runGuardSign, runGuardEnrol } = await import('../lib/guard-cli.js')
+  const principalAt = args.indexOf('--principal')
+  const principal = principalAt === -1 ? undefined : (args[principalAt + 1] ?? '')
+  const result = sub === 'descriptors' ? await runGuardDescriptors(cwd)
+    : sub === 'sign' ? await runGuardSign(cwd)
+      : await runGuardEnrol(principal === undefined ? {} : { principal }, { emit: (line) => console.log(line) })
+  for (const line of result.lines) console.log(line)
+  process.exit(result.status === 'refused' ? 1 : 0)
+}
+
 if (cmd === 'roadmap') {
   const subcmd = args[0]
 
   // compose roadmap generate — regenerate ROADMAP.md from feature.json files,
   // converging to a fixed point before finishing.
   if (subcmd === 'generate' || subcmd === 'gen') {
-    const { writeRoadmap } = await import('../lib/roadmap-gen.js')
     const { checkRoundtrip } = await import('../lib/roadmap-roundtrip.js')
+    const { generateRoadmapFromBase } = await import('../lib/roadmap-gen.js')
     const { listFeatures } = await import('../lib/feature-json.js')
-    const { loadExternalPrefixes } = await import('../lib/project-paths.js')
+    const { loadExternalPrefixes, resolveRoadmapPath, loadFeaturesDir } = await import('../lib/project-paths.js')
     const { isNarrativeOwned } = await import('../lib/roadmap-config.js')
+    const { readPreservedSections } = await import('../lib/roadmap-preservers.js')
+    const { computeResidue, protectResidue, RoadmapProseLossError } = await import('../lib/roadmap-residue.js')
     const { root: cwd } = resolveCwdWithWorkspace(args)
     // Narrative-owned workspaces (#39): ROADMAP.md is hand-authored, not a render
-    // of feature.json. writeRoadmap already no-ops, but the canonicalization pass
-    // below would still overwrite the file (or crash if it's absent) — skip the
-    // whole generate path here so the hand-authored file is never touched.
+    // of feature.json — never regenerate or overwrite it.
     if (isNarrativeOwned(cwd)) {
       console.log('narrative-owned workspace (roadmap.narrative=true) — ROADMAP.md is hand-authored; generate skipped.')
       process.exit(0)
     }
-    const path = writeRoadmap(cwd)
+    const path = resolveRoadmapPath(cwd)
+    const base = existsSync(path) ? readFileSync(path, 'utf-8') : ''
+    const acceptLoss = args.includes('--accept-loss')
+    const protect = args.includes('--protect')
     const externalPrefixes = loadExternalPrefixes(cwd)
-    // checkRoundtrip's now:'0000-00-00' is only used to detect/canonicalize
-    // structural non-convergence — once the file has headings, readPreamble
-    // preserves the existing preamble date verbatim, so no sentinel date leaks.
-    const rt = checkRoundtrip(readFileSync(path, 'utf-8'), listFeatures(cwd), { now: '0000-00-00', externalPrefixes })
-    if (!rt.fixedPoint) {
-      writeFileSync(path, rt.canonical)
-      console.log(`Generated ${path} (canonicalized over ${rt.passes} passes)`)
-    } else {
-      console.log(`Generated ${path} from feature.json files`)
+    const now = new Date().toISOString().slice(0, 10)
+
+    // Guard 1 (COMP-CONFLICT-MERGE): structural preserved-section marker defects
+    // silently drop the content they were meant to protect — an unbalanced open
+    // (typo'd close) or a duplicate id (Map collision). Fail loud, write nothing.
+    try {
+      readPreservedSections(base, { strict: true })
+    } catch (err) {
+      if (err?.code === 'ROADMAP_UNBALANCED_MARKER') {
+        console.error(`Refusing to write ${path}: unbalanced preserved-section marker(s):`)
+        for (const m of err.markers) console.error(`  line ${m.lineNo}: open "${m.id}" has no matching close`)
+        console.error(err.remediation)
+        process.exit(1)
+      }
+      if (err?.code === 'ROADMAP_DUPLICATE_MARKER') {
+        console.error(`Refusing to write ${path}: duplicate preserved-section id(s):`)
+        for (const m of err.markers) console.error(`  line ${m.lineNo}: id "${m.id}" is used more than once`)
+        console.error(err.remediation)
+        process.exit(1)
+      }
+      throw err
+    }
+
+    // Honor a configured non-default features directory (paths.features), else a
+    // project using one regenerates from the wrong/empty feature set.
+    const featuresDir = loadFeaturesDir(cwd)
+    const features = listFeatures(cwd, featuresDir)
+
+    // Emit the phase-override drift warning + roadmap_drift audit event, which the
+    // old writeRoadmap-first path produced and the pure roundtrip path suppresses.
+    generateRoadmapFromBase(base, features, { cwd, featuresDir, now })
+
+    // Guard 2: compute the FINAL canonical bytes (fixed point over all passes)
+    // BEFORE writing, then diff the base against exactly what will be written.
+    // The duplicate-heading loss only surfaces on a later pass, so checking the
+    // first candidate would pass cleanly and then write the lossy result.
+    const featureCodes = new Set(features.map(f => f.code))
+    const rt = checkRoundtrip(base, features, { now, externalPrefixes, featuresDir })
+    let finalText = rt.canonical
+    let residue = computeResidue(base, finalText, { featureCodes })
+
+    if (residue.length > 0 && protect) {
+      const protectedBase = protectResidue(base, residue)
+      const rt2 = checkRoundtrip(protectedBase, features, { now, externalPrefixes, featuresDir })
+      const stillLost = computeResidue(protectedBase, rt2.canonical, { featureCodes })
+      if (stillLost.length === 0) {
+        writeFileSync(path, rt2.canonical)
+        console.log(`Generated ${path} — wrapped ${residue.length} line(s) in preserved-section markers`)
+        process.exit(0)
+      }
+      // --protect could not fully account for the loss; fall through to the error
+      // with the residual set so the operator sees what remains.
+      finalText = rt2.canonical
+      residue = stillLost
+    }
+
+    if (residue.length > 0 && !acceptLoss) {
+      const err = new RoadmapProseLossError(residue)
+      console.error(`Refusing to write ${path}: ${err.message}:`)
+      for (const r of err.lines) {
+        console.error(`  line ${r.lineNo} (under "${r.nearestHeading ?? '(preamble)'}"): ${r.text}`)
+      }
+      console.error('')
+      console.error(err.remediation)
+      process.exit(1)
+    }
+
+    if (residue.length > 0 && acceptLoss) {
+      console.log(`--accept-loss: dropping ${residue.length} hand-authored line(s):`)
+      for (const r of residue) console.log(`  line ${r.lineNo}: ${r.text}`)
     }
+
+    writeFileSync(path, finalText)
+    if (!rt.fixedPoint) console.log(`Generated ${path} (canonicalized over ${rt.passes} passes)`)
+    else console.log(`Generated ${path} from feature.json files`)
     process.exit(0)
   }
 
@@ -1579,7 +1733,7 @@ if (cmd === 'record-completion') {
   //
   // Flags:
   //   --commit-sha=<sha>          required; full 40-char hex SHA (Decision 9)
-  //   --tests-pass=<bool>         default true
+  //   --tests-pass=<bool>         REQUIRED (true|false) — no default (COMP-COMPLETION-GATE)
   //   --notes=<string>            optional
   //   --files-changed-from-stdin  read newline-separated paths from stdin
   //   --no-status                 set_status: false (don't flip status to COMPLETE)
@@ -1624,7 +1778,8 @@ if (cmd === 'record-completion') {
     console.log('')
     console.log('Options:')
     console.log('  --commit-sha=<sha>          Full 40-char hex SHA (required)')
-    console.log('  --tests-pass=<bool>         Whether tests passed (default: true)')
+    console.log('  --tests-pass=<bool>         Whether tests passed — REQUIRED, no default')
+    console.log('                              (configure guard.testCommand to attest by running instead)')
     console.log('  --notes=<string>            Optional provenance notes')
     console.log('  --files-changed-from-stdin  Read newline-separated repo-relative paths from stdin')
     console.log('  --no-status                 Do not flip feature status to COMPLETE')
@@ -1647,8 +1802,13 @@ if (cmd === 'record-completion') {
     process.exit(1)
   }
 
-  // Parse tests-pass: default true
-  let testsPass = true
+  // Parse tests-pass. COMP-COMPLETION-GATE (BREAKING): there is NO default.
+  // This used to default to `true`, which meant every completion recorded from
+  // the CLI attested a test run the operator may never have made — the record
+  // said "tests passed" on the strength of nothing. An attestation nobody made
+  // is worse than an absent one, so the flag is now required unless a
+  // `guard.testCommand` is configured to attest by running.
+  let testsPass
   if (flags['tests-pass'] !== undefined) {
     const tp = flags['tests-pass']
     if (tp === 'false' || tp === false) testsPass = false
@@ -1685,7 +1845,48 @@ if (cmd === 'record-completion') {
   const { root: cwd } = resolveCwdWithWorkspace(args)
   const { recordCompletion } = await import('../lib/completion-writer.js')
   try {
-    const result = await recordCompletion(cwd, completionArgs)
+    let result
+    if (completionArgs.set_status === false) {
+      // --no-status records evidence without completing, so it does not drive
+      // the guard. tests_pass still has no default; the writer requires a boolean.
+      if (testsPass === undefined) {
+        console.error(
+          'Error: --tests-pass is required (true|false). It no longer defaults to true — ' +
+          'a completion record must not attest a test run that was never made.'
+        )
+        process.exit(1)
+      }
+      result = await recordCompletion(cwd, completionArgs)
+    } else {
+      const { completionGate } = await import('../lib/completion-gate.js')
+      const gated = await completionGate({
+        featureCode:    featureCode,
+        commitSha:      commitSha,
+        testsPass:      testsPass,
+        filesChanged:   filesChanged,
+        notes:          flags['notes'] || undefined,
+        force:          flags['force'] === true || undefined,
+        idempotencyKey: flags['idempotency-key'] || undefined,
+        workspaceRoot:  cwd,
+      })
+      if (!gated.ok) {
+        console.error(`Refused at ${gated.refusedAt}:\n  - ${gated.reasons.join('\n  - ')}`)
+        if (gated.refusedAt === 'evidence' && testsPass === undefined) {
+          console.error(
+            '\nHint: --tests-pass no longer defaults to true. Pass --tests-pass true|false, ' +
+            'or configure guard.testCommand in .compose/compose.json so the test run itself attests.'
+          )
+        }
+        process.exit(1)
+      }
+      result = gated.result
+      if (gated.partial) {
+        console.warn(
+          `Completed, but a projection failed — ` +
+          gated.failures.map(f => `${f.step}: ${f.message} (recover: ${f.recover})`).join('; ')
+        )
+      }
+    }
     console.log(JSON.stringify({
       completion_id:  result.completion_id,
       idempotent:     result.idempotent,
@@ -1898,6 +2099,276 @@ if (cmd === 'hooks') {
   process.exit(1)
 }
 
+if (cmd === 'guard') {
+  // compose guard {install,uninstall,status,verify} — COMP-CANON-GUARD S4/S5.
+  // Manages the write-time PreToolUse hook registration in .claude/settings.json.
+  // Scoped to compose's own checkout (dogfooding): the hook script uses a
+  // relative import into lib/, so it only works where .claude/ and lib/ are
+  // siblings — this repo. Cross-project install is design Open Question 2.
+  const sub = args[0] || 'status'
+  const { readFileSync: rfSync, writeFileSync: wfSync, existsSync: exSync, mkdirSync: mkSync } = await import('fs')
+  const { join: pjoin } = await import('path')
+  const { installGuardHook, uninstallGuardHook, guardHookStatus, HOOK_COMMAND, HOOK_MATCHER } =
+    await import('../lib/canon-guard.js')
+
+  const projectRoot = PACKAGE_ROOT
+  const claudeDir = pjoin(projectRoot, '.claude')
+  const settingsPath = pjoin(claudeDir, 'settings.json')
+  const hookScript = pjoin(claudeDir, 'hooks', 'canon-guard.mjs')
+
+  function readSettings() {
+    if (!exSync(settingsPath)) return {}
+    try {
+      return JSON.parse(rfSync(settingsPath, 'utf-8'))
+    } catch (e) {
+      console.error(`Error: ${settingsPath} is not valid JSON: ${e.message}`)
+      process.exit(1)
+    }
+  }
+  function writeSettings(obj) {
+    mkSync(claudeDir, { recursive: true })
+    wfSync(settingsPath, JSON.stringify(obj, null, 2) + '\n')
+  }
+
+  if (sub === 'init') {
+    // Establish the first record baseline (trust-on-first-use). This exists
+    // BECAUSE `verify --fix` correctly refuses to stamp records: without a
+    // separate, deliberate bootstrap there would be no way to create the very
+    // first manifest, and drift detection would report every record as `added`
+    // forever. Kept distinct so the one-time act of trusting the current records
+    // is explicit and auditable rather than a side effect of a repair flag.
+    // Reject unrecognised args rather than silently ignoring them: `init` WRITES
+    // a baseline, so a mistyped or unsupported scope flag must never quietly
+    // baseline the wrong workspace.
+    const initExtra = args.slice(1).filter((a) => a !== '--cwd' && !a.startsWith('--cwd='))
+    if (args.slice(1).length > 0) {
+      console.error('Usage: compose guard init')
+      console.error('`guard init` baselines the workspace it is run IN — cd there instead of passing a scope flag.')
+      if (initExtra.length !== args.slice(1).length) {
+        console.error('(--cwd is not supported here: it would write the baseline to a different repo than the one you named.)')
+      }
+      process.exit(1)
+    }
+
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+    const { computeRecordHashes, initManifestExclusive, manifestPathFor, recordFileSet } =
+      await import('../lib/judgment-attest.js')
+
+    // `init` WRITES trust, so be explicit about the destination. The shared
+    // resolver honours COMPOSE_TARGET, which can point somewhere other than the
+    // shell's cwd — never let that be silent for this command.
+    if (resolve(cwd) !== resolve(process.cwd())) {
+      console.log(`Baselining resolved workspace: ${cwd}`)
+      console.log('(resolved via COMPOSE_TARGET / workspace config, not your current directory)')
+    }
+
+    const records = recordFileSet(cwd)
+    if (records.length === 0) {
+      console.log('No judgment records found — nothing to baseline.')
+      process.exit(0)
+    }
+
+    // Existence is decided by the FILESYSTEM and the write is exclusive (O_EXCL).
+    // A parsed-value check was wrong twice over: a manifest whose contents are
+    // literally `null` parses to null and would read as "absent" (overwriting a
+    // real baseline), and a check-then-write race let two initializers both pass
+    // the check. Re-baselining over an existing manifest is the laundering step,
+    // so it must fail on the write itself, not on an advisory look.
+    let hashes
+    try {
+      hashes = computeRecordHashes(cwd)
+    } catch (e) {
+      if (e?.code === 'JUDGMENT_RECORD_MALFORMED') {
+        console.error(`Refusing to baseline: ${e.message}`)
+        console.error('A malformed record cannot be trusted as-is — fix or remove it, then re-run.')
+        process.exit(1)
+      }
+      throw e
+    }
+
+    try {
+      initManifestExclusive(cwd, hashes)
+    } catch (e) {
+      if (e?.code === 'EEXIST') {
+        console.error(`A judgment record baseline already exists: ${manifestPathFor(cwd)}`)
+        console.error('`guard init` will not overwrite it — that would launder any raw record edit.')
+        console.error('Use `compose guard verify --fix` for projection drift, or the judgment_* tools to change records.')
+        process.exit(1)
+      }
+      throw e
+    }
+
+    console.log(`Baselined ${records.length} judgment record${records.length === 1 ? '' : 's'}.`)
+    console.log('These records are trusted AS-IS: there is no prior attestation to verify them against.')
+    console.log('From here, drift detection reports any careless change that does not go through the judgment tools.')
+    console.log(`Commit ${manifestPathFor(cwd)} so the baseline travels with the repo and re-baselining shows up as a reviewable diff.`)
+    process.exit(0)
+  }
+
+  if (sub === 'verify') {
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+    const verifyArgs = args.slice(1)
+    const fix = verifyArgs.includes('--fix')
+    if (verifyArgs.some((arg) => arg !== '--fix') || verifyArgs.filter((arg) => arg === '--fix').length > 1) {
+      console.error('Usage: compose guard verify [--fix]')
+      process.exit(1)
+    }
+
+    const { verifyJudgmentCanon } = await import('../lib/judgment-verify.js')
+    const { regenerateProjections } = await import('../lib/judgment-gen.js')
+    const { computeRecordHashes, writeManifest } = await import('../lib/judgment-attest.js')
+
+    function formatProjectionFinding(finding) {
+      const match = /^(.*) \(([^)]+)\)$/.exec(finding)
+      return match ? `${match[1]} [${match[2]}]` : finding
+    }
+
+    function printDrift(result) {
+      console.error('Judgment canon drift detected:')
+      if (result.treeDrift.length > 0) {
+        console.error('  Tree drift (records-anchored file set):')
+        for (const finding of result.treeDrift) {
+          console.error(`    - ${finding.path} [${finding.kind}]`)
+        }
+      }
+      if (result.projectionDrift.length > 0) {
+        console.error('  Projection drift (records-anchored):')
+        for (const finding of result.projectionDrift) {
+          console.error(`    - ${formatProjectionFinding(finding)}`)
+        }
+      }
+      if (result.recordDrift.length > 0) {
+        console.error('  Record drift detection (careless changes only):')
+        for (const finding of result.recordDrift) {
+          console.error(`    - ${finding.path} [${finding.kind}]`)
+        }
+      }
+    }
+
+    let result = await verifyJudgmentCanon(cwd)
+
+    if (fix) {
+      const projectionDriftBefore = result.projectionDrift
+      if (projectionDriftBefore.length > 0) {
+        regenerateProjections(cwd)
+
+        // `--fix` NEVER writes the record manifest. The earlier "refresh it when
+        // records already passed" branch was both unnecessary and unsafe:
+        // unnecessary because a passing record set already matches the manifest,
+        // and unsafe because verifyJudgmentCanon releases the judgment lock when
+        // it returns, so a raw edit landing between that verdict and the rewrite
+        // would be stamped — laundering a hand-edit through the repair flag,
+        // exactly what R1 forbids. Projections are derived and safe to
+        // regenerate; records are not, so `--fix` simply does not touch them.
+        if (result.recordDrift.length > 0) {
+          console.log('Record drift was deliberately not fixed: --fix cannot bless record edits; use the judgment tools to make record changes.')
+        }
+
+        result = await verifyJudgmentCanon(cwd)
+        const remainingProjectionDrift = new Set(result.projectionDrift)
+        const repaired = projectionDriftBefore.filter((finding) => !remainingProjectionDrift.has(finding))
+        if (repaired.length > 0) {
+          console.log('Fixed projection drift:')
+          for (const finding of repaired) {
+            console.log(`  - ${formatProjectionFinding(finding)}`)
+          }
+        }
+      } else {
+        console.log('No projection drift to fix.')
+        if (result.recordDrift.length > 0) {
+          console.log('Record drift was deliberately not fixed: --fix cannot bless record edits; use the judgment tools to make record changes.')
+        }
+      }
+
+      if (result.treeDrift.length > 0) {
+        console.log('Tree drift was not fixed: --fix only regenerates derived projections.')
+      }
+    }
+
+    if (result.ok) {
+      console.log('Judgment canon drift detection passed.')
+      process.exit(0)
+    }
+
+    printDrift(result)
+    process.exit(1)
+  }
+
+  if (sub === 'install') {
+    if (!exSync(hookScript)) {
+      console.error(`Error: hook script missing at ${hookScript}`)
+      console.error('It is a tracked source file — ensure your checkout includes .claude/hooks/canon-guard.mjs')
+      process.exit(1)
+    }
+    const { settings, changed } = installGuardHook(readSettings())
+    if (changed) {
+      writeSettings(settings)
+      console.log('Installed canon-guard PreToolUse hook in .claude/settings.json')
+    } else {
+      console.log('canon-guard hook already installed (current).')
+    }
+    console.log(`  matcher: ${HOOK_MATCHER}`)
+    console.log(`  command: ${HOOK_COMMAND}`)
+    process.exit(0)
+  }
+
+  if (sub === 'uninstall') {
+    const { settings, changed } = uninstallGuardHook(readSettings())
+    if (changed) {
+      writeSettings(settings)
+      console.log('Removed canon-guard hook from .claude/settings.json')
+    } else {
+      console.log('No canon-guard hook installed.')
+    }
+    process.exit(0)
+  }
+
+  if (!sub || sub === 'status') {
+    const st = guardHookStatus(readSettings())
+    const scriptState = exSync(hookScript) ? 'present' : 'MISSING'
+    if (st.state === 'installed') console.log('canon-guard: installed (current)')
+    else if (st.state === 'stale') console.log('canon-guard: installed (stale — re-run `compose guard install`)')
+    else console.log('canon-guard: absent — run `compose guard install`')
+    console.log(`  hook script: ${scriptState} (${hookScript})`)
+    // Derived from the registry, never hardcoded: a literal string here
+    // silently under-reported the guarded set as soon as COMP-CANON-OVERRIDE
+    // widened it. "Claude-runtime only" is not modesty — Bash and Codex writes
+    // never reach this hook (drift detection, not enforcement).
+    const { guardedDisplaysFor } = await import('../lib/canon-registry.js')
+    for (const pattern of guardedDisplaysFor('hook')) {
+      console.log(`  guards: ${pattern} (Write|Edit|NotebookEdit) — Claude-runtime only`)
+    }
+    // `compose guard status` must keep working outside a workspace (it always
+    // has, for the canon-guard hook state above); only the newer `signing:`
+    // block needs a resolved workspace, so resolve it tolerantly here instead
+    // of going through resolveCwdWithWorkspace -> dieOnWorkspaceError.
+    let signingWorkspaceRoot = null
+    try {
+      const wsId = getWorkspaceFlag(args)
+      signingWorkspaceRoot = resolveWorkspace({ workspaceId: wsId === '__COMPOSE_WORKSPACE_ID__' ? null : wsId }).root
+    } catch { /* no workspace resolved — signing block is skipped below */ }
+
+    if (!signingWorkspaceRoot) {
+      console.log('signing: (no workspace resolved — run inside a compose workspace or pass --workspace)')
+      if (args.includes('--prune')) process.exit(1)
+      process.exit(0)
+    }
+
+    const { pruneGuardGenerations, signingStatusLines } = await import('../lib/guard-cli.js')
+    if (args.includes('--prune')) {
+      const pruned = await pruneGuardGenerations(signingWorkspaceRoot)
+      for (const line of pruned.lines) console.log(line)
+      if (pruned.status === 'refused') process.exit(1)
+    }
+    const signing = await signingStatusLines(signingWorkspaceRoot, { coverage: args.includes('--coverage') })
+    for (const line of signing.lines) console.log(line)
+    process.exit(0)
+  }
+
+  console.error(`Unknown guard subcommand: "${sub}". Use: install | uninstall | status [--prune] [--coverage] | init | verify [--fix] | enrol | sign | descriptors`)
+  process.exit(1)
+}
+
 if (cmd === 'validate') {
   // compose validate [--scope=feature|project] [--code=CODE] [--block-on=error|warning|info] [--json]
   let scope = 'project'
@@ -2105,6 +2576,7 @@ if (cmd === 'experiment') {
 }
 
 if (cmd === 'build') {
+  await emitDriftNudge()
   // Parse --cwd <path> for cross-repo builds
   let agentWorkDir = null
   const cwdIdx = args.indexOf('--cwd')
@@ -2138,6 +2610,29 @@ if (cmd === 'build') {
       console.error('Error: --template requires a name argument')
       process.exit(1)
     }
+    // COMP-PIPELINE-QUARANTINE round 3: refuse templates that belong to another
+    // command's runner. `compose build` is feature mode, which sends
+    // {featureCode, description, implementer_agent, reviewer_agent}; these four
+    // specs declare a different runner's envelope (task / projectName+intent /
+    // gateCommands), so selecting one here resolves the spec and then fails at
+    // plan time with an unhelpful error. Point at the command that can drive it.
+    const MODE_BOUND_TEMPLATES = {
+      'bug-fix': 'compose fix <bug-code>',
+      plan: 'compose plan "<intent>"',
+      new: 'compose new',
+      gsd: 'compose gsd <feature-code>',
+    }
+    // Compare the BASENAME: resolveTemplatePath builds `<cwd>/pipelines/<name>.stratum.yaml`
+    // via join(), which normalizes away a leading `./`, so `--template ./bug-fix`
+    // resolved the same spec while slipping past an exact-string check.
+    const templateKey = basename(String(templateValue)).replace(/\.stratum\.ya?ml$/, '')
+    if (MODE_BOUND_TEMPLATES[templateKey]) {
+      console.error(
+        `Error: --template ${templateValue} is not a build template — it belongs to ` +
+        `\`${MODE_BOUND_TEMPLATES[templateKey]}\`, which supplies the inputs it declares.`
+      )
+      process.exit(1)
+    }
     templateName = templateValue
   }
   if (teamTemplate && !templateName) {
@@ -2185,10 +2680,16 @@ if (cmd === 'build') {
     }
   }
 
+  const { root: buildCwd } = resolveCwdWithWorkspace(args)
+
   // Multiple codes: compose build FEAT-1 FEAT-2 FEAT-3
   const isMulti = featureCodes.length > 1
-  // Single prefix: compose build STRAT-COMP (no trailing digit)
-  const isPrefix = featureCodes.length === 1 && featureCode && !/\d$/.test(featureCode)
+  // Single prefix: compose build STRAT-COMP (no trailing digit). An exact
+  // feature on disk always wins over the prefix heuristic — codes like
+  // COMP-SEMVER-STRICT have no trailing digit but are single features.
+  const isExactFeature = featureCodes.length === 1 && featureCode &&
+    existsSync(join(buildCwd, 'docs', 'features', featureCode, 'feature.json'))
+  const isPrefix = featureCodes.length === 1 && featureCode && !isExactFeature && !/\d$/.test(featureCode)
   const isBatch = all || isPrefix || isMulti
 
   if (abort && isBatch) {
@@ -2261,7 +2762,6 @@ if (cmd === 'build') {
   // and there's no bundled preset fallback — so when --quick is requested and
   // that file is absent, treat it as init-needed (runInit re-seeds it) rather
   // than letting runBuild fail later with "Lifecycle spec not found".
-  const { root: buildCwd } = resolveCwdWithWorkspace(args)
   const needsInit =
     !existsSync(join(buildCwd, '.compose', 'compose.json')) ||
     !existsSync(join(buildCwd, 'pipelines', 'build.stratum.yaml')) ||
@@ -2374,7 +2874,11 @@ if (cmd === 'build') {
   const { root: fixCwd } = resolveCwdWithWorkspace(args)
   if (!existsSync(join(fixCwd, '.compose', 'compose.json')) || !existsSync(join(fixCwd, 'pipelines', 'bug-fix.stratum.yaml'))) {
     console.log('Running compose init...\n')
-    await runInit(args.filter(a => a.startsWith('--')))
+    // Thread the RESOLVED workspace root, exactly as the build path does. Without
+    // it runInit seeds process.cwd(), which differs from fixCwd when `compose fix`
+    // is invoked from a subdirectory — the guard checks fixCwd but the seed lands
+    // elsewhere, so the run still fails with the same missing-spec error.
+    await runInit(args.filter(a => a.startsWith('--')), fixCwd)
     console.log('')
   }
 
@@ -2451,6 +2955,7 @@ if (cmd === 'build') {
     })
   })
 } else if (cmd === 'plan') {
+  await emitDriftNudge()
   // compose plan "<intent>" — runs the plan.stratum.yaml product-planning
   // lifecycle (explore_design → plan → ship). Thin delegation to runBuild() with
   // template='plan', mode='plan'. Derives a PLAN-<slug> code from the intent
@@ -2801,306 +3306,82 @@ if (cmd === 'build') {
     }
     process.exit(1)
   })
-} else if (cmd === 'ideabox') {
+} else if (cmd === 'judgment') {
   // ---------------------------------------------------------------------------
-  // compose ideabox — idea management CLI
+  // compose judgment trace <slug> — causal ancestry of a position
+  // (COMP-JUDGMENT-PRECEDENT slice A). Read-only. The store has always persisted
+  // revision chains and the `supersedes` ref; nothing surfaced them.
   // ---------------------------------------------------------------------------
-  const ibSubcmd = args[0]
-  const { root: ibCwd } = resolveCwdWithWorkspace(args)
-
-  // Resolve compose config (paths, etc.)
-  function loadComposeConfig(cwd) {
-    const cfgPath = join(cwd, '.compose', 'compose.json')
-    if (existsSync(cfgPath)) {
-      try { return JSON.parse(readFileSync(cfgPath, 'utf-8')) } catch {}
-    }
-    return {}
-  }
-  function getIdeaboxRelPath(cwd) {
-    return loadComposeConfig(cwd)?.paths?.ideabox || 'docs/product/ideabox.md'
-  }
-  const ibConfig = loadComposeConfig(ibCwd)
-
-  const {
-    parseIdeabox: _parseIdeabox,
-    serializeIdeabox: _serializeIdeabox,
-    addIdea: _addIdea,
-    promoteIdea: _promoteIdea,
-    killIdea: _killIdea,
-    setPriority: _setPriority,
-    loadLens: _loadLens,
-    readIdeabox: _readIdeabox,
-    writeIdeabox: _writeIdeabox,
-    addDiscussion: _addDiscussion,
-  } = await import('../lib/ideabox.js')
-
-  const ibRelPath = getIdeaboxRelPath(ibCwd)
-  // ibFullPath is used for direct file ops (existsSync/mkdirSync/writeFileSync/
-  // display); resolve it absolute-safe. ibRelPath stays relative because the
-  // lib readIdeabox/writeIdeabox readers re-join it under ibCwd.
-  const { resolveIdeaboxPath: _resolveIdeaboxPathCli } = await import('../lib/project-paths.js')
-  const ibFullPath = _resolveIdeaboxPathCli(ibCwd)
-
-  if (!ibSubcmd || ibSubcmd === '--help' || ibSubcmd === '-h') {
-    console.log('Usage: compose ideabox <subcommand>')
-    console.log('')
-    console.log('Subcommands:')
-    console.log('  add "<title>"                Add a new idea')
-    console.log('  list                         List all ideas')
-    console.log('  promote <ID>                 Mark idea as PROMOTED (creates feature folder)')
-    console.log('  kill <ID> "<reason>"         Move idea to Killed Ideas')
-    console.log('  pri <ID> <P0|P1|P2>          Set priority')
-    console.log('  discuss <ID> "<comment>"     Add a discussion comment')
-    console.log('  triage [--lens <name>]       Walk untriaged ideas and assign priorities')
-    process.exit(0)
+  // `args` excludes the command itself (const [,, cmd, ...args]), so the
+  // subcommand is args[0] — same shape as `subcmd = args[0]` elsewhere.
+  const sub = args[0]
+  if (sub !== 'trace') {
+    console.log('Usage: compose judgment trace <slug> [--json]')
+    process.exit(sub ? 1 : 0)
   }
-
-  if (ibSubcmd === 'add') {
-    const title = args.slice(1).find(a => !a.startsWith('-')) || args[1]
-    if (!title) {
-      console.error('Usage: compose ideabox add "<title>" [--source "..."] [--desc "..."] [--cluster "..."]')
-      process.exit(1)
-    }
-    // Parse optional flags
-    const sourceIdx = args.indexOf('--source')
-    const descIdx = args.indexOf('--desc')
-    const clusterIdx = args.indexOf('--cluster')
-    const tagsIdx = args.indexOf('--tags')
-    const source = sourceIdx !== -1 ? args[sourceIdx + 1] : ''
-    const description = descIdx !== -1 ? args[descIdx + 1] : ''
-    const cluster = clusterIdx !== -1 ? args[clusterIdx + 1] : null
-    const tagsRaw = tagsIdx !== -1 ? args[tagsIdx + 1] : ''
-    const tags = tagsRaw ? tagsRaw.split(',').map(t => t.trim().startsWith('#') ? t.trim() : `#${t.trim()}`) : []
-
-    if (!existsSync(ibFullPath)) {
-      const { IDEABOX_TEMPLATE } = await import('../lib/ideabox.js')
-      mkdirSync(dirname(ibFullPath), { recursive: true })
-      writeFileSync(ibFullPath, IDEABOX_TEMPLATE)
-    }
-
-    const parsed = _readIdeabox(ibCwd, ibRelPath)
-    _addIdea(parsed, { title, description, source, tags, cluster })
-    _writeIdeabox(ibCwd, ibRelPath, parsed)
-    const newIdea = parsed.ideas[parsed.ideas.length - 1]
-    console.log(`Added ${newIdea.id}: ${newIdea.title}`)
-    process.exit(0)
+  const slug = args[1]
+  if (!slug || slug.startsWith('--')) {
+    console.error('Usage: compose judgment trace <slug> [--json]')
+    process.exit(1)
   }
-
-  if (ibSubcmd === 'list') {
-    if (!existsSync(ibFullPath)) {
-      console.log('No ideabox found. Run: compose ideabox add "<title>"')
-      process.exit(0)
-    }
-    const parsed = _readIdeabox(ibCwd, ibRelPath)
-    if (parsed.ideas.length === 0 && parsed.killed.length === 0) {
-      console.log('No ideas yet.')
+  const { root: jCwd } = resolveCwdWithWorkspace(args)
+  const { getJudgmentTrace } = await import('../lib/judgment-writer.js')
+  try {
+    const t = await getJudgmentTrace(jCwd, slug)
+    if (args.includes('--json')) {
+      console.log(JSON.stringify(t, null, 2))
       process.exit(0)
     }
-
-    // Group by status then priority
-    const byStatus = {}
-    for (const idea of parsed.ideas) {
-      const s = idea.status.startsWith('PROMOTED') ? 'PROMOTED' : idea.status
-      if (!byStatus[s]) byStatus[s] = []
-      byStatus[s].push(idea)
-    }
-
-    const statusOrder = ['NEW', 'DISCUSSING', 'PROMOTED']
-    const priorityOrder = { P0: 0, P1: 1, P2: 2, '—': 3 }
-
-    for (const status of statusOrder) {
-      const group = byStatus[status]
-      if (!group || group.length === 0) continue
-      group.sort((a, b) => (priorityOrder[a.priority] ?? 3) - (priorityOrder[b.priority] ?? 3))
-      console.log(`\n[${status}]`)
-      for (const idea of group) {
-        const pri = idea.priority !== '—' ? ` [${idea.priority}]` : ''
-        const tags = idea.tags.length ? ` ${idea.tags.join(' ')}` : ''
-        console.log(`  ${idea.id}${pri}  ${idea.title}${tags}`)
+    console.log(`${t.slug}  [${t.status}]`)
+    for (const r of t.revisions) {
+      const marks = [r.retracted ? 'retracted' : null, r.conviction ? `conviction=${r.conviction}` : null]
+        .filter(Boolean).join(' ')
+      const d = Array.isArray(r.delta) && r.delta.length ? `  (${r.delta.join('; ')})` : ''
+      console.log(`  r${r.rev}  ${r.written_at ?? '—'}  ${r.claim_count} claim(s)${marks ? '  ' + marks : ''}${d}`)
+    }
+    if (Array.isArray(t.supersededBy) && t.supersededBy.length) {
+      console.log(`  superseded by: ${t.supersededBy.map(s => `${s.slug}#r${s.rev}`).join(', ')}`)
+    }
+    let anc = t.supersedes, depth = 1
+    while (anc) {
+      const pin = anc.pinned ? `#r${anc.rev}` : ''
+      console.log(`${'  '.repeat(depth)}↳ supersedes ${anc.slug}${pin}  [${anc.status}]`)
+      for (const r of anc.revisions) {
+        const d = Array.isArray(r.delta) && r.delta.length ? `  (${r.delta.join('; ')})` : ''
+        console.log(`${'  '.repeat(depth + 1)}r${r.rev}  ${r.written_at ?? '—'}  conviction=${r.conviction ?? '—'}${d}`)
       }
+      anc = anc.supersedes; depth++
     }
-
-    if (parsed.killed.length > 0) {
-      console.log(`\n[KILLED] (${parsed.killed.length})`)
-      for (const idea of parsed.killed) {
-        console.log(`  ${idea.id}  ${idea.title}  — ${idea.killedReason}`)
-      }
-    }
-    process.exit(0)
-  }
-
-  if (ibSubcmd === 'promote') {
-    const ideaId = args[1]
-    if (!ideaId) {
-      console.error('Usage: compose ideabox promote <ID> [<FEATURE-CODE>]')
-      process.exit(1)
-    }
-    const featureCode = args[2] || ''
-
-    if (!existsSync(ibFullPath)) {
-      console.error(`Ideabox not found at ${ibFullPath}`)
-      process.exit(1)
-    }
-
-    const parsed = _readIdeabox(ibCwd, ibRelPath)
-    const idea = parsed.ideas.find(i => i.id.toUpperCase() === ideaId.toUpperCase())
-    if (!idea) {
-      console.error(`Idea not found: ${ideaId}`)
-      process.exit(1)
-    }
-
-    // Generate feature code if not provided
-    let resolvedCode = featureCode
-    if (!resolvedCode) {
-      // Derive a slug from the title
-      const slug = idea.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 20).replace(/-+$/, '')
-      resolvedCode = `IDEA-${idea.num}-${slug}`.toUpperCase()
-    }
-
-    // Create feature folder if missing — respect paths.features (may be
-    // relocated outside ibCwd — COMP-PATHS-EXTERNAL; resolve absolute, no re-root)
-    const featuresBase = resolveFeaturesPathFromConfig(ibCwd, ibConfig)
-    const featuresDir = join(featuresBase, resolvedCode)
-    if (!existsSync(featuresDir)) {
-      // COMP-MCP-VALIDATE-1: route through the validated writer (schema-guarded)
-      // instead of a raw writeFileSync.
-      const { writeFeature } = await import('../lib/feature-json.js')
-      writeFeature(ibCwd, {
-        code: resolvedCode,
-        description: idea.title,
-        status: 'PLANNED',
-        promotedFrom: ideaId,
-        createdAt: new Date().toISOString(),
-      }, featuresBase)
-      console.log(`Created feature folder: ${join(featuresBase, resolvedCode)}/`)
-    }
-
-    _promoteIdea(parsed, ideaId, resolvedCode)
-    _writeIdeabox(ibCwd, ibRelPath, parsed)
-    console.log(`Promoted ${ideaId} → ${resolvedCode}`)
-    process.exit(0)
-  }
-
-  if (ibSubcmd === 'kill') {
-    const ideaId = args[1]
-    const reason = args[2] || ''
-    if (!ideaId) {
-      console.error('Usage: compose ideabox kill <ID> "<reason>"')
-      process.exit(1)
-    }
-    if (!existsSync(ibFullPath)) {
-      console.error(`Ideabox not found at ${ibFullPath}`)
-      process.exit(1)
-    }
-
-    const parsed = _readIdeabox(ibCwd, ibRelPath)
-    _killIdea(parsed, ideaId, reason)
-    _writeIdeabox(ibCwd, ibRelPath, parsed)
-    console.log(`Killed ${ideaId}: ${reason}`)
-    process.exit(0)
-  }
-
-  if (ibSubcmd === 'pri') {
-    const ideaId = args[1]
-    const priority = args[2]
-    if (!ideaId || !priority) {
-      console.error('Usage: compose ideabox pri <ID> <P0|P1|P2>')
-      process.exit(1)
-    }
-    if (!existsSync(ibFullPath)) {
-      console.error(`Ideabox not found at ${ibFullPath}`)
-      process.exit(1)
-    }
-
-    const parsed = _readIdeabox(ibCwd, ibRelPath)
-    _setPriority(parsed, ideaId, priority)
-    _writeIdeabox(ibCwd, ibRelPath, parsed)
-    console.log(`Set ${ideaId} priority → ${priority}`)
+    if (t.cycle) console.error(`  WARNING: supersession cycle — ${t.cycle}`)
+    for (const w of t.warnings) console.error(`  WARNING: ${w}`)
     process.exit(0)
+  } catch (err) {
+    console.error(err?.message || String(err))
+    process.exit(1)
   }
-
-  if (ibSubcmd === 'discuss') {
-    const ideaId = args[1]
-    const comment = args[2]
-    if (!ideaId || !comment) {
-      console.error('Usage: compose ideabox discuss <ID> "<comment>"')
-      process.exit(1)
-    }
-    if (!existsSync(ibFullPath)) {
-      console.error(`Ideabox not found at ${ibFullPath}`)
-      process.exit(1)
-    }
-
-    const parsed = _readIdeabox(ibCwd, ibRelPath)
-    _addDiscussion(parsed, ideaId, 'human', comment)
-    _writeIdeabox(ibCwd, ibRelPath, parsed)
-    const today = new Date().toISOString().slice(0, 10)
-    console.log(`[${today}] human: ${comment}`)
-    process.exit(0)
+} else if (cmd === 'ideabox') {
+  // ---------------------------------------------------------------------------
+  // compose ideabox — idea management CLI
+  //
+  // The implementation lives in lib/ideabox-cli.js (COMP-PLAN-IDEA-UNIFY S3b-1).
+  // It was ~300 lines inline here, which made the cutover to the record store
+  // testable only by spawning a subprocess. Behaviour is unchanged; the backing
+  // store is not — every mutation now writes a record and re-renders
+  // docs/product/ideabox.md as a projection of them.
+  // ---------------------------------------------------------------------------
+  const { root: ibCwd } = resolveCwdWithWorkspace(args)
+  let ibConfig = {}
+  const ibCfgPath = join(ibCwd, '.compose', 'compose.json')
+  if (existsSync(ibCfgPath)) {
+    try { ibConfig = JSON.parse(readFileSync(ibCfgPath, 'utf-8')) } catch {}
   }
-
-  if (ibSubcmd === 'triage') {
-    const lensIdx = args.indexOf('--lens')
-    const lensName = lensIdx !== -1 ? args[lensIdx + 1] : null
-
-    if (!existsSync(ibFullPath)) {
-      console.log('No ideabox found. Run: compose ideabox add "<title>" first.')
-      process.exit(0)
-    }
-
-    const parsed = _readIdeabox(ibCwd, ibRelPath)
-    const untriaged = parsed.ideas.filter(i => i.priority === '—' && i.status === 'NEW')
-
-    if (untriaged.length === 0) {
-      console.log('No untriaged ideas.')
-      process.exit(0)
-    }
-
-    let lens = null
-    if (lensName) {
-      lens = _loadLens(ibCwd, lensName)
-      if (!lens) {
-        console.warn(`Lens not found: docs/product/ideabox-priority-${lensName}.md`)
-      } else {
-        console.log(`Using lens: ${lensName}`)
-      }
-    }
-
-    // Interactive triage using readline
-    const { createInterface } = await import('node:readline')
-    const rl = createInterface({ input: process.stdin, output: process.stdout })
-    const question = (q) => new Promise(resolve => rl.question(q, resolve))
-
-    let changed = false
-    for (const idea of untriaged) {
-      console.log(`\n${idea.id}: ${idea.title}`)
-      if (idea.description) console.log(`  ${idea.description.slice(0, 120)}`)
-      if (lens) console.log(`  [lens: ${lensName}]`)
-
-      const ans = await question('  Priority [P0/P1/P2/skip]: ')
-      const p = ans.trim().toUpperCase()
-      if (['P0', 'P1', 'P2'].includes(p)) {
-        _setPriority(parsed, idea.id, p)
-        changed = true
-        console.log(`  Set ${idea.id} → ${p}`)
-      } else {
-        console.log('  Skipped')
-      }
-    }
-
-    rl.close()
-
-    if (changed) {
-      _writeIdeabox(ibCwd, ibRelPath, parsed)
-      console.log('\nSaved.')
-    }
-    process.exit(0)
+  const { runIdeaboxCommand } = await import('../lib/ideabox-cli.js')
+  try {
+    process.exit(await runIdeaboxCommand(ibCwd, args, { config: ibConfig }))
+  } catch (err) {
+    console.error(err?.message || String(err))
+    process.exit(1)
   }
-
-  console.error(`Unknown ideabox subcommand: ${ibSubcmd}`)
-  console.error('Run: compose ideabox --help')
-  process.exit(1)
-
 } else if (cmd === 'qa-scope') {
   // ---------------------------------------------------------------------------
   // compose qa-scope <featureCode>
@@ -3225,6 +3506,96 @@ if (cmd === 'build') {
     process.exit(1)
   }
 
+} else if (cmd === 'lineage') {
+  // ---------------------------------------------------------------------------
+  // compose lineage <stamp|stale|show> --feature <FC> [--changed <file>] [--format text|json]
+  // COMP-PROV-LINEAGE: W3C PROV-O artifact lineage (vocabulary only, no RDF).
+  //   stamp — materialise wasGeneratedBy/wasDerivedFrom markers into artifacts
+  //   stale — reachability query: given a --changed artifact, list stale descendants
+  //   show  — print the derivation graph for the feature's canonical artifacts
+  // See docs/features/COMP-PROV-LINEAGE/. Read-only except `stamp`; no server.
+  // ---------------------------------------------------------------------------
+  const lineageSub = args[0]
+  const flagVal = (flag) => {
+    const i = args.indexOf(flag)
+    return i !== -1 && args[i + 1] ? args[i + 1] : null
+  }
+  const feature = flagVal('--feature')
+  const format = flagVal('--format') || 'text'
+  if (!feature || !['stamp', 'stale', 'show'].includes(lineageSub)) {
+    console.error('usage: compose lineage <stamp|stale|show> --feature <FC> [--changed <file>] [--format text|json]')
+    process.exit(1)
+  }
+  const { isFeatureCode } = await import('../lib/feature-code.js')
+  if (!isFeatureCode(feature)) {
+    console.error(`Invalid feature code: ${JSON.stringify(feature)} (must match ${'^[A-Z][A-Z0-9-]*[A-Z0-9]$'})`)
+    process.exit(1)
+  }
+  const { join } = await import('node:path')
+  const { existsSync } = await import('node:fs')
+  const { resolveFeaturesPath } = await import('../lib/project-paths.js')
+  const {
+    stampFeatureLineage, findStaleDescendants, buildDerivationGraph,
+  } = await import('../lib/lineage.js')
+  const featureDir = join(resolveFeaturesPath(process.cwd()), feature)
+  if (!existsSync(featureDir)) {
+    console.error(`No feature folder at ${featureDir}`)
+    process.exit(1)
+  }
+
+  if (lineageSub === 'stamp') {
+    const results = stampFeatureLineage(featureDir)
+    if (format === 'json') {
+      console.log(JSON.stringify(results, null, 2))
+    } else if (results.length === 0) {
+      console.log(`No canonical artifacts found in ${feature}.`)
+    } else {
+      const changed = results.filter(r => r.changed).length
+      console.log(`Stamped lineage on ${feature} — ${changed} of ${results.length} artifact(s) updated:\n`)
+      for (const r of results) {
+        const from = r.wasDerivedFrom.length ? r.wasDerivedFrom.join(', ') : '(origin)'
+        console.log(`  ${r.changed ? '✓' : '·'} ${r.file}  wasGeneratedBy=${r.wasGeneratedBy ?? '?'}  wasDerivedFrom=${from}`)
+      }
+    }
+  } else if (lineageSub === 'stale') {
+    const changedFile = flagVal('--changed')
+    if (!changedFile) {
+      console.error('compose lineage stale: --changed <file> is required')
+      process.exit(1)
+    }
+    // Must be a bare filename inside the feature folder — no path traversal.
+    if (changedFile.includes('/') || changedFile.includes('\\') || changedFile.includes('..')) {
+      console.error(`compose lineage stale: --changed must be a bare filename, got ${JSON.stringify(changedFile)}`)
+      process.exit(1)
+    }
+    const results = findStaleDescendants(featureDir, changedFile)
+    if (format === 'json') {
+      console.log(JSON.stringify(results, null, 2))
+    } else {
+      const stale = results.filter(r => r.stale)
+      if (results.length === 0) {
+        console.log(`${changedFile} has no downstream artifacts in ${feature}.`)
+      } else if (stale.length === 0) {
+        console.log(`No stale descendants of ${changedFile} — all ${results.length} downstream artifact(s) are newer.`)
+      } else {
+        console.log(`${stale.length} artifact(s) downstream of ${changedFile} are STALE (older than the change):\n`)
+        for (const r of stale) console.log(`  ⚠ ${r.file}`)
+      }
+    }
+  } else if (lineageSub === 'show') {
+    const graph = buildDerivationGraph(featureDir)
+    if (format === 'json') {
+      console.log(JSON.stringify(Object.fromEntries(graph), null, 2))
+    } else if (graph.size === 0) {
+      console.log(`No canonical artifacts found in ${feature}.`)
+    } else {
+      console.log(`Derivation graph for ${feature}:\n`)
+      for (const [file, parents] of graph) {
+        console.log(parents.length ? `  ${file}  ⟵  ${parents.join(', ')}` : `  ${file}  (origin)`)
+      }
+    }
+  }
+
 } else if (cmd === 'gates' || cmd === 'gate') {
   // ---------------------------------------------------------------------------
   // compose gate list [--item <id>] [--status pending|all|resolved] [--format text|json]
@@ -3822,6 +4193,42 @@ if (cmd === 'build') {
   console.error('  compose smartmemory sync [--dry-run] [--feature <CODE>]')
   process.exit(1)
 
+} else if (cmd === 'metrics') {
+  // ---------------------------------------------------------------------------
+  // compose metrics [--since <duration|ISO>] [--feature <code>] [--json]
+  // ---------------------------------------------------------------------------
+  const { root: cwd } = resolveCwdWithWorkspace(args)
+  let since = null
+  let feature = null
+  let json = false
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (arg === '--json') {
+      json = true
+      continue
+    }
+    if (arg === '--since' || arg === '--feature') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('--')) {
+        console.error(`compose metrics: ${arg} requires a value`)
+        process.exit(1)
+      }
+      if (arg === '--since') since = value
+      else feature = value
+      index++
+      continue
+    }
+    console.error(`compose metrics: unknown flag ${arg}`)
+    process.exit(1)
+  }
+
+  const { collectDispatchMetrics, renderDispatchMetrics } = await import('../lib/dispatch-metrics.js')
+  const report = collectDispatchMetrics(cwd, { since, feature })
+  if (json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  else process.stdout.write(renderDispatchMetrics(report))
+  process.exit(0)
+
 } else {
   console.error(`Unknown command: ${cmd}`)
   process.exit(1)