@smartmemory/compose 0.2.52-beta → 0.2.54-beta

package/.claude/skills/compose/SKILL.md

@@ -16,14 +16,6 @@ Both modes share Phase 6 (plan), Phase 7 (TDD execute + E2E + review loop + cove
 
 Before any phase begins, read project state via the `compose` MCP server (get_vision_items, get_phase_summary, get_blocked_items). Every feature OR bug maps to a vision item — check it exists, create it if not.
 
-## Platform Adaptation
-
-This SKILL.md uses **Claude Code** tool names (Skill, Agent/Task, EnterPlanMode, TodoWrite). On other harnesses, resolve each action to that harness's equivalent:
-
-- **Nous Hermes Agent** → `references/hermes-tools.md` (skills, `delegate_task` for subagents, MCP servers, AGENTS.md; Phase-6 plan mode degrades to a flat gate).
-
-The headless `compose build`/`compose fix` CLI is harness-agnostic — it runs from any shell and delegates agent execution to Stratum (Claude/Codex) regardless of the launching harness. The mapping files only matter for running the *interactive* lifecycle under a non-Claude-Code harness.
-
 ## Mode Selection
 
 `/compose` with no verb defaults to `build` for back-compat. Explicit verbs:

package/README.md

@@ -30,6 +30,17 @@ compose build TODO-1
   -> done: feature implemented, reviewed, tested, documented
 ```
 
+Starting from a fuzzy goal instead of a known feature? Use the planning lifecycle:
+
+```bash
+compose plan "a tool that summarizes my team's standups"
+  -> frame + research + ideate (ideas go to the ideabox) -> [gate]
+  -> converge + estimate -> writes build-ready feature.json + design.md -> [gate]
+  -> handoff: each feature ready for `compose build <CODE>`
+```
+
+`compose build` then picks up a plan-authored feature and ratifies its design rather than rewriting it.
+
 ## Quick install
 
 Prerequisites: Node.js 18+ and `stratum-mcp` on PATH (`pip install stratum-mcp`, requires Python 3.11+). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
@@ -150,6 +161,34 @@ Tunnel layer is yours: Tailscale (serve/funnel), Cloudflare Tunnel, or a reverse
 
 `compose remote rotate-secret --yes` invalidates every paired device (post-leak hammer).
 
+## SmartMemory coupling (opt-in)
+
+Compose can feed its own lifecycle history (feature events, gate decisions, journal entries,
+artifacts) into [SmartMemory](https://github.com/smartmemory) for relevance-ranked recall,
+via a `smartmemory` block in `.compose/compose.json`:
+
+```json
+{
+  "smartmemory": {
+    "enabled": true,
+    "baseUrl": "http://localhost:9001",
+    "apiKeyEnv": "SMARTMEMORY_API_KEY",
+    "timeoutMs": 3000
+  }
+}
+```
+
+`smartmemory` is absent by default, which means the coupling is fully off: no probes, no
+network calls, no new log lines. With `enabled: true` and a reachable SmartMemory service,
+compose ingests lifecycle events live (fail-open) and the cockpit gains a Recall tab on each
+feature's detail panel.
+
+```bash
+compose smartmemory sync                 # idempotent backfill of events, journal, artifacts
+compose smartmemory sync --dry-run       # preview counts without ingesting
+compose smartmemory sync --feature CODE  # scope the sync to one feature
+```
+
 ## Documentation
 
 Topic-scoped reference:

package/bin/compose.js

@@ -8,6 +8,7 @@
  * compose start    — start the compose app (supervisor.js)
  * compose build    — headless feature lifecycle runner
  * compose fix      — headless bug-fix lifecycle runner (pipelines/bug-fix.stratum.yaml)
+ * compose plan     — product-planning lifecycle runner (pipelines/plan.stratum.yaml)
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSync, readdirSync } from 'fs'
 import { resolve, join, basename, dirname, sep } from 'path'
@@ -19,6 +20,7 @@ import { resolveWorkspace, getWorkspaceFlag } from '../lib/resolve-workspace.js'
 import { resolvePort } from '../lib/resolve-port.js'
 import { resolveRoadmapPath, resolveFeaturesPath, resolveContextPathFromConfig, resolveFeaturesPathFromConfig, resolveRoadmapPathFromConfig } from '../lib/project-paths.js'
 import { installAgentDefs } from '../lib/install-agent-defs.js'
+import { validateAgentString } from '../lib/agent-string.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PACKAGE_ROOT = resolve(__dirname, '..')
@@ -565,7 +567,7 @@ async function runInit(flags, cwdOverride) {
   // 8. Copy default pipeline specs if absent
   const pipelinesDir = join(cwd, 'pipelines')
   mkdirSync(pipelinesDir, { recursive: true })
-  for (const specName of ['build.stratum.yaml', 'build-quick.stratum.yaml', 'new.stratum.yaml']) {
+  for (const specName of ['build.stratum.yaml', 'build-quick.stratum.yaml', 'new.stratum.yaml', 'plan.stratum.yaml']) {
     const dest = join(pipelinesDir, specName)
     if (!existsSync(dest)) {
       const src = join(PACKAGE_ROOT, 'pipelines', specName)
@@ -1180,6 +1182,125 @@ if (cmd === 'roadmap') {
     process.exit(0)
   }
 
+  // compose roadmap add <CODE> — write a (build-ready) feature via the canonical
+  // typed writer (lib/feature-writer.js addRoadmapEntry). This is the CLI mirror of
+  // the add_roadmap_entry MCP tool, so an agent of ANY runtime (claude, codex, ...)
+  // can emit a build-ready feature.json without the compose MCP. The plan
+  // lifecycle's spec step uses it to write build-ready features (COMP-ROADMAP-PLAN).
+  if (subcmd === 'add') {
+    const { addRoadmapEntry } = await import('../lib/feature-writer.js')
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+    const VALUE_FLAGS = ['--description', '--phase', '--status', '--complexity', '--profile', '--triage-timestamp', '--planned-by', '--impact', '--cwd', '--workspace', '--team']
+    // flagVal returns the value only when it exists and is not itself another flag,
+    // so `--description --phase X` does not silently capture "--phase" as the value.
+    const flagVal = (name) => {
+      const i = args.indexOf(name)
+      if (i === -1) return undefined
+      const v = args[i + 1]
+      return (v === undefined || v.startsWith('-')) ? undefined : v
+    }
+    // The positional <CODE> is the first non-flag token that is NOT a value-taking
+    // flag's argument (so `--planned-by PLAN-X REAL-1` resolves the code to REAL-1).
+    const valueFlagSet = new Set(VALUE_FLAGS)
+    const valueIdx = new Set()
+    for (let i = 1; i < args.length; i++) { if (valueFlagSet.has(args[i])) valueIdx.add(i + 1) }
+    let code
+    for (let i = 1; i < args.length; i++) {
+      if (!args[i].startsWith('-') && !valueIdx.has(i)) { code = args[i]; break }
+    }
+    const description = flagVal('--description')
+    const phase = flagVal('--phase')
+    if (!code || !description || !phase) {
+      console.error('Usage: compose roadmap add <CODE> --description "..." --phase "..." \\')
+      console.error('         [--status PLANNED] [--complexity S|M|L|XL] [--profile <JSON>] \\')
+      console.error('         [--triage-timestamp <ISO>] [--planned-by <CODE>] [--impact low|medium|high]')
+      console.error('')
+      console.error('Writes feature.json via the canonical writer and regenerates ROADMAP.md.')
+      process.exit(1)
+    }
+    const entry = { code, description, phase, status: flagVal('--status') ?? 'PLANNED' }
+    const complexity = flagVal('--complexity'); if (complexity) entry.complexity = complexity
+    const plannedBy = flagVal('--planned-by'); if (plannedBy) entry.plannedBy = plannedBy
+    // --planned-by present but valueless must NOT silently fall through to the
+    // non-handshake path (it would write a non-build-ready feature).
+    if (args.includes('--planned-by') && !plannedBy) {
+      console.error('--planned-by requires a value (the originating plan session code)')
+      process.exit(1)
+    }
+    const impact = flagVal('--impact'); if (impact) entry.impact = impact
+    const profileRaw = flagVal('--profile')
+    if (profileRaw) {
+      let parsed
+      try { parsed = JSON.parse(profileRaw) }
+      catch (e) { console.error(`--profile must be valid JSON: ${e.message}`); process.exit(1) }
+      // A build-ready triage profile must carry the four needs_* booleans build uses
+      // to gate skippable phases — otherwise build skips fresh triage on a cache with
+      // no gating fields (COMP-ROADMAP-PLAN; profile contract in lib/triage.js).
+      const NEEDS = ['needs_prd', 'needs_architecture', 'needs_verification', 'needs_report']
+      const missing = NEEDS.filter((k) => typeof parsed?.[k] !== 'boolean')
+      if (missing.length) {
+        console.error(`--profile must include boolean fields: ${missing.join(', ')} (build triage gating)`)
+        process.exit(1)
+      }
+      entry.profile = parsed
+    }
+    // A plan handshake (--planned-by) must be FULLY build-ready or build won't consume
+    // it as one: profile + complexity + PLANNED status + an existing design.md (build
+    // ratifies it). Enforce the whole contract here (build reuses cached triage only
+    // when feature.profile exists and the cache is fresh — lib/build.js, lib/triage.js).
+    let designMtime = 0
+    if (plannedBy) {
+      if (!entry.profile) {
+        console.error('--planned-by requires --profile (a build-ready plan handshake must carry the triage profile)')
+        process.exit(1)
+      }
+      if (!entry.complexity) {
+        console.error('--planned-by requires --complexity (S|M|L|XL) for a build-ready handshake')
+        process.exit(1)
+      }
+      if (entry.status !== 'PLANNED') {
+        console.error(`--planned-by must be PLANNED (got ${entry.status}) — a plan handshake produces a build-ready PLANNED feature`)
+        process.exit(1)
+      }
+      const { resolveFeaturesPath } = await import('../lib/project-paths.js')
+      // alias the fs import — statSync is re-bound later in this roadmap block
+      const { statSync: statFile } = await import('fs')
+      const designPath = join(resolveFeaturesPath(cwd), code, 'design.md')
+      if (!existsSync(designPath)) {
+        console.error(`--planned-by: ${code}/design.md not found (${designPath}). Write the plan-approved design.md BEFORE creating the feature — build ratifies it.`)
+        process.exit(1)
+      }
+      designMtime = statFile(designPath).mtime.getTime()
+    }
+    // triageTimestamp: explicit (validated, and for a handshake not older than design.md
+    // or build re-triages), else default to now for a plan handshake.
+    const ts = flagVal('--triage-timestamp')
+    if (ts) {
+      const tsMs = new Date(ts).getTime()
+      if (Number.isNaN(tsMs)) {
+        console.error(`--triage-timestamp must be a valid ISO 8601 date (got "${ts}")`)
+        process.exit(1)
+      }
+      if (plannedBy && tsMs < designMtime) {
+        console.error('--triage-timestamp is older than design.md — build would re-triage. Omit it to stamp now, or pass a time at/after the design write.')
+        process.exit(1)
+      }
+      entry.triageTimestamp = ts
+    } else if (plannedBy) {
+      // Stamp now, but never older than design.md (guards a future-dated design.md /
+      // clock skew, which would otherwise read as stale and force a re-triage).
+      entry.triageTimestamp = new Date(Math.max(Date.now(), designMtime)).toISOString()
+    }
+    try {
+      const r = await addRoadmapEntry(cwd, entry)
+      console.log(`Wrote ${r.code} (${entry.status}) and regenerated ROADMAP.md`)
+    } catch (e) {
+      console.error(`roadmap add failed: ${e.message}`)
+      process.exit(1)
+    }
+    process.exit(0)
+  }
+
   // compose roadmap migrate — extract ROADMAP.md entries into feature.json files
   if (subcmd === 'migrate') {
     const { migrateRoadmap } = await import('../lib/migrate-roadmap.js')
@@ -1286,9 +1407,11 @@ if (cmd === 'roadmap') {
   }
 
   // compose roadmap graph — generate a self-contained dependency-graph HTML
-  // from feature.json + deps.yaml + frontmatter (COMP-ROADMAP-GRAPH-1).
+  // from the canonical vision projection (COMP-ROADMAP-GRAPH-2: the vision
+  // model is the single source, deterministically seeded from feature.json +
+  // deps.yaml; renders through the one shared renderer).
   if (subcmd === 'graph') {
-    const { generateRoadmapGraph, checkRoadmapGraph } = await import('../lib/roadmap-graph/index.js')
+    const { generateRoadmapGraph, checkRoadmapGraph } = await import('../server/roadmap-graph-vision.js')
     let cwd
     const projIdx = args.indexOf('--project')
     if (projIdx !== -1 && args[projIdx + 1]) {
@@ -1952,6 +2075,34 @@ if (cmd === 'pipeline') {
   process.exit(0)
 }
 
+// COMP-MODEL-AB: compose experiment <spec.json> [--prune-workspaces]
+if (cmd === 'experiment') {
+  const specArg = args[0]
+  if (!specArg || specArg.startsWith('-')) {
+    console.error('Usage: compose experiment <spec.json> [--prune-workspaces]')
+    console.error('')
+    console.error('Runs a sandboxed A/B experiment across model configs.')
+    console.error('Writes results.json + report.md next to the spec file.')
+    process.exit(1)
+  }
+  const pruneWorkspaces = args.includes('--prune-workspaces')
+  const specPath = resolve(specArg)
+  if (!existsSync(specPath)) {
+    console.error(`Error: spec file not found: ${specPath}`)
+    process.exit(1)
+  }
+  const { runExperiment } = await import('../lib/experiment.js')
+  try {
+    const result = await runExperiment(specPath, { pruneWorkspaces })
+    console.log(`Results: ${result.resultsPath}`)
+    console.log(`Report:  ${result.reportPath}`)
+  } catch (err) {
+    console.error(`Error: ${err.message}`)
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
 if (cmd === 'build') {
   // Parse --cwd <path> for cross-repo builds
   let agentWorkDir = null
@@ -1999,6 +2150,8 @@ if (cmd === 'build') {
   const all = filteredArgs2.includes('--all')
   const dryRun = filteredArgs2.includes('--dry-run')
   const skipTriage = filteredArgs2.includes('--skip-triage')
+  const resume = filteredArgs2.includes('--resume')
+  const fresh = filteredArgs2.includes('--fresh')
   // COMP-BUILD-QUICK: --quick selects the trimmed build-quick pipeline
   // (design → implement → ship). Symmetric to fix mode's Quick path; the real
   // mirror is the existing --template mechanism (fix dispatches template:'bug-fix'),
@@ -2007,6 +2160,29 @@ if (cmd === 'build') {
   // COMP-CODEX-IMPL: --codex flips the implementer to Codex (Claude reviews). v1 is
   // full-build, single-feature only — mutually exclusive with --quick and batch.
   const codex = filteredArgs2.includes('--codex')
+  const nonInteractiveBuild = filteredArgs2.includes('--non-interactive')
+
+  // COMP-MODEL-AB: --implementer=<agentStr> / --reviewer=<agentStr> override the
+  // --codex-derived defaults. Format: --implementer=claude::critical (= operator).
+  // Mutual exclusion applies when the explicit value conflicts with --codex's implicit
+  // assignment; identical values (e.g. --codex --implementer=codex) are allowed.
+  const implementerFlagMatch = filteredArgs2.find(a => a.startsWith('--implementer='))
+  const implementerArg = implementerFlagMatch ? implementerFlagMatch.slice('--implementer='.length) : null
+  const reviewerFlagMatch = filteredArgs2.find(a => a.startsWith('--reviewer='))
+  const reviewerArg = reviewerFlagMatch ? reviewerFlagMatch.slice('--reviewer='.length) : null
+
+  if (implementerArg) {
+    try { validateAgentString(implementerArg) } catch (err) {
+      console.error(`Error: --implementer: ${err.message}`)
+      process.exit(1)
+    }
+  }
+  if (reviewerArg) {
+    try { validateAgentString(reviewerArg) } catch (err) {
+      console.error(`Error: --reviewer: ${err.message}`)
+      process.exit(1)
+    }
+  }
 
   // Multiple codes: compose build FEAT-1 FEAT-2 FEAT-3
   const isMulti = featureCodes.length > 1
@@ -2018,6 +2194,14 @@ if (cmd === 'build') {
     console.error('Error: --abort and --all/prefix/multi are mutually exclusive')
     process.exit(1)
   }
+  if (resume && fresh) {
+    console.error('--resume and --fresh are mutually exclusive')
+    process.exit(1)
+  }
+  if ((resume || fresh) && isBatch) {
+    console.error('Error: --resume/--fresh cannot be combined with --all/prefix/multi (single feature only)')
+    process.exit(1)
+  }
 
   // COMP-BUILD-QUICK: --quick is a single-feature shortcut for a specific
   // template, so it conflicts with an explicit --template and with batch builds.
@@ -2044,6 +2228,17 @@ if (cmd === 'build') {
     process.exit(1)
   }
 
+  // COMP-MODEL-AB: mutual exclusion — conflict only when the explicit value differs
+  // from what --codex would set (--codex sets implementer=codex, reviewer=claude).
+  if (codex && implementerArg && implementerArg !== 'codex') {
+    console.error(`Error: --implementer=${implementerArg} conflicts with --codex (--codex sets implementer=codex); omit --codex or use --implementer=codex`)
+    process.exit(1)
+  }
+  if (codex && reviewerArg && reviewerArg !== 'claude') {
+    console.error(`Error: --reviewer=${reviewerArg} conflicts with --codex (--codex sets reviewer=claude); omit --codex or use --reviewer=claude`)
+    process.exit(1)
+  }
+
   if (!featureCode && !abort && !all) {
     console.error('Usage: compose build <feature-code> [feature-code...]')
     console.error('       compose build STRAT-COMP          (prefix — builds all matching)')
@@ -2052,6 +2247,8 @@ if (cmd === 'build') {
     console.error('Options:')
     console.error('  --quick        Trimmed lifecycle (design → implement → ship) for small additive work')
     console.error('  --abort        Abort the active build')
+    console.error('  --resume       Resume the active build for <feature-code>')
+    console.error('  --fresh        Start a fresh build, discarding stale failed/resumable state')
     console.error('  --all          Build all PLANNED features in dependency order')
     console.error('  --dry-run      Print build order without executing')
     console.error('  --cwd <path>   Agent working directory (for cross-repo features)')
@@ -2100,6 +2297,25 @@ if (cmd === 'build') {
       })
     })
   } else {
+    let resumeFlowId = null
+    if (resume && !abort && featureCode) {
+      const activeBuildPath = join(buildCwd, '.compose', 'data', 'active-build.json')
+      let active = null
+      if (existsSync(activeBuildPath)) {
+        try { active = JSON.parse(readFileSync(activeBuildPath, 'utf-8')) } catch { active = null }
+      }
+      if (
+        !active ||
+        active.featureCode !== featureCode ||
+        !active.flowId ||
+        ['complete', 'aborted', 'killed'].includes(active.status)
+      ) {
+        console.error(`Nothing to resume for ${featureCode} (no in-progress or failed build found)`)
+        process.exit(1)
+      }
+      resumeFlowId = active.flowId
+    }
+
     import('../lib/build.js').then(({ runBuild }) => {
       const singleOpts = { abort }
       if (agentWorkDir) singleOpts.workingDirectory = agentWorkDir
@@ -2107,6 +2323,12 @@ if (cmd === 'build') {
       if (templateName) singleOpts.template = templateName
       if (quick) singleOpts.template = 'build-quick'   // COMP-BUILD-QUICK
       if (codex) singleOpts.codex = true               // COMP-CODEX-IMPL
+      if (implementerArg) singleOpts.implementer = implementerArg   // COMP-MODEL-AB
+      if (reviewerArg) singleOpts.reviewer = reviewerArg             // COMP-MODEL-AB
+      if (resume) singleOpts.resume = true
+      if (fresh) singleOpts.fresh = true
+      if (nonInteractiveBuild) singleOpts.gateOpts = { nonInteractive: true }
+      if (resumeFlowId) singleOpts.resumeFlowId = resumeFlowId
       runBuild(featureCode, singleOpts).then(() => {
         process.exit(0)
       }).catch((err) => {
@@ -2227,6 +2449,116 @@ if (cmd === 'build') {
       process.exit(1)
     })
   })
+} else if (cmd === 'plan') {
+  // 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
+  // (override with --code). Always passes opts.description so the dead
+  // descriptionLoader:'plan' branch never runs (it would read a stray design.md).
+  // Emits build-ready docs/features/<code>/{feature.json, design.md} that
+  // `compose build <code>` consumes.
+  let agentWorkDir = null
+  const cwdIdx = args.indexOf('--cwd')
+  if (cwdIdx !== -1) {
+    const cwdValue = args[cwdIdx + 1]
+    if (!cwdValue || cwdValue.startsWith('-')) {
+      console.error('Error: --cwd requires a path argument')
+      process.exit(1)
+    }
+    agentWorkDir = resolve(cwdValue)
+  }
+  const codeIdx = args.indexOf('--code')
+  const explicitCode = codeIdx !== -1 ? args[codeIdx + 1] : null
+  const abort = args.includes('--abort')
+  const resume = args.includes('--resume')
+  // Everything that isn't a flag or a value-taking flag's argument is the intent.
+  // Skip the values of every value-taking flag so e.g. `--workspace foo` or
+  // `--team t` never pollute the derived intent/slug.
+  const skip = new Set()
+  for (const flag of ['--cwd', '--code', '--workspace', '--team']) {
+    const fi = args.indexOf(flag)
+    if (fi !== -1) { skip.add(fi); skip.add(fi + 1) }
+  }
+  const intent = args.filter((a, i) => !a.startsWith('-') && !skip.has(i)).join(' ')
+
+  if (!intent && !abort && !resume) {
+    console.error('Usage: compose plan "<what you want to build>" [--code PLAN-X] [--resume] [--abort]')
+    console.error('')
+    console.error('Runs the product-planning lifecycle (frame → research → ideate → converge → handoff).')
+    console.error('Emits build-ready docs/features/<code>/{feature.json, design.md} for `compose build`.')
+    console.error('')
+    console.error('Options:')
+    console.error('  --code <CODE>  Use an explicit plan code instead of a derived PLAN-<slug>')
+    console.error('  --resume       Resume the active plan run')
+    console.error('  --abort        Abort the active plan run')
+    console.error('  --cwd <path>   Agent working directory')
+    process.exit(1)
+  }
+
+  const { root: planCwd } = resolveCwdWithWorkspace(args)
+  if (!existsSync(join(planCwd, '.compose', 'compose.json')) || !existsSync(join(planCwd, 'pipelines', 'plan.stratum.yaml'))) {
+    console.log('Running compose init...\n')
+    await runInit(args.filter(a => a.startsWith('--')))
+    console.log('')
+  }
+
+  // Resolve the plan code. --resume/--abort operate on the ACTIVE build, so they
+  // take the code from active-build.json (never derive a fresh one — that would
+  // mint PLAN-<slug>-2 and miss the live flow). A fresh run derives a
+  // deterministic PLAN-<slug> from the intent, dedup'd against existing workspaces.
+  let planCode = explicitCode
+  let resumeFlowId = null
+  if (resume || abort) {
+    const activeBuildPath = join(planCwd, '.compose', 'data', 'active-build.json')
+    let active = null
+    if (existsSync(activeBuildPath)) {
+      try { active = JSON.parse(readFileSync(activeBuildPath, 'utf-8')) } catch { active = null }
+    }
+    if (!planCode) planCode = active?.featureCode ?? null
+    if (resume) {
+      if (!active || !active.flowId || (planCode && active.featureCode !== planCode)) {
+        console.error(`No active plan build to resume${planCode ? ` for ${planCode}` : ''}.`)
+        process.exit(1)
+      }
+      if (active.mode && active.mode !== 'plan') {
+        console.error(`Cannot --resume: active build for ${active.featureCode} is in ${active.mode} mode, not plan mode.`)
+        process.exit(1)
+      }
+      planCode = active.featureCode
+      resumeFlowId = active.flowId
+    }
+    // --abort: only abort an active PLAN build — abortBuild does not check mode,
+    // so guard here or `compose plan --abort` could kill a feature/fix run.
+    if (abort && active && active.mode && active.mode !== 'plan') {
+      console.error(`Cannot --abort as plan: the active build for ${active.featureCode} is in ${active.mode} mode, not plan mode.`)
+      process.exit(1)
+    }
+    // planCode is now the active build's code (or an explicit --code);
+    // runBuild(planCode, {abort}) matches it against active-build.json.
+  } else if (!planCode) {
+    const rawSlug = intent.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24).replace(/-+$/, '')
+    const slug = rawSlug || 'session'
+    const base = `PLAN-${slug}`.toUpperCase()
+    let candidate = base
+    let n = 2
+    while (existsSync(join(planCwd, 'docs', 'plans', candidate))) {
+      candidate = `${base}-${n}`
+      n++
+    }
+    planCode = candidate
+  }
+
+  import('../lib/build.js').then(({ runBuild }) => {
+    const opts = { abort, template: 'plan', mode: 'plan', description: intent }
+    if (agentWorkDir) opts.workingDirectory = agentWorkDir
+    if (resumeFlowId) opts.resumeFlowId = resumeFlowId
+    runBuild(planCode, opts).then(() => {
+      process.exit(0)
+    }).catch((err) => {
+      console.error(`Plan failed: ${err.message}`)
+      process.exit(1)
+    })
+  })
 } else if (cmd === 'gsd') {
   // compose gsd <feature-code> — runs the per-task fresh-context dispatch
   // pipeline (pipelines/gsd.stratum.yaml). Hard-requires existing
@@ -3446,6 +3778,49 @@ if (cmd === 'build') {
     process.exit(1)
   }
 
+} else if (cmd === 'smartmemory') {
+  // ---------------------------------------------------------------------------
+  // compose smartmemory sync [--dry-run] [--feature <CODE>]
+  //   COMP-SMARTMEMORY-INGEST: idempotent backfill/re-sync of feature-events,
+  //   gate-log, journal entries, and per-feature artifacts into SmartMemory.
+  // ---------------------------------------------------------------------------
+  const sub = args[0]
+
+  if (sub === 'sync') {
+    const { runSync } = await import('../lib/smartmemory-sync.js')
+    const { flushPending } = await import('../lib/smartmemory-ingest.js')
+    const flagIdx = (flag) => args.indexOf(flag)
+    const flagVal = (flag) => {
+      const i = flagIdx(flag)
+      return i !== -1 && args[i + 1] ? args[i + 1] : null
+    }
+    const dryRun = args.includes('--dry-run')
+    const feature = flagVal('--feature')
+
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+
+    let result
+    try {
+      result = await runSync({ cwd, dryRun, feature })
+    } catch (err) {
+      console.error(`smartmemory sync failed: ${err.message}`)
+      process.exit(1)
+    }
+
+    console.log(
+      `smartmemory sync: ingested=${result.ingested} unchanged=${result.unchanged} ` +
+      `skipped=${result.skipped} failed=${result.failed}` +
+      (result.stoppedOnQuota ? ' (stopped: workspace quota reached)' : '')
+    )
+    await flushPending()
+    process.exit(0)
+  }
+
+  console.error(`Unknown smartmemory subcommand: ${sub}`)
+  console.error('Usage:')
+  console.error('  compose smartmemory sync [--dry-run] [--feature <CODE>]')
+  process.exit(1)
+
 } else {
   console.error(`Unknown command: ${cmd}`)
   process.exit(1)