code-as-plan 2.0.2 → 2.0.4

package/bin/install.js

@@ -61,7 +61,7 @@ const hasCopilot = args.includes('--copilot');
 const hasAntigravity = args.includes('--antigravity');
 const hasCursor = args.includes('--cursor');
 const hasWindsurf = args.includes('--windsurf');
-const hasSdk = args.includes('--sdk');
+// SDK install removed in CAP v2.0 — not needed
 const hasBoth = args.includes('--both'); // Legacy flag, keeps working
 const hasAll = args.includes('--all');
 const hasUninstall = args.includes('--uninstall') || args.includes('-u');
@@ -322,7 +322,7 @@ if (hasUninstall) {
 
 // Show help if requested
 if (hasHelp) {
-  console.log(`  ${yellow}Usage:${reset} npx code-as-plan [options]\n\n  ${yellow}Options:${reset}\n    ${cyan}-g, --global${reset}              Install globally (to config directory)\n    ${cyan}-l, --local${reset}               Install locally (to current directory)\n    ${cyan}--claude${reset}                  Install for Claude Code only\n    ${cyan}--opencode${reset}                Install for OpenCode only\n    ${cyan}--gemini${reset}                  Install for Gemini only\n    ${cyan}--codex${reset}                   Install for Codex only\n    ${cyan}--copilot${reset}                 Install for Copilot only\n    ${cyan}--antigravity${reset}             Install for Antigravity only\n    ${cyan}--cursor${reset}                  Install for Cursor only\n    ${cyan}--windsurf${reset}                Install for Windsurf only\n    ${cyan}--all${reset}                     Install for all runtimes\n    ${cyan}--sdk${reset}                     Also install CAP SDK CLI (cap-sdk)\n    ${cyan}-u, --uninstall${reset}           Uninstall CAP (remove all CAP files)\n    ${cyan}-c, --config-dir <path>${reset}   Specify custom config directory\n    ${cyan}-h, --help${reset}                Show this help message\n    ${cyan}--force-statusline${reset}        Replace existing statusline config\n\n  ${yellow}Examples:${reset}\n    ${dim}# Interactive install (prompts for runtime and location)${reset}\n    npx code-as-plan\n\n    ${dim}# Install for Claude Code globally${reset}\n    npx code-as-plan --claude --global\n\n    ${dim}# Install for Gemini globally${reset}\n    npx code-as-plan --gemini --global\n\n    ${dim}# Install for Codex globally${reset}\n    npx code-as-plan --codex --global\n\n    ${dim}# Install for Copilot globally${reset}\n    npx code-as-plan --copilot --global\n\n    ${dim}# Install for Copilot locally${reset}\n    npx code-as-plan --copilot --local\n\n    ${dim}# Install for Antigravity globally${reset}\n    npx code-as-plan --antigravity --global\n\n    ${dim}# Install for Antigravity locally${reset}\n    npx code-as-plan --antigravity --local\n\n    ${dim}# Install for Cursor globally${reset}\n    npx code-as-plan --cursor --global\n\n    ${dim}# Install for Cursor locally${reset}\n    npx code-as-plan --cursor --local\n\n    ${dim}# Install for Windsurf globally${reset}\n    npx code-as-plan --windsurf --global\n\n    ${dim}# Install for Windsurf locally${reset}\n    npx code-as-plan --windsurf --local\n\n    ${dim}# Install for all runtimes globally${reset}\n    npx code-as-plan --all --global\n\n    ${dim}# Install to custom config directory${reset}\n    npx code-as-plan --codex --global --config-dir ~/.codex-work\n\n    ${dim}# Install to current project only${reset}\n    npx code-as-plan --claude --local\n\n    ${dim}# Uninstall CAP from Cursor globally${reset}\n    npx code-as-plan --cursor --global --uninstall\n\n  ${yellow}Notes:${reset}\n    The --config-dir option is useful when you have multiple configurations.\n    It takes priority over CLAUDE_CONFIG_DIR / GEMINI_CONFIG_DIR / CODEX_HOME / COPILOT_CONFIG_DIR / ANTIGRAVITY_CONFIG_DIR / CURSOR_CONFIG_DIR / WINDSURF_CONFIG_DIR environment variables.\n`);
+  console.log(`  ${yellow}Usage:${reset} npx code-as-plan [options]\n\n  ${yellow}Options:${reset}\n    ${cyan}-g, --global${reset}              Install globally (to config directory)\n    ${cyan}-l, --local${reset}               Install locally (to current directory)\n    ${cyan}--claude${reset}                  Install for Claude Code only\n    ${cyan}--opencode${reset}                Install for OpenCode only\n    ${cyan}--gemini${reset}                  Install for Gemini only\n    ${cyan}--codex${reset}                   Install for Codex only\n    ${cyan}--copilot${reset}                 Install for Copilot only\n    ${cyan}--antigravity${reset}             Install for Antigravity only\n    ${cyan}--cursor${reset}                  Install for Cursor only\n    ${cyan}--windsurf${reset}                Install for Windsurf only\n    ${cyan}--all${reset}                     Install for all runtimes\n    ${cyan}-u, --uninstall${reset}           Uninstall CAP (remove all CAP files)\n    ${cyan}-c, --config-dir <path>${reset}   Specify custom config directory\n    ${cyan}-h, --help${reset}                Show this help message\n    ${cyan}--force-statusline${reset}        Replace existing statusline config\n\n  ${yellow}Examples:${reset}\n    ${dim}# Interactive install (prompts for runtime and location)${reset}\n    npx code-as-plan\n\n    ${dim}# Install for Claude Code globally${reset}\n    npx code-as-plan --claude --global\n\n    ${dim}# Install for Gemini globally${reset}\n    npx code-as-plan --gemini --global\n\n    ${dim}# Install for Codex globally${reset}\n    npx code-as-plan --codex --global\n\n    ${dim}# Install for Copilot globally${reset}\n    npx code-as-plan --copilot --global\n\n    ${dim}# Install for Copilot locally${reset}\n    npx code-as-plan --copilot --local\n\n    ${dim}# Install for Antigravity globally${reset}\n    npx code-as-plan --antigravity --global\n\n    ${dim}# Install for Antigravity locally${reset}\n    npx code-as-plan --antigravity --local\n\n    ${dim}# Install for Cursor globally${reset}\n    npx code-as-plan --cursor --global\n\n    ${dim}# Install for Cursor locally${reset}\n    npx code-as-plan --cursor --local\n\n    ${dim}# Install for Windsurf globally${reset}\n    npx code-as-plan --windsurf --global\n\n    ${dim}# Install for Windsurf locally${reset}\n    npx code-as-plan --windsurf --local\n\n    ${dim}# Install for all runtimes globally${reset}\n    npx code-as-plan --all --global\n\n    ${dim}# Install to custom config directory${reset}\n    npx code-as-plan --codex --global --config-dir ~/.codex-work\n\n    ${dim}# Install to current project only${reset}\n    npx code-as-plan --claude --local\n\n    ${dim}# Uninstall CAP from Cursor globally${reset}\n    npx code-as-plan --cursor --global --uninstall\n\n  ${yellow}Notes:${reset}\n    The --config-dir option is useful when you have multiple configurations.\n    It takes priority over CLAUDE_CONFIG_DIR / GEMINI_CONFIG_DIR / CODEX_HOME / COPILOT_CONFIG_DIR / ANTIGRAVITY_CONFIG_DIR / CURSOR_CONFIG_DIR / WINDSURF_CONFIG_DIR environment variables.\n`);
   process.exit(0);
 }
 
@@ -4691,70 +4691,6 @@ function handleStatusline(settings, isInteractive, callback) {
   });
 }
 
