@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdd/bin/sdd-tools.cjs

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 
 /**
+ * @deprecated The supported programmatic surface is `sdd-sdk query` (SDK query registry)
+ * and the `@bhargavvc/sdk` package. This Node CLI remains the compatibility implementation
+ * for shell scripts and older workflows; prefer calling the SDK from agents and automation.
+ *
  * SDD Tools — CLI utility for SDD workflow operations
  *
  * Replaces repetitive inline bash patterns across ~50 SDD command/workflow/agent files.
@@ -45,6 +49,7 @@
  *   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)
+ *   roadmap annotate-dependencies <N>  Add wave dependency notes + cross-cutting constraints to ROADMAP.md
  *
  * Requirements Operations:
  *   requirements mark-complete <ids>   Mark requirement IDs as complete in REQUIREMENTS.md
@@ -70,6 +75,19 @@
  *   audit-uat                           Scan all phases for unresolved UAT/verification items
  *   uat render-checkpoint --file <path> Render the current UAT checkpoint block
  *
+ * Open Artifact Audit:
+ *   audit-open [--json]                 Scan all .planning/ artifact types for unresolved items
+ *
+ * Intel:
+ *   intel query <term>             Query intel files for a term
+ *   intel status                   Show intel file freshness
+ *   intel update                   Trigger intel refresh (returns agent spawn hint)
+ *   intel diff                     Show changed intel entries since last snapshot
+ *   intel snapshot                 Save current intel state as diff baseline
+ *   intel patch-meta <file>        Update _meta.updated_at in an intel file
+ *   intel validate                 Validate intel file structure
+ *   intel extract-exports <file>   Extract exported symbols from a source file
+ *
  * Scaffolding:
  *   scaffold context --phase <N>       Create CONTEXT.md template
  *   scaffold uat --phase <N>           Create UAT.md template
@@ -93,6 +111,8 @@
  *   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
+ *   verify schema-drift <phase> [--skip]  Detect schema file changes without push
+ *   verify codebase-drift                Detect structural drift since last codebase map (#2003)
  *
  * Template Fill:
  *   template fill summary --phase N    Create pre-filled SUMMARY.md
@@ -133,12 +153,28 @@
  *   init milestone-op                  All context for milestone operations
  *   init map-codebase                  All context for map-codebase workflow
  *   init progress                      All context for progress workflow
+ *
+ * Documentation:
+ *   docs-init                            Project context for docs-update workflow
+ *
+ * Learnings:
+ *   learnings list                       List all global learnings (JSON)
+ *   learnings query --tag <tag>          Query learnings by tag
+ *   learnings copy                       Copy from current project's LEARNINGS.md
+ *   learnings prune --older-than <dur>   Remove entries older than duration (e.g. 90d)
+ *   learnings delete <id>                Delete a learning by ID
+ *
+ * SDD-2 Migration:
+ *   from-sdd2 [--path <dir>] [--force] [--dry-run]
+ *             Import a SDD-2 (.sdd/) project back to SDD v1 (.planning/) format
  */
 
 const fs = require('fs');
 const path = require('path');
 const core = require('./lib/core.cjs');
-const { error, findProjectRoot, getActiveWorkstream } = core;
+const { error, findProjectRoot, ERROR_REASON } = core;
+const { getActiveWorkstream } = require('./lib/planning-workspace.cjs');
+const { resolveActiveWorkstream, applyResolvedWorkstreamEnv } = require('./lib/active-workstream-store.cjs');
 const state = require('./lib/state.cjs');
 const phase = require('./lib/phase.cjs');
 const roadmap = require('./lib/roadmap.cjs');
@@ -152,6 +188,16 @@ const frontmatter = require('./lib/frontmatter.cjs');
 const profilePipeline = require('./lib/profile-pipeline.cjs');
 const profileOutput = require('./lib/profile-output.cjs');
 const workstream = require('./lib/workstream.cjs');
+const docs = require('./lib/docs.cjs');
+const learnings = require('./lib/learnings.cjs');
+const gapChecker = require('./lib/gap-checker.cjs');
+const { routeStateCommand } = require('./lib/state-command-router.cjs');
+const { routeVerifyCommand } = require('./lib/verify-command-router.cjs');
+const { routeInitCommand } = require('./lib/init-command-router.cjs');
+const { routePhaseCommand } = require('./lib/phase-command-router.cjs');
+const { routePhasesCommand } = require('./lib/phases-command-router.cjs');
+const { routeValidateCommand } = require('./lib/validate-command-router.cjs');
+const { routeRoadmapCommand } = require('./lib/roadmap-command-router.cjs');
 
 // ─── Arg parsing helpers ──────────────────────────────────────────────────────
 
