code-as-plan 2.0.3 → 2.0.6

package/cap/bin/lib/cap-feature-map.cjs

@@ -75,15 +75,17 @@ function generateTemplate() {
 `;
 }
 
-// @gsd-api readFeatureMap(projectRoot) -- Reads and parses FEATURE-MAP.md from project root.
+// @gsd-api readFeatureMap(projectRoot, appPath) -- Reads and parses FEATURE-MAP.md from project root or app subdirectory.
 // Returns: FeatureMap object with features and lastScan timestamp.
 // @gsd-todo(ref:AC-10) Feature Map is the single source of truth for feature identity, state, ACs, and relationships
 /**
  * @param {string} projectRoot - Absolute path to project root
+ * @param {string|null} [appPath=null] - Relative app path (e.g., "apps/flow"). If null, reads from projectRoot.
  * @returns {FeatureMap}
  */
-function readFeatureMap(projectRoot) {
-  const filePath = path.join(projectRoot, FEATURE_MAP_FILE);
+function readFeatureMap(projectRoot, appPath) {
+  const baseDir = appPath ? path.join(projectRoot, appPath) : projectRoot;
+  const filePath = path.join(baseDir, FEATURE_MAP_FILE);
   if (!fs.existsSync(filePath)) {
     return { features: [], lastScan: null };
   }
@@ -195,14 +197,16 @@ function parseFeatureMapContent(content) {
   return { features, lastScan };
 }
 
-// @gsd-api writeFeatureMap(projectRoot, featureMap) -- Serializes FeatureMap to FEATURE-MAP.md.
-// Side effect: overwrites FEATURE-MAP.md at project root.
+// @gsd-api writeFeatureMap(projectRoot, featureMap, appPath) -- Serializes FeatureMap to FEATURE-MAP.md.
+// Side effect: overwrites FEATURE-MAP.md at project root or app subdirectory.
 /**
  * @param {string} projectRoot - Absolute path to project root
  * @param {FeatureMap} featureMap - Structured feature map data
+ * @param {string|null} [appPath=null] - Relative app path (e.g., "apps/flow"). If null, writes to projectRoot.
  */
-function writeFeatureMap(projectRoot, featureMap) {
-  const filePath = path.join(projectRoot, FEATURE_MAP_FILE);
+function writeFeatureMap(projectRoot, featureMap, appPath) {
+  const baseDir = appPath ? path.join(projectRoot, appPath) : projectRoot;
+  const filePath = path.join(baseDir, FEATURE_MAP_FILE);
   const content = serializeFeatureMap(featureMap);
   fs.writeFileSync(filePath, content, 'utf8');
 }
@@ -271,14 +275,15 @@ function serializeFeatureMap(featureMap) {
   return lines.join('\n');
 }
 
-// @gsd-api addFeature(projectRoot, feature) -- Add a new feature entry to FEATURE-MAP.md.
+// @gsd-api addFeature(projectRoot, feature, appPath) -- Add a new feature entry to FEATURE-MAP.md.
 /**
  * @param {string} projectRoot - Absolute path to project root
  * @param {{ title: string, acs?: AcceptanceCriterion[], dependencies?: string[], metadata?: Object }} feature - Feature data (ID auto-generated)
+ * @param {string|null} [appPath=null] - Relative app path for monorepo scoping
  * @returns {Feature} - The added feature with generated ID
  */
-function addFeature(projectRoot, feature) {
-  const featureMap = readFeatureMap(projectRoot);
+function addFeature(projectRoot, feature, appPath) {
+  const featureMap = readFeatureMap(projectRoot, appPath);
   const id = getNextFeatureId(featureMap.features);
   const newFeature = {
     id,
@@ -290,22 +295,23 @@ function addFeature(projectRoot, feature) {
     metadata: feature.metadata || {},
   };
   featureMap.features.push(newFeature);
-  writeFeatureMap(projectRoot, featureMap);
+  writeFeatureMap(projectRoot, featureMap, appPath);
   return newFeature;
 }
 
-// @gsd-api updateFeatureState(projectRoot, featureId, newState) -- Transition feature state.
+// @gsd-api updateFeatureState(projectRoot, featureId, newState, appPath) -- Transition feature state.
 // @gsd-todo(ref:AC-9) Enforce valid state transitions: planned->prototyped->tested->shipped
 /**
  * @param {string} projectRoot - Absolute path to project root
  * @param {string} featureId - Feature ID (e.g., "F-001")
  * @param {string} newState - Target state
+ * @param {string|null} [appPath=null] - Relative app path for monorepo scoping
  * @returns {boolean} - True if transition was valid and applied
  */
-function updateFeatureState(projectRoot, featureId, newState) {
+function updateFeatureState(projectRoot, featureId, newState, appPath) {
   if (!VALID_STATES.includes(newState)) return false;
 
-  const featureMap = readFeatureMap(projectRoot);
+  const featureMap = readFeatureMap(projectRoot, appPath);
   const feature = featureMap.features.find(f => f.id === featureId);
   if (!feature) return false;
 
@@ -313,19 +319,20 @@ function updateFeatureState(projectRoot, featureId, newState) {
   if (!allowed || !allowed.includes(newState)) return false;
 
   feature.state = newState;
-  writeFeatureMap(projectRoot, featureMap);
+  writeFeatureMap(projectRoot, featureMap, appPath);
   return true;
 }
 
-// @gsd-api enrichFromTags(projectRoot, scanResults) -- Update file references from tag scan.
+// @gsd-api enrichFromTags(projectRoot, scanResults, appPath) -- Update file references from tag scan.
 // @gsd-todo(ref:AC-12) Feature Map auto-enriched from @cap-feature tags found in source code
 /**
  * @param {string} projectRoot - Absolute path to project root
  * @param {import('./cap-tag-scanner.cjs').CapTag[]} scanResults - Tags from cap-tag-scanner
+ * @param {string|null} [appPath=null] - Relative app path for monorepo scoping
  * @returns {FeatureMap}
  */
-function enrichFromTags(projectRoot, scanResults) {
-  const featureMap = readFeatureMap(projectRoot);
+function enrichFromTags(projectRoot, scanResults, appPath) {
+  const featureMap = readFeatureMap(projectRoot, appPath);
 
   for (const tag of scanResults) {
     if (tag.type !== 'feature') continue;
@@ -341,7 +348,7 @@ function enrichFromTags(projectRoot, scanResults) {
     }
   }
 
-  writeFeatureMap(projectRoot, featureMap);
+  writeFeatureMap(projectRoot, featureMap, appPath);
   return featureMap;
 }
 
@@ -486,6 +493,66 @@ function getStatus(featureMap) {
   return { totalFeatures, completedFeatures, totalACs, implementedACs, testedACs, reviewedACs };
 }
 
+// @gsd-api initAppFeatureMap(projectRoot, appPath) -- Create FEATURE-MAP.md for a specific app in a monorepo.
+// Idempotent: does not overwrite existing FEATURE-MAP.md.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} appPath - Relative app path (e.g., "apps/flow")
+ * @returns {boolean} - True if created, false if already existed
+ */
+function initAppFeatureMap(projectRoot, appPath) {
+  const baseDir = path.join(projectRoot, appPath);
+  const filePath = path.join(baseDir, FEATURE_MAP_FILE);
+  if (fs.existsSync(filePath)) return false;
+  // Ensure directory exists
+  if (!fs.existsSync(baseDir)) {
+    fs.mkdirSync(baseDir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, generateTemplate(), 'utf8');
+  return true;
+}
+
+// @gsd-api listAppFeatureMaps(projectRoot) -- Find all FEATURE-MAP.md files in a monorepo.
+// Returns array of relative paths to directories containing FEATURE-MAP.md.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string[]} - Relative directory paths that contain FEATURE-MAP.md (e.g., [".", "apps/flow", "packages/ui"])
+ */
+function listAppFeatureMaps(projectRoot) {
+  const results = [];
+
+  // Check root
+  if (fs.existsSync(path.join(projectRoot, FEATURE_MAP_FILE))) {
+    results.push('.');
+  }
+
+  // Walk subdirectories (max depth 3, skip excluded dirs)
+  const excludeDirs = new Set(['node_modules', '.git', '.cap', 'dist', 'build', 'coverage', '.planning']);
+
+  function walk(dir, depth) {
+    if (depth > 3) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_e) {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (excludeDirs.has(entry.name) || entry.name.startsWith('.')) continue;
+      const fullPath = path.join(dir, entry.name);
+      const fmPath = path.join(fullPath, FEATURE_MAP_FILE);
+      if (fs.existsSync(fmPath)) {
+        results.push(path.relative(projectRoot, fullPath));
+      }
+      walk(fullPath, depth + 1);
+    }
+  }
+
+  walk(projectRoot, 0);
+  return results;
+}
+
 module.exports = {
   FEATURE_MAP_FILE,
   VALID_STATES,
@@ -503,4 +570,6 @@ module.exports = {
   enrichFromScan,
   addFeatures,
   getStatus,
+  initAppFeatureMap,
+  listAppFeatureMaps,
 };

package/cap/bin/lib/cap-migrate.cjs

@@ -9,7 +9,7 @@ const path = require('node:path');
 
 // --- Constants ---
 
-const GSD_TAG_RE = /(@gsd-(feature|todo|risk|decision|context|status|depends|ref|pattern|api|constraint))(\([^)]*\))?\s*(.*)/;
+const GSD_TAG_RE = /(@gsd-(feature|todos?|risk|decision|context|status|depends|ref|pattern|api|constraint|placeholder|concern))(\([^)]*\))?\s*(.*)/;
 
 const SUPPORTED_EXTENSIONS = ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.rb', '.go', '.rs', '.sh', '.md'];
 const EXCLUDE_DIRS = ['node_modules', '.git', '.cap', 'dist', 'build', 'coverage'];
@@ -120,6 +120,27 @@ function migrateLineTag(line) {
         action: 'plain-comment',
       };
 
+    case 'todos':
+      // @gsd-todos (plural typo) → @cap-todo
+      return {
+        replaced: line.replace(fullTag, '@cap-todo'),
+        action: 'converted',
+      };
+
+    case 'placeholder':
+      // @gsd-placeholder → @cap-todo (placeholder is a todo variant)
+      return {
+        replaced: line.replace(fullTag, '@cap-todo'),
+        action: 'converted',
+      };
+
+    case 'concern':
+      // @gsd-concern → @cap-todo risk: (concerns are risks)
+      return {
+        replaced: line.replace(fullTag + metadata + (description ? ' ' : ''), '@cap-todo' + metadata + ' risk: ').replace(/  +/g, ' '),
+        action: 'converted',
+      };
+
     default:
       return null;
   }

package/cap/bin/lib/cap-session.cjs

@@ -16,6 +16,7 @@ const path = require('node:path');
  * @property {string} version - Session schema version (e.g., "2.0.0")
  * @property {string|null} lastCommand - Last /cap: command executed
  * @property {string|null} lastCommandTimestamp - ISO timestamp of last command
+ * @property {string|null} activeApp - Currently focused app path (e.g., "apps/flow") or null for single-repo/root
  * @property {string|null} activeFeature - Currently focused feature ID
  * @property {string|null} step - Current workflow step
  * @property {string|null} startedAt - ISO timestamp of when session started
@@ -42,6 +43,7 @@ function getDefaultSession() {
     version: '2.0.0',
     lastCommand: null,
     lastCommandTimestamp: null,
+    activeApp: null,
     activeFeature: null,
     step: null,
     startedAt: null,
@@ -175,6 +177,56 @@ function initCapDirectory(projectRoot) {
   }
 }
 
+// @gsd-api setActiveApp(projectRoot, appPath) -- Set the active app in SESSION.json for monorepo scoping.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string|null} appPath - Relative app path (e.g., "apps/flow") or null to clear
+ * @returns {CapSession}
+ */
+function setActiveApp(projectRoot, appPath) {
+  return updateSession(projectRoot, { activeApp: appPath || null });
+}
+
+// @gsd-api getActiveApp(projectRoot) -- Get current active app path from SESSION.json.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string|null} - Active app path or null
+ */
+function getActiveApp(projectRoot) {
+  const session = loadSession(projectRoot);
+  return session.activeApp || null;
+}
+
+// @gsd-api getAppRoot(projectRoot) -- Returns the effective root for app-scoped operations.
+// If activeApp is set, returns projectRoot + activeApp. Otherwise returns projectRoot.
+// This is the KEY function for all scoping decisions.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string} - Absolute path to the active app root (or project root if no app)
+ */
+function getAppRoot(projectRoot) {
+  const activeApp = getActiveApp(projectRoot);
+  if (activeApp) {
+    return path.join(projectRoot, activeApp);
+  }
+  return projectRoot;
+}
+
+// @gsd-api listApps(projectRoot) -- List available apps/packages in a monorepo using detectWorkspaces.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ isMonorepo: boolean, apps: string[] }}
+ */
+function listApps(projectRoot) {
+  // Lazy require to avoid circular dependency
+  const { detectWorkspaces } = require('./cap-tag-scanner.cjs');
+  const workspaces = detectWorkspaces(projectRoot);
+  return {
+    isMonorepo: workspaces.isMonorepo,
+    apps: workspaces.packages,
+  };
+}
+
 module.exports = {
   CAP_DIR,
   SESSION_FILE,
@@ -188,4 +240,8 @@ module.exports = {
   endSession,
   isInitialized,
   initCapDirectory,
+  setActiveApp,
+  getActiveApp,
+  getAppRoot,
+  listApps,
 };

package/cap/bin/lib/cap-stack-docs.cjs

@@ -551,27 +551,73 @@ function detectWorkspacePackages(projectRoot) {
     }
   }
 
-  // Check lerna.json
-  const lernaPath = path.join(projectRoot, 'lerna.json');
-  if (!result.isMonorepo && fs.existsSync(lernaPath)) {
-    try {
-      const lerna = JSON.parse(fs.readFileSync(lernaPath, 'utf8'));
-      result.isMonorepo = true;
-      const patterns = lerna.packages || ['packages/*'];
-      for (const pattern of patterns) {
-        const baseDir = pattern.replace(/\/\*.*$/, '');
-        const fullDir = path.join(projectRoot, baseDir);
-        if (fs.existsSync(fullDir) && fs.statSync(fullDir).isDirectory()) {
-          const entries = fs.readdirSync(fullDir, { withFileTypes: true });
-          for (const entry of entries) {
-            if (entry.isDirectory()) {
-              result.packages.push(path.join(baseDir, entry.name));
-            }
+  // Helper to expand workspace patterns
+  const expandPatterns = (patterns) => {
+    for (const pattern of patterns) {
+      const baseDir = pattern.replace(/\/\*.*$/, '');
+      const fullDir = path.join(projectRoot, baseDir);
+      if (fs.existsSync(fullDir) && fs.statSync(fullDir).isDirectory()) {
+        const entries = fs.readdirSync(fullDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            result.packages.push(path.join(baseDir, entry.name));
           }
         }
       }
-    } catch (_e) {
-      // Ignore
+    }
+  };
+
+  // Check pnpm-workspace.yaml
+  if (!result.isMonorepo) {
+    const pnpmPath = path.join(projectRoot, 'pnpm-workspace.yaml');
+    if (fs.existsSync(pnpmPath)) {
+      try {
+        const content = fs.readFileSync(pnpmPath, 'utf8');
+        const packagesMatch = content.match(/packages:\s*\n((?:\s+-\s*.+\n?)*)/);
+        if (packagesMatch) {
+          result.isMonorepo = true;
+          const patterns = packagesMatch[1]
+            .split('\n')
+            .map(line => line.replace(/^\s*-\s*['"]?/, '').replace(/['"]?\s*$/, ''))
+            .filter(Boolean);
+          expandPatterns(patterns);
+        }
+      } catch (_e) {}
+    }
+  }
+
+  // Check nx.json
+  if (!result.isMonorepo) {
+    const nxPath = path.join(projectRoot, 'nx.json');
+    if (fs.existsSync(nxPath)) {
+      try {
+        const nx = JSON.parse(fs.readFileSync(nxPath, 'utf8'));
+        result.isMonorepo = true;
+        const layout = nx.workspaceLayout || {};
+        const patterns = [];
+        if (layout.appsDir) patterns.push(layout.appsDir + '/*');
+        if (layout.libsDir) patterns.push(layout.libsDir + '/*');
+        if (patterns.length === 0) {
+          for (const dir of ['apps', 'packages', 'libs']) {
+            if (fs.existsSync(path.join(projectRoot, dir))) {
+              patterns.push(dir + '/*');
+            }
+          }
+        }
+        expandPatterns(patterns);
+      } catch (_e) {}
+    }
+  }
+
+  // Check lerna.json
+  if (!result.isMonorepo) {
+    const lernaPath = path.join(projectRoot, 'lerna.json');
+    if (fs.existsSync(lernaPath)) {
+      try {
+        const lerna = JSON.parse(fs.readFileSync(lernaPath, 'utf8'));
+        result.isMonorepo = true;
+        expandPatterns(lerna.packages || ['packages/*']);
+      } catch (_e) {}
     }
   }
 

package/cap/bin/lib/cap-tag-scanner.cjs

@@ -284,6 +284,60 @@ function detectWorkspaces(projectRoot) {
     }
   }
 
+  // Check pnpm-workspace.yaml
+  if (!result.isMonorepo) {
+    const pnpmPath = path.join(projectRoot, 'pnpm-workspace.yaml');
+    if (fs.existsSync(pnpmPath)) {
+      try {
+        const content = fs.readFileSync(pnpmPath, 'utf8');
+        // Simple YAML parsing for packages array — handles:
+        //   packages:
+        //     - "apps/*"
+        //     - "packages/*"
+        const packagesMatch = content.match(/packages:\s*\n((?:\s+-\s*.+\n?)*)/);
+        if (packagesMatch) {
+          result.isMonorepo = true;
+          const patterns = packagesMatch[1]
+            .split('\n')
+            .map(line => line.replace(/^\s*-\s*['"]?/, '').replace(/['"]?\s*$/, ''))
+            .filter(Boolean);
+          result.packages = resolveWorkspaceGlobs(projectRoot, patterns);
+        }
+      } catch (_e) {
+        // Malformed pnpm-workspace.yaml
+      }
+    }
+  }
+
+  // Check nx.json (NX workspace — look for project patterns or apps/packages dirs)
+  if (!result.isMonorepo) {
+    const nxPath = path.join(projectRoot, 'nx.json');
+    if (fs.existsSync(nxPath)) {
+      try {
+        const nx = JSON.parse(fs.readFileSync(nxPath, 'utf8'));
+        result.isMonorepo = true;
+        // NX may define workspaceLayout or rely on convention (apps/, packages/, libs/)
+        const layout = nx.workspaceLayout || {};
+        const patterns = [];
+        if (layout.appsDir) patterns.push(layout.appsDir + '/*');
+        if (layout.libsDir) patterns.push(layout.libsDir + '/*');
+        // Fallback: check common NX directories
+        if (patterns.length === 0) {
+          for (const dir of ['apps', 'packages', 'libs']) {
+            if (fs.existsSync(path.join(projectRoot, dir))) {
+              patterns.push(dir + '/*');
+            }
+          }
+        }
+        if (patterns.length > 0) {
+          result.packages = resolveWorkspaceGlobs(projectRoot, patterns);
+        }
+      } catch (_e) {
+        // Malformed nx.json
+      }
+    }
+  }
+
   // Check lerna.json
   if (!result.isMonorepo) {
     const lernaPath = path.join(projectRoot, 'lerna.json');
@@ -439,6 +493,92 @@ function groupByPackage(tags, packages) {
   return groups;
 }
 
+// @gsd-api scanApp(projectRoot, appPath, options) -- Scans a single app directory plus referenced shared packages.
+// When activeApp is set, scans only the active app and shared packages it imports.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} appPath - Relative app path (e.g., "apps/flow")
+ * @param {Object} [options]
+ * @param {string[]} [options.extensions] - File extensions to include
+ * @param {string[]} [options.exclude] - Directory names to exclude
+ * @returns {{ tags: CapTag[], scannedDirs: string[] }}
+ */
+function scanApp(projectRoot, appPath, options = {}) {
+  const appDir = path.join(projectRoot, appPath);
+  const scannedDirs = [appPath];
+
+  // Scan the app directory itself
+  const appTags = scanDirectory(appDir, {
+    ...options,
+    projectRoot,
+  });
+
+  const allTags = [...appTags];
+  const seen = new Set(appTags.map(t => `${t.file}:${t.line}`));
+
+  // Detect shared packages referenced by this app via package.json dependencies
+  const sharedPkgs = detectSharedPackages(projectRoot, appPath);
+  for (const pkg of sharedPkgs) {
+    const pkgDir = path.join(projectRoot, pkg);
+    if (!fs.existsSync(pkgDir)) continue;
+    scannedDirs.push(pkg);
+    const pkgTags = scanDirectory(pkgDir, {
+      ...options,
+      projectRoot,
+    });
+    for (const tag of pkgTags) {
+      const key = `${tag.file}:${tag.line}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        allTags.push(tag);
+      }
+    }
+  }
+
+  return { tags: allTags, scannedDirs };
+}
+
+// @gsd-api detectSharedPackages(projectRoot, appPath) -- Detects workspace packages referenced by an app's package.json.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} appPath - Relative app path
+ * @returns {string[]} - Array of relative paths to shared packages
+ */
+function detectSharedPackages(projectRoot, appPath) {
+  const packages = [];
+  const appPkgPath = path.join(projectRoot, appPath, 'package.json');
+  if (!fs.existsSync(appPkgPath)) return packages;
+
+  let appPkg;
+  try {
+    appPkg = JSON.parse(fs.readFileSync(appPkgPath, 'utf8'));
+  } catch (_e) {
+    return packages;
+  }
+
+  // Collect all dependency names
+  const allDeps = Object.keys(appPkg.dependencies || {}).concat(Object.keys(appPkg.devDependencies || {}));
+
+  // Resolve workspace packages -- check if any dep matches a workspace package name
+  const workspaces = detectWorkspaces(projectRoot);
+  if (!workspaces.isMonorepo) return packages;
+
+  for (const wsPkg of workspaces.packages) {
+    const wsPkgJsonPath = path.join(projectRoot, wsPkg, 'package.json');
+    if (!fs.existsSync(wsPkgJsonPath)) continue;
+    try {
+      const wsPkgJson = JSON.parse(fs.readFileSync(wsPkgJsonPath, 'utf8'));
+      if (wsPkgJson.name && allDeps.includes(wsPkgJson.name)) {
+        packages.push(wsPkg);
+      }
+    } catch (_e) {
+      // Skip malformed
+    }
+  }
+
+  return packages;
+}
+
 // @cap-todo Detect legacy @gsd-* tags and recommend /cap:migrate
 const LEGACY_TAG_RE = /^[ \t]*(?:\/\/|\/\*|\*|#|--|"""|''')[ \t]*@gsd-(feature|todo|risk|decision|context|status|depends|ref|pattern|api|constraint)/;
 
@@ -527,4 +667,6 @@ module.exports = {
   scanMonorepo,
   groupByPackage,
   detectLegacyTags,
+  scanApp,
+  detectSharedPackages,
 };

package/commands/cap/init.md

@@ -103,6 +103,51 @@ Note the `context7Available` field -- this gets set in Step 6 to indicate whethe
 
 If FEATURE-MAP.md does NOT exist, write the empty template.
 
+## Step 5b: Detect monorepo and create per-app FEATURE-MAP.md files
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+const projectRoot = process.cwd();
+const mono = session.listApps(projectRoot);
+
+if (!mono.isMonorepo) {
+  console.log(JSON.stringify({ isMonorepo: false, created: 0, apps: [] }));
+} else {
+  let created = 0;
+  const createdApps = [];
+  for (const app of mono.apps) {
+    // Only create FEATURE-MAP.md for apps that have source files
+    const appDir = path.join(projectRoot, app);
+    if (!fs.existsSync(appDir)) continue;
+    const entries = fs.readdirSync(appDir, { withFileTypes: true });
+    const hasSrc = entries.some(e =>
+      (e.isDirectory() && (e.name === 'src' || e.name === 'lib' || e.name === 'app')) ||
+      (e.isFile() && /\.(js|ts|py|go|rs|java|rb)$/.test(e.name))
+    );
+    if (hasSrc) {
+      const wasCreated = fm.initAppFeatureMap(projectRoot, app);
+      if (wasCreated) {
+        created++;
+        createdApps.push(app);
+      }
+    }
+  }
+  console.log(JSON.stringify({ isMonorepo: true, created, apps: createdApps, totalApps: mono.apps.length }));
+}
+"
+```
+
+Store as `monorepo_init`.
+
+**If monorepo detected:**
+Log: "Monorepo detected with {totalApps} workspace packages."
+If `created > 0`: Log: "Created FEATURE-MAP.md for {created} apps: {apps list}"
+If `created === 0`: Log: "All apps already have FEATURE-MAP.md (or no source files detected)."
+
 ## Step 6: Mandatory Context7 dependency fetch
 
 <!-- @gsd-decision Multi-language dependency detection runs in priority order: package.json first, then requirements.txt, then Cargo.toml, then go.mod. First match sets project type. -->

package/commands/cap/scan.md

@@ -47,6 +47,18 @@ Check `$ARGUMENTS` for:
 - `--features NAME` -- if present, store as `feature_filter`
 - `--json` -- if present, set `json_output = true`
 
+## Step 0b: Check active app scoping
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const s = session.loadSession(process.cwd());
+console.log(JSON.stringify({ activeApp: s.activeApp }));
+"
+```
+
+Store as `app_scope`. If `app_scope.activeApp` is set, this scan will be scoped to the active app directory and its shared packages. The results will be written to the app's FEATURE-MAP.md (not root).
+
 ## Step 1: Detect monorepo configuration
 
 <!-- @gsd-decision Monorepo detection reads package.json workspaces and lerna.json. Supports npm, yarn, pnpm workspace patterns. Glob expansion uses Bash for simplicity. -->
@@ -72,6 +84,43 @@ if (fs.existsSync(pkgPath)) {
   } catch (_e) {}
 }
 
