@smartmemory/compose 0.3.7 → 0.4.0

package/bin/compose.js

@@ -90,8 +90,13 @@ function resolveCwdWithWorkspace(args) {
 // --team flag (COMP-TEAMS)
 // ---------------------------------------------------------------------------
 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 { loadDeps, checkExternalSkills, printDepReport, buildDepReport, checkExternalBinaries, printBinaryReport, buildBinaryReport, installMissingPlugins, printInstallReport } from '../lib/deps.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,40 +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('  metrics [--since <duration|ISO>] [--feature <code>] [--json]  Report dispatch, settlement, and triage metrics')
-  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('  guard     Manage the canon guard and drift detection (install|uninstall|status|init|verify [--fix])')
-  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)
 }
 
@@ -197,7 +172,7 @@ function detectAgents() {
  *   - PACKAGE_ROOT/.claude/skills/*   (compose skill)
  *   - PACKAGE_ROOT/skills/*           (stratum base skill)
  */
-function syncSkills(agents) {
+function syncSkills(agents, setupFlags = []) {
   // Collect source skills: { name -> sourcePath }
   const sourceSkills = new Map()
   const skillSourceDirs = [
@@ -296,12 +271,28 @@ function syncSkills(agents) {
   // actionable install hints. Soft check: warnings only, exit code unaffected.
   const deps = loadDeps(PACKAGE_ROOT)
   if (deps) {
-    const result = checkExternalSkills(deps)
+    let result = checkExternalSkills(deps)
+    // COMP-DEPS-AUTOINSTALL: close the loop rather than printing a hint and
+    // running degraded. Only required deps with a `plugin` spec are installed.
+    // The report printed below is the POST-install scan, so what the user reads
+    // is the state they actually end up in, never the state we started from.
+    const installReport = installMissingPlugins(result, { enabled: pluginInstallEnabled(setupFlags) })
+    printInstallReport(installReport)
+    if (installReport.installed.length > 0) result = checkExternalSkills(deps)
     printDepReport(result)
     printBinaryReport(checkExternalBinaries(deps))
   }
 }
 
+/**
+ * COMP-DEPS-AUTOINSTALL opt-out. Off for `--no-install-deps` and for
+ * COMPOSE_NO_PLUGIN_INSTALL=1 (CI, sandboxes, anyone who manages plugins by hand).
+ */
+function pluginInstallEnabled(flags = []) {
+  if (process.env.COMPOSE_NO_PLUGIN_INSTALL === '1') return false
+  return !flags.includes('--no-install-deps')
+}
+
 // ---------------------------------------------------------------------------
 // compose doctor — re-run the external dep check
 // ---------------------------------------------------------------------------
@@ -568,10 +559,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)
@@ -580,10 +585,16 @@ 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
-  syncSkills(agents)
+  syncSkills(agents, flags)
 
   // 10. Summary
   console.log('')
@@ -597,7 +608,7 @@ async function runInit(flags, cwdOverride) {
 // compose setup — user-global skill setup
 // ---------------------------------------------------------------------------
 
-function runSetup() {
+function runSetup(setupFlags = []) {
   // 1. Sync all compose-owned skills to detected agents.
   //    If none detected, fall back to Claude — setup is unconditional
   //    "install global skill" per its help text.
@@ -605,7 +616,7 @@ function runSetup() {
   if (agents.length === 0) {
     agents = [{ name: 'claude', skillDir: join(homedir(), '.claude', 'skills', 'stratum') }]
   }
-  syncSkills(agents)
+  syncSkills(agents, setupFlags)
 
 }
 
@@ -718,7 +729,7 @@ async function runUpdate(flags) {
   // Refresh global skills.
   console.log('')
   console.log('Refreshing global skill installation...')
-  runSetup()
+  runSetup(args)
 
   // If invoked from inside a Compose project, refresh project artifacts too
   if (existsSync(join(cwd, '.compose', 'compose.json'))) {
@@ -757,11 +768,73 @@ async function runUpdate(flags) {
   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)
 }
@@ -771,7 +844,7 @@ if (cmd === 'setup' || cmd === 'sync') {
   // agent skill dirs. The name `sync` better signals
   // the idempotent "reconcile local skills with this install" job (run it after
   // editing skills locally, when there's no new version to `update` to).
-  runSetup()
+  runSetup(args)
   process.exit(0)
 }
 
@@ -825,7 +898,7 @@ if (cmd === 'migrate-anon') {
 if (cmd === 'install') {
   // Backwards-compat: run both init + setup
   await runInit(args)
-  runSetup()
+  runSetup(args)
   process.exit(0)
 }
 
@@ -1161,38 +1234,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)
   }
 
@@ -1592,7 +1749,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)
@@ -1637,7 +1794,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')
@@ -1660,8 +1818,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
@@ -1698,7 +1861,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,
@@ -2142,11 +2346,42 @@ if (cmd === 'guard') {
     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})`)
-    console.log(`  guards: docs/judgment/** (Write|Edit|NotebookEdit) — Claude-runtime only`)
+    // 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 | init | verify [--fix]`)
+  console.error(`Unknown guard subcommand: "${sub}". Use: install | uninstall | status [--prune] [--coverage] | init | verify [--fix] | enrol | sign | descriptors`)
   process.exit(1)
 }
 
@@ -2357,6 +2592,7 @@ if (cmd === 'experiment') {
 }
 
 if (cmd === 'build') {
+  await emitDriftNudge()
   // Parse --cwd <path> for cross-repo builds
   let agentWorkDir = null
   const cwdIdx = args.indexOf('--cwd')
@@ -2390,6 +2626,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) {
@@ -2437,10 +2696,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) {
@@ -2513,7 +2778,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')) ||
@@ -2626,7 +2890,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('')
   }
 
@@ -2703,6 +2971,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
@@ -3053,306 +3322,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}`)
-      }
-    }
-
-    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}`)
+    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 (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 === '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}`)
-    process.exit(0)
-  }
-
-  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>
@@ -3477,6 +3522,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]