@smartmemory/compose 0.1.7-beta → 0.1.9-beta

package/README.md

@@ -34,9 +34,20 @@ compose build TODO-1
 
 Prerequisites: Node.js 18+ and `stratum-mcp` on PATH (`pip install stratum`). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
 
+The package is published to npm as `@smartmemory/compose`. Pick one install style:
+
+**Option A — npm (recommended for users):**
+
+```bash
+npm install -g @smartmemory/compose
+compose setup                # global skill + stratum-mcp registration
+```
+
+**Option B — git clone (for development):**
+
 ```bash
 git clone https://github.com/smartmemory/compose.git && cd compose && npm install
-npx compose setup            # global skill + stratum-mcp registration
+npx @smartmemory/compose setup   # or: node bin/compose.js setup
 ln -s "$(pwd)/bin/compose.js" ~/bin/compose && chmod +x ~/bin/compose   # optional: bare `compose` command
 ```
 
@@ -44,15 +55,31 @@ Then in your project:
 
 ```bash
 cd /path/to/your/project
-npx compose init             # writes .compose/, registers MCP, scaffolds ROADMAP and pipeline specs
-npx compose new "what you want to build"
+compose init                 # writes .compose/, registers MCP, scaffolds ROADMAP and pipeline specs
+compose new "what you want to build"
 ```
 
 Add an isolated feature to an existing project:
 
 ```bash
-npx compose feature AUTH-1 "JWT middleware with refresh tokens"
-npx compose build AUTH-1
+compose feature AUTH-1 "JWT middleware with refresh tokens"
+compose build AUTH-1
+```
+
+## Upgrading
+
+One command — auto-detects whether compose was installed via npm or git clone:
+
+```bash
+compose update
+```
+
+For npm installs, this runs `npm install -g @smartmemory/compose@latest`. For git clones, it runs `git pull --ff-only && npm install`. Either way it then refreshes the global skill and (if invoked from inside a Compose project) re-runs `compose init` to refresh `.mcp.json` and pipeline templates. Use `compose update --force` to bypass the dirty-tree check on git clones.
+
+Check what you're running:
+
+```bash
+compose --version
 ```
 
 ## Documentation

package/bin/compose.js

@@ -10,20 +10,73 @@
  * 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'
+import { resolve, join, basename, dirname, sep } from 'path'
 import { homedir } from 'os'
 import { spawn, spawnSync } from 'child_process'
 import { fileURLToPath } from 'url'
 import { findProjectRoot } from '../server/find-root.js'
+import { resolveWorkspace, getWorkspaceFlag } from '../lib/resolve-workspace.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PACKAGE_ROOT = resolve(__dirname, '..')
 