@@ -196,7 +242,25 @@ function parseMultiwordArg(args, flag) {
 // ─── CLI Router ───────────────────────────────────────────────────────────────
 
 async function main() {
-  const args = process.argv.slice(2);
+  let args = process.argv.slice(2);
+
+  // --json-errors / SDD_JSON_ERRORS=1: when active, error() emits structured
+  // JSON ({ ok: false, reason: <ERROR_REASON code>, message }) to stderr
+  // instead of "Error: <text>". Lets test suites assert on typed reason codes
+  // per CONTRIBUTING.md "Prohibited: Raw Text Matching" (#2974).
+  //
+  // Detect early — before any flag parsing that can fire error() — so even
+  // --cwd and workstream-resolution failures emit structured stderr (#3310).
+  // The argv splice must happen here too, otherwise the dispatcher below sees
+  // "--json-errors" as an unknown command. Default off — human operators keep
+  // their plain-text diagnostic.
+  const jsonErrorsIdx = args.indexOf('--json-errors');
+  if (jsonErrorsIdx !== -1) {
+    core.setJsonErrorMode(true);
+    args.splice(jsonErrorsIdx, 1);
+  } else if (process.env.SDD_JSON_ERRORS === '1') {
+    core.setJsonErrorMode(true);
+  }
 
   // Optional cwd override for sandboxed subagents running outside project root.
   let cwd = process.cwd();
@@ -204,18 +268,18 @@ async function main() {
   const cwdIdx = args.indexOf('--cwd');
   if (cwdEqArg) {
     const value = cwdEqArg.slice('--cwd='.length).trim();
-    if (!value) error('Missing value for --cwd');
+    if (!value) error('Missing value for --cwd', ERROR_REASON.USAGE);
     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');
+    if (!value || value.startsWith('--')) error('Missing value for --cwd', ERROR_REASON.USAGE);
     args.splice(cwdIdx, 2);
     cwd = path.resolve(value);
   }
 
   if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) {
-    error(`Invalid --cwd: ${cwd}`);
+    error(`Invalid --cwd: ${cwd}`, ERROR_REASON.USAGE);
   }
 
   // Resolve worktree root: in a linked worktree, .planning/ lives in the main worktree.
@@ -230,30 +294,18 @@ async function main() {
   }
 
   // Optional workstream override for parallel milestone work.
-  // Priority: --ws flag > SDD_WORKSTREAM env var > active-workstream file > null (flat mode)
-  const wsEqArg = args.find(arg => arg.startsWith('--ws='));
-  const wsIdx = args.indexOf('--ws');
+  // Priority: --ws flag > SDD_WORKSTREAM env var > session/shared pointer > null.
   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.SDD_WORKSTREAM) {
-    ws = process.env.SDD_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.SDD_WORKSTREAM = ws;
+  try {
+    const wsResolution = resolveActiveWorkstream(cwd, args, process.env, {
+      getStored: getActiveWorkstream,
+    });
+    ws = wsResolution.ws;
+    args = wsResolution.args;
+    // Set env var so all modules (planningDir, planningPaths) auto-resolve workstream paths.
+    applyResolvedWorkstreamEnv(wsResolution, process.env);
+  } catch (err) {
+    error(err.message || String(err));
   }
 
   const rawIndex = args.indexOf('--raw');
@@ -267,14 +319,97 @@ async function main() {
   let pickField = null;
   if (pickIdx !== -1) {
     pickField = args[pickIdx + 1];
-    if (!pickField || pickField.startsWith('--')) error('Missing value for --pick');
+    if (!pickField || pickField.startsWith('--')) error('Missing value for --pick', ERROR_REASON.USAGE);
     args.splice(pickIdx, 2);
   }
 
-  const command = args[0];
+  // --default <value>: for config-get, return this value instead of erroring
+  // when the key is absent. Allows workflows to express optional config reads
+  // without defensive `2>/dev/null || true` boilerplate (#1893).
+  const defaultIdx = args.indexOf('--default');
+  let defaultValue = undefined;
+  if (defaultIdx !== -1) {
+    defaultValue = args[defaultIdx + 1];
+    if (defaultValue === undefined) defaultValue = '';
+    args.splice(defaultIdx, 2);
+  }
+
+  let command = args[0];
+
+  // #3243: accept dotted canonical form (e.g. `state.update`) as well as the
+  // spaced form (`state update`). Workflow files and stale SDK binaries pass
+  // the dotted canonical form directly; any caller that bypasses the SDK
+  // client-side split hit "Unknown command" before this shim.
+  //
+  // Split on the FIRST dot only — `check.decision-coverage-plan` becomes
+  // command='check', args=['check','decision-coverage-plan',...rest].
+  // Parallel to dottedCommandToCjsArgv in sdk/src/query/query-fallback-bridge-adapter.ts;
+  // kept separate here to avoid SDK coupling (see TODO: extract to shared helper).
+  //
+  // Guard: head and rest must both be non-empty (rejects leading-dot args like
+  // ".hidden" and bare-dot ".").
+  const originalCommand = command; // preserved for "Unknown command" suggestion
+  if (typeof command === 'string' && command.includes('.')) {
+    const dotIdx = command.indexOf('.');
+    const head = command.slice(0, dotIdx);
+    const rest = command.slice(dotIdx + 1);
+    if (head && rest) {
+      command = head;
+      args = [head, rest, ...args.slice(1)];
+    }
+  }
+
+  // Top-level usage string — emitted by `sdd-tools` (no args) and by
+  // `sdd-tools --help` / any `--help` request below.
+  // CR feedback: the command list must enumerate every top-level command
+  // supported by the dispatcher so `--help` is actually useful for
+  // discovery; previously it was a partial subset that didn't include
+  // phase / roadmap / milestone / progress / etc.
+  const TOP_LEVEL_USAGE = 'Usage: sdd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
+    'Commands: agent-skills, audit-open, audit-uat, check-commit, commit, commit-to-subrepo, ' +
+    'config-ensure-section, config-get, config-new-project, config-path, config-set, ' +
+    'current-timestamp, detect-custom-files, docs-init, extract-messages, find-phase, ' +
+    'from-sdd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
+    'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
+    'learnings, list-todos, milestone, phase, phase-plan-index, phases, profile-questionnaire, ' +
+    'profile-sample, progress, requirements, resolve-model, roadmap, scaffold, state, ' +
+    'template, validate, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
+    'Global flags:\n' +
+    '  --raw              Emit raw output without post-processing\n' +
+    '  --pick <field>     Extract a single field from JSON output (dot/bracket notation)\n' +
+    '  --cwd <path>       Override working directory for project-root resolution\n' +
+    '  --ws <name>        Override active workstream (or set SDD_WORKSTREAM)\n' +
+    '  --json-errors      Emit structured JSON error objects on stderr (or set SDD_JSON_ERRORS=1)\n\n' +
+    'For command-specific argument requirements, invoke the command without args ' +
+    '(e.g. `sdd-tools phase add`) — the resulting error lists what is required.';
 
   if (!command) {
-    error('Usage: sdd-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');
+    error(TOP_LEVEL_USAGE);
+  }
+
+  // #3019: a `--help` / `-h` flag in argv must render the top-level usage
+  // and exit 0 — not error out with "Unknown flag". The previous shape
+  // erred on agent-hallucinated flags, but it also blocked humans from
+  // discovering the command surface via subcommand help requests routed
+  // here from the SDK CLI's query dispatcher (after the cli.ts fix that
+  // stops harvesting --help as a global flag). Rendering top-level usage
+  // on --help is strictly better UX than the old short-circuit, which
+  // printed the SDK-level usage that doesn't mention any of these
+  // subcommands.
+  const HELP_FLAGS = new Set(['-h', '--help', '-?', '--h', '--usage']);
+  if (args.some((a) => HELP_FLAGS.has(a))) {
+    process.stdout.write(TOP_LEVEL_USAGE + '\n');
+    return;
+  }
+
+  // Reject version flags. AI agents sometimes hallucinate --version on tool
+  // invocations; silently ignoring it can cause destructive operations to
+  // proceed unchecked. (Help flags are handled above.)
+  const NEVER_VALID_FLAGS = new Set(['--version', '-v']);
+  for (const arg of args) {
+    if (NEVER_VALID_FLAGS.has(arg)) {
+      error(`Unknown flag: ${arg}\nsdd-tools does not accept version flags. Run "sdd-tools" with no arguments for usage.`, ERROR_REASON.USAGE);
+    }
   }
 
   // Multi-repo guard: resolve project root for commands that read/write .planning/.
@@ -282,7 +417,8 @@ async function main() {
   // filesystem traversal on every invocation.
   const SKIP_ROOT_RESOLUTION = new Set([
     'generate-slug', 'current-timestamp', 'verify-path-exists',
-    'verify-summary', 'template', 'frontmatter',
+    'verify-summary', 'template', 'frontmatter', 'detect-custom-files',
+    'worktree',
   ]);
   if (!SKIP_ROOT_RESOLUTION.has(command)) {
     cwd = findProjectRoot(cwd);
@@ -313,7 +449,7 @@ async function main() {
       }
     };
     try {
-      await runCommand(command, args, cwd, raw);
+      await runCommand(command, args, cwd, raw, defaultValue, originalCommand);
       cleanup();
     } catch (e) {
       fs.writeSync = origWriteSync;
@@ -322,7 +458,27 @@ async function main() {
     return;
   }
 
-  await runCommand(command, args, cwd, raw);
+  // Intercept stdout to transparently resolve @file: references (#1891).
+  // core.cjs output() writes @file:<path> when JSON > 50KB. The --pick path
+  // already resolves this, but the normal path wrote @file: to stdout, forcing
+  // every workflow to have a bash-specific `if [[ "$INIT" == @file:* ]]` check
+  // that breaks on PowerShell and other non-bash shells.
+  const origWriteSync2 = fs.writeSync;
+  const outChunks = [];
+  fs.writeSync = function (fd, data, ...rest) {
+    if (fd === 1) { outChunks.push(String(data)); return; }
+    return origWriteSync2.call(fs, fd, data, ...rest);
+  };
+  try {
+    await runCommand(command, args, cwd, raw, defaultValue, originalCommand);
+  } finally {
+    fs.writeSync = origWriteSync2;
+  }
+  let captured = outChunks.join('');
+  if (captured.startsWith('@file:')) {
+    captured = fs.readFileSync(captured.slice(6), 'utf-8');
+  }
+  origWriteSync2.call(fs, 1, captured);
 }
 
 /**
@@ -348,55 +504,17 @@ function extractField(obj, fieldPath) {
   return current;
 }
 
-async function runCommand(command, args, cwd, raw) {
+async function runCommand(command, args, cwd, raw, defaultValue, originalCommand) {
   switch (command) {
     case 'state': {
-      const subcommand = args[1];
-      if (subcommand === 'json') {
-        state.cmdStateJson(cwd, raw);
-      } else if (subcommand === 'update') {
-        state.cmdStateUpdate(cwd, args[2], args[3]);
-      } else if (subcommand === 'get') {
-        state.cmdStateGet(cwd, args[2], raw);
-      } else if (subcommand === 'patch') {
-        const patches = {};
-        for (let i = 2; i < args.length; i += 2) {
-          const key = args[i].replace(/^--/, '');
-          const value = args[i + 1];
-          if (key && value !== undefined) {
-            patches[key] = value;
-          }
-        }
-        state.cmdStatePatch(cwd, patches, raw);
-      } else if (subcommand === 'advance-plan') {
-        state.cmdStateAdvancePlan(cwd, raw);
-      } else if (subcommand === 'record-metric') {
-        const { phase: p, plan, duration, tasks, files } = parseNamedArgs(args, ['phase', 'plan', 'duration', 'tasks', 'files']);
-        state.cmdStateRecordMetric(cwd, { phase: p, plan, duration, tasks, files }, raw);
-      } else if (subcommand === 'update-progress') {
-        state.cmdStateUpdateProgress(cwd, raw);
-      } else if (subcommand === 'add-decision') {
-        const { phase: p, summary, 'summary-file': summary_file, rationale, 'rationale-file': rationale_file } = parseNamedArgs(args, ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file']);
-        state.cmdStateAddDecision(cwd, { phase: p, summary, summary_file, rationale: rationale || '', rationale_file }, raw);
-      } else if (subcommand === 'add-blocker') {
-        const { text, 'text-file': text_file } = parseNamedArgs(args, ['text', 'text-file']);
-        state.cmdStateAddBlocker(cwd, { text, text_file }, raw);
-      } else if (subcommand === 'resolve-blocker') {
-        state.cmdStateResolveBlocker(cwd, parseNamedArgs(args, ['text']).text, raw);
-      } else if (subcommand === 'record-session') {
-        const { 'stopped-at': stopped_at, 'resume-file': resume_file } = parseNamedArgs(args, ['stopped-at', 'resume-file']);
-        state.cmdStateRecordSession(cwd, { stopped_at, resume_file: resume_file || 'None' }, raw);
-      } else if (subcommand === 'begin-phase') {
-        const { phase: p, name, plans } = parseNamedArgs(args, ['phase', 'name', 'plans']);
-        state.cmdStateBeginPhase(cwd, p, name, plans !== null ? parseInt(plans, 10) : null, raw);
-      } else if (subcommand === 'signal-waiting') {
-        const { type, question, options, phase: p } = parseNamedArgs(args, ['type', 'question', 'options', 'phase']);
-        state.cmdSignalWaiting(cwd, type, question, options, p, raw);
-      } else if (subcommand === 'signal-resume') {
-        state.cmdSignalResume(cwd, raw);
-      } else {
-        state.cmdStateLoad(cwd, raw);
-      }
+      routeStateCommand({
+        state,
+        args,
+        cwd,
+        raw,
+        parseNamedArgs,
+        error,
+      });
       break;
     }
 
@@ -425,6 +543,11 @@ async function runCommand(command, args, cwd, raw) {
       break;
     }
 
+    case 'check-commit': {
+      commands.cmdCheckCommit(cwd, raw);
+      break;
+    }
+
     case 'commit-to-subrepo': {
       const message = args[1];
       const filesIndex = args.indexOf('--files');
@@ -461,7 +584,7 @@ async function runCommand(command, args, cwd, raw) {
           wave: wave || '1',
         }, raw);
       } else {
-        error('Unknown template subcommand. Available: select, fill');
+        error('Unknown template subcommand. Available: select, fill', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }
@@ -479,28 +602,19 @@ async function runCommand(command, args, cwd, raw) {
       } else if (subcommand === 'validate') {
         frontmatter.cmdFrontmatterValidate(cwd, file, parseNamedArgs(args, ['schema']).schema, raw);
       } else {
-        error('Unknown frontmatter subcommand. Available: get, set, merge, validate');
+        error('Unknown frontmatter subcommand. Available: get, set, merge, validate', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }
 
     case 'verify': {
-      const subcommand = args[1];
-      if (subcommand === 'plan-structure') {
-        verify.cmdVerifyPlanStructure(cwd, args[2], raw);
-      } else if (subcommand === 'phase-completeness') {
-        verify.cmdVerifyPhaseCompleteness(cwd, args[2], raw);
-      } else if (subcommand === 'references') {
-        verify.cmdVerifyReferences(cwd, args[2], raw);
-      } else if (subcommand === 'commits') {
-        verify.cmdVerifyCommits(cwd, args.slice(2), raw);
-      } else if (subcommand === 'artifacts') {
-        verify.cmdVerifyArtifacts(cwd, args[2], raw);
-      } else if (subcommand === 'key-links') {
-        verify.cmdVerifyKeyLinks(cwd, args[2], raw);
-      } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links');
-      }
+      routeVerifyCommand({
+        verify,
+        args,
+        cwd,
+        raw,
+        error,
+      });
       break;
     }
 
@@ -540,7 +654,7 @@ async function runCommand(command, args, cwd, raw) {
     }
 
     case 'config-get': {
-      config.cmdConfigGet(cwd, args[1], raw);
+      config.cmdConfigGet(cwd, args[1], raw, defaultValue);
       break;
     }
 
@@ -549,44 +663,46 @@ async function runCommand(command, args, cwd, raw) {
       break;
     }
 
+    case 'config-path': {
+      config.cmdConfigPath(cwd, raw);
+      break;
+    }
+
     case 'agent-skills': {
       init.cmdAgentSkills(cwd, args[1], raw);
       break;
     }
 
+    case 'skill-manifest': {
+      init.cmdSkillManifest(cwd, args, raw);
+      break;
+    }
+
     case 'history-digest': {
       commands.cmdHistoryDigest(cwd, raw);
       break;
     }
 
     case 'phases': {
-      const subcommand = args[1];
-      if (subcommand === 'list') {
-        const typeIndex = args.indexOf('--type');
-        const phaseIndex = args.indexOf('--phase');
-        const options = {
-          type: typeIndex !== -1 ? args[typeIndex + 1] : null,
-          phase: phaseIndex !== -1 ? args[phaseIndex + 1] : null,
-          includeArchived: args.includes('--include-archived'),
-        };
-        phase.cmdPhasesList(cwd, options, raw);
-      } else {
-        error('Unknown phases subcommand. Available: list');
-      }
+      routePhasesCommand({
+        phase,
+        milestone,
+        args,
+        cwd,
+        raw,
+        error,
+      });
       break;
     }
 
     case 'roadmap': {
-      const subcommand = args[1];
-      if (subcommand === 'get-phase') {
-        roadmap.cmdRoadmapGetPhase(cwd, args[2], raw);
-      } else if (subcommand === 'analyze') {
-        roadmap.cmdRoadmapAnalyze(cwd, raw);
-      } else if (subcommand === 'update-plan-progress') {
-        roadmap.cmdRoadmapUpdatePlanProgress(cwd, args[2], raw);
-      } else {
-        error('Unknown roadmap subcommand. Available: get-phase, analyze, update-plan-progress');
-      }
+      routeRoadmapCommand({
+        roadmap,
+        args,
+        cwd,
+        raw,
+        error,
+      });
       break;
     }
 
@@ -595,38 +711,26 @@ async function runCommand(command, args, cwd, raw) {
       if (subcommand === 'mark-complete') {
         milestone.cmdRequirementsMarkComplete(cwd, args.slice(2), raw);
       } else {
-        error('Unknown requirements subcommand. Available: mark-complete');
+        error('Unknown requirements subcommand. Available: mark-complete', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }
 
+    case 'gap-analysis': {
+      // Post-planning gap checker (#2493) — unified REQUIREMENTS.md +
+      // CONTEXT.md <decisions> coverage report against PLAN.md files.
+      gapChecker.cmdGapAnalysis(cwd, args.slice(1), raw);
+      break;
+    }
+
     case 'phase': {
-      const subcommand = args[1];
-      if (subcommand === 'next-decimal') {
-        phase.cmdPhaseNextDecimal(cwd, args[2], raw);
-      } else if (subcommand === 'add') {
-        const idIdx = args.indexOf('--id');
-        let customId = null;
-        const descArgs = [];
-        for (let i = 2; i < args.length; i++) {
-          if (args[i] === '--id' && i + 1 < args.length) {
-            customId = args[i + 1];
-            i++; // skip value
-          } else {
-            descArgs.push(args[i]);
-          }
-        }
-        phase.cmdPhaseAdd(cwd, descArgs.join(' '), raw, customId);
-      } else if (subcommand === 'insert') {
-        phase.cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw);
-      } else if (subcommand === 'remove') {
-        const forceFlag = args.includes('--force');
-        phase.cmdPhaseRemove(cwd, args[2], { force: forceFlag }, raw);
-      } else if (subcommand === 'complete') {
-        phase.cmdPhaseComplete(cwd, args[2], raw);
-      } else {
-        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete');
-      }
+      routePhaseCommand({
+        phase,
+        args,
+        cwd,
+        raw,
+        error,
+      });
       break;
     }
 
@@ -637,23 +741,21 @@ async function runCommand(command, args, cwd, raw) {
         const archivePhases = args.includes('--archive-phases');
         milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases }, raw);
       } else {
-        error('Unknown milestone subcommand. Available: complete');
+        error('Unknown milestone subcommand. Available: complete', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }
 
     case 'validate': {
-      const subcommand = args[1];
-      if (subcommand === 'consistency') {
-        verify.cmdValidateConsistency(cwd, raw);
-      } else if (subcommand === 'health') {
-        const repairFlag = args.includes('--repair');
-        verify.cmdValidateHealth(cwd, { repair: repairFlag }, raw);
-      } else if (subcommand === 'agents') {
-        verify.cmdValidateAgents(cwd, raw);
-      } else {
-        error('Unknown validate subcommand. Available: consistency, health, agents');
-      }
+      routeValidateCommand({
+        verify,
+        args,
+        cwd,
+        raw,
+        parseNamedArgs,
+        output: core.output,
+        error,
+      });
       break;
     }
 
@@ -669,6 +771,21 @@ async function runCommand(command, args, cwd, raw) {
       break;
     }
 
+    case 'audit-open': {
+      const { auditOpenArtifacts, formatAuditReport } = require('./lib/audit.cjs');
+      const wantJson = args.includes('--json');
+      const result = auditOpenArtifacts(cwd);
+      if (wantJson) {
+        // core.output JSON-stringifies its first arg; pass the object directly.
+        core.output(result, raw);
+      } else {
+        // Human-readable report must bypass JSON encoding — use the rawValue
+        // form (third arg) which core.output emits verbatim.
+        core.output(null, true, formatAuditReport(result));
+      }
+      break;
+    }
+
     case 'uat': {
       const subcommand = args[1];
       const uat = require('./lib/uat.cjs');
@@ -676,7 +793,7 @@ async function runCommand(command, args, cwd, raw) {
         const options = parseNamedArgs(args, ['file']);
         uat.cmdRenderCheckpoint(cwd, options, raw);
       } else {
-        error('Unknown uat subcommand. Available: render-checkpoint');
+        error('Unknown uat subcommand. Available: render-checkpoint', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }
@@ -694,7 +811,7 @@ async function runCommand(command, args, cwd, raw) {
       } else if (subcommand === 'match-phase') {
         commands.cmdTodoMatchPhase(cwd, args[2], raw);
       } else {
-        error('Unknown todo subcommand. Available: complete, match-phase');
+        error('Unknown todo subcommand. Available: complete, match-phase', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }
@@ -710,59 +827,14 @@ async function runCommand(command, args, cwd, raw) {
     }
 
     case 'init': {
-      const workflow = args[1];
-      switch (workflow) {
-        case 'execute-phase':
-          init.cmdInitExecutePhase(cwd, args[2], raw);
-          break;
-        case 'plan-phase':
-          init.cmdInitPlanPhase(cwd, args[2], raw);
-          break;
-        case 'new-project':
-          init.cmdInitNewProject(cwd, raw);
-          break;
-        case 'new-milestone':
-          init.cmdInitNewMilestone(cwd, raw);
-          break;
-        case 'quick':
-          init.cmdInitQuick(cwd, args.slice(2).join(' '), raw);
-          break;
-        case 'resume':
-          init.cmdInitResume(cwd, raw);
-          break;
-        case 'verify-work':
-          init.cmdInitVerifyWork(cwd, args[2], raw);
-          break;
-        case 'phase-op':
-          init.cmdInitPhaseOp(cwd, args[2], raw);
-          break;
-        case 'todos':
-          init.cmdInitTodos(cwd, args[2], raw);
-          break;
-        case 'milestone-op':
-          init.cmdInitMilestoneOp(cwd, raw);
-          break;
-        case 'map-codebase':
-          init.cmdInitMapCodebase(cwd, raw);
-          break;
-        case 'progress':
-          init.cmdInitProgress(cwd, raw);
-          break;
-        case 'manager':
-          init.cmdInitManager(cwd, raw);
-          break;
-        case 'new-workspace':
-          init.cmdInitNewWorkspace(cwd, raw);
-          break;
-        case 'list-workspaces':
-          init.cmdInitListWorkspaces(cwd, raw);
-          break;
-        case 'remove-workspace':
-          init.cmdInitRemoveWorkspace(cwd, args[2], raw);
-          break;
-        default:
-          error(`Unknown init workflow: ${workflow}\nAvailable: execute-phase, plan-phase, new-project, new-milestone, quick, resume, verify-work, phase-op, todos, milestone-op, map-codebase, progress, manager, new-workspace, list-workspaces, remove-workspace`);
-      }
+      routeInitCommand({
+        init,
+        args,
+        cwd,
+        raw,
+        parseNamedArgs,
+        error,
+      });
       break;
     }
 
@@ -815,7 +887,7 @@ async function runCommand(command, args, cwd, raw) {
       const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
       const projectArg = args[1];
       if (!projectArg || projectArg.startsWith('--')) {
-        error('Usage: sdd-tools extract-messages <project> [--session <id>] [--limit N] [--path <dir>]\nRun scan-sessions first to see available projects.');
+        error('Usage: sdd-tools extract-messages <project> [--session <id>] [--limit N] [--path <dir>]\nRun scan-sessions first to see available projects.', ERROR_REASON.USAGE);
       }
       await profilePipeline.cmdExtractMessages(projectArg, { sessionId, limit }, raw, sessionsPath);
       break;
@@ -839,7 +911,7 @@ async function runCommand(command, args, cwd, raw) {
     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');
+      if (!inputPath) error('--input <analysis-json-path> is required', ERROR_REASON.USAGE);
       const outputIdx = args.indexOf('--output');
       const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
       profileOutput.cmdWriteProfile(cwd, { input: inputPath, output: outputPath }, raw);
@@ -905,13 +977,247 @@ async function runCommand(command, args, cwd, raw) {
       } else if (subcommand === 'progress') {
         workstream.cmdWorkstreamProgress(cwd, raw);
       } else {
-        error('Unknown workstream subcommand. Available: create, list, status, complete, set, get, progress');
+        error('Unknown workstream subcommand. Available: create, list, status, complete, set, get, progress', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }
 
-    default:
-      error(`Unknown command: ${command}`);
+    case 'worktree': {
+      const subcommand = args[1];
+      const worktreeSafety = require('./lib/worktree-safety.cjs');
+      if (subcommand === 'cleanup-wave') {
+        worktreeSafety.cmdWorktreeCleanupWave(cwd, args.slice(2));
+      } else {
+        error('Unknown worktree subcommand. Available: cleanup-wave', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+      }
+      break;
+    }
+
+    // ─── Intel ────────────────────────────────────────────────────────────
+
+    case 'intel': {
+      const intel = require('./lib/intel.cjs');
+      const subcommand = args[1];
+      if (subcommand === 'query') {
+        const term = args[2];
+        if (!term) error('Usage: sdd-tools intel query <term>', ERROR_REASON.USAGE);
+        const planningDir = path.join(cwd, '.planning');
+        core.output(intel.intelQuery(term, planningDir), raw);
+      } else if (subcommand === 'status') {
+        const planningDir = path.join(cwd, '.planning');
+        const status = intel.intelStatus(planningDir);
+        if (!raw && status.files) {
+          for (const file of Object.values(status.files)) {
+            if (file.updated_at) {
+              file.updated_at = core.timeAgo(new Date(file.updated_at));
+            }
+          }
+        }
+        core.output(status, raw);
+      } else if (subcommand === 'diff') {
+        const planningDir = path.join(cwd, '.planning');
+        core.output(intel.intelDiff(planningDir), raw);
+      } else if (subcommand === 'snapshot') {
+        const planningDir = path.join(cwd, '.planning');
+        core.output(intel.intelSnapshot(planningDir), raw);
+      } else if (subcommand === 'patch-meta') {
+        const filePath = args[2];
+        if (!filePath) error('Usage: sdd-tools intel patch-meta <file-path>', ERROR_REASON.USAGE);
+        core.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw);
+      } else if (subcommand === 'validate') {
+        const planningDir = path.join(cwd, '.planning');
+        core.output(intel.intelValidate(planningDir), raw);
+      } else if (subcommand === 'extract-exports') {
+        const filePath = args[2];
+        if (!filePath) error('Usage: sdd-tools intel extract-exports <file-path>', ERROR_REASON.USAGE);
+        core.output(intel.intelExtractExports(path.resolve(cwd, filePath)), raw);
+      } else if (subcommand === 'update') {
+        const planningDir = path.join(cwd, '.planning');
+        core.output(intel.intelUpdate(planningDir), raw);
+      } else {
+        error('Unknown intel subcommand. Available: query, status, update, diff, snapshot, patch-meta, validate, extract-exports', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+      }
+      break;
+    }
+
+    // ─── Graphify ──────────────────────────────────────────────────────────
+
+    case 'graphify': {
+      const graphify = require('./lib/graphify.cjs');
+      const subcommand = args[1];
+      if (subcommand === 'query') {
+        const term = args[2];
+        if (!term) error('Usage: sdd-tools graphify query <term>', ERROR_REASON.USAGE);
+        const budgetIdx = args.indexOf('--budget');
+        const budget = budgetIdx !== -1 ? parseInt(args[budgetIdx + 1], 10) : null;
+        core.output(graphify.graphifyQuery(cwd, term, { budget }), raw);
+      } else if (subcommand === 'status') {
+        core.output(graphify.graphifyStatus(cwd), raw);
+      } else if (subcommand === 'diff') {
+        core.output(graphify.graphifyDiff(cwd), raw);
+      } else if (subcommand === 'build') {
+        if (args[2] === 'snapshot') {
+          core.output(graphify.writeSnapshot(cwd), raw);
+        } else {
+          core.output(graphify.graphifyBuild(cwd), raw);
+        }
+      } else {
+        error('Unknown graphify subcommand. Available: build, query, status, diff', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+      }
+      break;
+    }
+
+    // ─── Documentation ────────────────────────────────────────────────────
+
+    case 'docs-init': {
+      docs.cmdDocsInit(cwd, raw);
+      break;
+    }
+
+    // ─── Learnings ─────────────────────────────────────────────────────────
+
+    case 'learnings': {
+      const subcommand = args[1];
+      if (subcommand === 'list') {
+        learnings.cmdLearningsList(raw);
+      } else if (subcommand === 'query') {
+        const tagIdx = args.indexOf('--tag');
+        const tag = tagIdx !== -1 ? args[tagIdx + 1] : null;
+        if (!tag) error('Usage: sdd-tools learnings query --tag <tag>', ERROR_REASON.USAGE);
+        learnings.cmdLearningsQuery(tag, raw);
+      } else if (subcommand === 'copy') {
+        learnings.cmdLearningsCopy(cwd, raw);
+      } else if (subcommand === 'prune') {
+        const olderIdx = args.indexOf('--older-than');
+        const olderThan = olderIdx !== -1 ? args[olderIdx + 1] : null;
+        if (!olderThan) error('Usage: sdd-tools learnings prune --older-than <duration>', ERROR_REASON.USAGE);
+        learnings.cmdLearningsPrune(olderThan, raw);
+      } else if (subcommand === 'delete') {
+        const id = args[2];
+        if (!id) error('Usage: sdd-tools learnings delete <id>', ERROR_REASON.USAGE);
+        learnings.cmdLearningsDelete(id, raw);
+      } else {
+        error('Unknown learnings subcommand. Available: list, query, copy, prune, delete', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+      }
+      break;
+    }
+
+    // ─── detect-custom-files ───────────────────────────────────────────────
+    // Detect user-added files inside SDD-managed directories that are not
+    // tracked in sdd-file-manifest.json. Used by the update workflow to back
+    // up custom files before the installer wipes those directories.
+    //
+    // This replaces the fragile bash pattern:
+    //   MANIFEST_FILES=$(node -e "require('$RUNTIME_DIR/...')" 2>/dev/null)
+    //   ${filepath#$RUNTIME_DIR/}   # unreliable path stripping
+    // which silently returns CUSTOM_COUNT=0 when $RUNTIME_DIR is unset or
+    // when the stripped path does not match the manifest key format (#1997).
+
+    case 'detect-custom-files': {
+      const configDirIdx = args.indexOf('--config-dir');
+      const configDir = configDirIdx !== -1 ? args[configDirIdx + 1] : null;
+      if (!configDir) {
+        error('Usage: sdd-tools detect-custom-files --config-dir <path>', ERROR_REASON.USAGE);
+      }
+      const resolvedConfigDir = path.resolve(configDir);
+      if (!fs.existsSync(resolvedConfigDir)) {
+        error(`Config directory not found: ${resolvedConfigDir}`, ERROR_REASON.USAGE);
+      }
+
+      const manifestPath = path.join(resolvedConfigDir, 'sdd-file-manifest.json');
+      if (!fs.existsSync(manifestPath)) {
+        // No manifest — cannot determine what is custom. Return empty list
+        // (same behaviour as saveLocalPatches in install.js when no manifest).
+        const out = { custom_files: [], custom_count: 0, manifest_found: false };
+        process.stdout.write(JSON.stringify(out, null, 2));
+        break;
+      }
+
+      let manifest;
+      try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      } catch {
+        const out = { custom_files: [], custom_count: 0, manifest_found: false, error: 'manifest parse error' };
+        process.stdout.write(JSON.stringify(out, null, 2));
+        break;
+      }
+
+      const manifestKeys = new Set(Object.keys(manifest.files || {}));
+
+      // SDD-managed directories to scan for user-added files.
+      // These are the directories the installer wipes on update.
+      const SDD_MANAGED_DIRS = [
+        'sdd',
+        'agents',
+        path.join('commands', 'sdd'),
+        'hooks',
+        'skills',
+      ];
+
+      function walkDir(dir, baseDir) {
+        const results = [];
+        if (!fs.existsSync(dir)) return results;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            results.push(...walkDir(fullPath, baseDir));
+          } else {
+            // Use forward slashes for cross-platform manifest key compatibility
+            const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+            results.push(relPath);
+          }
+        }
+        return results;
+      }
+
+      const customFiles = [];
+      for (const managedDir of SDD_MANAGED_DIRS) {
+        const absDir = path.join(resolvedConfigDir, managedDir);
+        if (!fs.existsSync(absDir)) continue;
+        for (const relPath of walkDir(absDir, resolvedConfigDir)) {
+          if (!manifestKeys.has(relPath)) {
+            customFiles.push(relPath);
+          }
+        }
+      }
+
+      const out = {
+        custom_files: customFiles,
+        custom_count: customFiles.length,
+        manifest_found: true,
+        manifest_version: manifest.version || null,
+      };
+      process.stdout.write(JSON.stringify(out, null, 2));
+      break;
+    }
+
+    // ─── SDD-2 Reverse Migration ───────────────────────────────────────────
+
+    case 'from-sdd2': {
+      const sdd2Import = require('./lib/sdd2-import.cjs');
+      sdd2Import.cmdFromSdd2(args.slice(1), cwd, raw);
+      break;
+    }
+
+    default: {
+      // #3243: if the caller passed a dotted form (e.g. "foo.bar"), the shim
+      // above split it so `command` here is the head ("foo"). Use
+      // originalCommand to reconstruct the original dotted form and suggest
+      // the spaced equivalent — surfacing a useful diagnostic instead of just
+      // "Unknown command: foo".
+      const wasDotted =
+        typeof originalCommand === 'string' &&
+        originalCommand !== command &&
+        originalCommand.includes('.');
+      let suggestion = '';
+      if (wasDotted) {
+        const dotIdx = originalCommand.indexOf('.');
+        const head = originalCommand.slice(0, dotIdx);
+        const rest = originalCommand.slice(dotIdx + 1);
+        suggestion = ` — did you mean: "${head} ${rest}"?`;
+      }
+      error(`Unknown command: ${command}${suggestion}`, ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
   }
 }