gsd-opencode 1.22.1 → 1.33.0

package/get-shit-done/bin/gsd-tools.cjs

@@ -6,7 +6,7 @@
  * Replaces repetitive inline bash patterns across ~50 GSD command/workflow/agent files.
  * Centralizes: config parsing, model resolution, phase lookup, git commits, summary verification.
  *
- * Usage: node gsd-tools.cjs <command> [args] [--raw]
+ * Usage: node gsd-tools.cjs <command> [args] [--raw] [--pick <field>]
  *
  * Atomic Commands:
  *   state load                         Load project config + state
@@ -14,9 +14,13 @@
  *   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]   Commit planning docs
+ *   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)
@@ -32,7 +36,7 @@
  *
  * Phase Operations:
  *   phase next-decimal <phase>         Calculate next decimal phase number
- *   phase add <description>            Append new phase to roadmap + create dir
+ *   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
@@ -54,6 +58,7 @@
  * 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
@@ -61,6 +66,10 @@
  * 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
@@ -84,6 +93,7 @@
  *   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
  *
  * Template Fill:
  *   template fill summary --phase N    Create pre-filled SUMMARY.md
@@ -124,11 +134,15 @@
  *   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
  */
 
 const fs = require('fs');
 const path = require('path');
-const { error } = require('./lib/core.cjs');
+const core = require('./lib/core.cjs');
+const { error, findProjectRoot, getActiveWorkstream } = core;
 const state = require('./lib/state.cjs');
 const phase = require('./lib/phase.cjs');
 const roadmap = require('./lib/roadmap.cjs');
@@ -139,6 +153,50 @@ const milestone = require('./lib/milestone.cjs');
 const commands = require('./lib/commands.cjs');
 const init = require('./lib/init.cjs');
 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');
+
+// ─── Arg parsing helpers ──────────────────────────────────────────────────────
+
+/**
+ * Extract named --flag <value> pairs from an args array.
+ * Returns an object mapping flag names to their values (null if absent).
+ * Flags listed in `booleanFlags` are treated as boolean (no value consumed).
+ *
+ * parseNamedArgs(args, 'phase', 'plan')        → { phase: '3', plan: '1' }
+ * parseNamedArgs(args, [], ['amend', 'force'])  → { amend: true, force: false }
+ */
+function parseNamedArgs(args, valueFlags = [], booleanFlags = []) {
+  const result = {};
+  for (const flag of valueFlags) {
+    const idx = args.indexOf(`--${flag}`);
+    result[flag] = idx !== -1 && args[idx + 1] !== undefined && !args[idx + 1].startsWith('--')
+      ? args[idx + 1]
+      : null;
+  }
+  for (const flag of booleanFlags) {
+    result[flag] = args.includes(`--${flag}`);
+  }
+  return result;
+}
+
+/**
+ * Collect all tokens after --flag until the next --flag or end of args.
+ * Handles multi-word values like --name Foo Bar Version 1.
+ * Returns null if the flag is absent.
+ */
+function parseMultiwordArg(args, flag) {
+  const idx = args.indexOf(`--${flag}`);
+  if (idx === -1) return null;
+  const tokens = [];
+  for (let i = idx + 1; i < args.length; i++) {
+    if (args[i].startsWith('--')) break;
+    tokens.push(args[i]);
+  }
+  return tokens.length > 0 ? tokens.join(' ') : null;
+}
 
 // ─── CLI Router ───────────────────────────────────────────────────────────────
 
@@ -165,16 +223,137 @@ async function main() {
     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 > session-scoped pointer > shared legacy pointer > null
+  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: gsd-tools <command> [args] [--raw] [--cwd <path>]\nCommands: state, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, init');
+    error('Usage: gsd-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, docs-init');
+  }
+
+  // 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': {
       const subcommand = args[1];