+function dieOnWorkspaceError(err) {
+  switch (err.code) {
+    case 'WorkspaceAmbiguous':
+      console.error('Multiple workspaces match cwd. Add --workspace=<id> or set COMPOSE_TARGET:')
+      for (const c of err.candidates) console.error(`  --workspace=${c.id}    (${c.root})`)
+      process.exit(1)
+    case 'WorkspaceIdCollision':
+      console.error(`workspaceId "${err.id}" is used by multiple roots:`)
+      for (const r of err.roots) console.error(`  ${r}`)
+      console.error('Set an explicit workspaceId in each .compose/compose.json.')
+      process.exit(1)
+    case 'WorkspaceUnknown':
+      // err.message may be the path-doesn't-exist form; prefer it when richer.
+      console.error(err.message.includes('does not exist') ? err.message : `Unknown workspace: ${err.id}. Run \`compose doctor\` to list candidates.`)
+      process.exit(1)
+    case 'WorkspaceUnset':
+      console.error('No compose workspace found from the current directory.')
+      console.error('Run `compose init` to scaffold one, or cd into a project that has a .compose/ directory.')
+      process.exit(1)
+    case 'WorkspaceDiscoveryTooBroad':
+      console.error('Workspace discovery exceeded its bound from anchor.')
+      console.error('Set COMPOSE_TARGET=/absolute/path/to/workspace to bypass discovery.')
+      process.exit(1)
+    default:
+      throw err
+  }
+}
+
+// Cache the resolved cwd for the lifetime of this CLI process. resolveCwdWithWorkspace
+// strips --workspace from args on first call (via getWorkspaceFlag splice), so a second
+// call would re-resolve without the hint. Cache prevents this; ensures auto-init paths
+// (runInit re-entry from build/fix/import/new) see the same workspace.
+let _resolvedCwdCache = null
+
+function resolveCwdWithWorkspace(args) {
+  if (_resolvedCwdCache !== null) return _resolvedCwdCache
+  let wsId = getWorkspaceFlag(args)
+  // Legacy hooks may pass the unsubstituted token literally — treat as absent.
+  if (wsId === '__COMPOSE_WORKSPACE_ID__') {
+    console.warn('[compose] hook predates workspace-aware install — re-run `compose hooks install`')
+    wsId = null
+  }
+  try {
+    const ws = resolveWorkspace({ workspaceId: wsId })
+    _resolvedCwdCache = ws.root
+    return ws.root
+  } catch (err) {
+    dieOnWorkspaceError(err)
+  }
+}
+
 // ---------------------------------------------------------------------------
 // --team flag (COMP-TEAMS)
 // ---------------------------------------------------------------------------
 import { parseTeamFlag } from '../lib/team-flag.js';
-import { loadDeps, checkExternalSkills, printDepReport } from '../lib/deps.js';
+import { loadDeps, checkExternalSkills, printDepReport, buildDepReport } from '../lib/deps.js';
+import { checkLatestVersion } from '../lib/version-check.js';
 
 const [,, cmd, ...args] = process.argv
 
@@ -31,6 +84,20 @@ const [,, cmd, ...args] = process.argv
 // Help
 // ---------------------------------------------------------------------------
 
