@smartmemory/compose 0.1.1-beta → 0.1.2-beta

package/.compose-deps.json

@@ -0,0 +1,89 @@
+{
+  "version": 1,
+  "external_skills": [
+    {
+      "id": "superpowers:systematic-debugging",
+      "required_for": ["bug-fix Phase F3", "any unexpected failure"],
+      "install": "claude plugin install superpowers",
+      "fallback": "general-purpose Agent with debugging prompt",
+      "optional": false
+    },
+    {
+      "id": "superpowers:test-driven-development",
+      "required_for": ["bug-fix Phase F2", "build Phase 7 step 1"],
+      "install": "claude plugin install superpowers",
+      "fallback": "inline TDD instructions in SKILL.md",
+      "optional": false
+    },
+    {
+      "id": "superpowers:verification-before-completion",
+      "required_for": ["all phase exits"],
+      "install": "claude plugin install superpowers",
+      "fallback": "inline verification checklist in SKILL.md",
+      "optional": false
+    },
+    {
+      "id": "superpowers:requesting-code-review",
+      "required_for": ["Phase 7 review fallback"],
+      "install": "claude plugin install superpowers",
+      "fallback": "general-purpose Agent reviewer with canonical ReviewResult prompt",
+      "optional": true
+    },
+    {
+      "id": "superpowers:executing-plans",
+      "required_for": ["Phase 7 sequential execution"],
+      "install": "claude plugin install superpowers",
+      "fallback": "inline plan-execution instructions",
+      "optional": false
+    },
+    {
+      "id": "superpowers:dispatching-parallel-agents",
+      "required_for": ["Phase 7 parallel execution"],
+      "install": "claude plugin install superpowers",
+      "fallback": "sequential execution",
+      "optional": true
+    },
+    {
+      "id": "interface-design:init",
+      "required_for": ["Phase 7 — new UI components"],
+      "install": "claude plugin install interface-design",
+      "fallback": null,
+      "optional": true
+    },
+    {
+      "id": "interface-design:critique",
+      "required_for": ["Phase 7 — UI critique pass"],
+      "install": "claude plugin install interface-design",
+      "fallback": null,
+      "optional": true
+    },
+    {
+      "id": "interface-design:audit",
+      "required_for": ["Phase 7 — UI design-system audit"],
+      "install": "claude plugin install interface-design",
+      "fallback": null,
+      "optional": true
+    },
+    {
+      "id": "codex:review",
+      "required_for": ["Phase 7 review gate (human-driven)"],
+      "install": "claude plugin install openai-codex",
+      "fallback": "mcp__stratum__stratum_agent_run type=codex",
+      "optional": true
+    },
+    {
+      "id": "refactor",
+      "required_for": ["Phase 7 large-file split"],
+      "install": "user-installed skill at ~/.claude/skills/refactor/",
+      "fallback": null,
+      "optional": true
+    },
+    {
+      "id": "update-docs",
+      "required_for": ["Phase 9 docs sync"],
+      "install": "user-installed skill at ~/.claude/skills/update-docs/",
+      "fallback": "manual TODO surfaced in implementation report",
+      "optional": true
+    }
+  ]
+}

package/README.md

@@ -2,7 +2,7 @@
 
 AI-powered product lifecycle orchestrator. Compose takes a product idea from intent to shipped code through structured, agent-driven pipelines with human gates at every critical decision point.
 