+// Check pnpm-workspace.yaml
+const pnpmPath = path.join(process.cwd(), 'pnpm-workspace.yaml');
+if (!result.isMonorepo && fs.existsSync(pnpmPath)) {
+  try {
+    const content = fs.readFileSync(pnpmPath, 'utf8');
+    const packagesMatch = content.match(/packages:\\s*\\n((?:\\s+-\\s*.+\\n?)*)/);
+    if (packagesMatch) {
+      result.isMonorepo = true;
+      result.workspaces = packagesMatch[1]
+        .split('\\n')
+        .map(line => line.replace(/^\\s*-\\s*['\"]?/, '').replace(/['\"]?\\s*$/, ''))
+        .filter(Boolean);
+    }
+  } catch (_e) {}
+}
+
+// Check nx.json
+const nxPath = path.join(process.cwd(), 'nx.json');
+if (!result.isMonorepo && fs.existsSync(nxPath)) {
+  try {
+    const nx = JSON.parse(fs.readFileSync(nxPath, 'utf8'));
+    result.isMonorepo = true;
+    const layout = nx.workspaceLayout || {};
+    const patterns = [];
+    if (layout.appsDir) patterns.push(layout.appsDir + '/*');
+    if (layout.libsDir) patterns.push(layout.libsDir + '/*');
+    if (patterns.length === 0) {
+      for (const dir of ['apps', 'packages', 'libs']) {
+        if (fs.existsSync(path.join(process.cwd(), dir))) {
+          patterns.push(dir + '/*');
+        }
+      }
+    }
+    result.workspaces = patterns;
+  } catch (_e) {}
+}
+
 // Check lerna.json
 if (!result.isMonorepo && fs.existsSync(lernaPath)) {
   try {
@@ -108,9 +157,27 @@ Store as `monorepo_info`. Log project type:
 - Monorepo: "Detected monorepo with {N} workspace packages: {list}"
 - Single repo: "Single repository project detected."
 
-## Step 2: Run tag scanner (with monorepo awareness)
+## Step 2: Run tag scanner (with monorepo and app-scoping awareness)
+
+**If `app_scope.activeApp` is set (app-scoped scan):**
 
-If monorepo detected, scan each workspace package independently AND the root:
+Scan only the active app directory and its referenced shared packages:
+
+```bash
+node -e "
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const projectRoot = process.cwd();
+const appPath = process.argv[1];
+const result = scanner.scanApp(projectRoot, appPath);
+console.log(JSON.stringify({ tags: result.tags, scannedDirs: result.scannedDirs }, null, 2));
+" '<ACTIVE_APP_PATH>'
+```
+
+Log: "App-scoped scan: {activeApp} (+ {N} shared packages)"
+
+**Else if monorepo detected (full monorepo scan):**
+
+Scan each workspace package independently AND the root:
 
 ```bash
 node -e "
@@ -152,6 +219,10 @@ if (monorepoInfo.isMonorepo) {
 " '<MONOREPO_INFO_JSON>'
 ```
 
+**Else (single repo):**
+
+Standard scan as before.
+
 Store as `all_tags`.
 
 ## Step 3: Group tags by feature and by package
@@ -187,6 +258,25 @@ Same as base scan -- run orphan detection against FEATURE-MAP.md.
 
 <!-- @gsd-decision Cross-package file refs are stored as full relative paths from project root. This means packages/core/src/auth.ts, not just src/auth.ts. Feature Map readers can identify the package from the path prefix. -->
 
+**If app-scoped (activeApp set):** Enrich the app's FEATURE-MAP.md, not root.
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const activeApp = process.argv[1] === 'null' ? null : process.argv[1];
+const tags = JSON.parse(process.argv[2]);
+const updated = fm.enrichFromTags(process.cwd(), tags, activeApp);
+console.log(JSON.stringify({
+  features_enriched: updated.features.filter(f => f.files.length > 0).length,
+  total_file_refs: updated.features.reduce((sum, f) => sum + f.files.length, 0),
+  cross_package_refs: updated.features.reduce((sum, f) =>
+    sum + f.files.filter(fp => fp.startsWith('packages/')).length, 0)
+}));
+" '<ACTIVE_APP_OR_NULL>' '<ALL_TAGS_JSON>'
+```
+
+**If not app-scoped (full scan):**
+
 ```bash
 node -e "
 const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');

package/commands/cap/start.md

@@ -73,6 +73,61 @@ console.log('FEATURE-MAP.md created');
 
 Log: "Created .cap/ directory and FEATURE-MAP.md"
 
+## Step 1b: Detect monorepo and handle app scoping
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const s = session.loadSession(process.cwd());
+const mono = session.listApps(process.cwd());
+console.log(JSON.stringify({ isMonorepo: mono.isMonorepo, apps: mono.apps, activeApp: s.activeApp }));
+"
+```
+
+Store as `mono_info`.
+
+**If monorepo and no activeApp in session:**
+
+Log: "Monorepo detected with {N} apps. Select an app to scope your session."
+
+List apps:
+```
+Available apps:
+{For each app:}
+  {index}. {app}
+{End for}
+  0. (root) -- Work at monorepo root level
+```
+
+Use AskUserQuestion:
+> "Select an app to focus on (enter number or path, e.g., 'apps/flow'), or '0' for root-level work:"
+
+Process response and set active app:
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const selected = process.argv[1] === 'null' ? null : process.argv[1];
+session.setActiveApp(process.cwd(), selected);
+console.log('Active app set to: ' + (selected || '(root)'));
+" '<SELECTED_APP_PATH_OR_NULL>'
+```
+
+**If monorepo and activeApp is set:**
+
+Log: "Monorepo session restored. Active app: {activeApp}"
+Continue with existing activeApp. User can switch later with /cap:switch-app.
+
+**If not a monorepo:**
+
+Continue with single-repo behavior (no app scoping).
+
+**For all subsequent steps:** When reading/writing FEATURE-MAP.md, use the activeApp path.
+The effective FEATURE-MAP.md location is:
+- Monorepo with activeApp: `{projectRoot}/{activeApp}/FEATURE-MAP.md`
+- Monorepo without activeApp (root): `{projectRoot}/FEATURE-MAP.md`
+- Single repo: `{projectRoot}/FEATURE-MAP.md`
+
 ## Step 2: Auto-detect project context
 
 <!-- @gsd-todo(ref:AC-35) /cap:start shall auto-scope to the project by deriving project information from actual code (package.json, directory structure) rather than asking questions. -->

package/commands/cap/switch-app.md

@@ -0,0 +1,166 @@
+---
+name: cap:switch-app
+description: "Switch active app in a monorepo -- lists available workspace packages, shows tag counts, updates SESSION.json."
+allowed-tools:
+  - Bash
+  - Read
+  - AskUserQuestion
+---
+
+<!-- @cap-feature(feature:monorepo-scoping) Per-app monorepo scoping -- switch active app context for all CAP commands. -->
+
+<objective>
+Switch the active app in a monorepo project. Lists available workspace packages with their tag counts, lets the user select one, updates SESSION.json, and shows the selected app's FEATURE-MAP.md status.
+
+If the project is not a monorepo, inform the user and exit.
+</objective>
+
+<context>
+$ARGUMENTS
+
+@.cap/SESSION.json
+</context>
+
+<process>
+
+## Step 1: Detect monorepo
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const result = session.listApps(process.cwd());
+console.log(JSON.stringify(result));
+"
+```
+
+Store as `mono_info`.
+
+**If not a monorepo:**
+Log: "This project is not a monorepo. /cap:switch-app is only available for monorepo projects."
+Exit.
+
+## Step 2: Get current session state
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const s = session.loadSession(process.cwd());
+console.log(JSON.stringify({ activeApp: s.activeApp }));
+"
+```
+
+Store as `current_session`.
+
+## Step 3: Scan each app for tag counts
+
+For each app in `mono_info.apps`:
+
+```bash
+node -e "
+const scanner = require('./cap/bin/lib/cap-tag-scanner.cjs');
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+const projectRoot = process.cwd();
+const apps = JSON.parse(process.argv[1]);
+const results = [];
+
+for (const app of apps) {
+  const appDir = path.join(projectRoot, app);
+  if (!fs.existsSync(appDir)) continue;
+  const tags = scanner.scanDirectory(appDir, { projectRoot });
+  const featureMap = fm.readFeatureMap(projectRoot, app);
+  const status = fm.getStatus(featureMap);
+  results.push({
+    path: app,
+    tagCount: tags.length,
+    featureCount: status.totalFeatures,
+    hasFeatureMap: fs.existsSync(path.join(appDir, 'FEATURE-MAP.md'))
+  });
+}
+
+console.log(JSON.stringify(results, null, 2));
+" '<APPS_JSON>'
+```
+
+Store as `app_stats`.
+
+## Step 4: Present app list and ask user to select
+
+Display:
+
+```
+=== Monorepo App Selector ===
+
+{If current_session.activeApp:}
+Currently active: {current_session.activeApp}
+{End if}
+
+Available apps:
+{For each app in app_stats:}
+  {index}. {app.path} -- {app.tagCount} tags, {app.featureCount} features {app.hasFeatureMap ? "" : "(no FEATURE-MAP.md)"}
+{End for}
+
+  0. (root) -- Work at monorepo root level
+```
+
+Use AskUserQuestion:
+> "Select an app by number or path (e.g., 'apps/flow'), or '0' for root-level work:"
+
+## Step 5: Update SESSION.json
+
+Process user response:
+- If `0` or `root` or `none`: set activeApp to null
+- If a number: map to the corresponding app path
+- If a path string: validate it exists in the app list
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+const selected = process.argv[1] === 'null' ? null : process.argv[1];
+session.setActiveApp(process.cwd(), selected);
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:switch-app',
+  lastCommandTimestamp: new Date().toISOString()
+});
+console.log('Active app set to: ' + (selected || '(root)'));
+" '<SELECTED_APP_PATH_OR_NULL>'
+```
+
+## Step 6: Show selected app status
+
+If an app was selected (not root):
+
+```bash
+node -e "
+const fm = require('./cap/bin/lib/cap-feature-map.cjs');
+const appPath = process.argv[1];
+const featureMap = fm.readFeatureMap(process.cwd(), appPath);
+const status = fm.getStatus(featureMap);
+console.log(JSON.stringify({
+  features: featureMap.features.map(f => ({ id: f.id, title: f.title, state: f.state })),
+  ...status
+}));
+" '<SELECTED_APP_PATH>'
+```
+
+Display:
+
+```
+Switched to: {selected_app}
+
+Feature Map status:
+  Features: {totalFeatures} ({completedFeatures} shipped)
+  ACs: {totalACs} total, {implementedACs} implemented
+
+{If features exist:}
+Features in {selected_app}:
+{For each feature:}
+  {feature.id}: {feature.title} [{feature.state}]
+{End for}
+{Else:}
+No features yet. Run /cap:brainstorm or /cap:init to create FEATURE-MAP.md for this app.
+{End if}
+```
+
+</process>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-as-plan",
-  "version": "2.0.3",
+  "version": "2.0.6",
   "description": "CAP — Code as Plan. Build first, plan from code. Farley-aligned engineering framework for Claude Code.",
   "bin": {
     "cap": "bin/install.js"