@smartmemory/compose 0.2.49-beta → 0.2.51-beta

package/bin/compose.js

@@ -17,6 +17,8 @@ import { fileURLToPath } from 'url'
 import { findProjectRoot } from '../server/find-root.js'
 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'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PACKAGE_ROOT = resolve(__dirname, '..')
@@ -83,6 +85,7 @@ 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 { computeHooksStatus, formatHookStatusLines, HOOK_MARKERS } from '../lib/hooks-status.js';
 
 const [,, cmd, ...args] = process.argv
 
@@ -123,10 +126,14 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   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 skills + register stratum-mcp (alias: sync)')
   console.log('  sync      Re-sync global skills from this install (alias of setup)')
@@ -243,6 +250,17 @@ function syncSkills(agents) {
       copyFileSync(depsSrc, join(composeSkillDir, '.compose-deps.json'))
     }
 
+    // COMP-AGENT-VENDOR-1: install the vendored Claude subagents the compose
+    // SKILL.md depends on (compose-explorer/compose-architect) into the Claude
+    // agents dir — sibling of the skills root. Claude tree only (basename check):
+    // gemini is skipped above and codex shares the claude root.
+    if (basename(dirname(agentSkillsRoot)) === '.claude') {
+      const agentDefsDest = join(dirname(agentSkillsRoot), 'agents')
+      for (const d of installAgentDefs(join(PACKAGE_ROOT, '.claude', 'agents'), agentDefsDest)) {
+        console.log(`  + ${agent.name}/agents/${d}`)
+      }
+    }
+
     // Remove skills we previously installed that no longer exist in source
     const removed = previousSkills.filter(name => !sourceSkills.has(name))
     for (const name of removed) {
@@ -412,6 +430,7 @@ async function runInit(flags, cwdOverride) {
     },
     paths: {
       docs: 'docs',
+      roadmap: 'ROADMAP.md',
       features: 'docs/features',
       journal: 'docs/journal',
       context: 'docs/context',
@@ -447,8 +466,9 @@ async function runInit(flags, cwdOverride) {
     }
   }
 
-  // 5b. Scaffold docs/context/ with ambient context templates
-  const contextDir = join(cwd, config.paths.context)
+  // 5b. Scaffold docs/context/ with ambient context templates.
+  // COMP-PATHS-EXTERNAL: resolve from the in-memory config (may be relocated).
+  const contextDir = resolveContextPathFromConfig(cwd, config)
   mkdirSync(contextDir, { recursive: true })
   const contextTemplates = {
     'tech-stack.md': '# Tech Stack\n\nDescribe your technology stack here.\n',
@@ -464,8 +484,8 @@ async function runInit(flags, cwdOverride) {
   }
 
   // 5c. Scaffold docs/product/ideabox.md if absent
-  const ideaboxRel = config.paths.ideabox || 'docs/product/ideabox.md'
-  const ideaboxDest = join(cwd, ideaboxRel)
+  const { resolveIdeaboxPath: _resolveIdeaboxPathInit } = await import('../lib/project-paths.js')
+  const ideaboxDest = _resolveIdeaboxPathInit(cwd)
   if (!existsSync(ideaboxDest)) {
     mkdirSync(dirname(ideaboxDest), { recursive: true })
     const { IDEABOX_TEMPLATE } = await import('../lib/ideabox.js')
@@ -473,6 +493,16 @@ async function runInit(flags, cwdOverride) {
     console.log(`Created ${ideaboxDest}`)
   }
 
+  // 5d. STRAT-VOCAB-3: scaffold contracts/vocabulary.yaml (starter is comments-only,
+  // so vocabulary enforcement stays inert until the user fills it in).
+  const { VOCABULARY_FILE, VOCABULARY_TEMPLATE } = await import('../lib/vocabulary-inject.js')
+  const vocabDest = join(cwd, VOCABULARY_FILE)
+  if (!existsSync(vocabDest)) {
+    mkdirSync(dirname(vocabDest), { recursive: true })
+    writeFileSync(vocabDest, VOCABULARY_TEMPLATE)
+    console.log(`Created ${vocabDest}`)
+  }
+
   // 6. Register compose-mcp in .mcp.json
   const mcpPath = join(cwd, '.mcp.json')
   let mcpConfig = {}
@@ -513,8 +543,10 @@ async function runInit(flags, cwdOverride) {
     }
   }
 
-  // 7. Scaffold ROADMAP.md from template if absent
-  const roadmapDest = join(cwd, 'ROADMAP.md')
+  // 7. Scaffold ROADMAP.md from template if absent. COMP-PATHS-EXTERNAL:
+  // honor a configured (possibly relocated) paths.roadmap instead of always
+  // seeding <cwd>/ROADMAP.md. Byte-identical for the default.
+  const roadmapDest = resolveRoadmapPathFromConfig(cwd, config)
   if (!existsSync(roadmapDest)) {
     const roadmapSrc = join(PACKAGE_ROOT, 'templates', 'ROADMAP.md')
     if (existsSync(roadmapSrc)) {
@@ -533,7 +565,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', 'new.stratum.yaml']) {
+  for (const specName of ['build.stratum.yaml', 'build-quick.stratum.yaml', 'new.stratum.yaml']) {
     const dest = join(pipelinesDir, specName)
     if (!existsSync(dest)) {
       const src = join(PACKAGE_ROOT, 'pipelines', specName)
@@ -756,6 +788,24 @@ if (cmd === 'migrate-state') {
   process.exit(0)
 }
 
+if (cmd === 'migrate-anon') {
+  // COMP-MCP-MIGRATION-2-1-1-1 — interactively promote historical anonymous
+  // ROADMAP rows to typed features. The non-TTY guard lives here (where
+  // process.stdin does): piped stdin / --non-interactive / --dry-run → list-only,
+  // never hang waiting for a prompt.
+  const { root: cwd } = resolveCwdWithWorkspace(args)
+  const nonInteractive = args.includes('--non-interactive') || args.includes('--dry-run') || !process.stdin.isTTY
+  const dryRun = args.includes('--dry-run')
+  const { runMigrateAnon } = await import('../lib/migrate-anon.js')
+  try {
+    await runMigrateAnon(cwd, { nonInteractive, dryRun })
+  } catch (err) {
+    console.error(`\nError: ${err.message}`)
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
 if (cmd === 'install') {
   // Backwards-compat: run both init + setup
   await runInit(args)
@@ -942,10 +992,12 @@ if (cmd === 'feature') {
 
   let config = {}
   try { config = JSON.parse(readFileSync(configPath, 'utf-8')) } catch {}
-  const featuresDir = config.paths?.features || 'docs/features'
+  // COMP-PATHS-EXTERNAL: absolute features dir (may be relocated outside cwd).
+  // Never join(cwd, …) below — that would re-root an absolute/../-escaping override.
+  const featuresDir = resolveFeaturesPath(cwd)
 
   // 1. Create feature folder + seed design doc
-  const featureDir = join(cwd, featuresDir, featureCode)
+  const featureDir = join(featuresDir, featureCode)
   const designPath = join(featureDir, 'design.md')
 
   if (existsSync(designPath)) {
@@ -985,7 +1037,7 @@ if (cmd === 'feature') {
   // Count existing features for complexity estimate
   const existingFeatureCount = (() => {
     try {
-      const fdir = join(cwd, featuresDir)
+      const fdir = featuresDir
       if (!existsSync(fdir)) return 0
       return readdirSync(fdir, { withFileTypes: true })
         .filter(e => e.isDirectory() && existsSync(join(fdir, e.name, 'feature.json')))
@@ -1042,7 +1094,7 @@ _This is a seed design doc created by \`compose feature\`. The \`compose build\`
   console.log(`Created ${designPath}`)
 
   // 2. Add entry to ROADMAP.md
-  const roadmapPath = join(cwd, 'ROADMAP.md')
+  const roadmapPath = resolveRoadmapPath(cwd)
   if (existsSync(roadmapPath)) {
     let roadmap = readFileSync(roadmapPath, 'utf-8')
 
@@ -1157,7 +1209,7 @@ if (cmd === 'roadmap') {
     const { checkRoundtrip, describeLossyDiff } = await import('../lib/roadmap-roundtrip.js')
     const { loadExternalPrefixes } = await import('../lib/project-paths.js')
     const { root: cwd } = resolveCwdWithWorkspace(args)
-    const roadmapPath = join(cwd, 'ROADMAP.md')
+    const roadmapPath = resolveRoadmapPath(cwd)
     if (!existsSync(roadmapPath)) {
       console.error('No ROADMAP.md found. Run: compose roadmap generate')
       process.exit(1)
@@ -1350,7 +1402,7 @@ if (cmd === 'roadmap') {
   }
 
   const { root: cwd } = resolveCwdWithWorkspace(args)
-  const roadmapPath = join(cwd, 'ROADMAP.md')
+  const roadmapPath = resolveRoadmapPath(cwd)
 
   if (existsSync(roadmapPath)) {
     // Show cwd roadmap
@@ -1593,12 +1645,12 @@ if (cmd === 'hooks') {
   const HOOK_TYPES = {
     'post-commit': {
       template: pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'post-commit.template'),
-      marker:   '# Compose post-commit hook —',
+      marker:   HOOK_MARKERS['post-commit'],
       dest:     pjoin(hooksDir, 'post-commit'),
     },
     'pre-push': {
       template: pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'pre-push.template'),
-      marker:   '# Compose pre-push hook —',
+      marker:   HOOK_MARKERS['pre-push'],
       dest:     pjoin(hooksDir, 'pre-push'),
     },
   }
@@ -1667,48 +1719,14 @@ if (cmd === 'hooks') {
     return 0
   }
 
-  function extractBakedWorkspaceId(content) {
-    const m = content.match(/^COMPOSE_WORKSPACE_ID="([^"]*)"$/m)
-    return m ? m[1] : null
-  }
-
-  function statusOne(type) {
-    const { marker, dest } = HOOK_TYPES[type]
-    if (!exSync(dest)) {
-      console.log(`${type}: absent — no hook installed`)
-      return
-    }
-    const content = rfSync(dest, 'utf-8')
-    if (!content.includes(marker)) {
-      console.log(`${type}: foreign — hook exists but is not a Compose hook`)
-      return
-    }
+  // Resolve the expected workspace id once (identical across hook types).
+  // Hook-status detection itself lives in lib/hooks-status.js (shared with the
+  // /api/environment-health endpoint); this just supplies the comparison id.
+  function resolveExpectedWsId() {
     const wsHint = hookFlags['workspace']
-    let expectedWsId = null
-    if (wsHint) {
-      try { expectedWsId = resolveWorkspace({ cwd: projectRoot, workspaceId: wsHint }).id } catch { /* ignore for status */ }
-    } else {
-      try { expectedWsId = resolveWorkspace({ cwd: projectRoot }).id } catch { /* ignore for status */ }
-    }
-    const nodeMatch = content.includes(`COMPOSE_NODE="${composeNode}"`)
-    const binMatch  = content.includes(`COMPOSE_BIN="${composeBin}"`)
-    const hasRawToken = content.includes('__COMPOSE_WORKSPACE_ID__')
-    const wsMatch = hasRawToken ? false
-                  : expectedWsId ? content.includes(`COMPOSE_WORKSPACE_ID="${expectedWsId}"`)
-                  : true
-    if (nodeMatch && binMatch && wsMatch && !hasRawToken) {
-      console.log(`${type}: installed (current)`)
-      const baked = extractBakedWorkspaceId(content)
-      if (baked) console.log(`  workspace: ${baked}`)
-    } else {
-      const reason = hasRawToken ? 'MISSING_WORKSPACE_ID'
-                   : (expectedWsId && !wsMatch) ? 'STALE_WORKSPACE_ID'
-                   : 'stale paths'
-      console.log(`${type}: installed (${reason} — re-run install)`)
-      if (expectedWsId && !wsMatch && !hasRawToken) console.log(`  expected COMPOSE_WORKSPACE_ID="${expectedWsId}"`)
-      if (!nodeMatch) console.log(`  expected COMPOSE_NODE="${composeNode}"`)
-      if (!binMatch)  console.log(`  expected COMPOSE_BIN="${composeBin}"`)
-    }
+    try {
+      return resolveWorkspace(wsHint ? { cwd: projectRoot, workspaceId: wsHint } : { cwd: projectRoot }).id
+    } catch { return null /* ignore for status */ }
   }
 
   if (sub === 'install') {
@@ -1738,7 +1756,17 @@ if (cmd === 'hooks') {
   if (!sub || sub === 'status') {
     // Status reports on ALL known hook types (selection flags ignored), so users
     // see the full picture. Selection only affects install/uninstall.
-    for (const t of Object.keys(HOOK_TYPES)) statusOne(t)
+    const computed = computeHooksStatus({
+      projectRoot,
+      expectedWsId: resolveExpectedWsId(),
+      composeNode,
+      composeBin,
+    })
+    for (const t of Object.keys(HOOK_TYPES)) {
+      for (const line of formatHookStatusLines(t, computed[t], { composeNode, composeBin })) {
+        console.log(line)
+      }
+    }
     process.exit(0)
   }
 
@@ -1971,6 +1999,14 @@ if (cmd === 'build') {
   const all = filteredArgs2.includes('--all')
   const dryRun = filteredArgs2.includes('--dry-run')
   const skipTriage = filteredArgs2.includes('--skip-triage')
+  // 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'),
+  // so --quick is sugar for template:'build-quick'. Single-feature only.
+  const quick = filteredArgs2.includes('--quick')
+  // 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')
 
   // Multiple codes: compose build FEAT-1 FEAT-2 FEAT-3
   const isMulti = featureCodes.length > 1
@@ -1983,12 +2019,38 @@ if (cmd === 'build') {
     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.
+  if (quick && templateName) {
+    console.error('Error: --quick and --template are mutually exclusive (--quick selects the build-quick template)')
+    process.exit(1)
+  }
+  if (quick && isBatch) {
+    console.error('Error: --quick cannot be combined with --all/prefix/multi (single feature only)')
+    process.exit(1)
+  }
+
+  // COMP-CODEX-IMPL: v1 scopes --codex to the full build, single feature.
+  if (codex && quick) {
+    console.error('Error: --codex and --quick are mutually exclusive in v1 (build-quick Codex parity is a follow-up)')
+    process.exit(1)
+  }
+  if (codex && templateName) {
+    console.error('Error: --codex and --template are mutually exclusive (--codex parameterizes the build template)')
+    process.exit(1)
+  }
+  if (codex && isBatch) {
+    console.error('Error: --codex cannot be combined with --all/prefix/multi (single feature only in v1)')
+    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)')
     console.error('       compose build --all               (builds entire roadmap)')
     console.error('')
     console.error('Options:')
+    console.error('  --quick        Trimmed lifecycle (design → implement → ship) for small additive work')
     console.error('  --abort        Abort the active build')
     console.error('  --all          Build all PLANNED features in dependency order')
     console.error('  --dry-run      Print build order without executing')
@@ -1996,11 +2058,23 @@ if (cmd === 'build') {
     process.exit(1)
   }
 
-  // Auto-init if needed
+  // Auto-init if needed. COMP-BUILD-QUICK: a workspace initialized before the
+  // build-quick pipeline existed won't have pipelines/build-quick.stratum.yaml,
+  // 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)
-  if (!existsSync(join(buildCwd, '.compose', 'compose.json')) || !existsSync(join(buildCwd, 'pipelines', 'build.stratum.yaml'))) {
+  const needsInit =
+    !existsSync(join(buildCwd, '.compose', 'compose.json')) ||
+    !existsSync(join(buildCwd, 'pipelines', 'build.stratum.yaml')) ||
+    (quick && !existsSync(join(buildCwd, 'pipelines', 'build-quick.stratum.yaml')))
+  if (needsInit) {
     console.log('Running compose init...\n')
-    await runInit(args.filter(a => a.startsWith('--')))
+    // Thread the RESOLVED workspace root into runInit. Without it runInit seeds
+    // process.cwd(), which differs from buildCwd when invoked from a subdirectory
+    // — the guard checks buildCwd but the seed would land in the wrong dir, so
+    // runBuild would still fail with the same missing-spec error (Codex review).
+    await runInit(args.filter(a => a.startsWith('--')), buildCwd)
     console.log('')
   }
 
@@ -2031,6 +2105,8 @@ if (cmd === 'build') {
       if (agentWorkDir) singleOpts.workingDirectory = agentWorkDir
       if (skipTriage) singleOpts.skipTriage = true
       if (templateName) singleOpts.template = templateName
+      if (quick) singleOpts.template = 'build-quick'   // COMP-BUILD-QUICK
+      if (codex) singleOpts.codex = true               // COMP-CODEX-IMPL
       runBuild(featureCode, singleOpts).then(() => {
         process.exit(0)
       }).catch((err) => {
@@ -2426,7 +2502,11 @@ if (cmd === 'build') {
   } = await import('../lib/ideabox.js')
 
   const ibRelPath = getIdeaboxRelPath(ibCwd)
-  const ibFullPath = join(ibCwd, ibRelPath)
+  // 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>')
@@ -2544,9 +2624,10 @@ if (cmd === 'build') {
       resolvedCode = `IDEA-${idea.num}-${slug}`.toUpperCase()
     }
 
-    // Create feature folder if missing — respect paths.features from compose.json
-    const featuresRel = ibConfig.paths?.features || 'docs/features'
-    const featuresDir = join(ibCwd, featuresRel, resolvedCode)
+    // 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.
@@ -2557,8 +2638,8 @@ if (cmd === 'build') {
         status: 'PLANNED',
         promotedFrom: ideaId,
         createdAt: new Date().toISOString(),
-      }, featuresRel)
-      console.log(`Created feature folder: ${featuresRel}/${resolvedCode}/`)
+      }, featuresBase)
+      console.log(`Created feature folder: ${join(featuresBase, resolvedCode)}/`)
     }
 
     _promoteIdea(parsed, ideaId, resolvedCode)
@@ -2750,11 +2831,76 @@ if (cmd === 'build') {
     process.exit(1)
   })
 
-} else if (cmd === 'gates') {
+} else if (cmd === 'context') {
+  // ---------------------------------------------------------------------------
+  // compose context decisions [--feature <FC>] [--format text|json]
+  // COMP-CTX-3: read-side of the decision log. During `compose build` each gate
+  // outcome is auto-appended to docs/context/decisions.md (appendDecisionEntry);
+  // this surfaces it. Read-only; no server.
+  // ---------------------------------------------------------------------------
+  const contextSubcmd = args[0]
+  if (contextSubcmd === 'decisions') {
+    const { existsSync, readFileSync } = await import('node:fs')
+    const { join } = await import('node:path')
+    const { resolveContextPath } = await import('../lib/project-paths.js')
+    const flagVal = (flag) => {
+      const i = args.indexOf(flag)
+      return i !== -1 && args[i + 1] ? args[i + 1] : null
+    }
+    const featureFilter = flagVal('--feature')
+    const format = flagVal('--format') || 'text'
+
+    const decisionsPath = join(resolveContextPath(process.cwd()), 'decisions.md')
+    if (!existsSync(decisionsPath)) {
+      console.error(`No decision log at ${decisionsPath} — run \`compose init\` to scaffold docs/context/, then decisions accrue during builds.`)
+      process.exit(1)
+    }
+    const raw = readFileSync(decisionsPath, 'utf-8')
+
+    // Each entry is a "## [YYYY-MM-DD] FEATURE — step" heading + body
+    // (see appendDecisionEntry in lib/build.js). Slice raw on the headings.
+    const heads = []
+    const re = /^## \[(\d{4}-\d{2}-\d{2})\] (\S+) — (.+)$/gm
+    let m
+    while ((m = re.exec(raw)) !== null) {
+      heads.push({ idx: m.index, date: m[1], feature: m[2], step: m[3] })
+    }
+    const blocks = heads.map((h, i) => ({
+      ...h,
+      text: raw.slice(h.idx, i + 1 < heads.length ? heads[i + 1].idx : raw.length).trim(),
+    }))
+    const filtered = featureFilter ? blocks.filter(b => b.feature === featureFilter) : blocks
+
+    if (format === 'json') {
+      const out = filtered.map(b => ({
+        date: b.date,
+        feature: b.feature,
+        step: b.step,
+        outcome: (b.text.match(/\*\*Outcome:\*\* (.+)/) || [])[1] || null,
+        rationale: (b.text.match(/\*\*Rationale:\*\* ([\s\S]+?)(?:\n## |\s*$)/) || [])[1]?.trim() || null,
+      }))
+      console.log(JSON.stringify(out, null, 2))
+    } else if (filtered.length === 0) {
+      console.log(featureFilter ? `No decisions recorded for ${featureFilter}.` : 'No decisions recorded yet.')
+    } else {
+      const label = featureFilter ? ` for ${featureFilter}` : ''
+      console.log(`Decision log${label} — ${filtered.length} entr${filtered.length === 1 ? 'y' : 'ies'}:\n`)
+      for (const b of filtered) console.log(b.text + '\n')
+    }
+  } else {
+    console.error('usage: compose context decisions [--feature <FC>] [--format text|json]')
+    process.exit(1)
+  }
+
+} else if (cmd === 'gates' || cmd === 'gate') {
   // ---------------------------------------------------------------------------
+  // compose gate list [--item <id>] [--status pending|all|resolved] [--format text|json]
+  // compose gate resolve <gateId> (--approve|--revise|--kill) [--comment <text>] [--reason <text>]
+  //   COMP-PARITY-1: CLI gate resolution — wraps GET/POST /api/vision/gates[/:id/resolve]
   // compose gates report [--since 24h|7d|1h|<ISO>] [--feature <FC>]
   //                       [--format text|json] [--rubber-stamp-ms <N>]
-  // COMP-OBS-GATELOG: audit gate log report (Decision 5)
+  //   COMP-OBS-GATELOG: audit gate log report (Decision 5)
+  // (`gate` and `gates` are aliases.)
   // ---------------------------------------------------------------------------
   const gatesSubcmd = args[0]
 
@@ -2828,8 +2974,132 @@ if (cmd === 'build') {
     process.exit(0)
   }
 
-  console.error(`Unknown gates subcommand: ${gatesSubcmd}`)
-  console.error('Usage: compose gates report [--since 24h] [--feature FC] [--format text|json] [--rubber-stamp-ms N]')
+  if (gatesSubcmd === 'list' || gatesSubcmd === 'resolve') {
+    // --- COMP-PARITY-1: CLI gate list/resolve over the :4001 vision endpoints ---
+    const flagVal = (flag) => { const i = args.indexOf(flag); return i !== -1 && args[i + 1] ? args[i + 1] : null }
+    const hasFlag = (flag) => args.includes(flag)
+    const baseUrl = process.env.COMPOSE_URL || `http://127.0.0.1:${resolvePort()}`
+
+    // Tolerant workspace resolution (mirror `compose loops`): attach the header
+    // when resolvable, otherwise send none (server soft-falls back to boot ws).
+    let _wsId = null
+    try {
+      const wsId = getWorkspaceFlag(args)
+      const ws = resolveWorkspace({ workspaceId: wsId === '__COMPOSE_WORKSPACE_ID__' ? null : wsId })
+      _wsId = ws.id || null
+    } catch { /* no header */ }
+
+    const reqJson = async (method, urlStr, body) => {
+      const { default: http } = await import(urlStr.startsWith('https') ? 'https' : 'http')
+      return new Promise((resolveP, reject) => {
+        const u = new URL(urlStr)
+        const data = body ? JSON.stringify(body) : null
+        const headers = {}
+        if (_wsId) headers['X-Compose-Workspace-Id'] = _wsId
+        if (data) { headers['Content-Type'] = 'application/json'; headers['Content-Length'] = Buffer.byteLength(data) }
+        // Sensitive-token header — only consumed when capabilities.guardAuth is on.
+        if (method === 'POST' && process.env.COMPOSE_API_TOKEN) headers['x-compose-token'] = process.env.COMPOSE_API_TOKEN
+        const r = http.request({
+          hostname: u.hostname,
+          port: u.port || (urlStr.startsWith('https') ? 443 : 80),
+          path: u.pathname + u.search,
+          method,
+          headers,
+        }, (res) => {
+          let buf = ''
+          res.on('data', c => { buf += c })
+          res.on('end', () => { try { resolveP({ status: res.statusCode, body: JSON.parse(buf) }) } catch { resolveP({ status: res.statusCode, body: buf }) } })
+        })
+        r.on('error', reject)
+        if (data) r.end(data); else r.end()
+      })
+    }
+
+    const dieUnreachable = (err) => {
+      if (err && (err.code === 'ECONNREFUSED' || /ECONNREFUSED/.test(err.message || ''))) {
+        console.error(`compose server not reachable on :${resolvePort()} — start it with \`npm run dev:server\` (or \`npm run dev:watch\`)`)
+      } else {
+        console.error(`gate ${gatesSubcmd}: ${err.message}`)
+      }
+      process.exit(1)
+    }
+
+    if (gatesSubcmd === 'list') {
+      const itemId = flagVal('--item')
+      const status = flagVal('--status') || 'pending'
+      const format = flagVal('--format') || 'text'
+      if (!['pending', 'all', 'resolved'].includes(status)) {
+        console.error(`gate list: --status must be one of pending|all|resolved (got '${status}')`)
+        process.exit(1)
+      }
+      if (!['text', 'json'].includes(format)) {
+        console.error(`gate list: --format must be one of text|json (got '${format}')`)
+        process.exit(1)
+      }
+      const params = new URLSearchParams()
+      if (status !== 'pending') params.set('status', status)
+      if (itemId) params.set('itemId', itemId)
+      const qs = params.toString() ? `?${params.toString()}` : ''
+      let resp
+      try { resp = await reqJson('GET', `${baseUrl}/api/vision/gates${qs}`) } catch (e) { dieUnreachable(e) }
+      if (resp.status !== 200) {
+        console.error(`gate list failed (HTTP ${resp.status}): ${resp.body?.error || JSON.stringify(resp.body)}`)
+        process.exit(1)
+      }
+      // The server only honors itemId on the pending path; filter client-side so
+      // --item works uniformly across --status all|resolved too (Codex review).
+      let gates = resp.body.gates || []
+      if (itemId) gates = gates.filter(g => g.itemId === itemId)
+      if (format === 'json') { console.log(JSON.stringify(gates, null, 2)); process.exit(0) }
+      if (gates.length === 0) { console.log(`No ${status} gates.`); process.exit(0) }
+      const ageOf = (iso) => {
+        const m = Math.floor((Date.now() - new Date(iso).getTime()) / 60000)
+        if (m < 60) return `${m}m`
+        const h = Math.floor(m / 60)
+        return h < 24 ? `${h}h` : `${Math.floor(h / 24)}d`
+      }
+      // Record-per-gate, not a fixed-width table: real gate ids are long
+      // `<uuid>:<step>:<round>` strings, so columns smush together. Keep the full
+      // copy-pasteable id on its own line (it's the arg to `gate resolve`).
+      console.log(`${gates.length} ${status} gate${gates.length === 1 ? '' : 's'}:\n`)
+      for (const g of gates) {
+        console.log(`${g.id}  [${g.status || 'pending'}]`)
+        console.log(`    item ${g.itemId || '·'}   step ${g.stepId || '·'}   ${g.fromPhase || '·'}→${g.toPhase || '·'}   ${ageOf(g.createdAt)}\n`)
+      }
+      process.exit(0)
+    }
+
+    if (gatesSubcmd === 'resolve') {
+      const gateId = args[1] && !args[1].startsWith('-') ? args[1] : null
+      if (!gateId) {
+        console.error('usage: compose gate resolve <gateId> (--approve|--revise|--kill) [--comment <text>] [--reason <text>]')
+        process.exit(1)
+      }
+      const outcomes = ['approve', 'revise', 'kill'].filter(o => hasFlag(`--${o}`))
+      if (outcomes.length !== 1) {
+        console.error('gate resolve: exactly one of --approve | --revise | --kill is required')
+        process.exit(1)
+      }
+      const outcome = outcomes[0]
+      const comment = flagVal('--comment') ?? flagVal('--reason') ?? undefined
+      let resp
+      try {
+        resp = await reqJson('POST', `${baseUrl}/api/vision/gates/${encodeURIComponent(gateId)}/resolve`, { outcome, comment, resolvedBy: 'cli' })
+      } catch (e) { dieUnreachable(e) }
+      if (resp.status < 200 || resp.status >= 300) {
+        console.error(`gate resolve failed (HTTP ${resp.status}): ${resp.body?.error || JSON.stringify(resp.body)}`)
+        process.exit(1)
+      }
+      console.log(`Gate ${gateId} resolved: ${outcome}${comment ? ` — ${comment}` : ''}`)
+      process.exit(0)
+    }
+  }
+
+  console.error(`Unknown gate subcommand: ${gatesSubcmd}`)
+  console.error('Usage:')
+  console.error('  compose gate list [--item <id>] [--status pending|all|resolved] [--format text|json]')
+  console.error('  compose gate resolve <gateId> (--approve|--revise|--kill) [--comment <text>] [--reason <text>]')
+  console.error('  compose gates report [--since 24h] [--feature FC] [--format text|json] [--rubber-stamp-ms N]')
   process.exit(1)
 
 } else if (cmd === 'loops') {