-Compose coordinates multiple AI agents (Claude, Codex) through YAML-defined workflows powered by [Stratum](https://github.com/regression-io/stratum), enforcing postconditions, retrying on failure, and producing auditable execution traces.
+Compose coordinates multiple AI agents (Claude, Codex) through YAML-defined workflows powered by [Stratum](https://github.com/smartmemory/stratum), enforcing postconditions, retrying on failure, and producing auditable execution traces.
 
 ## Table of Contents
 
@@ -75,7 +75,7 @@ compose build FEAT-1
 ### Install Compose
 
 ```bash
-git clone https://github.com/regression-io/compose.git
+git clone https://github.com/smartmemory/compose.git
 cd compose
 npm install
 ```
@@ -224,12 +224,23 @@ compose init --no-lifecycle
 
 ### `compose setup`
 
-Global skill and MCP registration. Installs the `/compose` skill and Stratum skill to all detected agents.
+Global skill and MCP registration. Installs the `/compose` skill and Stratum skill to all detected agents. At the end, runs an external-dependency check (see `compose doctor`) and prints actionable install hints for any missing external skills or commands.
 
 ```bash
 compose setup
 ```
 
+### `compose doctor`
+
+Verifies that the external skills and commands the lifecycle relies on (e.g. `superpowers:*`, `interface-design:*`, `codex:review`, `refactor`, `update-docs`) are installed locally. The authoritative dep list lives in `.compose-deps.json` at the package root.
+
+```bash
+compose doctor              # human-readable report
+compose doctor --json       # machine-readable, full dep records (id, required_for, install, fallback, optional)
+compose doctor --strict     # exit 1 on any missing required dep (use in CI)
+compose doctor --verbose    # also list the filesystem paths scanned
+```
+
 ### `compose start`
 
 Start the Compose app (supervisor with web UI, terminal, and API server).

package/bin/compose.js

@@ -7,6 +7,7 @@
  * compose install  — run init + setup (backwards-compat alias)
  * 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)
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSync, readdirSync } from 'fs'
 import { resolve, join, basename, dirname } from 'path'
@@ -22,6 +23,7 @@ const PACKAGE_ROOT = resolve(__dirname, '..')
 // --team flag (COMP-TEAMS)
 // ---------------------------------------------------------------------------
 import { parseTeamFlag } from '../lib/team-flag.js';
+import { loadDeps, checkExternalSkills, printDepReport } from '../lib/deps.js';
 
 const [,, cmd, ...args] = process.argv
 
@@ -37,6 +39,7 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  import    Scan existing project and generate structured analysis')
   console.log('  feature   Add a single feature (folder, design seed, ROADMAP entry)')
   console.log('  build     Run a feature through the headless lifecycle')
+  console.log('  fix       Run a bug through the headless bug-fix lifecycle')
   console.log('  pipeline  View and edit the build pipeline')
   console.log('  roadmap            Show roadmap status and next buildable features')
   console.log('  roadmap generate   Regenerate ROADMAP.md from feature.json files')
@@ -46,6 +49,7 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  qa-scope  Show affected routes from a feature\'s changed files')
   console.log('  init      Initialize Compose in the current project')
   console.log('  setup     Install global skill + register stratum-mcp')
+  console.log('  doctor    Check external skill dependencies')
   process.exit(0)
 }
 
@@ -148,6 +152,14 @@ function syncSkills(agents) {
       console.log(`  + ${agent.name}/${name}`)
     }
 
+    // Copy .compose-deps.json next to the compose SKILL.md so the lifecycle
+    // can read it as a fallback when `compose doctor` is unreachable.
+    const depsSrc = join(PACKAGE_ROOT, '.compose-deps.json')
+    const composeSkillDir = join(agentSkillsRoot, 'compose')
+    if (existsSync(depsSrc) && existsSync(composeSkillDir)) {
+      copyFileSync(depsSrc, join(composeSkillDir, '.compose-deps.json'))
+    }
+
     // Remove skills we previously installed that no longer exist in source
     const removed = previousSkills.filter(name => !sourceSkills.has(name))
     for (const name of removed) {
@@ -169,6 +181,34 @@ function syncSkills(agents) {
       console.log(`  - ${name} — not found`)
     }
   }
+
+  // External skill dep check — surface missing plugins / user skills with
+  // actionable install hints. Soft check: warnings only, exit code unaffected.
+  const deps = loadDeps(PACKAGE_ROOT)
+  if (deps) {
+    const result = checkExternalSkills(deps)
+    printDepReport(result)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// compose doctor — re-run the external dep check
+// ---------------------------------------------------------------------------
+
+function runDoctor(flags = []) {
+  const json = flags.includes('--json')
+  const strict = flags.includes('--strict')
+  const verbose = flags.includes('--verbose') || flags.includes('-v')
+
+  const deps = loadDeps(PACKAGE_ROOT)
+  if (!deps) {
+    console.error('Error: .compose-deps.json missing or invalid at package root')
+    process.exit(1)
+  }
+  const result = checkExternalSkills(deps)
+  const allRequiredPresent = printDepReport(result, { json, verbose })
+
+  if (strict && !allRequiredPresent) process.exit(1)
 }
 
 // ---------------------------------------------------------------------------
@@ -408,6 +448,11 @@ if (cmd === 'setup') {
   process.exit(0)
 }
 
+if (cmd === 'doctor') {
+  runDoctor(args)
+  process.exit(0)
+}
+
 if (cmd === 'install') {
   // Backwards-compat: run both init + setup
   await runInit(args)
@@ -1075,6 +1120,118 @@ if (cmd === 'build') {
       })
     })
   }
