cap-pro 1.0.0

package/cap/bin/cap-tools.cjs

@@ -0,0 +1,853 @@
+#!/usr/bin/env node
+
+/**
+ * CAP Tools — CLI utility for CAP workflow operations
+ *
+ * Centralizes: config parsing, model resolution, phase lookup, git commits, summary verification.
+ *
+ * Usage: node cap-tools.cjs <command> [args] [--raw] [--pick <field>]
+ *
+ * Atomic Commands:
+ *   state load                         Load project config + state
+ *   state json                         Output STATE.md frontmatter as JSON
+ *   state update <field> <value>       Update a STATE.md field
+ *   state get [section]                Get STATE.md content or section
+ *   state patch --field val ...        Batch update STATE.md fields
+ *   state begin-phase --phase N --name S --plans C  Update STATE.md for new phase start
+ *   state signal-waiting --type T --question Q --options "A|B" --phase P  Write WAITING.json signal
+ *   state signal-resume                Remove WAITING.json signal
+ *   resolve-model <agent-type>         Get model for agent based on profile
+ *   find-phase <phase>                 Find phase directory by number
+ *   commit <message> [--files f1 f2] [--no-verify]   Commit planning docs
+ *   commit-to-subrepo <msg> --files f1 f2  Route commits to sub-repos
+ *   verify-summary <path>              Verify a SUMMARY.md file
+ *   generate-slug <text>               Convert text to URL-safe slug
+ *   current-timestamp [format]         Get timestamp (full|date|filename)
+ *   list-todos [area]                  Count and enumerate pending todos
+ *   verify-path-exists <path>          Check file/directory existence
+ *   config-ensure-section              Initialize .planning/config.json
+ *   history-digest                     Aggregate all SUMMARY.md data
+ *   summary-extract <path> [--fields]  Extract structured data from SUMMARY.md
+ *   state-snapshot                     Structured parse of STATE.md
+ *   phase-plan-index <phase>           Index plans with waves and status
+ *   websearch <query>                  Search web via Brave API (if configured)
+ *     [--limit N] [--freshness day|week|month]
+ *
+ * Phase Operations:
+ *   phase next-decimal <phase>         Calculate next decimal phase number
+ *   phase add <description> [--id ID]   Append new phase to roadmap + create dir
+ *   phase insert <after> <description> Insert decimal phase after existing
+ *   phase remove <phase> [--force]     Remove phase, renumber all subsequent
+ *   phase complete <phase>             Mark phase done, update state + roadmap
+ *
+ * Roadmap Operations:
+ *   roadmap get-phase <phase>          Extract phase section from ROADMAP.md
+ *   roadmap analyze                    Full roadmap parse with disk status
+ *   roadmap update-plan-progress <N>   Update progress table row from disk (PLAN vs SUMMARY counts)
+ *
+ * Requirements Operations:
+ *   requirements mark-complete <ids>   Mark requirement IDs as complete in REQUIREMENTS.md
+ *                                      Accepts: REQ-01,REQ-02 or REQ-01 REQ-02 or [REQ-01, REQ-02]
+ *
+ * Milestone Operations:
+ *   milestone complete <version>       Archive milestone, create MILESTONES.md
+ *     [--name <name>]
+ *     [--archive-phases]               Move phase dirs to milestones/vX.Y-phases/
+ *
+ * Validation:
+ *   validate consistency               Check phase numbering, disk/roadmap sync
+ *   validate health [--repair]         Check .planning/ integrity, optionally repair
+ *   validate agents                    Check GSD agent installation status
+ *
+ * Progress:
+ *   progress [json|table|bar]          Render progress in various formats
+ *
+ * Todos:
+ *   todo complete <filename>           Move todo from pending to completed
+ *
+ * UAT Audit:
+ *   audit-uat                           Scan all phases for unresolved UAT/verification items
+ *   uat render-checkpoint --file <path> Render the current UAT checkpoint block
+ *
+ * Scaffolding:
+ *   scaffold context --phase <N>       Create CONTEXT.md template
+ *   scaffold uat --phase <N>           Create UAT.md template
+ *   scaffold verification --phase <N>  Create VERIFICATION.md template
+ *   scaffold phase-dir --phase <N>     Create phase directory
+ *     --name <name>
+ *
+ * Frontmatter CRUD:
+ *   frontmatter get <file> [--field k] Extract frontmatter as JSON
+ *   frontmatter set <file> --field k   Update single frontmatter field
+ *     --value jsonVal
+ *   frontmatter merge <file>           Merge JSON into frontmatter
+ *     --data '{json}'
+ *   frontmatter validate <file>        Validate required fields
+ *     --schema plan|summary|verification
+ *
+ * Verification Suite:
+ *   verify plan-structure <file>       Check PLAN.md structure + tasks
+ *   verify phase-completeness <phase>  Check all plans have summaries
+ *   verify references <file>           Check @-refs + paths resolve
+ *   verify commits <h1> [h2] ...      Batch verify commit hashes
+ *   verify artifacts <plan-file>       Check must_haves.artifacts
+ *   verify key-links <plan-file>       Check must_haves.key_links
+ *
+ * Template Fill:
+ *   template fill summary --phase N    Create pre-filled SUMMARY.md
+ *     [--plan M] [--name "..."]
+ *     [--fields '{json}']
+ *   template fill plan --phase N       Create pre-filled PLAN.md
+ *     [--plan M] [--type execute|tdd]
+ *     [--wave N] [--fields '{json}']
+ *   template fill verification         Create pre-filled VERIFICATION.md
+ *     --phase N [--fields '{json}']
+ *
+ * State Progression:
+ *   state advance-plan                 Increment plan counter
+ *   state record-metric --phase N      Record execution metrics
+ *     --plan M --duration Xmin
+ *     [--tasks N] [--files N]
+ *   state update-progress              Recalculate progress bar
+ *   state add-decision --summary "..."  Add decision to STATE.md
+ *     [--phase N] [--rationale "..."]
+ *     [--summary-file path] [--rationale-file path]
+ *   state add-blocker --text "..."     Add blocker
+ *     [--text-file path]
+ *   state resolve-blocker --text "..." Remove blocker
+ *   state record-session               Update session continuity
+ *     --stopped-at "..."
+ *     [--resume-file path]
+ *
+ * Compound Commands (workflow-specific initialization):
+ *   init execute-phase <phase>         All context for execute-phase workflow
+ *   init plan-phase <phase>            All context for plan-phase workflow
+ *   init new-project                   All context for new-project workflow
+ *   init new-milestone                 All context for new-milestone workflow
+ *   init quick <description>           All context for quick workflow
+ *   init resume                        All context for resume-project workflow
+ *   init verify-work <phase>           All context for verify-work workflow
+ *   init phase-op <phase>              Generic phase operation context
+ *   init todos [area]                  All context for todo workflows
+ *   init milestone-op                  All context for milestone operations
+ *   init map-codebase                  All context for map-codebase workflow
+ *   init progress                      All context for progress workflow
+ *
+ * Test Detection:
+ *   detect-test-framework [dir]        Detect test framework from package.json
+ *                                      Outputs: { framework, testCommand, filePattern }
+ *                                      Defaults to cwd if dir not provided
+ *
+ * Feature Aggregation:
+ *   aggregate-features [--output path] [--inventory path]  Generate .planning/FEATURES.md from PRDs and CODE-INVENTORY.md
+ *
+ * Session & Migration Operations:
+ *   monorepo-migrate [--output file]    Audit monorepo apps for existing .planning/ dirs
+ *   session-get                         Print current SESSION.json or "No session"
+ *   session-set --app <path>            Set active app in SESSION.json
+ *   session-set --global                Clear active app (root/global scope)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const core = require('./lib/core.cjs');
+const { error, findProjectRoot, getActiveWorkstream } = core;
+const config = require('./lib/config.cjs');
+const commands = require('./lib/commands.cjs');
+const phase = require('./lib/phase.cjs');
+const init = require('./lib/init.cjs');
+const profilePipeline = require('./lib/profile-pipeline.cjs');
+const profileOutput = require('./lib/profile-output.cjs');
+const arcScanner = require('./lib/arc-scanner.cjs');
+const verify = require('./lib/verify.cjs');
+const state = require('./lib/state.cjs');
+
+// Routers — extracted from the formerly-monolithic switch statement.
+// Each router exports a `dispatch(args, cwd, raw)` (or named variant) and
+// owns the sub-switch for its command group. Routers are pure delegation —
+// no business logic moved with them, only the wiring.
+const stateRouter = require('./lib/cli/state-router.cjs');
+const templateRouter = require('./lib/cli/template-router.cjs');
+const frontmatterRouter = require('./lib/cli/frontmatter-router.cjs');
+const verificationRouter = require('./lib/cli/verification-router.cjs');
+const validationRouter = require('./lib/cli/validation-router.cjs');
+const phaseRouter = require('./lib/cli/phase-router.cjs');
+const initRouter = require('./lib/cli/init-router.cjs');
+const workstreamRouter = require('./lib/cli/workstream-router.cjs');
+const uatRouter = require('./lib/cli/uat-router.cjs');
+const { parseNamedArgs, parseMultiwordArg } = require('./lib/cli/arg-helpers.cjs');
+
+// ─── CLI Router ───────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Optional cwd override for sandboxed subagents running outside project root.
+  let cwd = process.cwd();
+  const cwdEqArg = args.find(arg => arg.startsWith('--cwd='));
+  const cwdIdx = args.indexOf('--cwd');
+  if (cwdEqArg) {
+    const value = cwdEqArg.slice('--cwd='.length).trim();
+    if (!value) error('Missing value for --cwd');
+    args.splice(args.indexOf(cwdEqArg), 1);
+    cwd = path.resolve(value);
+  } else if (cwdIdx !== -1) {
+    const value = args[cwdIdx + 1];
+    if (!value || value.startsWith('--')) error('Missing value for --cwd');
+    args.splice(cwdIdx, 2);
+    cwd = path.resolve(value);
+  }
+
+  if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) {
+    error(`Invalid --cwd: ${cwd}`);
+  }
+
+  // Resolve worktree root: in a linked worktree, .planning/ lives in the main worktree.
+  // However, in monorepo worktrees where the subdirectory itself owns .planning/,
+  // skip worktree resolution — the CWD is already the correct project root.
+  const { resolveWorktreeRoot } = require('./lib/core.cjs');
+  if (!fs.existsSync(path.join(cwd, '.planning'))) {
+    const worktreeRoot = resolveWorktreeRoot(cwd);
+    if (worktreeRoot !== cwd) {
+      cwd = worktreeRoot;
+    }
+  }
+
+  // Optional workstream override for parallel milestone work.
+  // Priority: --ws flag > GSD_WORKSTREAM env var > active-workstream file > null (flat mode)
+  const wsEqArg = args.find(arg => arg.startsWith('--ws='));
+  const wsIdx = args.indexOf('--ws');
+  let ws = null;
+  if (wsEqArg) {
+    ws = wsEqArg.slice('--ws='.length).trim();
+    if (!ws) error('Missing value for --ws');
+    args.splice(args.indexOf(wsEqArg), 1);
+  } else if (wsIdx !== -1) {
+    ws = args[wsIdx + 1];
+    if (!ws || ws.startsWith('--')) error('Missing value for --ws');
+    args.splice(wsIdx, 2);
+  } else if (process.env.GSD_WORKSTREAM) {
+    ws = process.env.GSD_WORKSTREAM.trim();
+  } else {
+    ws = getActiveWorkstream(cwd);
+  }
+  // Validate workstream name to prevent path traversal attacks.
+  if (ws && !/^[a-zA-Z0-9_-]+$/.test(ws)) {
+    error('Invalid workstream name: must be alphanumeric, hyphens, and underscores only');
+  }
+  // Set env var so all modules (planningDir, planningPaths) auto-resolve workstream paths
+  if (ws) {
+    process.env.GSD_WORKSTREAM = ws;
+  }
+
+  const rawIndex = args.indexOf('--raw');
+  const raw = rawIndex !== -1;
+  if (rawIndex !== -1) args.splice(rawIndex, 1);
+
+  // --pick <name>: extract a single field from JSON output (replaces jq dependency).
+  // Supports dot-notation (e.g., --pick workflow.research) and bracket notation
+  // for arrays (e.g., --pick directories[-1]).
+  const pickIdx = args.indexOf('--pick');
+  let pickField = null;
+  if (pickIdx !== -1) {
+    pickField = args[pickIdx + 1];
+    if (!pickField || pickField.startsWith('--')) error('Missing value for --pick');
+    args.splice(pickIdx, 2);
+  }
+
+  const command = args[0];
+
+  if (!command) {
+    error('Usage: cap-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>]\nCommands: state, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-new-project, init, workstream');
+  }
+
+  // Multi-repo guard: resolve project root for commands that read/write .planning/.
+  // Skip for pure-utility commands that don't touch .planning/ to avoid unnecessary
+  // filesystem traversal on every invocation.
+  const SKIP_ROOT_RESOLUTION = new Set([
+    'generate-slug', 'current-timestamp', 'verify-path-exists',
+    'verify-summary', 'template', 'frontmatter',
+  ]);
+  if (!SKIP_ROOT_RESOLUTION.has(command)) {
+    cwd = findProjectRoot(cwd);
+  }
+
+  // When --pick is active, intercept stdout to extract the requested field.
+  if (pickField) {
+    const origWriteSync = fs.writeSync;
+    const chunks = [];
+    fs.writeSync = function (fd, data, ...rest) {
+      if (fd === 1) { chunks.push(String(data)); return; }
+      return origWriteSync.call(fs, fd, data, ...rest);
+    };
+    const cleanup = () => {
+      fs.writeSync = origWriteSync;
+      const captured = chunks.join('');
+      let jsonStr = captured;
+      if (jsonStr.startsWith('@file:')) {
+        jsonStr = fs.readFileSync(jsonStr.slice(6), 'utf-8');
+      }
+      try {
+        const obj = JSON.parse(jsonStr);
+        const value = extractField(obj, pickField);
+        const result = value === null || value === undefined ? '' : String(value);
+        origWriteSync.call(fs, 1, result);
+      } catch {
+        origWriteSync.call(fs, 1, captured);
+      }
+    };
+    try {
+      await runCommand(command, args, cwd, raw);
+      cleanup();
+    } catch (e) {
+      fs.writeSync = origWriteSync;
+      throw e;
+    }
+    return;
+  }
+
+  await runCommand(command, args, cwd, raw);
+}
+
+/**
+ * Extract a field from an object using dot-notation and bracket syntax.
+ * Supports: 'field', 'parent.child', 'arr[-1]', 'arr[0]'
+ */
+function extractField(obj, fieldPath) {
+  const parts = fieldPath.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    const bracketMatch = part.match(/^(.+?)\[(-?\d+)]$/);
+    if (bracketMatch) {
+      const key = bracketMatch[1];
+      const index = parseInt(bracketMatch[2], 10);
+      current = current[key];
+      if (!Array.isArray(current)) return undefined;
+      current = index < 0 ? current[current.length + index] : current[index];
+    } else {
+      current = current[part];
+    }
+  }
+  return current;
+}
+
+async function runCommand(command, args, cwd, raw) {
+  switch (command) {
+    case 'state':
+      stateRouter.dispatch(args, cwd, raw);
+      break;
+
+    case 'resolve-model': {
+      commands.cmdResolveModel(cwd, args[1], raw);
+      break;
+    }
+
+    case 'find-phase': {
+      phase.cmdFindPhase(cwd, args[1], raw);
+      break;
+    }
+
+    case 'commit': {
+      const amend = args.includes('--amend');
+      const noVerify = args.includes('--no-verify');
+      const filesIndex = args.indexOf('--files');
+      // Collect all positional args between command name and first flag,
+      // then join them — handles both quoted ("multi word msg") and
+      // unquoted (multi word msg) invocations from different shells
+      const endIndex = filesIndex !== -1 ? filesIndex : args.length;
+      const messageArgs = args.slice(1, endIndex).filter(a => !a.startsWith('--'));
+      const message = messageArgs.join(' ') || undefined;
+      const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
+      commands.cmdCommit(cwd, message, files, raw, amend, noVerify);
+      break;
+    }
+
+    case 'commit-to-subrepo': {
+      const message = args[1];
+      const filesIndex = args.indexOf('--files');
+      const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
+      commands.cmdCommitToSubrepo(cwd, message, files, raw);
+      break;
+    }
+
+    case 'verify-summary': {
+      const summaryPath = args[1];
+      const countIndex = args.indexOf('--check-count');
+      const checkCount = countIndex !== -1 ? parseInt(args[countIndex + 1], 10) : 2;
+      verify.cmdVerifySummary(cwd, summaryPath, checkCount, raw);
+      break;
+    }
+
+    case 'template':
+      templateRouter.dispatch(args, cwd, raw);
+      break;
+
+    case 'frontmatter':
+      frontmatterRouter.dispatch(args, cwd, raw);
+      break;
+
+    case 'verify':
+      verificationRouter.dispatch(args, cwd, raw);
+      break;
+
+    case 'generate-slug': {
+      commands.cmdGenerateSlug(args[1], raw);
+      break;
+    }
+
+    case 'current-timestamp': {
+      commands.cmdCurrentTimestamp(args[1] || 'full', raw);
+      break;
+    }
+
+    case 'list-todos': {
+      commands.cmdListTodos(cwd, args[1], raw);
+      break;
+    }
+
+    case 'verify-path-exists': {
+      commands.cmdVerifyPathExists(cwd, args[1], raw);
+      break;
+    }
+
+    case 'config-ensure-section': {
+      config.cmdConfigEnsureSection(cwd, raw);
+      break;
+    }
+
+    case 'config-set': {
+      config.cmdConfigSet(cwd, args[1], args[2], raw);
+      break;
+    }
+
+    case "config-set-model-profile": {
+      config.cmdConfigSetModelProfile(cwd, args[1], raw);
+      break;
+    }
+
+    case 'config-get': {
+      config.cmdConfigGet(cwd, args[1], raw);
+      break;
+    }
+
+    case 'config-new-project': {
+      config.cmdConfigNewProject(cwd, args[1], raw);
+      break;
+    }
+
+    case 'agent-skills': {
+      init.cmdAgentSkills(cwd, args[1], raw);
+      break;
+    }
+
+    case 'history-digest': {
+      commands.cmdHistoryDigest(cwd, raw);
+      break;
+    }
+
+    case 'phases':
+      phaseRouter.dispatchPhases(args, cwd, raw);
+      break;
+
+    case 'roadmap':
+      phaseRouter.dispatchRoadmap(args, cwd, raw);
+      break;
+
+    case 'requirements':
+      phaseRouter.dispatchRequirements(args, cwd, raw);
+      break;
+
+    case 'phase':
+      phaseRouter.dispatchPhase(args, cwd, raw);
+      break;
+
+    case 'milestone':
+      phaseRouter.dispatchMilestone(args, cwd, raw);
+      break;
+
+    case 'validate':
+      validationRouter.dispatch(args, cwd, raw);
+      break;
+
+    case 'progress': {
+      const subcommand = args[1] || 'json';
+      commands.cmdProgressRender(cwd, subcommand, raw);
+      break;
+    }
+
+    case 'audit-uat':
+      uatRouter.dispatchAuditUat(args, cwd, raw);
+      break;
+
+    case 'uat':
+      uatRouter.dispatchUat(args, cwd, raw);
+      break;
+
+    case 'stats': {
+      const subcommand = args[1] || 'json';
+      commands.cmdStats(cwd, subcommand, raw);
+      break;
+    }
+
+    case 'todo': {
+      const subcommand = args[1];
+      if (subcommand === 'complete') {
+        commands.cmdTodoComplete(cwd, args[2], raw);
+      } else if (subcommand === 'match-phase') {
+        commands.cmdTodoMatchPhase(cwd, args[2], raw);
+      } else {
+        error('Unknown todo subcommand. Available: complete, match-phase');
+      }
+      break;
+    }
+
+    case 'scaffold': {
+      const scaffoldType = args[1];
+      const scaffoldOptions = {
+        phase: parseNamedArgs(args, ['phase']).phase,
+        name: parseMultiwordArg(args, 'name'),
+      };
+      commands.cmdScaffold(cwd, scaffoldType, scaffoldOptions, raw);
+      break;
+    }
+
+    case 'init':
+      initRouter.dispatch(args, cwd, raw);
+      break;
+
+    case 'phase-plan-index': {
+      phase.cmdPhasePlanIndex(cwd, args[1], raw);
+      break;
+    }
+
+    case 'state-snapshot': {
+      state.cmdStateSnapshot(cwd, raw);
+      break;
+    }
+
+    case 'summary-extract': {
+      const summaryPath = args[1];
+      const fieldsIndex = args.indexOf('--fields');
+      const fields = fieldsIndex !== -1 ? args[fieldsIndex + 1].split(',') : null;
+      commands.cmdSummaryExtract(cwd, summaryPath, fields, raw);
+      break;
+    }
+
+    case 'websearch': {
+      const query = args[1];
+      const limitIdx = args.indexOf('--limit');
+      const freshnessIdx = args.indexOf('--freshness');
+      await commands.cmdWebsearch(query, {
+        limit: limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : 10,
+        freshness: freshnessIdx !== -1 ? args[freshnessIdx + 1] : null,
+      }, raw);
+      break;
+    }
+
+    // ─── Profiling Pipeline ────────────────────────────────────────────────
+
+    case 'scan-sessions': {
+      const pathIdx = args.indexOf('--path');
+      const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
+      const verboseFlag = args.includes('--verbose');
+      const jsonFlag = args.includes('--json');
+      await profilePipeline.cmdScanSessions(sessionsPath, { verbose: verboseFlag, json: jsonFlag }, raw);
+      break;
+    }
+
+    case 'extract-messages': {
+      const sessionIdx = args.indexOf('--session');
+      const sessionId = sessionIdx !== -1 ? args[sessionIdx + 1] : null;
+      const limitIdx = args.indexOf('--limit');
+      const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : null;
+      const pathIdx = args.indexOf('--path');
+      const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
+      const projectArg = args[1];
+      if (!projectArg || projectArg.startsWith('--')) {
+        error('Usage: cap-tools extract-messages <project> [--session <id>] [--limit N] [--path <dir>]\nRun scan-sessions first to see available projects.');
+      }
+      await profilePipeline.cmdExtractMessages(projectArg, { sessionId, limit }, raw, sessionsPath);
+      break;
+    }
+
+    case 'profile-sample': {
+      const pathIdx = args.indexOf('--path');
+      const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
+      const limitIdx = args.indexOf('--limit');
+      const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : 150;
+      const maxPerIdx = args.indexOf('--max-per-project');
+      const maxPerProject = maxPerIdx !== -1 ? parseInt(args[maxPerIdx + 1], 10) : null;
+      const maxCharsIdx = args.indexOf('--max-chars');
+      const maxChars = maxCharsIdx !== -1 ? parseInt(args[maxCharsIdx + 1], 10) : 500;
+      await profilePipeline.cmdProfileSample(sessionsPath, { limit, maxPerProject, maxChars }, raw);
+      break;
+    }
+
+    // ─── Profile Output ──────────────────────────────────────────────────
+
+    case 'write-profile': {
+      const inputIdx = args.indexOf('--input');
+      const inputPath = inputIdx !== -1 ? args[inputIdx + 1] : null;
+      if (!inputPath) error('--input <analysis-json-path> is required');
+      const outputIdx = args.indexOf('--output');
+      const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+      profileOutput.cmdWriteProfile(cwd, { input: inputPath, output: outputPath }, raw);
+      break;
+    }
+
+    case 'profile-questionnaire': {
+      const answersIdx = args.indexOf('--answers');
+      const answers = answersIdx !== -1 ? args[answersIdx + 1] : null;
+      profileOutput.cmdProfileQuestionnaire({ answers }, raw);
+      break;
+    }
+
+    case 'generate-dev-preferences': {
+      const analysisIdx = args.indexOf('--analysis');
+      const analysisPath = analysisIdx !== -1 ? args[analysisIdx + 1] : null;
+      const outputIdx = args.indexOf('--output');
+      const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+      const stackIdx = args.indexOf('--stack');
+      const stack = stackIdx !== -1 ? args[stackIdx + 1] : null;
+      profileOutput.cmdGenerateDevPreferences(cwd, { analysis: analysisPath, output: outputPath, stack }, raw);
+      break;
+    }
+
+    case 'generate-claude-profile': {
+      const analysisIdx = args.indexOf('--analysis');
+      const analysisPath = analysisIdx !== -1 ? args[analysisIdx + 1] : null;
+      const outputIdx = args.indexOf('--output');
+      const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+      const globalFlag = args.includes('--global');
+      profileOutput.cmdGenerateClaudeProfile(cwd, { analysis: analysisPath, output: outputPath, global: globalFlag }, raw);
+      break;
+    }
+
+    case 'generate-claude-md': {
+      const outputIdx = args.indexOf('--output');
+      const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+      const autoFlag = args.includes('--auto');
+      const forceFlag = args.includes('--force');
+      profileOutput.cmdGenerateClaudeMd(cwd, { output: outputPath, auto: autoFlag, force: forceFlag }, raw);
+      break;
+    }
+
+    case 'workstream':
+      workstreamRouter.dispatch(args, cwd, raw);
+      break;
+
+    case 'extract-tags': {
+      const allArgs = args.slice(1);
+      const namedFlags = ['phase', 'type', 'format', 'output', 'app'];
+      const { phase: phaseFilter, type: typeFilter, format, output: outputFile, app } = parseNamedArgs(allArgs, namedFlags);
+      // Filter out --flag tokens and their values so positional arg detection works
+      const consumed = new Set();
+      for (const f of namedFlags) { const i = allArgs.indexOf(`--${f}`); if (i !== -1) { consumed.add(i); if (allArgs[i + 1] && !allArgs[i + 1].startsWith('--')) consumed.add(i + 1); } }
+      const targetPath = allArgs.filter((_, i) => !consumed.has(i) && !allArgs[i].startsWith('--'))[0] || cwd;
+
+      if (app) {
+        const workspaceDetector = require('./lib/workspace-detector.cjs');
+        const monorepoContext = require('./lib/monorepo-context.cjs');
+        const workspace = workspaceDetector.detectWorkspace(cwd);
+        const validation = workspaceDetector.validateAppPath(workspace, app);
+        if (!validation.valid) { error(validation.error); }
+        const scoped = monorepoContext.scopeExtractTags(cwd, validation.resolved.path, {
+          phaseFilter, typeFilter, format: format || 'json', outputFile,
+        });
+        arcScanner.cmdExtractTags(cwd, scoped.targetPath, { ...scoped });
+
+        if (scoped.outputFile) {
+          try {
+            const featureAggregator = require('./lib/feature-aggregator.cjs');
+            featureAggregator.cmdAggregateFeatures(cwd, {
+              inventoryFile: scoped.outputFile,
+            });
+          } catch (e) {
+            process.stderr.write(`feature-aggregator: auto-chain skipped — ${e.message}\n`);
+          }
+        }
+        break;
+      }
+
+      // Session fallback: auto-scope to SESSION.json current_app when no --app flag
+      {
+        const sessionManager = require('./lib/session-manager.cjs');
+        const sessionApp = sessionManager.resolveCurrentApp(cwd, null);
+        if (sessionApp) {
+          const workspaceDetector = require('./lib/workspace-detector.cjs');
+          const monorepoContext = require('./lib/monorepo-context.cjs');
+          const workspace = workspaceDetector.detectWorkspace(cwd);
+          const validation = workspace ? workspaceDetector.validateAppPath(workspace, sessionApp) : { valid: false };
+          if (validation.valid) {
+            const scoped = monorepoContext.scopeExtractTags(cwd, validation.resolved.path, {
+              phaseFilter, typeFilter, format: format || 'json', outputFile,
+            });
+            arcScanner.cmdExtractTags(cwd, scoped.targetPath, { ...scoped });
+
+            if (scoped.outputFile) {
+              try {
+                const featureAggregator = require('./lib/feature-aggregator.cjs');
+                featureAggregator.cmdAggregateFeatures(cwd, {
+                  inventoryFile: scoped.outputFile,
+                });
+              } catch (e) {
+                process.stderr.write(`feature-aggregator: auto-chain skipped — ${e.message}\n`);
+              }
+            }
+            break;
+          }
+        }
+      }
+
+      arcScanner.cmdExtractTags(cwd, targetPath, {
+        phaseFilter,
+        typeFilter,
+        format: format || 'json',
+        outputFile,
+      });
+
+      // Auto-chain: regenerate FEATURES.md after extract-tags completes
+      // Only run when outputFile is set (markdown mode) — skip for JSON stdout mode
+      if (outputFile) {
+        try {
+          const featureAggregator = require('./lib/feature-aggregator.cjs');
+          featureAggregator.cmdAggregateFeatures(cwd, {
+            inventoryFile: outputFile,
+          });
+        } catch (e) {
+          // Non-fatal: feature aggregation failure should not break extract-tags
+          process.stderr.write(`feature-aggregator: auto-chain skipped — ${e.message}\n`);
+        }
+      }
+
+      break;
+    }
+
+    case 'set-mode': {
+      const allArgs = args.slice(1);
+      const named = parseNamedArgs(allArgs, ['phase']);
+      const modeValue = allArgs.find(a => !a.startsWith('--'));
+      const VALID_MODES = new Set(['code-first', 'plan-first', 'hybrid']);
+      if (!modeValue || !VALID_MODES.has(modeValue)) {
+        error('Usage: set-mode <code-first|plan-first|hybrid> [--phase N]');
+      }
+      const keyPath = named.phase ? `phase_modes.${named.phase}` : 'default_phase_mode';
+      const result = config.setConfigValue(cwd, keyPath, modeValue);
+      core.output(result, raw, `Mode set: ${keyPath} = ${modeValue}`);
+      break;
+    }
+
+    case 'detect-test-framework': {
+      const targetDir = args[1] || cwd;
+      const testDetector = require('./lib/test-detector.cjs');
+      const result = testDetector.detectTestFramework(targetDir);
+      core.output(result, raw, `${result.framework}: ${result.testCommand}`);
+      break;
+    }
+
+    case 'aggregate-features': {
+      const allArgs = args.slice(1);
+      const named = parseNamedArgs(allArgs, ['output', 'inventory']);
+      const featureAggregator = require('./lib/feature-aggregator.cjs');
+      featureAggregator.cmdAggregateFeatures(cwd, {
+        outputFile: named.output,
+        inventoryFile: named.inventory,
+      });
+      break;
+    }
+
+    case 'detect-workspace': {
+      const workspaceDetector = require('./lib/workspace-detector.cjs');
+      workspaceDetector.cmdDetectWorkspace(cwd, raw);
+      break;
+    }
+
+    case 'generate-manifest': {
+      const manifestGenerator = require('./lib/manifest-generator.cjs');
+      manifestGenerator.cmdGenerateManifest(cwd, args[1], raw);
+      break;
+    }
+
+    case 'generate-manifests': {
+      const workspaceDetector = require('./lib/workspace-detector.cjs');
+      const manifestGenerator = require('./lib/manifest-generator.cjs');
+      const workspace = workspaceDetector.detectWorkspace(cwd);
+      if (!workspace) {
+        process.stderr.write('No workspace detected.\n');
+        process.exitCode = 1;
+        break;
+      }
+      const written = manifestGenerator.generateAllManifests(cwd, workspace.packages, {});
+      for (const f of written) process.stdout.write(f + '\n');
+      break;
+    }
+
+    case 'monorepo-init-app': {
+      const monorepoContext = require('./lib/monorepo-context.cjs');
+      const appPath = args[1];
+      if (!appPath) { process.stderr.write('Usage: monorepo-init-app <app-relative-path>\n'); process.exitCode = 1; break; }
+      const appName = parseNamedArgs(args.slice(2), ['name']).name || path.basename(appPath);
+      const created = monorepoContext.initAppPlanning(cwd, appPath, { appName });
+      process.stdout.write(`Initialized: ${created}\n`);
+      break;
+    }
+
+    case 'monorepo-migrate': {
+      const workspaceDetector = require('./lib/workspace-detector.cjs');
+      const monorepoMigrator = require('./lib/monorepo-migrator.cjs');
+      const workspace = workspaceDetector.detectWorkspace(cwd);
+      if (!workspace) {
+        process.stderr.write('No workspace detected. Not a monorepo or missing workspace config.\n');
+        process.exitCode = 1;
+        break;
+      }
+      const audit = monorepoMigrator.auditAppPlanning(cwd, workspace.apps);
+      const report = monorepoMigrator.formatAuditReport(audit);
+      process.stdout.write(report + '\n');
+      const allArgs = args.slice(1);
+      const { output: outputFile } = parseNamedArgs(allArgs, ['output']);
+      if (outputFile) {
+        const outDir = path.dirname(outputFile);
+        fs.mkdirSync(outDir, { recursive: true });
+        fs.writeFileSync(outputFile, report + '\n', 'utf-8');
+      }
+      break;
+    }
+
+    case 'session-get': {
+      const sessionManager = require('./lib/session-manager.cjs');
+      const session = sessionManager.getSession(cwd);
+      core.output(session, raw, session ? JSON.stringify(session, null, 2) : 'No session');
+      break;
+    }
+
+    case 'session-set': {
+      const sessionManager = require('./lib/session-manager.cjs');
+      const allArgs = args.slice(1);
+      const { app: appPath } = parseNamedArgs(allArgs, ['app']);
+      const isGlobal = allArgs.includes('--global');
+      if (!appPath && !isGlobal) {
+        error('Usage: session-set --app <path> | --global');
+      }
+      const updated = isGlobal
+        ? sessionManager.setCurrentApp(cwd, null, [])
+        : sessionManager.setCurrentApp(cwd, appPath, []);
+      core.output(updated, raw, JSON.stringify(updated, null, 2));
+      break;
+    }
+
+    case 'session-set-default': {
+      const sessionManager = require('./lib/session-manager.cjs');
+      const appPath = args[1] || null;
+      const updated = sessionManager.setDefaultApp(cwd, appPath);
+      core.output(updated, raw, JSON.stringify(updated, null, 2));
+      break;
+    }
+
+    default:
+      error(`Unknown command: ${command}`);
+  }
+}
+
+main();