@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/dgs-tools.cjs

@@ -0,0 +1,1444 @@
+#!/usr/bin/env node
+
+/**
+ * DGS Tools — CLI utility for DGS workflow operations
+ *
+ * Replaces repetitive inline bash patterns across ~50 DGS command/workflow/agent files.
+ * Centralizes: config parsing, model resolution, phase lookup, git commits, summary verification.
+ *
+ * Usage: node dgs-tools.cjs <command> [args] [--raw]
+ *
+ * Atomic Commands:
+ *   state load                         Load project config + state
+ *   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 archive-quick-tasks          Archive excess quick task rows to HISTORY.md
+ *   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
+ *   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
+ *   review-config                      Load review config with defaults
+ *   check-config-gitignore             Check if config.json needs .gitignore
+ *   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>            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
+ *
+ * Progress:
+ *   progress [json|table|bar]          Render progress in various formats
+ *
+ * Todos:
+ *   todo complete <filename>           Move todo from pending to completed
+ *
+ * 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>
+ *
+ * Context:
+ *   context load-tier <name>          Get file list for a context tier
+ *     [--phase N] [--idea N] [--spec N]  Scope-specific enrichment
+ *
+ * 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 "..."]
+ *   state add-blocker --text "..."     Add blocker
+ *   state resolve-blocker --text "..." Remove blocker
+ *   state record-session               Update session continuity
+ *     --stopped-at "..."
+ *     [--resume-file path]
+ *
+ * Projects Operations:
+ *   projects create <name>              Create new project subfolder
+ *     [--repos "repo1,repo2"]
+ *   projects switch <name>              Switch active project context
+ *   projects list                       List all projects with status
+ *   projects complete [--slug name]     Mark project as completed
+ *   projects regenerate                 Re-derive PROJECTS.md from disk
+ *
+ * Overlap Detection:
+ *   overlap check                       Check for cross-project repo/file overlaps
+ *
+ * Merge Conflict Resolution:
+ *   merge-conflicts detect              Detect conflicted files after failed merge
+ *     [--phase-dir <dir>]
+ *   merge-conflicts context <file>      Assemble resolution context for a file
+ *     [--phase-dir <dir>]
+ *   merge-conflicts resolved <file>     Record resolution outcome
+ *     --phase-dir <dir>
+ *     --resolution '{json}'
+ *   merge-conflicts summary             Aggregate all resolutions
+ *     --phase-dir <dir>
+ *
+ * Conflict Resolution Agent:
+ *   conflict-agent run                  Run automated conflict resolution
+ *     --phase-dir <dir>
+ *   conflict-agent resolve-file <file>  Resolve a single file (retry/escalation)
+ *     --phase-dir <dir> [--hint <text>]
+ *
+ * Multi-Repo Commit:
+ *   commit preflight <repo1> [repo2]    Check repos are clean before execution
+ *   commit detect-manual <repo>         Detect if repo changes were manually resolved
+ *     --files f1 f2 [--prior-sha SHA]
+ *   commit --multi-repo                  Per-repo commit with project-prefixed messages
+ *     --type <type> --project <slug>
+ *     --phase <N> --plan <M>
+ *     --desc <description>
+ *     --repos <repo1,repo2>
+ *     [--phase-dir <dir>]               Phase directory for context
+ *     [--retry --prior-results '[]']    Retry failed repos from prior commit
+ *
+ * Repo Operations:
+ *   repos list                          List all registered repos as JSON
+ *   repos add <path>                    Register a new repo
+ *     [--name N] [--desc D]
+ *   repos remove <name>                 Unregister a repo
+ *     [--force]
+ *   repos validate                      Check all repo paths exist on disk
+ *   repos resolve <filepath>            Resolve file path to owning repo
+ *   repos init-product [name]           Initialize product folder structure
+ *   repos scan-tags <phase-dir>         Scan plan files for <repos> tags
+ *   repos auto-populate <plan-file>    Auto-populate <repos> tags from <files> paths
+ *   repos validate-consistency <plan>  Validate <repos>/<files> consistency
+ *   repos migrate <slug>              Migrate v1 install to v2 structure
+ *
+ * Ideas Operations:
+ *   ideas create --title T --body B     Create new idea with auto-assigned ID
+ *     [--tags "t1,t2"]
+ *   ideas update --id N --field F       Update idea field (title, body, tags)
+ *     --value V
+ *   ideas append-note --id N --note T   Append timestamped note to idea
+ *   ideas list [--state S] [--tag T]    List ideas grouped by state
+ *     [--orphan-check]
+ *   ideas reject --id N [--reason R]    Reject idea (move to rejected/)
+ *   ideas restore --id N                Restore idea to pending
+ *   ideas move-state --id N --to S      Move idea to target state
+ *   ideas discuss-save --id N           Save structured discussion entry
+ *     --entry '{json}'                  JSON: { date, keyInsights, refinedProblem, refinedApproach, openQuestions, decision }
+ *   ideas research-save --id N           Save structured research log entry
+ *     --entry '{json}'                  JSON: { date, summary, keyFindings, recommendation, documentLink, outcome }
+ *   ideas find-related --id N         Find ideas related to anchor idea by tag overlap
+ *     [--threshold high|medium|low]   Filter by minimum match level (default: medium)
+ *   ideas undo-consolidation --id N    Undo consolidation: restore sources, delete result
+ *
+ * Specs Operations:
+ *   specs create --title T --body B [--source-document PATH]  Create new spec
+ *     [--source-ideas "f1,f2"]
+ *   specs list [--status S]                 List all specs with status
+ *   specs update-status --id N --status S   Update spec status
+ *   specs append-review --id N --entry T    Append review history entry
+ *   specs finalize --id N                   Finalize spec and move ideas to done
+ *
+ * Docs Operations:
+ *   docs add --source <path> --scope <product|idea|spec> [--scope-id <id>]   Add document to scope
+ *   docs list [--scope <filter>]                                               List all documents
+ *   docs remove --scope <product|idea|spec> [--scope-id <id>] --slug <slug>  Remove document
+ *   docs move --slug <slug> --from-scope <scope> [--from-id <id>] --to-scope <scope> [--to-id <id>]  Move document
+ *   docs check-duplicate --scope <scope> [--scope-id <id>] --slug <slug>     Check if slug exists
+ *
+ * Identity:
+ *   identity resolve                  Resolve git identity (name + email)
+ *
+ * Jobs:
+ *   jobs parse <file>                 Parse job file into structured JSON
+ *   jobs update-step <file> <index>   Update step status in job file
+ *     <status> [--timestamp ts]
+ *     [--error "msg"]
+ *   jobs move <file> <target-dir>     Move job file to target directory
+ *   jobs insert-gap-fix-section       Insert gap-fix section marker + steps
+ *     <file> <after-index> <cycle>
+ *     <version> <phases-json>
+ *   jobs insert-phase-gap-fix         Insert phase-level gap-fix steps
+ *     <file> <after-index> <cycle>
+ *     <phase-number>
+ *   jobs create-milestone [version]   Generate milestone job from roadmap
+ *     [--no-check]                    Omit audit/complete steps
+ *   jobs milestone-preview [version]  Preview milestone job without writing
+ *     [--no-check]                    Omit audit/complete steps
+ *   jobs record-start-shas <file>     Record starting commit SHAs into job file
+ *   jobs rollback <version>           Roll back code repos to pre-job SHAs
+ *
+ * Search Operations:
+ *   search <query> [--flags]          Search across ideas, specs, docs, projects
+ *     [--ideas-only] [--specs-only] [--docs-only]
+ *     [--include-rejected] [--tags "t1,t2"]
+ *     [--max-per-type N]
+ *
+ * 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
+ */
+
+const { error } = require('./lib/core.cjs');
+const state = require('./lib/state.cjs');
+const phase = require('./lib/phase.cjs');
+const roadmap = require('./lib/roadmap.cjs');
+const verify = require('./lib/verify.cjs');
+const config = require('./lib/config.cjs');
+const template = require('./lib/template.cjs');
+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 repos = require('./lib/repos.cjs');
+const projects = require('./lib/projects.cjs');
+const execution = require('./lib/execution.cjs');
+const overlap = require('./lib/overlap.cjs');
+const ideas = require('./lib/ideas.cjs');
+const specs = require('./lib/specs.cjs');
+const docs = require('./lib/docs.cjs');
+const search = require('./lib/search.cjs');
+const jobs = require('./lib/jobs.cjs');
+const mergeConflicts = require('./lib/merge-conflicts.cjs');
+const conflictAgent = require('./lib/conflict-agent.cjs');
+const { requireGitIdentity, formatAuthorString, cmdIdentityResolve } = require('./lib/identity.cjs');
+
+// ─── Identity Gate ────────────────────────────────────────────────────────────
+
+/**
+ * Enforces git identity for write commands. Calls requireGitIdentity() and
+ * converts thrown errors into clean CLI error output via error().
+ * Read-only commands must NOT call this.
+ *
+ * @returns {string} Formatted author string (e.g., "Name <email>" or "Name")
+ */
+function gateIdentity() {
+  try {
+    const identity = requireGitIdentity();
+    return formatAuthorString(identity);
+  } catch (e) {
+    error(e.message);
+  }
+}
+
+// ─── CLI Router ───────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  const rawIndex = args.indexOf('--raw');
+  const raw = rawIndex !== -1;
+  if (rawIndex !== -1) args.splice(rawIndex, 1);
+
+  const command = args[0];
+  const cwd = process.cwd();
+
+  if (!command) {
+    error('Usage: dgs-tools <command> [args] [--raw]\nCommands: state, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, repos, projects, overlap, merge-conflicts, conflict-agent, init');
+  }
+
+  switch (command) {
+    case 'state': {
+      const subcommand = args[1];
+      // Gate write subcommands
+      if (subcommand && subcommand !== 'load' && subcommand !== 'get') {
+        gateIdentity();
+      }
+      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 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);
+      } 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 rationaleIdx = args.indexOf('--rationale');
+        state.cmdStateAddDecision(cwd, {
+          phase: phaseIdx !== -1 ? args[phaseIdx + 1] : null,
+          summary: summaryIdx !== -1 ? args[summaryIdx + 1] : null,
+          rationale: rationaleIdx !== -1 ? args[rationaleIdx + 1] : '',
+        }, raw);
+      } else if (subcommand === 'add-blocker') {
+        const textIdx = args.indexOf('--text');
+        state.cmdStateAddBlocker(cwd, textIdx !== -1 ? args[textIdx + 1] : null, raw);
+      } else if (subcommand === 'resolve-blocker') {
+        const textIdx = args.indexOf('--text');
+        state.cmdStateResolveBlocker(cwd, textIdx !== -1 ? args[textIdx + 1] : null, 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);
+      } else if (subcommand === 'archive-quick-tasks') {
+        state.cmdStateArchiveQuickTasks(cwd, raw);
+      } else {
+        state.cmdStateLoad(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': {
+      gateIdentity();
+      // Check for preflight subcommand
+      if (args[1] === 'preflight') {
+        const repoNames = args.slice(2);
+        execution.cmdCommitPreflight(cwd, repoNames, raw);
+        break;
+      }
+
+      // Check for detect-manual subcommand
+      if (args[1] === 'detect-manual') {
+        const repoName = args[2];
+        const filesIdx = args.indexOf('--files');
+        const expectedFiles = filesIdx !== -1 ? args.slice(filesIdx + 1).filter(a => !a.startsWith('--')) : [];
+        const priorShaIdx = args.indexOf('--prior-sha');
+        const priorSha = priorShaIdx !== -1 ? args[priorShaIdx + 1] : undefined;
+        const result = execution.detectManualResolution(cwd, repoName, expectedFiles, priorSha);
+        if (raw) {
+          console.log(JSON.stringify(result));
+        } else {
+          console.log(`Resolution: ${result.resolved ? 'YES' : 'NO'} (${result.reason})`);
+        }
+        break;
+      }
+
+      // Check for --multi-repo flag
+      const multiRepoIdx = args.indexOf('--multi-repo');
+      if (multiRepoIdx !== -1) {
+        const typeIdx = args.indexOf('--type');
+        const projectIdx = args.indexOf('--project');
+        const phaseIdx = args.indexOf('--phase');
+        const planIdx = args.indexOf('--plan');
+        const descIdx = args.indexOf('--desc');
+        const reposIdx = args.indexOf('--repos');
+        const retryIdx = args.indexOf('--retry');
+        const priorResultsIdx = args.indexOf('--prior-results');
+        const phaseDirIdx = args.indexOf('--phase-dir');
+        execution.cmdCommitMultiRepo(cwd, {
+          type: typeIdx !== -1 ? args[typeIdx + 1] : 'feat',
+          project: projectIdx !== -1 ? args[projectIdx + 1] : null,
+          phase: phaseIdx !== -1 ? args[phaseIdx + 1] : null,
+          plan: planIdx !== -1 ? args[planIdx + 1] : null,
+          description: descIdx !== -1 ? args[descIdx + 1] : null,
+          repos: reposIdx !== -1 ? args[reposIdx + 1].split(',') : null,
+          retry: retryIdx !== -1,
+          priorResults: priorResultsIdx !== -1 ? JSON.parse(args[priorResultsIdx + 1]) : null,
+          phaseDir: phaseDirIdx !== -1 ? args[phaseDirIdx + 1] : null,
+        }, raw);
+        break;
+      }
+
+      // Existing single-repo commit logic
+      const amend = args.includes('--amend');
+      const message = args[1];
+      // Parse --files flag (collect args after --files, stopping at other flags)
+      const filesIndex = args.indexOf('--files');
+      const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
+      // Parse --phase-dir flag (available for context, passed through if supported)
+      const phaseDirIdx = args.indexOf('--phase-dir');
+      const phaseDir = phaseDirIdx !== -1 ? args[phaseDirIdx + 1] : null;
+      commands.cmdCommit(cwd, message, files, raw, amend);
+      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': {
+      const subcommand = args[1];
+      // Gate write subcommand and capture author string
+      let author = null;
+      if (subcommand === 'fill') {
+        author = gateIdentity();
+      }
+      if (subcommand === 'select') {
+        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');
+        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]) : {},
+          author,
+        }, raw);
+      } else {
+        error('Unknown template subcommand. Available: select, fill');
+      }
+      break;
+    }
+
+    case 'frontmatter': {
+      const subcommand = args[1];
+      const file = args[2];
+      // Gate write subcommands
+      if (subcommand === 'set' || subcommand === 'merge') {
+        gateIdentity();
+      }
+      if (subcommand === 'get') {
+        const fieldIdx = args.indexOf('--field');
+        frontmatter.cmdFrontmatterGet(cwd, file, fieldIdx !== -1 ? args[fieldIdx + 1] : null, 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);
+      } else if (subcommand === 'merge') {
+        const dataIdx = args.indexOf('--data');
+        frontmatter.cmdFrontmatterMerge(cwd, file, dataIdx !== -1 ? args[dataIdx + 1] : null, raw);
+      } else if (subcommand === 'validate') {
+        const schemaIdx = args.indexOf('--schema');
+        frontmatter.cmdFrontmatterValidate(cwd, file, schemaIdx !== -1 ? args[schemaIdx + 1] : null, raw);
+      } else {
+        error('Unknown frontmatter subcommand. Available: get, set, merge, validate');
+      }
+      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');
+      }
+      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-get': {
+      config.cmdConfigGet(cwd, args[1], raw);
+      break;
+    }
+
+    case 'review-config': {
+      const result = config.loadReviewConfig(cwd);
+      const { output: out } = require('./lib/core.cjs');
+      out(result, raw);
+      break;
+    }
+
+    case 'check-config-gitignore': {
+      const result = config.checkConfigGitignore(cwd);
+      const { output: out } = require('./lib/core.cjs');
+      out(result, 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');
+      }
+      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');
+      }
+      break;
+    }
+
+    case 'repos': {
+      const subcommand = args[1];
+      // Gate write subcommands
+      if (subcommand === 'init-product' || subcommand === 'add' || subcommand === 'remove' || subcommand === 'migrate') {
+        gateIdentity();
+      }
+      if (subcommand === 'list') {
+        repos.cmdReposList(cwd, raw);
+      } else if (subcommand === 'add') {
+        const repoPath = args[2];
+        const nameIdx = args.indexOf('--name');
+        const descIdx = args.indexOf('--desc');
+        repos.cmdReposAdd(cwd, repoPath, {
+          name: nameIdx !== -1 ? args[nameIdx + 1] : null,
+          desc: descIdx !== -1 ? args[descIdx + 1] : null,
+        }, raw);
+      } else if (subcommand === 'remove') {
+        const forceFlag = args.includes('--force');
+        repos.cmdReposRemove(cwd, args[2], { force: forceFlag }, raw);
+      } else if (subcommand === 'validate') {
+        repos.cmdReposValidate(cwd, raw);
+      } else if (subcommand === 'resolve') {
+        repos.cmdReposResolve(cwd, args[2], raw);
+      } else if (subcommand === 'init-product') {
+        const layoutIdx = args.indexOf('--layout');
+        const layoutFlag = layoutIdx !== -1 ? args[layoutIdx + 1] : null;
+        // productName is first positional arg after subcommand, skip --layout and its value
+        let productName = null;
+        for (let i = 2; i < args.length; i++) {
+          if (args[i] === '--layout') { i++; continue; } // skip --layout and its value
+          productName = args[i];
+          break;
+        }
+        repos.cmdReposInitProduct(cwd, { productName, layout: layoutFlag }, raw);
+      } else if (subcommand === 'detect-layout') {
+        repos.cmdDetectLayout(cwd, raw);
+      } else if (subcommand === 'scan-tags') {
+        const phaseDir = args[2];
+        repos.cmdReposScanTags(cwd, phaseDir, raw);
+      } else if (subcommand === 'auto-populate') {
+        const planFile = args[2];
+        repos.cmdReposAutoPopulate(cwd, planFile, raw);
+      } else if (subcommand === 'validate-consistency') {
+        const planFile = args[2];
+        repos.cmdReposValidateConsistency(cwd, planFile, raw);
+      } else if (subcommand === 'migrate') {
+        const migrationMod = require('./lib/migration.cjs');
+        const slug = args[2];
+        if (!slug) error('Usage: repos migrate <slug>');
+        migrationMod.cmdMigrateV1ToV2(cwd, slug, raw);
+      } else {
+        error('Unknown repos subcommand. Available: list, add, remove, validate, resolve, init-product, detect-layout, scan-tags, auto-populate, validate-consistency, migrate');
+      }
+      break;
+    }
+
+    case 'projects': {
+      const subcommand = args[1];
+      // Gate write subcommands
+      if (subcommand === 'create' || subcommand === 'switch' || subcommand === 'complete' || subcommand === 'reactivate') {
+        gateIdentity();
+      }
+      if (subcommand === 'create') {
+        const name = args[2];
+        const reposIdx = args.indexOf('--repos');
+        projects.cmdProjectsCreate(cwd, name, {
+          initial_repos: reposIdx !== -1 ? args[reposIdx + 1] : null,
+        }, raw);
+      } else if (subcommand === 'switch') {
+        projects.cmdProjectsSwitch(cwd, args[2], raw);
+      } else if (subcommand === 'list') {
+        projects.cmdProjectsList(cwd, raw);
+      } else if (subcommand === 'complete') {
+        const slugIdx = args.indexOf('--slug');
+        projects.cmdProjectsComplete(cwd, {
+          slug: slugIdx !== -1 ? args[slugIdx + 1] : null,
+        }, raw);
+      } else if (subcommand === 'reactivate') {
+        const slugIdx = args.indexOf('--slug');
+        const setCurrent = args.includes('--set-current');
+        projects.cmdProjectsReactivate(cwd, {
+          slug: slugIdx !== -1 ? args[slugIdx + 1] : null,
+          set_current: setCurrent,
+        }, raw);
+      } else if (subcommand === 'regenerate') {
+        projects.cmdProjectsRegenerate(cwd, raw);
+      } else {
+        error('Unknown projects subcommand. Available: create, switch, list, complete, reactivate, regenerate');
+      }
+      break;
+    }
+
+    case 'overlap': {
+      const subcommand = args[1];
+      if (subcommand === 'check') {
+        overlap.cmdOverlapCheck(cwd, raw);
+      } else {
+        error('Unknown overlap subcommand. Available: check');
+      }
+      break;
+    }
+
+    case 'requirements': {
+      const subcommand = args[1];
+      // Gate write subcommand
+      if (subcommand === 'mark-complete') {
+        gateIdentity();
+      }
+      if (subcommand === 'mark-complete') {
+        milestone.cmdRequirementsMarkComplete(cwd, args.slice(2), raw);
+      } else {
+        error('Unknown requirements subcommand. Available: mark-complete');
+      }
+      break;
+    }
+
+    case 'phase': {
+      const subcommand = args[1];
+      // Gate write subcommands
+      if (subcommand === 'add' || subcommand === 'insert' || subcommand === 'remove' || subcommand === 'complete') {
+        gateIdentity();
+      }
+      if (subcommand === 'next-decimal') {
+        phase.cmdPhaseNextDecimal(cwd, args[2], raw);
+      } else if (subcommand === 'add') {
+        phase.cmdPhaseAdd(cwd, args.slice(2).join(' '), raw);
+      } 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');
+      }
+      break;
+    }
+
+    case 'milestone': {
+      gateIdentity();
+      const subcommand = args[1];
+      if (subcommand === 'complete') {
+        const nameIndex = args.indexOf('--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');
+      }
+      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 {
+        error('Unknown validate subcommand. Available: consistency, health');
+      }
+      break;
+    }
+
+    case 'progress': {
+      const subcommand = args[1] || 'json';
+      commands.cmdProgressRender(cwd, subcommand, raw);
+      break;
+    }
+
+    case 'todo': {
+      const subcommand = args[1];
+      // Gate write subcommand
+      if (subcommand === 'complete') {
+        gateIdentity();
+      }
+      if (subcommand === 'complete') {
+        commands.cmdTodoComplete(cwd, args[2], raw);
+      } else {
+        error('Unknown todo subcommand. Available: complete');
+      }
+      break;
+    }
+
+    case 'scaffold': {
+      gateIdentity();
+      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,
+      };
+      commands.cmdScaffold(cwd, scaffoldType, scaffoldOptions, raw);
+      break;
+    }
+
+    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 'audit-phase':
+          init.cmdInitAuditPhase(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': {
+          const onlyIdx = args.indexOf('--only');
+          let onlyRepo = null;
+          if (onlyIdx !== -1) {
+            onlyRepo = args[onlyIdx + 1] || null;
+            if (!onlyRepo || onlyRepo.startsWith('--')) {
+              error('--only requires a repo name argument');
+            }
+          } else if (args[2] && !args[2].startsWith('--')) {
+            // Positional argument: /dgs:map-codebase <repo-name>
+            onlyRepo = args[2];
+          }
+          init.cmdInitMapCodebase(cwd, onlyRepo, raw);
+          break;
+        }
+        case 'progress':
+          init.cmdInitProgress(cwd, raw);
+          break;
+        default:
+          error(`Unknown init workflow: ${workflow}\nAvailable: execute-phase, plan-phase, new-project, new-milestone, quick, resume, verify-work, audit-phase, phase-op, todos, milestone-op, map-codebase, progress`);
+      }
+      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;
+    }
+
+    case 'ideas': {
+      const subcommand = args[1];
+      // Gate write subcommands and capture author string for authorship fields
+      let author = null;
+      if (subcommand !== 'list') {
+        author = gateIdentity();
+      }
+      if (subcommand === 'create') {
+        const titleIdx = args.indexOf('--title');
+        const bodyIdx = args.indexOf('--body');
+        const tagsIdx = args.indexOf('--tags');
+        ideas.cmdIdeasCreate(cwd,
+          titleIdx !== -1 ? args[titleIdx + 1] : null,
+          bodyIdx !== -1 ? args[bodyIdx + 1] : null,
+          tagsIdx !== -1 ? args[tagsIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'update') {
+        const idIdx = args.indexOf('--id');
+        const fieldIdx = args.indexOf('--field');
+        const valueIdx = args.indexOf('--value');
+        ideas.cmdIdeasUpdate(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          fieldIdx !== -1 ? args[fieldIdx + 1] : null,
+          valueIdx !== -1 ? args[valueIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'append-note') {
+        const idIdx = args.indexOf('--id');
+        const noteIdx = args.indexOf('--note');
+        ideas.cmdIdeasAppendNote(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          noteIdx !== -1 ? args[noteIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'list') {
+        const stateIdx = args.indexOf('--state');
+        const tagIdx = args.indexOf('--tag');
+        const authorIdx = args.indexOf('--author');
+        const orphanCheck = args.includes('--orphan-check');
+        const consolidatedFlag = args.includes('--consolidated');
+        const allFlag = args.includes('--all');
+        ideas.cmdIdeasList(cwd, {
+          state: stateIdx !== -1 ? args[stateIdx + 1] : null,
+          tag: tagIdx !== -1 ? args[tagIdx + 1] : null,
+          author: authorIdx !== -1 ? args[authorIdx + 1] : null,
+          include_orphan_check: orphanCheck,
+          include_consolidated: consolidatedFlag,
+          show_all: allFlag,
+        }, raw);
+      } else if (subcommand === 'reject') {
+        const idIdx = args.indexOf('--id');
+        const reasonIdx = args.indexOf('--reason');
+        ideas.cmdIdeasReject(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          reasonIdx !== -1 ? args[reasonIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'restore') {
+        const idIdx = args.indexOf('--id');
+        ideas.cmdIdeasRestore(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'move-state') {
+        const idIdx = args.indexOf('--id');
+        const toIdx = args.indexOf('--to');
+        ideas.cmdIdeasMoveState(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          toIdx !== -1 ? args[toIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'discuss-save') {
+        const idIdx = args.indexOf('--id');
+        const entryIdx = args.indexOf('--entry');
+        ideas.cmdIdeasDiscussSave(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          entryIdx !== -1 ? args[entryIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'research-save') {
+        const idIdx = args.indexOf('--id');
+        const entryIdx = args.indexOf('--entry');
+        ideas.cmdIdeasResearchSave(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          entryIdx !== -1 ? args[entryIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'consolidate') {
+        const idsIdx = args.indexOf('--ids');
+        const titleIdx = args.indexOf('--title');
+        const bodyIdx = args.indexOf('--body');
+        const tagsIdx = args.indexOf('--tags');
+        const discussionIdx = args.indexOf('--discussion');
+        const researchIdx = args.indexOf('--research');
+        ideas.cmdIdeasConsolidate(cwd, {
+          ids: idsIdx !== -1 ? args[idsIdx + 1] : null,
+          title: titleIdx !== -1 ? args[titleIdx + 1] : null,
+          body: bodyIdx !== -1 ? args[bodyIdx + 1] : null,
+          tags: tagsIdx !== -1 ? args[tagsIdx + 1] : null,
+          discussion: discussionIdx !== -1 ? args[discussionIdx + 1] : null,
+          research: researchIdx !== -1 ? args[researchIdx + 1] : null,
+        }, raw, author);
+      } else if (subcommand === 'find-related') {
+        const idIdx = args.indexOf('--id');
+        const thresholdIdx = args.indexOf('--threshold');
+        ideas.cmdIdeasFindRelated(cwd, {
+          id: idIdx !== -1 ? args[idIdx + 1] : null,
+          threshold: thresholdIdx !== -1 ? args[thresholdIdx + 1] : 'medium',
+        }, raw);
+      } else if (subcommand === 'undo-consolidation') {
+        const idIdx = args.indexOf('--id');
+        ideas.cmdIdeasUndoConsolidation(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          raw,
+          author
+        );
+      } else {
+        error('Unknown ideas subcommand: ' + subcommand);
+      }
+      break;
+    }
+
+    case 'specs': {
+      const subcommand = args[1];
+      // Gate write subcommands and capture author string for authorship fields
+      let author = null;
+      if (subcommand !== 'list' && subcommand !== 'validate') {
+        author = gateIdentity();
+      }
+      if (subcommand === 'create') {
+        const titleIdx = args.indexOf('--title');
+        const bodyIdx = args.indexOf('--body');
+        const sourceIdeasIdx = args.indexOf('--source-ideas');
+        const sourceDocIdx = args.indexOf('--source-document');
+        specs.cmdSpecsCreate(cwd, {
+          title: titleIdx !== -1 ? args[titleIdx + 1] : null,
+          source_ideas: sourceIdeasIdx !== -1 ? args[sourceIdeasIdx + 1].split(',').map(s => s.trim()) : [],
+          body: bodyIdx !== -1 ? args[bodyIdx + 1] : '',
+          source_document: sourceDocIdx !== -1 ? args[sourceDocIdx + 1] : null,
+          author,
+        }, raw);
+      } else if (subcommand === 'list') {
+        const statusIdx = args.indexOf('--status');
+        const authorIdx = args.indexOf('--author');
+        specs.cmdSpecsList(cwd, {
+          status: statusIdx !== -1 ? args[statusIdx + 1] : null,
+          author: authorIdx !== -1 ? args[authorIdx + 1] : null,
+        }, raw);
+      } else if (subcommand === 'update-status') {
+        const idIdx = args.indexOf('--id');
+        const statusIdx = args.indexOf('--status');
+        specs.cmdSpecsUpdateStatus(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          statusIdx !== -1 ? args[statusIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'append-review') {
+        const idIdx = args.indexOf('--id');
+        const entryIdx = args.indexOf('--entry');
+        specs.cmdSpecsAppendReviewHistory(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          entryIdx !== -1 ? args[entryIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'finalize') {
+        const idIdx = args.indexOf('--id');
+        specs.cmdSpecsFinalize(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'set-status') {
+        const idIdx = args.indexOf('--id');
+        const statusIdx = args.indexOf('--status');
+        specs.cmdSpecsSetStatus(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          statusIdx !== -1 ? args[statusIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'validate') {
+        const idIdx = args.indexOf('--id');
+        specs.cmdSpecsValidate(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          raw
+        );
+      } else if (subcommand === 'add-log-entry') {
+        const idIdx = args.indexOf('--id');
+        const dateIdx = args.indexOf('--date');
+        const versionIdx = args.indexOf('--version');
+        const actionIdx = args.indexOf('--action');
+        const summaryIdx = args.indexOf('--summary');
+        specs.cmdSpecsAddLogEntry(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          dateIdx !== -1 ? args[dateIdx + 1] : null,
+          versionIdx !== -1 ? args[versionIdx + 1] : null,
+          actionIdx !== -1 ? args[actionIdx + 1] : null,
+          summaryIdx !== -1 ? args[summaryIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'link-milestone') {
+        const idIdx = args.indexOf('--id');
+        const milestoneIdx = args.indexOf('--milestone');
+        specs.cmdSpecsLinkMilestone(cwd,
+          idIdx !== -1 ? args[idIdx + 1] : null,
+          milestoneIdx !== -1 ? args[milestoneIdx + 1] : null,
+          raw,
+          author
+        );
+      } else {
+        error('Unknown specs subcommand: ' + (subcommand || '(none)') + '. Available: create, list, update-status, append-review, finalize, set-status, validate, add-log-entry, link-milestone');
+      }
+      break;
+    }
+
+    case 'docs': {
+      const subcommand = args[1];
+      // Gate write subcommands and capture author string for authorship fields
+      let author = null;
+      if (subcommand !== 'list' && subcommand !== 'check-duplicate') {
+        author = gateIdentity();
+      }
+      if (subcommand === 'add') {
+        const sourceIdx = args.indexOf('--source');
+        const scopeIdx = args.indexOf('--scope');
+        const scopeIdIdx = args.indexOf('--scope-id');
+        docs.cmdDocsAdd(cwd,
+          sourceIdx !== -1 ? args[sourceIdx + 1] : null,
+          scopeIdx !== -1 ? args[scopeIdx + 1] : null,
+          scopeIdIdx !== -1 ? args[scopeIdIdx + 1] : null,
+          raw,
+          author
+        );
+      } else if (subcommand === 'list') {
+        const scopeIdx = args.indexOf('--scope');
+        docs.cmdDocsList(cwd,
+          scopeIdx !== -1 ? args[scopeIdx + 1] : null,
+          raw
+        );
+      } else if (subcommand === 'remove') {
+        const scopeIdx = args.indexOf('--scope');
+        const scopeIdIdx = args.indexOf('--scope-id');
+        const slugIdx = args.indexOf('--slug');
+        docs.cmdDocsRemove(cwd,
+          scopeIdx !== -1 ? args[scopeIdx + 1] : null,
+          scopeIdIdx !== -1 ? args[scopeIdIdx + 1] : null,
+          slugIdx !== -1 ? args[slugIdx + 1] : null,
+          raw
+        );
+      } else if (subcommand === 'move') {
+        const slugIdx = args.indexOf('--slug');
+        const fromScopeIdx = args.indexOf('--from-scope');
+        const fromIdIdx = args.indexOf('--from-id');
+        const toScopeIdx = args.indexOf('--to-scope');
+        const toIdIdx = args.indexOf('--to-id');
+        docs.cmdDocsMove(cwd,
+          slugIdx !== -1 ? args[slugIdx + 1] : null,
+          fromScopeIdx !== -1 ? args[fromScopeIdx + 1] : null,
+          fromIdIdx !== -1 ? args[fromIdIdx + 1] : null,
+          toScopeIdx !== -1 ? args[toScopeIdx + 1] : null,
+          toIdIdx !== -1 ? args[toIdIdx + 1] : null,
+          raw
+        );
+      } else if (subcommand === 'check-duplicate') {
+        const scopeIdx = args.indexOf('--scope');
+        const scopeIdIdx = args.indexOf('--scope-id');
+        const slugIdx = args.indexOf('--slug');
+        const scope = scopeIdx !== -1 ? args[scopeIdx + 1] : null;
+        const scopeId = scopeIdIdx !== -1 ? args[scopeIdIdx + 1] : null;
+        const slug = slugIdx !== -1 ? args[slugIdx + 1] : null;
+        if (!scope || !slug) {
+          error('scope and slug required for docs check-duplicate');
+        }
+        const docsDir = docs.resolveDocsDir(cwd, scope, scopeId);
+        const docPath = require('path').join(docsDir, slug);
+        const exists = require('fs').existsSync(docPath);
+        const { output: out } = require('./lib/core.cjs');
+        out({ exists, path: exists ? docPath : null }, raw);
+      } else {
+        error('Unknown docs subcommand: ' + (subcommand || '(none)') + '. Available: add, list, remove, move, check-duplicate');
+      }
+      break;
+    }
+
+    case 'search': {
+      const query = args[1];
+      const ideasOnly = args.includes('--ideas-only');
+      const specsOnly = args.includes('--specs-only');
+      const docsOnly = args.includes('--docs-only');
+      const includeRejected = args.includes('--include-rejected');
+      const tagsIdx = args.indexOf('--tags');
+      const maxIdx = args.indexOf('--max-per-type');
+      search.cmdSearch(cwd, query, {
+        ideas_only: ideasOnly,
+        specs_only: specsOnly,
+        docs_only: docsOnly,
+        include_rejected: includeRejected,
+        tags: tagsIdx !== -1 ? args[tagsIdx + 1] : null,
+        max_per_type: maxIdx !== -1 ? args[maxIdx + 1] : 5,
+      }, raw);
+      break;
+    }
+
+    case 'identity': {
+      const sub = args[1];
+      if (sub === 'resolve') {
+        cmdIdentityResolve(cwd, raw);
+      } else {
+        error('Unknown identity command: ' + sub);
+      }
+      break;
+    }
+
+    case 'merge-conflicts': {
+      const subcommand = args[1];
+      const phaseDirIdx = args.indexOf('--phase-dir');
+      const phaseDir = phaseDirIdx !== -1 ? args[phaseDirIdx + 1] : null;
+
+      if (subcommand === 'detect') {
+        mergeConflicts.cmdMergeConflictsDetect(cwd, phaseDir, raw);
+      } else if (subcommand === 'context') {
+        const file = args[2];
+        if (!file) error('File path required. Usage: merge-conflicts context <file> [--phase-dir <dir>]');
+        mergeConflicts.cmdMergeConflictsContext(cwd, file, phaseDir, raw);
+      } else if (subcommand === 'resolved') {
+        gateIdentity();
+        const file = args[2];
+        if (!file) error('File path required. Usage: merge-conflicts resolved <file> --phase-dir <dir> --resolution \'{"strategy":"..."}\'');
+        if (!phaseDir) error('--phase-dir required for resolved command');
+        const resIdx = args.indexOf('--resolution');
+        const resolution = resIdx !== -1 ? args[resIdx + 1] : null;
+        if (!resolution) error('--resolution required. Pass JSON: --resolution \'{"strategy":"ours","description":"...","confidence":"HIGH"}\'');
+        mergeConflicts.cmdMergeConflictsResolved(cwd, file, phaseDir, resolution, raw);
+      } else if (subcommand === 'summary') {
+        if (!phaseDir) error('--phase-dir required for summary command');
+        mergeConflicts.cmdMergeConflictsSummary(cwd, phaseDir, raw);
+      } else {
+        error('Unknown merge-conflicts subcommand: ' + (subcommand || '(none)') + '. Available: detect, context, resolved, summary');
+      }
+      break;
+    }
+
+    case 'conflict-agent': {
+      const subcommand = args[1];
+      gateIdentity();
+      const phaseDirIdx = args.indexOf('--phase-dir');
+      const phaseDir = phaseDirIdx !== -1 ? args[phaseDirIdx + 1] : null;
+      const learningsIdx = args.indexOf('--learnings');
+      const learningsFile = learningsIdx !== -1 ? args[learningsIdx + 1] : null;
+      const hintIdx = args.indexOf('--hint');
+      const hint = hintIdx !== -1 ? args[hintIdx + 1] : null;
+
+      if (subcommand === 'run') {
+        if (!phaseDir) error('--phase-dir required for conflict-agent run');
+        conflictAgent.cmdConflictAgentRun(cwd, phaseDir, raw, learningsFile);
+      } else if (subcommand === 'resolve-file') {
+        const file = args[2];
+        if (!file) error('File path required. Usage: conflict-agent resolve-file <file> --phase-dir <dir> [--hint <text>]');
+        if (!phaseDir) error('--phase-dir required for resolve-file command');
+        conflictAgent.cmdConflictAgentResolveFile(cwd, file, phaseDir, raw, hint);
+      } else {
+        error('Unknown conflict-agent subcommand: ' + (subcommand || '(none)') + '. Available: run, resolve-file');
+      }
+      break;
+    }
+
+    case 'jobs': {
+      const subcommand = args[1];
+      if (subcommand === 'parse') {
+        if (!args[2]) error('Usage: jobs parse <file>');
+        jobs.cmdJobsParse(cwd, args[2], raw);
+      } else if (subcommand === 'update-step') {
+        if (!args[2] || args[3] === undefined || !args[4]) {
+          error('Usage: jobs update-step <file> <step-index> <status> [--timestamp <ts>] [--error "msg"]');
+        }
+        const timestampIdx = args.indexOf('--timestamp');
+        const errorIdx = args.indexOf('--error');
+        const timestampVal = timestampIdx !== -1 ? args[timestampIdx + 1] : undefined;
+        const errorVal = errorIdx !== -1 ? args[errorIdx + 1] : undefined;
+        jobs.cmdJobsUpdateStep(cwd, args[2], args[3], args[4], { timestamp: timestampVal, error: errorVal }, raw);
+      } else if (subcommand === 'move') {
+        if (!args[2] || !args[3]) error('Usage: jobs move <file> <target-dir>');
+        jobs.cmdJobsMove(cwd, args[2], args[3], raw);
+      } else if (subcommand === 'create-milestone') {
+        const noCheckIdx = args.indexOf('--no-check');
+        const check = noCheckIdx === -1;
+        // Version is the first positional arg after subcommand that doesn't start with --
+        let version = null;
+        for (let i = 2; i < args.length; i++) {
+          if (!args[i].startsWith('--')) { version = args[i]; break; }
+        }
+        try {
+          const result = jobs.cmdJobsCreateMilestone(cwd, version, check, raw);
+          const { output: out } = require('./lib/core.cjs');
+          out(result, raw);
+        } catch (err) {
+          error(err.message);
+        }
+      } else if (subcommand === 'milestone-preview') {
+        const noCheckIdx = args.indexOf('--no-check');
+        const check = noCheckIdx === -1;
+        let version = null;
+        for (let i = 2; i < args.length; i++) {
+          if (!args[i].startsWith('--')) { version = args[i]; break; }
+        }
+        try {
+          const result = jobs.cmdJobsMilestonePreview(cwd, version, check, raw);
+          const { output: out } = require('./lib/core.cjs');
+          out(result, raw);
+        } catch (err) {
+          error(err.message);
+        }
+      } else if (subcommand === 'find-job') {
+        if (!args[2]) error('Usage: jobs find-job <version>');
+        jobs.cmdJobsFindJob(cwd, args[2], raw);
+      } else if (subcommand === 'update-header') {
+        if (!args[2] || !args[3] || !args[4]) {
+          error('Usage: jobs update-header <file> <field> <value>');
+        }
+        jobs.cmdJobsUpdateHeader(cwd, args[2], args[3], args[4], raw);
+      } else if (subcommand === 'insert-steps') {
+        if (!args[2] || args[3] === undefined || !args[4]) {
+          error('Usage: jobs insert-steps <file> <after-index> <steps-json>');
+        }
+        jobs.cmdJobsInsertSteps(cwd, args[2], args[3], args[4], raw);
+      } else if (subcommand === 'insert-gap-fix-section') {
+        if (!args[2] || args[3] === undefined || args[4] === undefined || !args[5] || !args[6]) {
+          error('Usage: jobs insert-gap-fix-section <file> <after-index> <cycle> <version> <phases-json>');
+        }
+        jobs.cmdJobsInsertGapFixSection(cwd, args[2], args[3], args[4], args[5], args[6], raw);
+      } else if (subcommand === 'insert-phase-gap-fix') {
+        if (!args[2] || args[3] === undefined || args[4] === undefined || !args[5]) {
+          error('Usage: jobs insert-phase-gap-fix <file> <after-index> <cycle> <phase-number>');
+        }
+        jobs.cmdJobsInsertPhaseGapFix(cwd, args[2], args[3], args[4], args[5], raw);
+      } else if (subcommand === 'list-jobs') {
+        jobs.cmdJobsListJobs(cwd, raw);
+      } else if (subcommand === 'cancel-job') {
+        if (!args[2]) error('Usage: jobs cancel-job <version>');
+        jobs.cmdJobsCancelJob(cwd, args[2], raw);
+      } else if (subcommand === 'health') {
+        jobs.cmdJobsHealthCheck(cwd, raw);
+      } else if (subcommand === 'dry-run') {
+        if (!args[2]) error('Usage: jobs dry-run <version>');
+        jobs.cmdJobsDryRun(cwd, args[2], raw);
+      } else if (subcommand === 'generate-summary') {
+        if (!args[2]) error('Usage: jobs generate-summary <version>');
+        jobs.cmdJobsGenerateSummary(cwd, args[2], raw);
+      } else if (subcommand === 'record-start-shas') {
+        if (!args[2]) error('Usage: jobs record-start-shas <file>');
+        jobs.cmdJobsRecordStartShas(cwd, args[2], raw);
+      } else if (subcommand === 'rollback') {
+        if (!args[2]) error('Usage: jobs rollback <version>');
+        jobs.cmdJobsRollback(cwd, args[2], raw);
+      } else {
+        error('Unknown jobs subcommand: ' + (subcommand || '(none)') + '. Available: parse, update-step, move, find-job, update-header, insert-steps, insert-gap-fix-section, insert-phase-gap-fix, create-milestone, milestone-preview, list-jobs, cancel-job, health, dry-run, generate-summary, record-start-shas, rollback');
+      }
+      break;
+    }
+
+    case 'auto-test': {
+      const subCmd = args[1];
+      const autoTest = require('./lib/auto-test.cjs');
+      const cwdFlagIdx = args.indexOf('--cwd');
+      const testCwd = cwdFlagIdx !== -1 ? args[cwdFlagIdx + 1] : undefined;
+      switch (subCmd) {
+        case 'collect':
+          autoTest.cmdCollectTestCommands(cwd, args[2], raw);
+          break;
+        case 'run': {
+          const timeoutIdx = args.indexOf('--timeout');
+          const timeout_ms = timeoutIdx !== -1 ? parseInt(args[timeoutIdx + 1], 10) : undefined;
+          autoTest.cmdRunTestSuite(cwd, args[2], raw, { timeout_ms, testCwd });
+          break;
+        }
+        case 'map': {
+          const timeoutIdx = args.indexOf('--timeout');
+          const timeout_ms = timeoutIdx !== -1 ? parseInt(args[timeoutIdx + 1], 10) : undefined;
+          autoTest.cmdMapResults(cwd, args[2], raw, { timeout_ms, testCwd });
+          break;
+        }
+        case 'check-diagnosis':
+          autoTest.cmdCheckDiagnosis(cwd, args[2], raw);
+          break;
+        case 'rerun':
+          autoTest.cmdRerunFailed(cwd, args[2], raw, { testCwd });
+          break;
+        default:
+          error(`Unknown auto-test command: ${subCmd}. Available: collect, run, map, check-diagnosis, rerun`);
+      }
+      break;
+    }
+
+    case 'phase-uat-status': {
+      const autoTest = require('./lib/auto-test.cjs');
+      autoTest.cmdPhaseUatStatus(cwd, args[1], raw);
+      break;
+    }
+
+    case 'context': {
+      const context = require('./lib/context.cjs');
+      const subCmd = args[1];
+      if (subCmd === 'load-tier') {
+        if (!args[2]) error('Usage: context load-tier <tier-name> [--phase N] [--idea N] [--spec N]');
+        context.cmdContextLoadTier(cwd, args[2], args.slice(3), raw);
+      } else {
+        error('Unknown context command: ' + (subCmd || '(none)') + '. Available: load-tier');
+      }
+      break;
+    }
+
+    default:
+      error(`Unknown command: ${command}`);
+  }
+}
+
+main();