@smartmemory/compose 0.2.50-beta → 0.2.51-beta

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

@@ -16,6 +16,14 @@ 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:
@@ -23,10 +31,25 @@ Before any phase begins, read project state via the `compose` MCP server (get_vi
 | Verb | Use | Folder |
 |---|---|---|
 | `/compose build <feature-ref>` | New feature, 3+ files, 2+ phases, needs design | `docs/features/<feature-code>/` |
+| `/compose build --quick <feature-ref>` | **Small-but-real** additive work — one flag + a test + changelog entry; well-scoped, single component | `docs/features/<feature-code>/` |
 | `/compose fix <bug-ref>` | Non-trivial bug, test failure, regression, hotfix | `docs/bugs/<bug-code>/` |
 
 **Skip Compose entirely for:** typos, one-line obvious fixes, cosmetic changes — just fix those directly.
 
+### Build Quick path: `/compose build --quick` (COMP-BUILD-QUICK)
+
+`--quick` collapses the build lifecycle to **design → implement → ship** with a *single design gate*. The phases `prd`, `architecture`, `blueprint`, `blueprint-verification`, `plan`, and `report` are **omitted** (not just self-skipping). Use it for small additive work that would otherwise pay full-lifecycle ceremony: a new flag plus its test, a small helper with a golden test, a one-component addition.
+
+This is the symmetric counterpart to fix mode's Quick path. Note the implementation asymmetry: fix's Quick path is a **triage decision** the agent makes at Phase F1, whereas build's `--quick` is a **CLI flag** that selects the trimmed `build-quick` pipeline (headless CLI: `compose build --quick <code>` → `template: 'build-quick'`, the same `--template` mechanism fix uses with `bug-fix`).
+
+**What `--quick` keeps (NOT OpenSpec's no-gates model):**
+- The design gate and ship gate.
+- All Phase-7 enforcement: TDD per task, verification-before-completion, the parallel + Codex review loop, the coverage sweep, and the generated-test review. Only phase *count* shrinks — enforcement is the differentiator and stays.
+
+**Escalation guardrail.** If, during design or decomposition, the work proves multi-file, cross-cutting, or in need of architecture/PRD-level design, **stop and recommend the user re-run with full `/compose build` (no `--quick`)** rather than silently under-scoping. Note the recommendation in the design doc.
+
+`--quick` is single-feature only — it is mutually exclusive with `--template` (it already selects one) and with batch builds (`--all`, prefix, or multiple codes).
+
 ## Partial Execution: `--through <phase>`
 
 By default, `/compose` runs the full lifecycle. Use `--through` to stop after a specific phase's gate is approved:
@@ -580,7 +603,7 @@ After completing a feature OR bug-fix lifecycle, update project memory:
 
 ## Dependencies
 
-`compose setup` (see `bin/compose.js` `syncSkills()`) installs compose-owned skills from `PACKAGE_ROOT/.claude/skills/` and `PACKAGE_ROOT/skills/` to `~/.claude/skills/` and tracks them in `~/.claude/skills/.compose-skills.json`.
+`compose setup` (see `bin/compose.js` `syncSkills()`) installs compose-owned skills from `PACKAGE_ROOT/.claude/skills/` and `PACKAGE_ROOT/skills/` to `~/.claude/skills/` and tracks them in `~/.claude/skills/.compose-skills.json`. It also installs the vendored agent definitions from `PACKAGE_ROOT/.claude/agents/` (`compose-explorer`, `compose-architect`) to `~/.claude/agents/` (COMP-AGENT-VENDOR-1).
 
 ### Vendored (ship with compose)
 

package/.claude/skills/compose/references/hermes-tools.md

@@ -0,0 +1,80 @@
+# Compose on Hermes Agent — Tool Mapping
+
+SKILL.md is written against **Claude Code** tool names. This file maps each
+primitive the compose lifecycle uses to its **Nous Hermes Agent** equivalent, so
+the lifecycle can run under Hermes. Scope: the *interactive* `/compose` lifecycle
+(the headless `compose` CLI is already harness-agnostic — it runs from any shell
+and delegates agent execution to Stratum).
+
+Hermes shares the three primitives the lifecycle depends on — **skills**, an
+**MCP client**, and **parallel subagent delegation** — so this is a name/packaging
+adaptation, not an architecture port. The one genuine gap is plan mode (Phase 6);
+see below.
+
+## Action mapping
+
+| Action compose requests (Claude Code) | Hermes equivalent |
+|---|---|
+| Invoke a skill (`/compose`, `superpowers:*`) — **Skill** tool | Skills load natively from `~/.hermes/skills/`. Install with `hermes skills install <git-url\|file\|registry-id>` (SKILL.md frontmatter convention). |
+| Dispatch a subagent (`compose-explorer`, `compose-architect`, `general-purpose`) — **Agent/Task** tool | `delegate_task` (runtime tool) — spawns an isolated child agent with its own conversation, terminal, and toolset; only the final summary returns. |
+| Dispatch 2-3 subagents **in parallel** (Phase 1 explorers, Phase 3 architects) | `delegate_task` with a **`tasks` array** — runs in parallel via a thread pool, `max_concurrent_children` (default **3**, matches compose's fan-out). Orchestrator→leaf nesting needs `delegation.max_spawn_depth: 2`. |
+| **Plan mode** (Phase 6) — `EnterPlanMode` / `ExitPlanMode` | **No direct equivalent.** Degrade to a flat gate: write `plan.md`, present it in chat, human approves before Phase 7. Compose already supports this fallback ("If Stratum unavailable, continue with flat prompt chain"). |
+| Task tracking ("create a todo", "mark complete") — **TodoWrite** | `hermes kanban` (statuses todo/triage/scheduled/blocked/running/done; `hermes kanban create "<title>"`). Optional/advisory — skip if not wired. |
+| Read a file — **Read** | Native file read, `@file` context injection, or shell (`cat`/`head`). |
+| Create / edit a file — **Write / Edit** | Native file tools, or a filesystem MCP server (`hermes mcp add fs --command ...`). |
+| Run a shell command — **Bash** | Hermes shell / per-subagent terminal session. |
+| Search contents / find files — **Grep / Glob** | Shell (`rg`, `grep`, `find`). |
+| compose tracker (`mcp__compose__*`) | `hermes mcp add compose --command "<compose-mcp-launch>"`, then call natively. |
+| Stratum (`mcp__stratum__stratum_*`, incl. `stratum_agent_run type=codex`) | `hermes mcp add stratum --command "<stratum-mcp-launch>"`, then call natively. **Codex review works unchanged** — it's an MCP call, harness-agnostic. |
+| Bind flow → vision item — `POST /api/stratum/bind` (HTTP) | Shell `curl` (harness-agnostic). |
+| Project instructions — **CLAUDE.md** | **AGENTS.md** (Hermes auto-injects `AGENTS.md`/`SOUL.md`/`USER.md`/`MEMORY.md` unless `--ignore-rules`). |
+
+## Setup (one-time, per workspace)
+
+```bash
+# 1. Install the compose skill into Hermes
+hermes skills install <compose-skill-git-url>        # → ~/.hermes/skills/compose/
+
+# 2. Register the MCP servers the lifecycle reads/writes through
+hermes mcp add compose  --command "<compose-mcp-launch-command>"
+hermes mcp add stratum  --command "<stratum-mcp-launch-command>"
+hermes mcp test compose && hermes mcp test stratum   # verify discovery
+
+# 3. Mirror compose's project guidance for auto-injection
+#    (compose's CLAUDE.md content → AGENTS.md at the project root)
+```
+
+## What does NOT port 1:1 (the real work)
+
+1. **`compose-explorer` / `compose-architect` are Claude agent files** (installed to
+   `~/.claude/agents/` by `compose setup` → `syncSkills()`). Hermes has no agent-file
+   format; re-express each as a **`delegate_task` prompt template** carrying the same
+   mandate (explorer = read-only codebase mapping; architect = competing-mandate
+   proposals). The prompts in SKILL.md Phases 1/3/4 are the source of truth — port
+   those strings, not the `.md` agent files.
+
+2. **`compose setup` targets Claude paths** (`~/.claude/skills/`, `~/.claude/agents/`,
+   `.compose-skills.json`). A Hermes path would install to `~/.hermes/skills/` via
+   `hermes skills install`. This is a `bin/compose.js syncSkills()` branch, not a
+   lifecycle change.
+
+3. **Plan mode (Phase 6)** has no Hermes analog — use the flat-gate degrade above.
+   This is the only lifecycle *behavior* that changes shape; everything else is a
+   rename.
+
+4. **Tier→model mapping is Claude-centric** (`server/model-tiers.js` maps
+   `critical/standard/fast` → Opus/Sonnet/Haiku). Under Hermes-as-driver this only
+   matters if you also make Hermes the *executing agent* — which is a **Stratum**
+   change (add a `hermes` provider to Stratum's agent runner), out of scope for this
+   harness-driver adaptation. See SKILL.md "Stratum Integration".
+
+## Quick decision guide
+
+- **Just want to launch builds from Hermes?** Don't port anything — run the headless
+  `compose build`/`compose fix` CLI from the Hermes shell. It executes via Claude/Codex
+  under Stratum regardless of the launching harness.
+- **Want the interactive lifecycle inside Hermes?** Use this mapping: install the skill,
+  register the two MCP servers, port the two agent prompts to `delegate_task`, accept the
+  flat-gate Phase-6 degrade.
+- **Want Hermes to be the building agent?** That's the Stratum provider-addition path,
+  not this file.

package/README.md

@@ -55,7 +55,7 @@ Then in your project:
 
 ```bash
 cd /path/to/your/project
-compose init                 # writes .compose/, registers MCP, scaffolds ROADMAP and pipeline specs
+compose init                 # writes .compose/, registers MCP, scaffolds ROADMAP, pipeline specs, contracts/vocabulary.yaml
 compose new "what you want to build"
 ```
 

package/bin/compose.js

@@ -18,6 +18,7 @@ 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, '..')
@@ -84,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
 
@@ -124,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)')
@@ -244,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) {
@@ -476,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 = {}
@@ -538,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)
@@ -761,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)
@@ -1600,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'),
     },
   }
@@ -1674,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') {
@@ -1745,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)
   }
 
@@ -1978,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
@@ -1990,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')
@@ -2003,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('')
   }
 
@@ -2038,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) => {
@@ -2762,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]
 
@@ -2840,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') {