+} else if (cmd === 'fix') {
+  // compose fix <bug-code> — runs the bug-fix.stratum.yaml pipeline.
+  // Thin delegation to runBuild() with template='bug-fix'. The pipeline owns
+  // iteration (test step retries=5 + ensure passing==true; retro_check enforces
+  // hard-stop at attempt 2 for visual/CSS bugs and flags fix chains).
+  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 filteredArgs = args.filter((a, i) => i !== cwdIdx && (cwdIdx === -1 || i !== cwdIdx + 1))
+  const bugCodes = filteredArgs.filter(a => !a.startsWith('-'))
+  const bugCode = bugCodes[0]
+  const abort = filteredArgs.includes('--abort')
+  const resume = filteredArgs.includes('--resume')
+
+  if (!bugCode && !abort) {
+    console.error('Usage: compose fix <bug-code>')
+    console.error('')
+    console.error('Runs the bug-fix pipeline (reproduce → diagnose → scope → fix → test → verify → retro → ship).')
+    console.error('')
+    console.error('Options:')
+    console.error('  --abort        Abort the active fix run')
+    console.error('  --resume       Resume the active fix run for <bug-code>')
+    console.error('  --cwd <path>   Agent working directory (for cross-repo bugs)')
+    process.exit(1)
+  }
+
+  const fixCwd = process.cwd()
+  if (!existsSync(join(fixCwd, '.compose', 'compose.json')) || !existsSync(join(fixCwd, 'pipelines', 'bug-fix.stratum.yaml'))) {
+    console.log('Running compose init...\n')
+    await runInit(args.filter(a => a.startsWith('--')))
+    console.log('')
+  }
+
+  // COMP-FIX-HARD T4: bug description lives at docs/bugs/<bug-code>/description.md.
+  // If absent, scaffold a stub and exit 1 so the user can fill it before retrying.
+  let bugDescription = null
+  if (!abort && bugCode) {
+    const bugDir = join(fixCwd, 'docs', 'bugs', bugCode)
+    const descPath = join(bugDir, 'description.md')
+    if (!existsSync(descPath)) {
+      mkdirSync(bugDir, { recursive: true })
+      const scaffold = `# ${bugCode}: <symptom in one sentence>
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+## Actual behavior
+
+## Environment / Notes
+`
+      writeFileSync(descPath, scaffold)
+      console.error(`No description found at docs/bugs/${bugCode}/description.md. Scaffold written. Edit it and re-run 'compose fix ${bugCode}'.`)
+      process.exit(1)
+    }
+    try {
+      bugDescription = readFileSync(descPath, 'utf-8').trim()
+    } catch (err) {
+      console.error(`Failed to read ${descPath}: ${err.message}`)
+      process.exit(1)
+    }
+    if (!bugDescription) {
+      console.error(`docs/bugs/${bugCode}/description.md is empty. Edit it and re-run 'compose fix ${bugCode}'.`)
+      process.exit(1)
+    }
+  }
+
+  // COMP-FIX-HARD T8: --resume requires a matching active build for this bug.
+  let resumeFlowId = null
+  if (resume && !abort && bugCode) {
+    const activeBuildPath = join(fixCwd, '.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 !== bugCode || !active.flowId) {
+      console.error(`No active build to resume for ${bugCode}`)
+      process.exit(1)
+    }
+    // Refuse to resume a feature build as a bug build. Mode is best-effort:
+    // legacy active-build.json files that predate the mode field have no
+    // active.mode, in which case we trust the runBuild-side mode check.
+    if (active.mode && active.mode !== 'bug') {
+      console.error(`Cannot --resume: active build for ${bugCode} is in ${active.mode} mode, not bug mode.`)
+      process.exit(1)
+    }
+    resumeFlowId = active.flowId
+  }
+
+  import('../lib/build.js').then(({ runBuild }) => {
+    const opts = { abort, template: 'bug-fix', mode: 'bug' }
+    if (agentWorkDir) opts.workingDirectory = agentWorkDir
+    if (bugDescription) opts.description = bugDescription
+    if (resumeFlowId) opts.resumeFlowId = resumeFlowId
+    runBuild(bugCode, opts).then(() => {
+      process.exit(0)
+    }).catch((err) => {
+      console.error(`Fix failed: ${err.message}`)
+      process.exit(1)
+    })
+  })
 } else if (cmd === 'triage') {
   const triageCode = args.find(a => !a.startsWith('-'))
   if (!triageCode) {
@@ -1509,7 +1666,323 @@ if (cmd === 'build') {
     process.exit(1)
   })
 
+} else if (cmd === 'gates') {
+  // ---------------------------------------------------------------------------
+  // 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)
+  // ---------------------------------------------------------------------------
+  const gatesSubcmd = args[0]
+
+  if (gatesSubcmd === 'report') {
+    const { readGateLog } = await import('../server/gate-log-store.js')
+    const flagIdx = (flag) => args.indexOf(flag)
+    const flagVal = (flag) => {
+      const i = flagIdx(flag)
+      return i !== -1 && args[i + 1] ? args[i + 1] : null
+    }
+
+    // Parse --since: shorthand (24h, 7d, 1h) or ISO date string
+    const sinceStr = flagVal('--since')
+    let sinceMs = null
+    if (sinceStr) {
+      const shorthand = sinceStr.match(/^(\d+)(h|d)$/)
+      if (shorthand) {
+        const n = parseInt(shorthand[1], 10)
+        const mult = shorthand[2] === 'h' ? 3600000 : 86400000
+        sinceMs = Date.now() - n * mult
+      } else {
+        const parsed = Date.parse(sinceStr)
+        if (!isNaN(parsed)) sinceMs = parsed
+        else {
+          console.error(`--since: cannot parse "${sinceStr}" (use e.g. 24h, 7d, or ISO date)`)
+          process.exit(1)
+        }
+      }
+    } else {
+      // Default: last 24h
+      sinceMs = Date.now() - 86400000
+    }
+
+    const featureFilter = flagVal('--feature')
+    const format = flagVal('--format') || 'text'
+    const rubberStampMs = parseInt(flagVal('--rubber-stamp-ms') || '3000', 10)
+
+    const entries = readGateLog({ since: sinceMs, featureCode: featureFilter || undefined })
+
+    if (format === 'json') {
+      // Per-gate_id stats as JSON
+      const stats = buildGateStats(entries, rubberStampMs)
+      console.log(JSON.stringify(stats, null, 2))
+      process.exit(0)
+    }
+
+    // Text table
+    const stats = buildGateStats(entries, rubberStampMs)
+    if (stats.length === 0) {
+      console.log('No gate log entries found for the specified window.')
+      process.exit(0)
+    }
+
+    const col = (s, w) => String(s ?? '').padEnd(w)
+    const hdr = col('gate_id', 28) + col('logged', 8) + col('approve%', 10) + col('deny%', 7) + col('interrupt%', 12) + col('median_ms', 11) + 'rubber_stamp%'
+    const sep = '-'.repeat(hdr.length)
+    console.log(hdr)
+    console.log(sep)
+    for (const row of stats) {
+      const flag = row.rubber_stamp_pct > 50 ? '  <- rubber-stamp candidate' : ''
+      console.log(
+        col(row.gate_id, 28) +
+        col(row.logged_decisions, 8) +
+        col(row.approve_pct.toFixed(1), 10) +
+        col(row.deny_pct.toFixed(1), 7) +
+        col(row.interrupt_pct.toFixed(1), 12) +
+        col(row.median_ms !== null ? row.median_ms : 'N/A', 11) +
+        row.rubber_stamp_pct.toFixed(1) + flag
+      )
+    }
+    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]')
+  process.exit(1)
+
+} else if (cmd === 'loops') {
+  // ---------------------------------------------------------------------------
+  // compose loops add --feature <FC> --kind <kind> --summary "<text>" [--ttl-days N] [--parent-branch <bid>]
+  // compose loops list --feature <FC> [--include-resolved] [--format json]
+  // compose loops resolve <loopId> --feature <FC> --note "<text>"
+  // COMP-OBS-LOOPS (Decision 4)
+  // ---------------------------------------------------------------------------
+  const loopsSubcmd = args[0]
+
+  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 featureCode = flagVal('--feature')
+
+  // --feature is required on every subcommand
+  if (!featureCode) {
+    console.error('compose loops: --feature <FC> is required on every subcommand')
+    console.error('  compose loops add --feature <FC> --kind <kind> --summary "<text>"')
+    console.error('  compose loops list --feature <FC>')
+    console.error('  compose loops resolve <loopId> --feature <FC> --note "<text>"')
+    process.exit(1)
+  }
+
+  // Resolve compose server URL (default http://localhost:3000)
+  const baseUrl = process.env.COMPOSE_URL || 'http://localhost:3000'
+
+  async function httpGet(url) {
+    const { default: http } = await import(url.startsWith('https') ? 'https' : 'http')
+    return new Promise((resolve, reject) => {
+      http.get(url, (res) => {
+        let buf = ''
+        res.on('data', c => { buf += c })
+        res.on('end', () => {
+          try { resolve({ status: res.statusCode, body: JSON.parse(buf) }) }
+          catch { resolve({ status: res.statusCode, body: buf }) }
+        })
+      }).on('error', reject)
+    })
+  }
+
+  async function httpPost(urlStr, body) {
+    const { default: http } = await import(urlStr.startsWith('https') ? 'https' : 'http')
+    return new Promise((resolve, reject) => {
+      const data = JSON.stringify(body)
+      const url = new URL(urlStr)
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (urlStr.startsWith('https') ? 443 : 80),
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) },
+      }
+      const req = http.request(options, (res) => {
+        let buf = ''
+        res.on('data', c => { buf += c })
+        res.on('end', () => {
+          try { resolve({ status: res.statusCode, body: JSON.parse(buf) }) }
+          catch { resolve({ status: res.statusCode, body: buf }) }
+        })
+      })
+      req.on('error', reject)
+      req.end(data)
+    })
+  }
+
+  // Resolve item id from feature code
+  async function getItemByFeatureCode(fc) {
+    const r = await httpGet(`${baseUrl}/api/vision/items`)
+    if (r.status !== 200) throw new Error(`Failed to list items: ${JSON.stringify(r.body)}`)
+    const items = r.body.items || r.body
+    const item = items.find(i => i.lifecycle?.featureCode === fc)
+    if (!item) throw new Error(`No item found with featureCode=${fc}`)
+    return item
+  }
+
+  if (loopsSubcmd === 'add') {
+    const kind = flagVal('--kind')
+    const summary = flagVal('--summary')
+    const ttlDays = flagVal('--ttl-days') ? parseInt(flagVal('--ttl-days'), 10) : undefined
+    const parentBranch = flagVal('--parent-branch') || undefined
+
+    if (!kind) { console.error('--kind is required'); process.exit(1) }
+    if (!summary) { console.error('--summary is required'); process.exit(1) }
+
+    try {
+      const item = await getItemByFeatureCode(featureCode)
+      const r = await httpPost(`${baseUrl}/api/vision/items/${item.id}/loops`, { kind, summary, ttl_days: ttlDays, parent_branch: parentBranch })
+      if (r.status !== 201) {
+        console.error(`Error: ${JSON.stringify(r.body)}`)
+        process.exit(1)
+      }
+      const format = flagVal('--format')
+      if (format === 'json') {
+        console.log(JSON.stringify(r.body.loop, null, 2))
+      } else {
+        console.log(`Created loop: ${r.body.loop.id}`)
+        console.log(`  kind:    ${r.body.loop.kind}`)
+        console.log(`  summary: ${r.body.loop.summary}`)
+      }
+      process.exit(0)
+    } catch (err) {
+      console.error(`loops add failed: ${err.message}`)
+      process.exit(1)
+    }
+
+  } else if (loopsSubcmd === 'list') {
+    const includeResolved = hasFlag('--include-resolved')
+    const format = flagVal('--format')
+    const nowMs = Date.now()
+
+    try {
+      const item = await getItemByFeatureCode(featureCode)
+      const r = await httpGet(`${baseUrl}/api/vision/items/${item.id}/loops${includeResolved ? '?includeResolved=true' : ''}`)
+      if (r.status !== 200) {
+        console.error(`Error: ${JSON.stringify(r.body)}`)
+        process.exit(1)
+      }
+      const loops = r.body.loops
+
+      if (format === 'json') {
+        console.log(JSON.stringify(loops, null, 2))
+        process.exit(0)
+      }
+
+      if (loops.length === 0) {
+        console.log(`No open loops for ${featureCode}`)
+        process.exit(0)
+      }
+
+      // Sort oldest first
+      const sorted = [...loops].sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at))
+      // ANSI red for stale
+      const RED = '\x1b[31m'
+      const RESET = '\x1b[0m'
+
+      for (const loop of sorted) {
+        const { isStaleLoop } = await import('../server/open-loops-store.js')
+        const stale = isStaleLoop(loop, nowMs)
+        const prefix = stale ? `${RED}>TTL ` : '     '
+        const suffix = stale ? RESET : ''
+        const status = loop.resolution ? '[resolved]' : '[open]'
+        console.log(`${prefix}${loop.id.slice(0, 8)}  ${status}  [${loop.kind}]  ${loop.summary}${suffix}`)
+      }
+      process.exit(0)
+    } catch (err) {
+      console.error(`loops list failed: ${err.message}`)
+      process.exit(1)
+    }
+
+  } else if (loopsSubcmd === 'resolve') {
+    const loopId = args[1]
+    const note = flagVal('--note') || ''
+
+    if (!loopId || loopId.startsWith('-')) {
+      console.error('Usage: compose loops resolve <loopId> --feature <FC> [--note "<text>"]')
+      process.exit(1)
+    }
+
+    try {
+      const item = await getItemByFeatureCode(featureCode)
+      const r = await httpPost(`${baseUrl}/api/vision/items/${item.id}/loops/${loopId}/resolve`, {
+        note,
+        resolved_by: process.env.USER || 'unknown',
+      })
+      if (r.status !== 200) {
+        console.error(`Error: ${JSON.stringify(r.body)}`)
+        process.exit(1)
+      }
+      const format = flagVal('--format')
+      if (format === 'json') {
+        console.log(JSON.stringify(r.body.loop, null, 2))
+      } else {
+        console.log(`Resolved loop: ${r.body.loop.id}`)
+        if (note) console.log(`  note: ${note}`)
+      }
+      process.exit(0)
+    } catch (err) {
+      console.error(`loops resolve failed: ${err.message}`)
+      process.exit(1)
+    }
+
+  } else {
+    console.error(`Unknown loops subcommand: ${loopsSubcmd}`)
+    console.error('  compose loops add --feature <FC> --kind <kind> --summary "<text>"')
+    console.error('  compose loops list --feature <FC>')
+    console.error('  compose loops resolve <loopId> --feature <FC> --note "<text>"')
+    process.exit(1)
+  }
+
 } else {
   console.error(`Unknown command: ${cmd}`)
   process.exit(1)
 }
