@smartmemory/compose 0.1.8-beta → 0.1.9-beta

package/bin/compose.js

@@ -15,10 +15,62 @@ 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)
 // ---------------------------------------------------------------------------
@@ -267,6 +319,10 @@ async 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
@@ -516,7 +572,20 @@ function getGitSha(repoPath) {
 
 async function runUpdate(flags) {
   const force = flags.includes('--force')
-  const cwd = process.cwd()
+  // 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}`)
@@ -623,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'))) {
@@ -664,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)
@@ -792,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.")
@@ -958,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)
@@ -967,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 })
@@ -986,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')
@@ -1107,7 +1176,7 @@ if (cmd === 'roadmap') {
     }
   }
 
-  const cwd = process.cwd()
+  const cwd = resolveCwdWithWorkspace(args)
   const roadmapPath = join(cwd, 'ROADMAP.md')
 
   if (existsSync(roadmapPath)) {
@@ -1264,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)
@@ -1332,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)')
@@ -1387,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
   }
 
@@ -1415,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)) {
@@ -1426,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}"`)
     }
@@ -1522,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}`)
@@ -1568,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)
@@ -1650,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('--')))
@@ -1725,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('--')))
@@ -1812,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}`)
@@ -1856,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.")
@@ -1887,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) {
@@ -2186,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

package/lib/discover-workspaces.js

@@ -0,0 +1,109 @@
+/**
+ * discover-workspaces.js — bounded bidirectional discovery of compose workspaces.
+ *
+ * Walks upward to find an "anchor" (any of ANCHOR_MARKERS), then scans the anchor
+ * subtree to MAX_DEPTH for `.compose/` markers. Hard-capped at MAX_VISITED dirs;
+ * over-cap throws an Error with code='WorkspaceDiscoveryTooBroad'. Permission
+ * errors during readdir are skipped silently — discovery is best-effort, not
+ * authoritative for individual subtrees.
+ *
+ * Exports:
+ *   - findAnchor(startDir) → string|null
+ *   - discoverWorkspaces(startDir) → { anchor, candidates: [{id, root, configPath}] }
+ *   - deriveId({root}) → {id, root, configPath}
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+
+export const ANCHOR_MARKERS = ['.compose', '.stratum.yaml', '.git'];
+export const WORKSPACE_MARKER = '.compose';
+export const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.turbo']);
+export const MAX_DEPTH = 3;
+export const MAX_VISITED = 500;
+
+/**
+ * Walk upward from startDir; return the first directory containing any
+ * ANCHOR_MARKER, or null if none found before filesystem root.
+ */
+export function findAnchor(startDir) {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+  while (true) {
+    for (const marker of ANCHOR_MARKERS) {
+      if (fs.existsSync(path.join(dir, marker))) return dir;
+    }
+    if (dir === root) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Discover candidate workspaces under the anchor for startDir.
+ * If no anchor exists upward, anchors at startDir itself.
+ */
+export function discoverWorkspaces(startDir) {
+  const anchor = findAnchor(startDir) ?? path.resolve(startDir);
+  const visited = { count: 0 };
+  const candidates = [];
+  walkDescendants(anchor, 0, candidates, visited);
+  if (fs.existsSync(path.join(anchor, WORKSPACE_MARKER))) {
+    if (!candidates.find((c) => c.root === anchor)) {
+      candidates.unshift({ root: anchor });
+    }
+  }
+  return { anchor, candidates: candidates.map(deriveId) };
+}
+
+function walkDescendants(dir, depth, out, visited) {
+  if (depth > MAX_DEPTH) return;
+  if (++visited.count > MAX_VISITED) {
+    const e = new Error(
+      `Workspace discovery exceeded ${MAX_VISITED} directories from anchor. ` +
+      'Set COMPOSE_TARGET=/absolute/path to bypass discovery.',
+    );
+    e.code = 'WorkspaceDiscoveryTooBroad';
+    throw e;
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    // EACCES, EPERM, ENOENT (race with rm), ENOTDIR (symlink target gone) —
+    // skip silently. Discovery is best-effort; missing perms aren't fatal.
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
+    const child = path.join(dir, entry.name);
+    if (fs.existsSync(path.join(child, WORKSPACE_MARKER))) {
+      out.push({ root: child });
+    }
+    walkDescendants(child, depth + 1, out, visited);
+  }
+}
+
+/**
+ * Resolve {id, root, configPath} for a candidate workspace root.
+ * Honors `.compose/compose.json#workspaceId` if it matches the canonical regex;
+ * otherwise falls back to path.basename(root).
+ *
+ * Exported so resolve-workspace.js can derive ids without re-running discovery.
+ */
+export function deriveId({ root }) {
+  const configPath = path.join(root, '.compose', 'compose.json');
+  let id = path.basename(root);
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (
+      typeof cfg.workspaceId === 'string' &&
+      /^[a-z][a-z0-9-]{1,63}$/.test(cfg.workspaceId)
+    ) {
+      id = cfg.workspaceId;
+    }
+  } catch {
+    // missing/unreadable/malformed → basename is fine
+  }
+  return { id, root, configPath };
+}

package/lib/resolve-workspace.js

@@ -0,0 +1,166 @@
+/**
+ * resolve-workspace.js — single resolver chain for compose workspaces.
+ *
+ * Precedence:
+ *   1. explicit hint.workspaceId  (cheap upward walk first; falls back to discovery)
+ *   2. COMPOSE_TARGET env         (absolute path bypasses discovery; id routes through it)
+ *   3. hint.getBinding() (MCP binding)
+ *   4. discovery (auto-pick when exactly one candidate; throws otherwise)
+ *
+ * Throws structured errors with `.code`: WorkspaceUnknown, WorkspaceAmbiguous,
+ * WorkspaceIdCollision, WorkspaceUnset. The CLI's dieOnWorkspaceError consumes them.
+ *
+ * Design intent: explicit-flag path uses findWorkspaceById (cheap upward walk)
+ * BEFORE invoking discoverWorkspaces — this lets users escape WorkspaceDiscoveryTooBroad
+ * by passing --workspace=<ancestor-id>. A descendant id still routes through discovery.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { discoverWorkspaces, deriveId } from './discover-workspaces.js';
+
+export class WorkspaceUnknown extends Error {
+  constructor(id) {
+    super(`Unknown workspaceId: ${id}`);
+    this.code = 'WorkspaceUnknown';
+    this.id = id;
+  }
+}
+
+export class WorkspaceAmbiguous extends Error {
+  constructor(candidates) {
+    super('Multiple workspaces match cwd');
+    this.code = 'WorkspaceAmbiguous';
+    this.candidates = candidates;
+  }
+}
+
+export class WorkspaceIdCollision extends Error {
+  constructor(id, roots) {
+    super(`workspaceId "${id}" used by multiple roots`);
+    this.code = 'WorkspaceIdCollision';
+    this.id = id;
+    this.roots = roots;
+  }
+}
+
+export class WorkspaceUnset extends Error {
+  constructor() {
+    super('No workspace resolved');
+    this.code = 'WorkspaceUnset';
+  }
+}
+
+/**
+ * Resolve a workspace from hints + env + cwd.
+ *
+ * @param {object} hint
+ * @param {string} [hint.cwd]          — defaults to process.cwd()
+ * @param {string} [hint.workspaceId]  — explicit --workspace=<id>
+ * @param {() => string|null} [hint.getBinding] — MCP binding accessor
+ * @returns {{id: string, root: string, configPath: string, source: string}}
+ */
+export function resolveWorkspace(hint = {}) {
+  const cwd = hint.cwd ?? process.cwd();
+
+  // 1. Explicit flag — authoritative. Cheap upward walk first; fall back to
+  //    discovery (which may throw TooBroad for pathological trees).
+  if (hint.workspaceId) {
+    const found = findWorkspaceById(cwd, hint.workspaceId);
+    if (found) return { ...found, source: 'explicit-flag' };
+    const { candidates } = discoverWorkspaces(cwd);
+    return resolveByIdScopedCollisionCheck(hint.workspaceId, candidates, 'explicit-flag');
+  }
+
+  // 2. COMPOSE_TARGET — absolute path is authoritative without discovery.
+  if (process.env.COMPOSE_TARGET) {
+    const t = process.env.COMPOSE_TARGET;
+    if (path.isAbsolute(t)) {
+      if (!fs.existsSync(t)) {
+        const e = new Error(`COMPOSE_TARGET=${t} does not exist`);
+        e.code = 'WorkspaceUnknown';
+        e.id = t;
+        throw e;
+      }
+      return { ...deriveId({ root: t }), source: 'env' };
+    }
+    const { candidates } = discoverWorkspaces(cwd);
+    return resolveByIdScopedCollisionCheck(t, candidates, 'env');
+  }
+
+  // 3. MCP binding — scoped collision check on the bound id.
+  if (hint.getBinding) {
+    const id = hint.getBinding();
+    if (id) {
+      const { candidates } = discoverWorkspaces(cwd);
+      return resolveByIdScopedCollisionCheck(id, candidates, 'mcp-binding');
+    }
+  }
+
+  // 4. Discovery — collisions matter because we're auto-picking.
+  const { candidates } = discoverWorkspaces(cwd);
+  detectCollisions(candidates);
+  if (candidates.length === 0) throw new WorkspaceUnset();
+  if (candidates.length === 1) return { ...candidates[0], source: 'discovery' };
+  throw new WorkspaceAmbiguous(candidates.map(({ id, root }) => ({ id, root })));
+}
+
+/**
+ * Cheap upward-only lookup: walk ancestors from startDir, return the first
+ * `.compose/` directory whose derived id matches targetId. Lets users bypass
+ * descendant-cap entirely via `--workspace=<ancestor-id>`.
+ */
+function findWorkspaceById(startDir, targetId) {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.compose'))) {
+      const candidate = deriveId({ root: dir });
+      if (candidate.id === targetId) return candidate;
+    }
+    if (dir === root) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function resolveByIdScopedCollisionCheck(id, candidates, source) {
+  const matching = candidates.filter((c) => c.id === id);
+  if (matching.length === 0) throw new WorkspaceUnknown(id);
+  if (matching.length > 1) {
+    throw new WorkspaceIdCollision(id, matching.map((m) => m.root));
+  }
+  return { ...matching[0], source };
+}
+
+function detectCollisions(candidates) {
+  const byId = new Map();
+  for (const c of candidates) {
+    if (!byId.has(c.id)) byId.set(c.id, []);
+    byId.get(c.id).push(c.root);
+  }
+  for (const [id, roots] of byId) {
+    if (roots.length > 1) throw new WorkspaceIdCollision(id, roots);
+  }
+}
+
+/**
+ * Pull --workspace=<id> or --workspace <id> out of args, mutating in place.
+ * Returns the id, or null if absent.
+ */
+export function getWorkspaceFlag(args) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--workspace' && i + 1 < args.length) {
+      const id = args[i + 1];
+      args.splice(i, 2);
+      return id;
+    }
+    if (typeof a === 'string' && a.startsWith('--workspace=')) {
+      const id = a.slice('--workspace='.length);
+      args.splice(i, 1);
+      return id;
+    }
+  }
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.1.8-beta",
+  "version": "0.1.9-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",
@@ -95,7 +95,6 @@
     "date-fns": "^3.6.0",
     "diff": "^8.0.4",
     "express": "^4.21.0",