+if (cmd === '--version' || cmd === '-V' || cmd === 'version') {
+  const pkgPath = join(PACKAGE_ROOT, 'package.json')
+  let version = 'unknown'
+  try { version = JSON.parse(readFileSync(pkgPath, 'utf-8')).version } catch {}
+  console.log(`compose ${version}`)
+  const gitDir = join(PACKAGE_ROOT, '.git')
+  if (existsSync(gitDir)) {
+    const sha = spawnSync('git', ['-C', PACKAGE_ROOT, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf-8' })
+    if (sha.status === 0) console.log(`  git: ${sha.stdout.trim()}`)
+  }
+  console.log(`  root: ${PACKAGE_ROOT}`)
+  process.exit(0)
+}
+
 if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('Usage: compose <command>')
   console.log('')
@@ -49,7 +116,9 @@ 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('  update    Pull latest compose, reinstall deps, refresh global skill')
   console.log('  doctor    Check external skill dependencies')
+  console.log('  --version Print compose version, git SHA, and install root')
   process.exit(0)
 }
 
@@ -195,10 +264,11 @@ function syncSkills(agents) {
 // compose doctor — re-run the external dep check
 // ---------------------------------------------------------------------------
 
-function runDoctor(flags = []) {
+async function runDoctor(flags = []) {
   const json = flags.includes('--json')
   const strict = flags.includes('--strict')
   const verbose = flags.includes('--verbose') || flags.includes('-v')
+  const refresh = flags.includes('--refresh-versions')
 
   const deps = loadDeps(PACKAGE_ROOT)
   if (!deps) {
@@ -206,8 +276,39 @@ function runDoctor(flags = []) {
     process.exit(1)
   }
   const result = checkExternalSkills(deps)
-  const allRequiredPresent = printDepReport(result, { json, verbose })
 
+  // Version drift check — never fails the doctor run.
+  const currentVersion = (() => {
+    try { return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8')).version }
+    catch { return null }
+  })()
+  const versionInfo = await checkLatestVersion(currentVersion, { force: refresh })
+
+  if (json) {
+    // Single top-level JSON document — the deps report and the version block share one root
+    // so consumers like `JSON.parse(stdout)` work. (Previously two concatenated objects.)
+    const report = buildDepReport(result)
+    console.log(JSON.stringify({ ...report, version: versionInfo }, null, 2))
+    const allRequiredPresent = result.missing.every(d => d.optional)
+    if (strict && !allRequiredPresent) process.exit(1)
+    return
+  }
+
+  // Version section — printed first so it's visible above long dep lists.
+  console.log('Version:')
+  console.log(`  installed: ${currentVersion ?? 'unknown'}`)
+  if (versionInfo) {
+    console.log(`  latest:    ${versionInfo.latest} (${versionInfo.source})`)
+    if (versionInfo.behind) {
+      console.log(`  ⚠ behind — run: compose update`)
+    } else {
+      console.log(`  ✓ up to date`)
+    }
+  } else {
+    console.log(`  latest:    unavailable (registry unreachable or cache missing)`)
+  }
+
+  const allRequiredPresent = printDepReport(result, { json: false, verbose })
   if (strict && !allRequiredPresent) process.exit(1)
 }
 
@@ -218,6 +319,10 @@ function runDoctor(flags = []) {
 async function runInit(flags) {
   const noStratum = flags.includes('--no-stratum')
   const noLifecycle = flags.includes('--no-lifecycle')
+  // init creates the workspace — never go through resolveCwdWithWorkspace (which
+  // requires one to exist). Strip --workspace if present to avoid leaving it in
+  // the shared args array for downstream subcommands.
+  getWorkspaceFlag(args)
   const cwd = process.cwd()
 
   // 1. Create .compose/ directory
@@ -434,6 +539,127 @@ function runSetup() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// compose update — pull latest, reinstall deps, refresh global skill
+// ---------------------------------------------------------------------------
+
+function detectInstallStyle() {
+  // npm install resolves bin to either:
+  //   - global: /<prefix>/lib/node_modules/@smartmemory/compose/bin/compose.js
+  //   - local:  <project>/node_modules/@smartmemory/compose/bin/compose.js
+  //   - npx cache: ~/.npm/_npx/<hash>/node_modules/@smartmemory/compose/bin/compose.js
+  // git clone places it under any path WITHOUT a node_modules ancestor that
+  // contains the package itself, but WITH a .git directory at PACKAGE_ROOT.
+  if (PACKAGE_ROOT.includes(`${sep}node_modules${sep}`)) {
+    return { style: 'npm', root: PACKAGE_ROOT }
+  }
+  if (existsSync(join(PACKAGE_ROOT, '.git'))) {
+    return { style: 'git', root: PACKAGE_ROOT }
+  }
+  return { style: 'unknown', root: PACKAGE_ROOT }
+}
+
+function getPkgVersion() {
+  try {
+    return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8')).version
+  } catch { return 'unknown' }
+}
+
+function getGitSha(repoPath) {
+  const r = spawnSync('git', ['-C', repoPath, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf-8' })
+  return r.status === 0 ? r.stdout.trim() : null
+}
+
+async function runUpdate(flags) {
+  const force = flags.includes('--force')
+  // update is user-global — workspace is optional. Try to resolve; if no
+  // workspace exists, just use process.cwd() (we may still operate on
+  // user-global state below).
+  const wsId = getWorkspaceFlag(args)
+  let cwd
+  try {
+    cwd = resolveWorkspace({ workspaceId: wsId }).root
+    _resolvedCwdCache = cwd
+  } catch (err) {
+    // Only WorkspaceUnset is benign for `update` (user-global). Any explicit
+    // mistake (bad --workspace, collision, ambiguity, too-broad) should still die.
+    if (err.code !== 'WorkspaceUnset') dieOnWorkspaceError(err)
+    cwd = process.cwd()
+  }
+  const { style, root } = detectInstallStyle()
+
+  console.log(`compose update — install style: ${style}`)
+  console.log(`  root: ${root}`)
+  console.log(`  current: v${getPkgVersion()}${style === 'git' ? ` @ ${getGitSha(root) || '?'}` : ''}`)
+  console.log('')
+
+  if (style === 'unknown') {
+    console.error('Cannot determine install style. Expected either:')
+    console.error(`  - npm install: PACKAGE_ROOT inside node_modules`)
+    console.error(`  - git clone:   .git directory at ${root}`)
+    console.error('Reinstall with: npm install -g @smartmemory/compose')
+    process.exit(1)
+  }
+
+  if (style === 'npm') {
+    // Decide global vs local: global if root is under a global prefix.
+    const npmPrefix = spawnSync('npm', ['prefix', '-g'], { encoding: 'utf-8' }).stdout.trim()
+    const isGlobal = npmPrefix && root.startsWith(npmPrefix)
+    const installCmd = isGlobal
+      ? ['install', '-g', '@smartmemory/compose@latest']
+      : ['install', '@smartmemory/compose@latest']
+    console.log(`Running: npm ${installCmd.join(' ')}`)
+    const r = spawnSync('npm', installCmd, { stdio: 'inherit' })
+    if (r.status !== 0) {
+      console.error('npm install failed')
+      process.exit(r.status || 1)
+    }
+  } else {
+    // git clone — check clean, fast-forward pull, npm install
+    const status = spawnSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf-8' })
+    if (status.stdout.trim() && !force) {
+      console.error(`Working tree at ${root} has uncommitted changes.`)
+      console.error('Commit/stash them, or re-run with --force to skip the check.')
+      process.exit(1)
+    }
+    const beforeSha = getGitSha(root)
+    console.log(`Running: git fetch && git pull --ff-only`)
+    const fetch = spawnSync('git', ['-C', root, 'fetch'], { stdio: 'inherit' })
+    if (fetch.status !== 0) { process.exit(fetch.status || 1) }
+    const pull = spawnSync('git', ['-C', root, 'pull', '--ff-only'], { stdio: 'inherit' })
+    if (pull.status !== 0) {
+      console.error('git pull --ff-only failed (likely diverged from remote).')
+      console.error(`Reconcile manually in ${root}, then re-run compose update.`)
+      process.exit(pull.status || 1)
+    }
+    const afterSha = getGitSha(root)
+    if (beforeSha === afterSha) {
+      console.log(`Already up to date at ${afterSha}.`)
+    } else {
+      console.log(`Updated ${beforeSha} → ${afterSha}`)
+    }
+
+    console.log('Running: npm install')
+    const ni = spawnSync('npm', ['install'], { cwd: root, stdio: 'inherit' })
+    if (ni.status !== 0) { process.exit(ni.status || 1) }
+  }
+
+  // Refresh global skill + stratum-mcp registration
+  console.log('')
+  console.log('Refreshing global skill installation...')
+  runSetup()
+
+  // If invoked from inside a Compose project, refresh project artifacts too
+  if (existsSync(join(cwd, '.compose', 'compose.json'))) {
+    console.log('')
+    console.log(`Refreshing project at ${cwd}...`)
+    await runInit([])
+  }
+
+  console.log('')
+  console.log(`compose updated to v${getPkgVersion()}${style === 'git' ? ` @ ${getGitSha(root) || '?'}` : ''}`)
+}
+
 // ---------------------------------------------------------------------------
 // Command dispatch
 // ---------------------------------------------------------------------------
@@ -449,7 +675,12 @@ if (cmd === 'setup') {
 }
 
 if (cmd === 'doctor') {
-  runDoctor(args)
+  await runDoctor(args)
+  process.exit(0)
+}
+
+if (cmd === 'update' || cmd === 'upgrade') {
+  await runUpdate(args)
   process.exit(0)
 }
 
@@ -461,7 +692,7 @@ if (cmd === 'install') {
 }
 
 if (cmd === 'import') {
-  const cwd = process.cwd()
+  const cwd = resolveCwdWithWorkspace(args)
 
   // Auto-init if needed
   if (!existsSync(join(cwd, '.compose', 'compose.json'))) {
@@ -502,7 +733,7 @@ if (cmd === 'new') {
     process.exit(1)
   }
 
-  const cwd = process.cwd()
+  const cwd = resolveCwdWithWorkspace(args)
   const name = basename(cwd)
 
   // --from-idea <ID>: pre-populate intent from a promoted ideabox entry (Item 184)
@@ -630,7 +861,7 @@ if (cmd === 'feature') {
     process.exit(1)
   }
 
-  const cwd = process.cwd()
+  const cwd = resolveCwdWithWorkspace(args)
   const configPath = join(cwd, '.compose', 'compose.json')
   if (!existsSync(configPath)) {
     console.error("No .compose/compose.json found. Run 'compose init' first.")
@@ -796,7 +1027,7 @@ if (cmd === 'roadmap') {
   // compose roadmap generate — regenerate ROADMAP.md from feature.json files
   if (subcmd === 'generate' || subcmd === 'gen') {
     const { writeRoadmap } = await import('../lib/roadmap-gen.js')
-    const cwd = process.cwd()
+    const cwd = resolveCwdWithWorkspace(args)
     const path = writeRoadmap(cwd)
     console.log(`Generated ${path} from feature.json files`)
     process.exit(0)
@@ -805,7 +1036,7 @@ if (cmd === 'roadmap') {
   // compose roadmap migrate — extract ROADMAP.md entries into feature.json files
   if (subcmd === 'migrate') {
     const { migrateRoadmap } = await import('../lib/migrate-roadmap.js')
-    const cwd = process.cwd()
+    const cwd = resolveCwdWithWorkspace(args)
     const dryRun = args.includes('--dry-run')
     const overwrite = args.includes('--overwrite')
     const result = migrateRoadmap(cwd, { dryRun, overwrite })
@@ -824,7 +1055,7 @@ if (cmd === 'roadmap') {
   if (subcmd === 'check') {
     const { listFeatures } = await import('../lib/feature-json.js')
     const { parseRoadmap } = await import('../lib/roadmap-parser.js')
-    const cwd = process.cwd()
+    const cwd = resolveCwdWithWorkspace(args)
     const roadmapPath = join(cwd, 'ROADMAP.md')
     if (!existsSync(roadmapPath)) {
       console.error('No ROADMAP.md found. Run: compose roadmap generate')
@@ -945,7 +1176,7 @@ if (cmd === 'roadmap') {
     }
   }
 
-  const cwd = process.cwd()
+  const cwd = resolveCwdWithWorkspace(args)
   const roadmapPath = join(cwd, 'ROADMAP.md')
 
   if (existsSync(roadmapPath)) {
@@ -1102,7 +1333,7 @@ if (cmd === 'record-completion') {
   if (flags['force'] === true) completionArgs.force = true
   if (flags['idempotency-key']) completionArgs.idempotency_key = flags['idempotency-key']
 
-  const cwd = findProjectRoot(process.cwd())
+  const cwd = resolveCwdWithWorkspace(args)
   const { recordCompletion } = await import('../lib/completion-writer.js')
   try {
     const result = await recordCompletion(cwd, completionArgs)
@@ -1170,7 +1401,7 @@ if (cmd === 'hooks') {
   const { join: pjoin, resolve: presolve } = await import('path')
   const { fileURLToPath: futp } = await import('url')
 
-  const projectRoot = findProjectRoot(process.cwd())
+  const projectRoot = resolveCwdWithWorkspace(args)
   const gitDir = pjoin(projectRoot, '.git')
   if (!exSync(gitDir)) {
     console.error('Error: not a git repository (no .git directory found)')
@@ -1225,14 +1456,24 @@ if (cmd === 'hooks') {
         return 1
       }
     }
+    // Hook install must pick exactly one workspace. Repo-level hooks bake one ID.
+    const wsHint = hookFlags['workspace']
+    let wsId
+    try {
+      wsId = resolveWorkspace({ cwd: projectRoot, workspaceId: wsHint }).id
+    } catch (err) {
+      dieOnWorkspaceError(err)
+    }
     const substituted = template
       .replace(/__COMPOSE_NODE__/g, composeNode)
       .replace(/__COMPOSE_BIN__/g, composeBin)
+      .replace(/__COMPOSE_WORKSPACE_ID__/g, wsId)
     wfSync(dest, substituted)
     chmodSync(dest, 0o755)
     console.log(`Installed ${type} hook at ${dest}`)
     console.log(`  COMPOSE_NODE=${composeNode}`)
     console.log(`  COMPOSE_BIN=${composeBin}`)
+    console.log(`  COMPOSE_WORKSPACE_ID=${wsId}`)
     return 0
   }
 
@@ -1253,6 +1494,11 @@ 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)) {
@@ -1264,12 +1510,29 @@ if (cmd === 'hooks') {
       console.log(`${type}: foreign — hook exists but is not a Compose hook`)
       return
     }
+    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}"`)
-    if (nodeMatch && binMatch) {
+    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 {
-      console.log(`${type}: installed (stale paths — re-run install)`)
+      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}"`)
     }
@@ -1360,11 +1623,12 @@ Exit codes:
   }
 
   const { validateFeature, validateProject } = await import('../lib/feature-validator.js')
+  const valCwd = resolveCwdWithWorkspace(args)
   let result
   try {
     result = scope === 'feature'
-      ? await validateFeature(process.cwd(), code)
-      : await validateProject(process.cwd())
+      ? await validateFeature(valCwd, code)
+      : await validateProject(valCwd)
   } catch (err) {
     if (err.code === 'INVALID_INPUT') {
       console.error(`Error [INVALID_INPUT]: ${err.message}`)
@@ -1406,8 +1670,9 @@ Exit codes:
 
 if (cmd === 'pipeline') {
   const { runPipelineCli } = await import('../lib/pipeline-cli.js')
+  const pipeCwd = resolveCwdWithWorkspace(args)
   try {
-    runPipelineCli(process.cwd(), args)
+    runPipelineCli(pipeCwd, args)
   } catch (err) {
     console.error(`Error: ${err.message}`)
     process.exit(1)
@@ -1488,7 +1753,7 @@ if (cmd === 'build') {
   }
 
   // Auto-init if needed
-  const buildCwd = process.cwd()
+  const buildCwd = resolveCwdWithWorkspace(args)
   if (!existsSync(join(buildCwd, '.compose', 'compose.json')) || !existsSync(join(buildCwd, 'pipelines', 'build.stratum.yaml'))) {
     console.log('Running compose init...\n')
     await runInit(args.filter(a => a.startsWith('--')))
@@ -1563,7 +1828,7 @@ if (cmd === 'build') {
     process.exit(1)
   }
 
-  const fixCwd = process.cwd()
+  const fixCwd = resolveCwdWithWorkspace(args)
   if (!existsSync(join(fixCwd, '.compose', 'compose.json')) || !existsSync(join(fixCwd, 'pipelines', 'bug-fix.stratum.yaml'))) {
     console.log('Running compose init...\n')
     await runInit(args.filter(a => a.startsWith('--')))
@@ -1650,7 +1915,7 @@ if (cmd === 'build') {
   }
   import('../lib/triage.js').then(({ runTriage }) => {
     import('../lib/feature-json.js').then(({ readFeature, writeFeature, updateFeature }) => {
-      const trCwd = process.cwd()
+      const trCwd = resolveCwdWithWorkspace(args)
       runTriage(triageCode, { cwd: trCwd }).then((result) => {
         console.log(`\nFeature: ${triageCode}`)
         console.log(`Tier:     ${result.tier}`)
@@ -1694,16 +1959,11 @@ if (cmd === 'build') {
     })
   })
 } else if (cmd === 'start') {
-  // Resolve target root BEFORE spawning supervisor
-  const explicitTarget = process.env.COMPOSE_TARGET
-  const targetRoot = explicitTarget
-    ? resolve(explicitTarget)
-    : findProjectRoot(process.cwd())
-
-  if (explicitTarget && !existsSync(resolve(explicitTarget))) {
-    console.error(`[compose] COMPOSE_TARGET=${explicitTarget} does not exist.`)
-    process.exit(1)
-  }
+  // Resolve target root BEFORE spawning supervisor.
+  // Use the unified resolver — it handles COMPOSE_TARGET as either ID or absolute path,
+  // --workspace=<id>, and discovery. No need for the legacy explicitTarget short-circuit.
+  const targetRoot = resolveCwdWithWorkspace(args)
+
   if (!targetRoot || !existsSync(join(targetRoot, '.compose', 'compose.json'))) {
     console.error('[compose] No .compose/ found (searched from cwd upward).')
     console.error("[compose] Run 'compose init' first, or set COMPOSE_TARGET.")
@@ -1725,7 +1985,7 @@ if (cmd === 'build') {
   // compose ideabox — idea management CLI
   // ---------------------------------------------------------------------------
   const ibSubcmd = args[0]
-  const ibCwd = process.cwd()
+  const ibCwd = resolveCwdWithWorkspace(args)
 
   // Resolve compose config (paths, etc.)
   function loadComposeConfig(cwd) {
@@ -2024,7 +2284,7 @@ if (cmd === 'build') {
     process.exit(1)
   }
 
-  const qsCwd = process.cwd()
+  const qsCwd = resolveCwdWithWorkspace(args)
 
   import('../lib/feature-json.js').then(({ readFeature }) => {
     import('../lib/qa-scoping.js').then(({ mapFilesToRoutes, classifyRoutes }) => {

package/bin/git-hooks/post-commit.template

@@ -6,6 +6,7 @@
 set -u
 COMPOSE_NODE="__COMPOSE_NODE__"
 COMPOSE_BIN="__COMPOSE_BIN__"
+COMPOSE_WORKSPACE_ID="__COMPOSE_WORKSPACE_ID__"
 LOG="${COMPOSE_HOOK_LOG:-.compose/data/post-commit.log}"
 mkdir -p "$(dirname "$LOG")"
 
@@ -52,7 +53,7 @@ echo "$trailers" | while IFS= read -r line; do
   done
 
   if ! echo "$files" | "$COMPOSE_NODE" "$COMPOSE_BIN" record-completion "$code" \
-    --commit-sha="$sha" --tests-pass="$tp" --notes="$notes" \
+    --commit-sha="$sha" --tests-pass="$tp" --notes="$notes" --workspace="$COMPOSE_WORKSPACE_ID" \
     --files-changed-from-stdin >> "$LOG" 2>&1; then
     echo "[$(date -Iseconds)] hook: record_completion failed for $code (sha=$sha) — see above" >> "$LOG"
   fi

package/bin/git-hooks/pre-push.template

@@ -6,10 +6,11 @@
 set -u
 COMPOSE_NODE="__COMPOSE_NODE__"
 COMPOSE_BIN="__COMPOSE_BIN__"
+COMPOSE_WORKSPACE_ID="__COMPOSE_WORKSPACE_ID__"
 LOG="${COMPOSE_HOOK_LOG:-.compose/data/pre-push.log}"
 mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
 
-OUTPUT=$("$COMPOSE_NODE" "$COMPOSE_BIN" validate --scope=project --block-on=error 2>&1)
+OUTPUT=$("$COMPOSE_NODE" "$COMPOSE_BIN" validate --scope=project --block-on=error --workspace="$COMPOSE_WORKSPACE_ID" 2>&1)
 EXIT_CODE=$?
 
 if [ "$EXIT_CODE" -ne 0 ]; then