+
+// ---------------------------------------------------------------------------
+// Helper: build per-gate stats for `compose gates report`
+// ---------------------------------------------------------------------------
+function buildGateStats(entries, rubberStampMs = 3000) {
+  const byGate = new Map()
+
+  for (const e of entries) {
+    const gid = e.gate_id
+    if (!byGate.has(gid)) byGate.set(gid, [])
+    byGate.get(gid).push(e)
+  }
+
+  const rows = []
+  for (const [gate_id, gEntries] of byGate) {
+    const n = gEntries.length
+    const approve = gEntries.filter(e => e.decision === 'approve').length
+    const deny = gEntries.filter(e => e.decision === 'deny').length
+    const interrupt = gEntries.filter(e => e.decision === 'interrupt').length
+    const durations = gEntries
+      .map(e => e.duration_to_decide_ms)
+      .filter(d => typeof d === 'number')
+      .sort((a, b) => a - b)
+    const median_ms = durations.length > 0
+      ? durations[Math.floor(durations.length / 2)]
+      : null
+    const rubber_stamp_count = durations.filter(d => d < rubberStampMs).length
+    const rubber_stamp_pct = n > 0 ? (rubber_stamp_count / n) * 100 : 0
+
+    rows.push({
+      gate_id,
+      logged_decisions: n,
+      approve_pct: n > 0 ? (approve / n) * 100 : 0,
+      deny_pct:    n > 0 ? (deny    / n) * 100 : 0,
+      interrupt_pct: n > 0 ? (interrupt / n) * 100 : 0,
+      median_ms,
+      rubber_stamp_pct,
+    })
+  }
+
+  return rows.sort((a, b) => a.gate_id.localeCompare(b.gate_id))
+}