-/**
- * Install the CAP SDK globally via npm.
- * @returns {boolean} true if install succeeded
- */
-function installSdk() {
-  const sdkPkg = `@gsd-build/sdk@latest`;
-  console.log(`\n  ${cyan}Installing CAP SDK...${reset}`);
-  console.log(`  ${dim}npm install -g ${sdkPkg}${reset}\n`);
-  try {
-    require('child_process').execSync(`npm install -g ${sdkPkg}`, { stdio: 'inherit' });
-    console.log(`\n  ${green}✓${reset} CAP SDK installed (${cyan}cap-sdk${reset} command available)`);
-    return true;
-  } catch (e) {
-    console.log(`\n  ${yellow}⚠${reset} SDK install failed: ${e.message}`);
-    console.log(`  ${dim}You can install it manually: npm install -g ${sdkPkg}${reset}`);
-    return false;
-  }
-}
-
-/**
- * Prompt the user to optionally install the CAP SDK.
- * Called after runtime installation completes.
- * @param {Function} callback - called with true/false
- */
-function promptSdk(callback) {
-  if (!process.stdin.isTTY) {
-    callback(false);
-    return;
-  }
-
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-
-  let answered = false;
-
-  rl.on('close', () => {
-    if (!answered) {
-      answered = true;
-      callback(false);
-    }
-  });
-
-  console.log(`
-  ${yellow}Also install the CAP SDK?${reset}
-
-  The SDK provides a standalone CLI for autonomous execution:
-    ${dim}cap-sdk init @prd.md${reset}    Bootstrap a project from a PRD
-    ${dim}cap-sdk auto${reset}            Run full autonomous lifecycle
-    ${dim}cap-sdk run "prompt"${reset}    Execute a milestone from text
-
-  ${cyan}1${reset}) No
-  ${cyan}2${reset}) Yes ${dim}(runs: npm install -g @gsd-build/sdk)${reset}
-`);
-
-  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
-    answered = true;
-    rl.close();
-    const choice = answer.trim() || '1';
-    callback(choice === '2');
-  });
-}
-
 /**
  * Prompt for runtime selection
  */