@@ -197,50 +376,37 @@ async function main() {
       } else if (subcommand === 'advance-plan') {
         state.cmdStateAdvancePlan(cwd, raw);
       } else if (subcommand === 'record-metric') {
-        const phaseIdx = args.indexOf('--phase');
-        const planIdx = args.indexOf('--plan');
-        const durationIdx = args.indexOf('--duration');
-        const tasksIdx = args.indexOf('--tasks');
-        const filesIdx = args.indexOf('--files');
-        state.cmdStateRecordMetric(cwd, {
-          phase: phaseIdx !== -1 ? args[phaseIdx + 1] : null,
-          plan: planIdx !== -1 ? args[planIdx + 1] : null,
-          duration: durationIdx !== -1 ? args[durationIdx + 1] : null,
-          tasks: tasksIdx !== -1 ? args[tasksIdx + 1] : null,
-          files: filesIdx !== -1 ? args[filesIdx + 1] : null,
-        }, raw);
+        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 phaseIdx = args.indexOf('--phase');
-        const summaryIdx = args.indexOf('--summary');
-        const summaryFileIdx = args.indexOf('--summary-file');
-        const rationaleIdx = args.indexOf('--rationale');
-        const rationaleFileIdx = args.indexOf('--rationale-file');
-        state.cmdStateAddDecision(cwd, {
-          phase: phaseIdx !== -1 ? args[phaseIdx + 1] : null,
-          summary: summaryIdx !== -1 ? args[summaryIdx + 1] : null,
-          summary_file: summaryFileIdx !== -1 ? args[summaryFileIdx + 1] : null,
-          rationale: rationaleIdx !== -1 ? args[rationaleIdx + 1] : '',
-          rationale_file: rationaleFileIdx !== -1 ? args[rationaleFileIdx + 1] : null,
-        }, raw);
+        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 textIdx = args.indexOf('--text');
-        const textFileIdx = args.indexOf('--text-file');
-        state.cmdStateAddBlocker(cwd, {
-          text: textIdx !== -1 ? args[textIdx + 1] : null,
-          text_file: textFileIdx !== -1 ? args[textFileIdx + 1] : null,
-        }, raw);
+        const { text, 'text-file': text_file } = parseNamedArgs(args, ['text', 'text-file']);
+        state.cmdStateAddBlocker(cwd, { text, text_file }, raw);
       } else if (subcommand === 'resolve-blocker') {
-        const textIdx = args.indexOf('--text');
-        state.cmdStateResolveBlocker(cwd, textIdx !== -1 ? args[textIdx + 1] : null, raw);
+        state.cmdStateResolveBlocker(cwd, parseNamedArgs(args, ['text']).text, raw);
       } else if (subcommand === 'record-session') {
-        const stoppedIdx = args.indexOf('--stopped-at');
-        const resumeIdx = args.indexOf('--resume-file');
-        state.cmdStateRecordSession(cwd, {
-          stopped_at: stoppedIdx !== -1 ? args[stoppedIdx + 1] : null,
-          resume_file: resumeIdx !== -1 ? args[resumeIdx + 1] : 'None',
-        }, raw);
+        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 if (subcommand === 'planned-phase') {
+        const { phase: p, name, plans } = parseNamedArgs(args, ['phase', 'name', 'plans']);
+        state.cmdStatePlannedPhase(cwd, p, plans !== null ? parseInt(plans, 10) : null, raw);
+      } else if (subcommand === 'validate') {
+        state.cmdStateValidate(cwd, raw);
+      } else if (subcommand === 'sync') {
+        const { verify } = parseNamedArgs(args, [], ['verify']);
+        state.cmdStateSync(cwd, { verify }, raw);
       } else {
         state.cmdStateLoad(cwd, raw);
       }
@@ -259,6 +425,7 @@ async function main() {
 
     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
@@ -267,7 +434,20 @@ async function main() {
       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);
+      commands.cmdCommit(cwd, message, files, raw, amend, noVerify);
+      break;
+    }
+
+    case 'check-commit': {
+      commands.cmdCheckCommit(cwd, raw);
+      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;
     }
 
@@ -285,19 +465,18 @@ async function main() {
         template.cmdTemplateSelect(cwd, args[2], raw);
       } else if (subcommand === 'fill') {
         const templateType = args[2];
-        const phaseIdx = args.indexOf('--phase');
-        const planIdx = args.indexOf('--plan');
-        const nameIdx = args.indexOf('--name');
-        const typeIdx = args.indexOf('--type');
-        const waveIdx = args.indexOf('--wave');
-        const fieldsIdx = args.indexOf('--fields');
+        const { phase, plan, name, type, wave, fields: fieldsRaw } = parseNamedArgs(args, ['phase', 'plan', 'name', 'type', 'wave', 'fields']);
+        let fields = {};
+        if (fieldsRaw) {
+          const { safeJsonParse } = require('./lib/security.cjs');
+          const result = safeJsonParse(fieldsRaw, { label: '--fields' });
+          if (!result.ok) error(result.error);
+          fields = result.value;
+        }
         template.cmdTemplateFill(cwd, templateType, {
-          phase: phaseIdx !== -1 ? args[phaseIdx + 1] : null,
-          plan: planIdx !== -1 ? args[planIdx + 1] : null,
-          name: nameIdx !== -1 ? args[nameIdx + 1] : null,
-          type: typeIdx !== -1 ? args[typeIdx + 1] : 'execute',
-          wave: waveIdx !== -1 ? args[waveIdx + 1] : '1',
-          fields: fieldsIdx !== -1 ? JSON.parse(args[fieldsIdx + 1]) : {},
+          phase, plan, name, fields,
+          type: type || 'execute',
+          wave: wave || '1',
         }, raw);
       } else {
         error('Unknown template subcommand. Available: select, fill');
@@ -309,18 +488,14 @@ async function main() {
       const subcommand = args[1];
       const file = args[2];
       if (subcommand === 'get') {
-        const fieldIdx = args.indexOf('--field');
-        frontmatter.cmdFrontmatterGet(cwd, file, fieldIdx !== -1 ? args[fieldIdx + 1] : null, raw);
+        frontmatter.cmdFrontmatterGet(cwd, file, parseNamedArgs(args, ['field']).field, raw);
       } else if (subcommand === 'set') {
-        const fieldIdx = args.indexOf('--field');
-        const valueIdx = args.indexOf('--value');
-        frontmatter.cmdFrontmatterSet(cwd, file, fieldIdx !== -1 ? args[fieldIdx + 1] : null, valueIdx !== -1 ? args[valueIdx + 1] : undefined, raw);
+        const { field, value } = parseNamedArgs(args, ['field', 'value']);
+        frontmatter.cmdFrontmatterSet(cwd, file, field, value !== null ? value : undefined, raw);
       } else if (subcommand === 'merge') {
-        const dataIdx = args.indexOf('--data');
-        frontmatter.cmdFrontmatterMerge(cwd, file, dataIdx !== -1 ? args[dataIdx + 1] : null, raw);
+        frontmatter.cmdFrontmatterMerge(cwd, file, parseNamedArgs(args, ['data']).data, raw);
       } else if (subcommand === 'validate') {
-        const schemaIdx = args.indexOf('--schema');
-        frontmatter.cmdFrontmatterValidate(cwd, file, schemaIdx !== -1 ? args[schemaIdx + 1] : null, raw);
+        frontmatter.cmdFrontmatterValidate(cwd, file, parseNamedArgs(args, ['schema']).schema, raw);
       } else {
         error('Unknown frontmatter subcommand. Available: get, set, merge, validate');
       }
@@ -341,8 +516,11 @@ async function main() {
         verify.cmdVerifyArtifacts(cwd, args[2], raw);
       } else if (subcommand === 'key-links') {
         verify.cmdVerifyKeyLinks(cwd, args[2], raw);
+      } else if (subcommand === 'schema-drift') {
+        const skipFlag = args.includes('--skip');
+        verify.cmdVerifySchemaDrift(cwd, args[2], skipFlag, raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, schema-drift');
       }
       break;
     }
@@ -377,11 +555,26 @@ async function main() {
       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;
@@ -398,8 +591,10 @@ async function main() {
           includeArchived: args.includes('--include-archived'),
         };
         phase.cmdPhasesList(cwd, options, raw);
+      } else if (subcommand === 'clear') {
+        milestone.cmdPhasesClear(cwd, raw);
       } else {
-        error('Unknown phases subcommand. Available: list');
+        error('Unknown phases subcommand. Available: list, clear');
       }
       break;
     }
@@ -433,7 +628,18 @@ async function main() {
       if (subcommand === 'next-decimal') {
         phase.cmdPhaseNextDecimal(cwd, args[2], raw);
       } else if (subcommand === 'add') {
-        phase.cmdPhaseAdd(cwd, args.slice(2).join(' '), raw);
+        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') {
@@ -450,18 +656,8 @@ async function main() {
     case 'milestone': {
       const subcommand = args[1];
       if (subcommand === 'complete') {
-        const nameIndex = args.indexOf('--name');
+        const milestoneName = parseMultiwordArg(args, 'name');
         const archivePhases = args.includes('--archive-phases');
-        // Collect --name value (everything after --name until next flag or end)
-        let milestoneName = null;
-        if (nameIndex !== -1) {
-          const nameArgs = [];
-          for (let i = nameIndex + 1; i < args.length; i++) {
-            if (args[i].startsWith('--')) break;
-            nameArgs.push(args[i]);
-          }
-          milestoneName = nameArgs.join(' ') || null;
-        }
         milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases }, raw);
       } else {
         error('Unknown milestone subcommand. Available: complete');
@@ -476,8 +672,10 @@ async function main() {
       } 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');
+        error('Unknown validate subcommand. Available: consistency, health, agents');
       }
       break;
     }
@@ -488,23 +686,47 @@ async function main() {
       break;
     }
 
+    case 'audit-uat': {
+      const uat = require('./lib/uat.cjs');
+      uat.cmdAuditUat(cwd, raw);
+      break;
+    }
+
+    case 'uat': {
+      const subcommand = args[1];
+      const uat = require('./lib/uat.cjs');
+      if (subcommand === 'render-checkpoint') {
+        const options = parseNamedArgs(args, ['file']);
+        uat.cmdRenderCheckpoint(cwd, options, raw);
+      } else {
+        error('Unknown uat subcommand. Available: render-checkpoint');
+      }
+      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');
+        error('Unknown todo subcommand. Available: complete, match-phase');
       }
       break;
     }
 
     case 'scaffold': {
       const scaffoldType = args[1];
-      const phaseIndex = args.indexOf('--phase');
-      const nameIndex = args.indexOf('--name');
       const scaffoldOptions = {
-        phase: phaseIndex !== -1 ? args[phaseIndex + 1] : null,
-        name: nameIndex !== -1 ? args.slice(nameIndex + 1).join(' ') : null,
+        phase: parseNamedArgs(args, ['phase']).phase,
+        name: parseMultiwordArg(args, 'name'),
       };
       commands.cmdScaffold(cwd, scaffoldType, scaffoldOptions, raw);
       break;
@@ -513,12 +735,16 @@ async function main() {
     case 'init': {
       const workflow = args[1];
       switch (workflow) {
-        case 'execute-phase':
-          init.cmdInitExecutePhase(cwd, args[2], raw);
+        case 'execute-phase': {
+          const { validate: epValidate } = parseNamedArgs(args, [], ['validate']);
+          init.cmdInitExecutePhase(cwd, args[2], raw, { validate: epValidate });
           break;
-        case 'plan-phase':
-          init.cmdInitPlanPhase(cwd, args[2], raw);
+        }
+        case 'plan-phase': {
+          const { validate: ppValidate } = parseNamedArgs(args, [], ['validate']);
+          init.cmdInitPlanPhase(cwd, args[2], raw, { validate: ppValidate });
           break;
+        }
         case 'new-project':
           init.cmdInitNewProject(cwd, raw);
           break;
@@ -549,8 +775,20 @@ async function main() {
         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`);
+          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`);
       }
       break;
     }
@@ -584,6 +822,128 @@ async function main() {
       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: gsd-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-OpenCode-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-OpenCode-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': {
+      const subcommand = args[1];
+      if (subcommand === 'create') {
+        const migrateNameIdx = args.indexOf('--migrate-name');
+        const noMigrate = args.includes('--no-migrate');
+        workstream.cmdWorkstreamCreate(cwd, args[2], {
+          migrate: !noMigrate,
+          migrateName: migrateNameIdx !== -1 ? args[migrateNameIdx + 1] : null,
+        }, raw);
+      } else if (subcommand === 'list') {
+        workstream.cmdWorkstreamList(cwd, raw);
+      } else if (subcommand === 'status') {
+        workstream.cmdWorkstreamStatus(cwd, args[2], raw);
+      } else if (subcommand === 'complete') {
+        workstream.cmdWorkstreamComplete(cwd, args[2], {}, raw);
+      } else if (subcommand === 'set') {
+        workstream.cmdWorkstreamSet(cwd, args[2], raw);
+      } else if (subcommand === 'get') {
+        workstream.cmdWorkstreamGet(cwd, raw);
+      } else if (subcommand === 'progress') {
+        workstream.cmdWorkstreamProgress(cwd, raw);
+      } else {
+        error('Unknown workstream subcommand. Available: create, list, status, complete, set, get, progress');
+      }
+      break;
+    }
+
+    // ─── Documentation ────────────────────────────────────────────────────
+
+    case 'docs-init': {
+      docs.cmdDocsInit(cwd, raw);
+      break;
+    }
+
     default:
       error(`Unknown command: ${command}`);
   }