-    "ink": "^5.2.1",
     "lucide-react": "^0.563.0",
     "mermaid": "^11.13.0",
     "react": "^19.2.5",

package/server/compose-mcp-tools.js

@@ -9,11 +9,12 @@ import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { ArtifactManager, ARTIFACT_SCHEMAS } from './artifact-manager.js';
-import { getTargetRoot, getDataDir, resolveProjectPath } from './project-root.js';
+import { getTargetRoot, getDataDir, resolveProjectPath, switchProject, setCurrentWorkspaceId } from './project-root.js';
+import { resolveWorkspace } from '../lib/resolve-workspace.js';
+import { discoverWorkspaces } from '../lib/discover-workspaces.js';
 
-export const PROJECT_ROOT = getTargetRoot();
-export const VISION_FILE = path.join(getDataDir(), 'vision-state.json');
-export const SESSIONS_FILE = path.join(getDataDir(), 'sessions.json');
+export function getVisionFile() { return path.join(getDataDir(), 'vision-state.json'); }
+export function getSessionsFile() { return path.join(getDataDir(), 'sessions.json'); }
 
 // ---------------------------------------------------------------------------
 // Data access
@@ -21,7 +22,7 @@ export const SESSIONS_FILE = path.join(getDataDir(), 'sessions.json');
 
 export function loadVisionState() {
   try {
-    const raw = fs.readFileSync(VISION_FILE, 'utf-8');
+    const raw = fs.readFileSync(getVisionFile(), 'utf-8');
     const state = JSON.parse(raw);
     if (Array.isArray(state.gates)) {
       const seen = new Map();
@@ -36,7 +37,7 @@ export function loadVisionState() {
 
 export function loadSessions() {
   try {
-    const raw = fs.readFileSync(SESSIONS_FILE, 'utf-8');
+    const raw = fs.readFileSync(getSessionsFile(), 'utf-8');
     const sessions = JSON.parse(raw);
     return Array.isArray(sessions) ? sessions : [];
   } catch {
@@ -466,3 +467,24 @@ export function toolGetPendingGates({ itemId }) {
   return { count: pending.length, gates: pending };
 }
 
+// ---------------------------------------------------------------------------
+// Workspace binding (MCP session-scoped)
+// ---------------------------------------------------------------------------
+
+let _binding = null;
+
+export function toolSetWorkspace({ workspaceId }) {
+  const resolved = resolveWorkspace({ workspaceId });
+  switchProject(resolved.root);
+  setCurrentWorkspaceId(resolved.id);
+  _binding = resolved;
+  return { id: resolved.id, root: resolved.root, source: 'mcp-binding' };
+}
+
+export function toolGetWorkspace() {
+  const { candidates } = discoverWorkspaces(process.cwd());
+  return { current: _binding, candidates };
+}
+
+export function _getBinding() { return _binding?.id ?? null; }
+

package/server/compose-mcp.js

@@ -59,7 +59,12 @@ import {
   toolGetCompletions,
   toolValidateFeature,
   toolValidateProject,
+  toolSetWorkspace,
+  toolGetWorkspace,
+  _getBinding,
 } from './compose-mcp-tools.js';
+import { switchProject, getTargetRoot } from './project-root.js';
+import { resolveWorkspace } from '../lib/resolve-workspace.js';
 
 // ---------------------------------------------------------------------------
 // Tool definitions
@@ -151,6 +156,20 @@ const TOOLS = [
       required: ['featureCode'],
     },
   },
+  {
+    name: 'set_workspace',
+    description: 'Bind this MCP session to a workspace. Required when cwd contains multiple workspaces. Lives in process memory; lost on MCP restart.',
+    inputSchema: {
+      type: 'object',
+      required: ['workspaceId'],
+      properties: { workspaceId: { type: 'string', description: 'Workspace ID (kebab-case)' } },
+    },
+  },
+  {
+    name: 'get_workspace',
+    description: 'Get the current MCP workspace binding plus all candidates discovered from cwd.',
+    inputSchema: { type: 'object', properties: {} },
+  },
   {
     name: 'get_feature_lifecycle',
     description: 'Get the lifecycle state of a feature: current phase, phase history, artifacts, warnings.',
@@ -570,7 +589,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
 
+  const WORKSPACE_EXEMPT = new Set(['set_workspace', 'get_workspace']);
+
   try {
+    if (!WORKSPACE_EXEMPT.has(name)) {
+      const ws = resolveWorkspace({ getBinding: _getBinding });
+      if (ws.root !== getTargetRoot()) switchProject(ws.root);
+    }
     let result;
     switch (name) {
       case 'get_vision_items':    result = toolGetVisionItems(args); break;
@@ -579,6 +604,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_blocked_items':   result = toolGetBlockedItems(); break;
       case 'get_current_session': result = await toolGetCurrentSession(args); break;
       case 'bind_session':             result = await toolBindSession(args); break;
+      case 'set_workspace':            result = toolSetWorkspace(args); break;
+      case 'get_workspace':            result = toolGetWorkspace(); break;
       case 'get_feature_lifecycle':    result = toolGetFeatureLifecycle(args); break;
       case 'kill_feature':             result = await toolKillFeature(args); break;
       case 'complete_feature':         result = await toolCompleteFeature(args); break;
@@ -624,6 +651,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     let text = err && err.code
       ? `Error [${err.code}]: ${err.message}`
       : `Error: ${err.message}`;
+    // For workspace ambiguity, include the candidate list and the call to fix it
+    // so Claude can prompt the user without a follow-up tool call.
+    if (err && err.code === 'WorkspaceAmbiguous' && Array.isArray(err.candidates)) {
+      text += '\n\nCandidates:';
+      for (const c of err.candidates) text += `\n  - ${c.id}  (${c.root})`;
+      text += '\n\nNext step: call set_workspace({"workspaceId": "<id>"}) and retry.';
+    }
+    if (err && err.code === 'WorkspaceIdCollision' && Array.isArray(err.roots)) {
+      text += `\n\nworkspaceId "${err.id}" is used by multiple roots:`;
+      for (const r of err.roots) text += `\n  - ${r}`;
+      text += '\n\nFix: set an explicit workspaceId in each .compose/compose.json.';
+    }
+    if (err && err.code === 'WorkspaceUnset') {
+      text += '\n\nNo .compose/ workspace was found. Run `compose init` to scaffold one.';
+    }
     if (err && err.cause && typeof err.cause.message === 'string') {
       text += err.cause.code
         ? `\n  Caused by [${err.cause.code}]: ${err.cause.message}`

package/server/project-root.js

@@ -48,6 +48,10 @@ export function getTargetRoot() { return _targetRoot; }
 /** Data directory for Compose state. Lives in the target project. */
 export function getDataDir() { return _dataDir; }
 
+let _currentWorkspaceId = null;
+export function getCurrentWorkspaceId() { return _currentWorkspaceId; }
+export function setCurrentWorkspaceId(id) { _currentWorkspaceId = id; }
+
 // ---------------------------------------------------------------------------
 // Switch project at runtime
 // ---------------------------------------------------------------------------