@@ -4884,7 +4820,7 @@ function installAllRuntimes(runtimes, isGlobal, isInteractive) {
   const primaryStatuslineResult = results.find(r => statuslineRuntimes.includes(r.runtime));
 
   const finalize = (shouldInstallStatusline) => {
-    // Handle SDK installation before printing final summaries
+    // Print final summaries
     const printSummaries = () => {
       for (const result of results) {
         const useStatusline = statuslineRuntimes.includes(result.runtime) && shouldInstallStatusline;
@@ -4899,18 +4835,7 @@ function installAllRuntimes(runtimes, isGlobal, isInteractive) {
       }
     };
 
-    if (hasSdk) {
-      // --sdk flag: install without prompting
-      installSdk();
-      printSummaries();
-    } else if (isInteractive) {
-      promptSdk((wantsSdk) => {
-        if (wantsSdk) installSdk();
-        printSummaries();
-      });
-    } else {
-      printSummaries();
-    }
+    printSummaries();
   };
 
   if (primaryStatuslineResult) {

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

@@ -0,0 +1,534 @@
+// @cap-feature(feature:F-MIGRATE) GSD-to-CAP migration utility -- converts @gsd-* tags, planning artifacts, and session format to CAP v2.0.
+// @cap-todo decision: Regex-based tag replacement (not AST) -- language-agnostic, zero dependencies, handles all comment styles.
+// @cap-todo risk: Destructive file writes -- dry-run mode is the default safety net.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// --- Constants ---
+
+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'];
+
+const GSD_ARTIFACTS = [
+  '.planning/FEATURES.md',
+  '.planning/REQUIREMENTS.md',
+  '.planning/PRD.md',
+  '.planning/ROADMAP.md',
+  '.planning/STATE.md',
+  '.planning/CODE-INVENTORY.md',
+  '.planning/BRAINSTORM-LEDGER.md',
+  '.planning/SESSION.json',
+];
+
+// --- Tag migration ---
+
+/**
+ * @typedef {Object} TagChange
+ * @property {string} file - Relative file path
+ * @property {number} line - 1-based line number
+ * @property {string} original - Original line content
+ * @property {string} replaced - Replacement line content (or null if removed)
+ * @property {string} action - 'converted' | 'removed' | 'plain-comment'
+ */
+
+/**
+ * Apply tag migration to a single line.
+ * @param {string} line - Source line
+ * @returns {{ replaced: string, action: string } | null} - null if no @gsd- tag found
+ */
+function migrateLineTag(line) {
+  const match = line.match(GSD_TAG_RE);
+  if (!match) return null;
+
+  const fullTag = match[1];       // e.g., @gsd-feature
+  const tagType = match[2];       // e.g., feature
+  const metadata = match[3] || ''; // e.g., (ref:AC-20)
+  const description = match[4] || '';
+
+  switch (tagType) {
+    case 'feature':
+      return {
+        replaced: line.replace(fullTag, '@cap-feature'),
+        action: 'converted',
+      };
+
+    case 'todo':
+      return {
+        replaced: line.replace(fullTag, '@cap-todo'),
+        action: 'converted',
+      };
+
+    case 'risk':
+      // @gsd-risk Some risk → @cap-todo risk: Some risk
+      return {
+        replaced: line.replace(fullTag + metadata + (description ? ' ' : ''), '@cap-todo' + metadata + ' risk: ').replace(/  +/g, ' '),
+        action: 'converted',
+      };
+
+    case 'decision':
+      // @gsd-decision Some decision → @cap-todo decision: Some decision
+      return {
+        replaced: line.replace(fullTag + metadata + (description ? ' ' : ''), '@cap-todo' + metadata + ' decision: ').replace(/  +/g, ' '),
+        action: 'converted',
+      };
+
+    case 'constraint':
+      // @gsd-constraint Some constraint → @cap-todo risk: [constraint] Some constraint
+      return {
+        replaced: line.replace(fullTag + metadata + (description ? ' ' : ''), '@cap-todo' + metadata + ' risk: [constraint] ').replace(/  +/g, ' '),
+        action: 'converted',
+      };
+
+    case 'context':
+      // @gsd-context Some context → plain comment (remove the tag)
+      return {
+        replaced: line.replace(fullTag + metadata + ' ', '').replace(fullTag + metadata, ''),
+        action: 'plain-comment',
+      };
+
+    case 'status':
+    case 'depends':
+      // Remove entirely (convert to plain comment to avoid losing info)
+      return {
+        replaced: line.replace(fullTag + metadata + ' ', '').replace(fullTag + metadata, ''),
+        action: 'removed',
+      };
+
+    case 'ref':
+      // Keep as @cap-ref if it has content, otherwise remove
+      if (description.trim()) {
+        return {
+          replaced: line.replace(fullTag, '@cap-ref'),
+          action: 'converted',
+        };
+      }
+      return {
+        replaced: line.replace(fullTag + metadata + ' ', '').replace(fullTag + metadata, ''),
+        action: 'removed',
+      };
+
+    case 'pattern':
+    case 'api':
+      // Convert to plain comment (remove the tag prefix)
+      return {
+        replaced: line.replace(fullTag + metadata + ' ', '').replace(fullTag + metadata, ''),
+        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;
+  }
+}
+
+/**
+ * Scan all source files and replace @gsd-* tags with @cap-* equivalents.
+ *
+ * Mapping:
+ *   @gsd-feature    → @cap-feature
+ *   @gsd-todo       → @cap-todo
+ *   @gsd-risk       → @cap-todo risk:
+ *   @gsd-decision   → @cap-todo decision:
+ *   @gsd-context    → plain comment (tag removed)
+ *   @gsd-status     → plain comment (tag removed)
+ *   @gsd-depends    → plain comment (tag removed)
+ *   @gsd-ref        → @cap-ref (if content exists) or removed
+ *   @gsd-pattern    → plain comment (tag removed)
+ *   @gsd-api        → plain comment (tag removed)
+ *   @gsd-constraint → @cap-todo risk: [constraint]
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun] - If true, report changes without writing
+ * @param {string[]} [options.extensions] - File extensions to process
+ * @returns {{ filesScanned: number, filesModified: number, tagsConverted: number, tagsRemoved: number, changes: TagChange[] }}
+ */
+function migrateTags(projectRoot, options = {}) {
+  const dryRun = options.dryRun || false;
+  const extensions = options.extensions || SUPPORTED_EXTENSIONS;
+  const result = {
+    filesScanned: 0,
+    filesModified: 0,
+    tagsConverted: 0,
+    tagsRemoved: 0,
+    changes: [],
+  };
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_e) {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (EXCLUDE_DIRS.includes(entry.name)) continue;
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name);
+        if (!extensions.includes(ext)) continue;
+        processFile(fullPath);
+      }
+    }
+  }
+
+  function processFile(filePath) {
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (_e) {
+      return;
+    }
+
+    result.filesScanned++;
+    const relativePath = path.relative(projectRoot, filePath);
+    const lines = content.split('\n');
+    let modified = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const migration = migrateLineTag(lines[i]);
+      if (!migration) continue;
+
+      const change = {
+        file: relativePath,
+        line: i + 1,
+        original: lines[i],
+        replaced: migration.replaced,
+        action: migration.action,
+      };
+      result.changes.push(change);
+
+      if (migration.action === 'converted') {
+        result.tagsConverted++;
+      } else {
+        result.tagsRemoved++;
+      }
+
+      lines[i] = migration.replaced;
+      modified = true;
+    }
+
+    if (modified) {
+      result.filesModified++;
+      if (!dryRun) {
+        fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+      }
+    }
+  }
+
+  walk(projectRoot);
+  return result;
+}
+
+// --- Artifact migration ---
+
+/**
+ * Convert .planning/FEATURES.md or REQUIREMENTS.md into FEATURE-MAP.md format.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun] - If true, report without writing
+ * @returns {{ featuresFound: number, featureMapCreated: boolean, source: string }}
+ */
+function migrateArtifacts(projectRoot, options = {}) {
+  const dryRun = options.dryRun || false;
+  const result = { featuresFound: 0, featureMapCreated: false, source: 'none' };
+
+  // Check if FEATURE-MAP.md already exists
+  const featureMapPath = path.join(projectRoot, 'FEATURE-MAP.md');
+  const featureMapExists = fs.existsSync(featureMapPath);
+
+  // Try reading source artifacts in priority order
+  let sourceContent = null;
+  let sourceName = null;
+
+  const sources = [
+    { file: '.planning/FEATURES.md', name: 'FEATURES.md' },
+    { file: '.planning/REQUIREMENTS.md', name: 'REQUIREMENTS.md' },
+    { file: '.planning/PRD.md', name: 'PRD.md' },
+  ];
+
+  for (const src of sources) {
+    const srcPath = path.join(projectRoot, src.file);
+    if (fs.existsSync(srcPath)) {
+      try {
+        sourceContent = fs.readFileSync(srcPath, 'utf8');
+        sourceName = src.name;
+        result.source = src.name;
+        break;
+      } catch (_e) {
+        continue;
+      }
+    }
+  }
+
+  if (!sourceContent) return result;
+
+  // Extract features from the source artifact
+  const features = extractFeaturesFromLegacy(sourceContent);
+  result.featuresFound = features.length;
+
+  if (features.length === 0) return result;
+
+  if (featureMapExists) {
+    // Merge into existing Feature Map
+    const capFeatureMap = require('./cap-feature-map.cjs');
+    if (!dryRun) {
+      const existing = capFeatureMap.readFeatureMap(projectRoot);
+      const existingTitles = new Set(existing.features.map(f => f.title.toLowerCase()));
+
+      for (const feature of features) {
+        if (!existingTitles.has(feature.title.toLowerCase())) {
+          capFeatureMap.addFeature(projectRoot, feature);
+        }
+      }
+      result.featureMapCreated = true;
+    }
+  } else {
+    // Create new Feature Map
+    if (!dryRun) {
+      const capFeatureMap = require('./cap-feature-map.cjs');
+      const template = capFeatureMap.generateTemplate();
+      fs.writeFileSync(featureMapPath, template, 'utf8');
+      for (const feature of features) {
+        capFeatureMap.addFeature(projectRoot, feature);
+      }
+      result.featureMapCreated = true;
+    } else {
+      result.featureMapCreated = true; // Would be created
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract feature entries from legacy GSD planning artifacts.
+ * Looks for markdown headings, list items with feature-like patterns.
+ *
+ * @param {string} content - Markdown content of legacy artifact
+ * @returns {{ title: string, acs: Array, dependencies: string[] }[]}
+ */
+function extractFeaturesFromLegacy(content) {
+  const features = [];
+  const lines = content.split('\n');
+
+  // Match headings that look like features: ## Feature Name, ### Feature Name, ## 1. Feature Name
+  const featureHeadingRE = /^#{2,4}\s+(?:\d+\.\s*)?(?:Feature:\s*)?(.+?)(?:\s*\[.*\])?\s*$/;
+  // Match list items that look like acceptance criteria: - [ ] description, - [x] description
+  const acRE = /^[-*]\s+\[([x ])\]\s+(.+)/i;
+  // Match plain list items as potential ACs
+  const plainListRE = /^[-*]\s+(?!#)(.+)/;
+
+  let currentFeature = null;
+  let acCounter = 0;
+
+  for (const line of lines) {
+    const headingMatch = line.match(featureHeadingRE);
+    if (headingMatch) {
+      if (currentFeature && currentFeature.title) {
+        features.push(currentFeature);
+      }
+      currentFeature = {
+        title: headingMatch[1].trim(),
+        acs: [],
+        dependencies: [],
+      };
+      acCounter = 0;
+      continue;
+    }
+
+    if (currentFeature) {
+      const acMatch = line.match(acRE);
+      if (acMatch) {
+        acCounter++;
+        currentFeature.acs.push({
+          id: `AC-${acCounter}`,
+          description: acMatch[2].trim(),
+          status: acMatch[1] === 'x' || acMatch[1] === 'X' ? 'implemented' : 'pending',
+        });
+        continue;
+      }
+
+      // Empty line after ACs but before next heading -- stop collecting ACs
+      if (line.trim() === '' && currentFeature.acs.length > 0) {
+        // Keep collecting -- next heading or feature resets
+      }
+    }
+  }
+
+  if (currentFeature && currentFeature.title) {
+    features.push(currentFeature);
+  }
+
+  return features;
+}
+
+// --- Session migration ---
+
+/**
+ * Migrate .planning/SESSION.json to .cap/SESSION.json format.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun] - If true, report without writing
+ * @returns {{ migrated: boolean, oldFormat: string, newFormat: string }}
+ */
+function migrateSession(projectRoot, options = {}) {
+  const dryRun = options.dryRun || false;
+  const result = { migrated: false, oldFormat: 'none', newFormat: 'none' };
+
+  const oldSessionPath = path.join(projectRoot, '.planning', 'SESSION.json');
+  if (!fs.existsSync(oldSessionPath)) return result;
+
+  let oldSession;
+  try {
+    const content = fs.readFileSync(oldSessionPath, 'utf8');
+    oldSession = JSON.parse(content);
+    result.oldFormat = 'v1.x';
+  } catch (_e) {
+    result.oldFormat = 'corrupt';
+    return result;
+  }
+
+  // Map old session fields to new CAP session format
+  const capSession = require('./cap-session.cjs');
+  const newSession = capSession.getDefaultSession();
+
+  // Map known v1.x fields
+  if (oldSession.current_app) {
+    newSession.metadata.legacyApp = oldSession.current_app;
+  }
+  if (oldSession.current_phase) {
+    newSession.step = `legacy-phase-${oldSession.current_phase}`;
+  }
+  if (oldSession.started_at || oldSession.startedAt) {
+    newSession.startedAt = oldSession.started_at || oldSession.startedAt;
+  }
+  if (oldSession.last_command || oldSession.lastCommand) {
+    newSession.lastCommand = oldSession.last_command || oldSession.lastCommand;
+  }
+
+  // Preserve all old fields as metadata for reference
+  for (const [key, value] of Object.entries(oldSession)) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      newSession.metadata[`gsd_${key}`] = String(value);
+    }
+  }
+
+  result.newFormat = 'v2.0';
+
+  if (!dryRun) {
+    capSession.initCapDirectory(projectRoot);
+    capSession.saveSession(projectRoot, newSession);
+    result.migrated = true;
+  } else {
+    result.migrated = true; // Would be migrated
+  }
+
+  return result;
+}
+
+// --- Analysis ---
+
+/**
+ * Generate a migration report summarizing what was found and what needs attention.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ gsdTagCount: number, gsdArtifacts: string[], planningDir: boolean, sessionJson: boolean, recommendations: string[] }}
+ */
+function analyzeMigration(projectRoot) {
+  const result = {
+    gsdTagCount: 0,
+    gsdArtifacts: [],
+    planningDir: false,
+    sessionJson: false,
+    recommendations: [],
+  };
+
+  // Check for .planning/ directory
+  const planningDir = path.join(projectRoot, '.planning');
+  result.planningDir = fs.existsSync(planningDir);
+
+  // Check for known GSD artifacts
+  for (const artifact of GSD_ARTIFACTS) {
+    const artifactPath = path.join(projectRoot, artifact);
+    if (fs.existsSync(artifactPath)) {
+      result.gsdArtifacts.push(artifact);
+    }
+  }
+
+  // Check for .planning/SESSION.json specifically
+  result.sessionJson = fs.existsSync(path.join(projectRoot, '.planning', 'SESSION.json'));
+
+  // Count @gsd-* tags in source files
+  const tagResult = migrateTags(projectRoot, { dryRun: true });
+  result.gsdTagCount = tagResult.tagsConverted + tagResult.tagsRemoved;
+
+  // Build recommendations
+  if (result.gsdTagCount > 0) {
+    result.recommendations.push(`Found ${result.gsdTagCount} @gsd-* tags to migrate. Run /cap:migrate to convert them to @cap-* tags.`);
+  }
+
+  if (result.gsdArtifacts.length > 0) {
+    result.recommendations.push(`Found ${result.gsdArtifacts.length} legacy planning artifacts: ${result.gsdArtifacts.join(', ')}. These can be converted to FEATURE-MAP.md entries.`);
+  }
+
+  if (result.sessionJson) {
+    result.recommendations.push('Found .planning/SESSION.json. This can be migrated to .cap/SESSION.json format.');
+  }
+
+  if (!fs.existsSync(path.join(projectRoot, 'FEATURE-MAP.md'))) {
+    result.recommendations.push('No FEATURE-MAP.md found. Migration will create one from existing artifacts.');
+  }
+
+  if (!fs.existsSync(path.join(projectRoot, '.cap'))) {
+    result.recommendations.push('No .cap/ directory found. Migration will initialize it.');
+  }
+
+  if (result.gsdTagCount === 0 && result.gsdArtifacts.length === 0 && !result.sessionJson) {
+    result.recommendations.push('No GSD v1.x artifacts detected. This project may already be using CAP v2.0 or is a fresh project.');
+  }
+
+  return result;
+}
+
+module.exports = {
+  GSD_TAG_RE,
+  SUPPORTED_EXTENSIONS,
+  EXCLUDE_DIRS,
+  GSD_ARTIFACTS,
+  migrateLineTag,
+  migrateTags,
+  migrateArtifacts,
+  extractFeaturesFromLegacy,
+  migrateSession,
+  analyzeMigration,
+};

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

@@ -439,11 +439,82 @@ function groupByPackage(tags, packages) {
   return groups;
 }
 
+// @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)/;
+
+/**
+ * Detect legacy @gsd-* tags in scanned files.
+ * Re-scans source files for @gsd-* patterns that the primary scanner ignores.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Object} [options]
+ * @param {string[]} [options.extensions] - File extensions to include
+ * @param {string[]} [options.exclude] - Directory names to exclude
+ * @returns {{ count: number, files: string[], recommendation: string }}
+ */
+function detectLegacyTags(projectRoot, options = {}) {
+  const extensions = options.extensions || SUPPORTED_EXTENSIONS;
+  const exclude = options.exclude || DEFAULT_EXCLUDE;
+  const result = { count: 0, files: [], recommendation: '' };
+  const fileSet = new Set();
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_e) {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (exclude.includes(entry.name)) continue;
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name);
+        if (!extensions.includes(ext)) continue;
+        scanFileForLegacy(fullPath);
+      }
+    }
+  }
+
+  function scanFileForLegacy(filePath) {
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (_e) {
+      return;
+    }
+    const lines = content.split('\n');
+    let found = false;
+    for (const line of lines) {
+      if (LEGACY_TAG_RE.test(line)) {
+        result.count++;
+        found = true;
+      }
+    }
+    if (found) {
+      const relativePath = path.relative(projectRoot, filePath);
+      fileSet.add(relativePath);
+    }
+  }
+
+  walk(projectRoot);
+  result.files = Array.from(fileSet).sort();
+
+  if (result.count > 0) {
+    result.recommendation = `Found ${result.count} legacy @gsd-* tag(s) in ${result.files.length} file(s). Run /cap:migrate to convert them to @cap-* format.`;
+  }
+
+  return result;
+}
+
 module.exports = {
   CAP_TAG_TYPES,
   CAP_TAG_RE,
   SUPPORTED_EXTENSIONS,
   DEFAULT_EXCLUDE,
+  LEGACY_TAG_RE,
   scanFile,
   scanDirectory,
   extractTags,
@@ -455,4 +526,5 @@ module.exports = {
   resolveWorkspaceGlobs,
   scanMonorepo,
   groupByPackage,
+  detectLegacyTags,
 };

package/commands/cap/migrate.md

@@ -0,0 +1,177 @@
+---
+name: cap:migrate
+description: "Migrate GSD Code-First v1.x projects to CAP v2.0 -- converts @gsd-* tags, planning artifacts, and session format."
+argument-hint: "[--dry-run] [--tags-only] [--force]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<!-- @cap-feature(feature:F-MIGRATE) Migration command -- converts GSD v1.x projects to CAP v2.0 format. -->
+<!-- @cap-todo Supports --dry-run, --tags-only, and --force flags. -->
+
+<objective>
+Migrate a GSD Code-First v1.x project to CAP v2.0 format. Converts @gsd-* tags to @cap-* equivalents, transforms planning artifacts into FEATURE-MAP.md entries, and migrates .planning/SESSION.json to .cap/SESSION.json.
+</objective>
+
+<context>
+$ARGUMENTS
+
+@FEATURE-MAP.md
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for:
+- `--dry-run` — show what would change without writing files
+- `--tags-only` — only migrate tags, skip artifact and session migration
+- `--force` — skip user confirmation gate
+
+## Step 1: Analyze migration scope
+
+Run the analysis to determine what needs migrating:
+
+```bash
+node -e "
+const migrate = require('./cap/bin/lib/cap-migrate.cjs');
+const report = migrate.analyzeMigration(process.cwd());
+console.log(JSON.stringify(report, null, 2));
+"
+```
+
+Store as `analysis`. Present a summary to the user:
+
+```
+Migration Analysis
+==================
+
+@gsd-* tags found:     {gsdTagCount}
+Legacy artifacts:       {gsdArtifacts.length} ({list})
+.planning/ directory:   {yes/no}
+SESSION.json (v1.x):   {yes/no}
+
+Recommendations:
+{For each recommendation:}
+  - {recommendation}
+```
+
+## Step 2: Confirm with user (unless --force)
+
+If `--force` is NOT set and this is NOT `--dry-run`, use AskUserQuestion to confirm:
+
+> "Proceed with migration? This will modify source files and create CAP v2.0 artifacts. Use --dry-run first if you want to preview changes."
+
+If user declines, abort with message: "Migration cancelled. Run with --dry-run to preview changes."
+
+## Step 3: Migrate tags
+
+```bash
+node -e "
+const migrate = require('./cap/bin/lib/cap-migrate.cjs');
+const dryRun = process.argv[1] === 'true';
+const result = migrate.migrateTags(process.cwd(), { dryRun });
+console.log(JSON.stringify(result, null, 2));
+" '<DRY_RUN_VALUE>'
+```
+
+Store as `tag_result`. Report:
+
+```
+Tag Migration
+=============
+Files scanned:    {filesScanned}
+Files modified:   {filesModified}
+Tags converted:   {tagsConverted}
+Tags removed:     {tagsRemoved}
+
+{If changes.length > 0, show first 20 changes:}
+Changes:
+  {file}:{line} [{action}]
+    - {original}
+    + {replaced}
+```
+
+If `--tags-only` is set, skip to Step 6.
+
+## Step 4: Migrate artifacts
+
+```bash
+node -e "
+const migrate = require('./cap/bin/lib/cap-migrate.cjs');
+const dryRun = process.argv[1] === 'true';
+const result = migrate.migrateArtifacts(process.cwd(), { dryRun });
+console.log(JSON.stringify(result, null, 2));
+" '<DRY_RUN_VALUE>'
+```
+
+Store as `artifact_result`. Report:
+
+```
+Artifact Migration
+==================
+Source:            {source}
+Features found:    {featuresFound}
+Feature Map:       {featureMapCreated ? 'created/updated' : 'no changes'}
+```
+
+## Step 5: Migrate session
+
+```bash
+node -e "
+const migrate = require('./cap/bin/lib/cap-migrate.cjs');
+const dryRun = process.argv[1] === 'true';
+const result = migrate.migrateSession(process.cwd(), { dryRun });
+console.log(JSON.stringify(result, null, 2));
+" '<DRY_RUN_VALUE>'
+```
+
+Store as `session_result`. Report:
+
+```
+Session Migration
+=================
+Old format:   {oldFormat}
+New format:   {newFormat}
+Migrated:     {migrated ? 'yes' : 'no'}
+```
+
+## Step 6: Final report and session update
+
+```
+Migration Complete
+==================
+
+Tags:       {tagsConverted} converted, {tagsRemoved} removed
+Artifacts:  {featuresFound} features extracted → FEATURE-MAP.md
+Session:    {migrated ? 'migrated to .cap/SESSION.json' : 'no session to migrate'}
+
+{If dry run:}
+NOTE: This was a dry run. No files were modified. Run without --dry-run to apply changes.
+
+{If not dry run:}
+Next steps:
+  1. Review changes with `git diff`
+  2. Run /cap:scan to verify tag migration
+  3. Run /cap:status to see project state from Feature Map
+  4. Commit migrated files
+```
+
+Update session state (unless dry run):
+
+```bash
+node -e "
+const session = require('./cap/bin/lib/cap-session.cjs');
+session.updateSession(process.cwd(), {
+  lastCommand: '/cap:migrate',
+  lastCommandTimestamp: new Date().toISOString()
+});
+"
+```
+
+</process>

package/package.json

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