@ktpartners/dgs-platform 2.9.0 → 3.3.0

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

@@ -14,6 +14,7 @@
  *   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
+ *   state mark-milestone-complete      Mark milestone complete in STATE.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
@@ -29,6 +30,7 @@
  *   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
+ *   package-scan [--raw]               Scan all repos for dependency vulnerabilities; writes committed report
  *   websearch <query>                  Search web via Brave API (if configured)
  *     [--limit N] [--freshness day|week|month]
  *
@@ -38,6 +40,13 @@
  *   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
+ *   phase finalize <phase>             Mark phase done + commit tracking files + VERIFICATION.md atomically
+ *     [--push]                         Push after commit (respects sync_push config)
+ *
+ * Plan Operations:
+ *   plan finalize <phase> <plan>       Update state/roadmap/requirements + commit PLAN+SUMMARY+tracking atomically
+ *     [--push]                         Push after commit
+ *     [--plan-name <name>]             Override plan name in commit message
  *
  * Roadmap Operations:
  *   roadmap get-phase <phase>          Extract phase section from ROADMAP.md
@@ -62,6 +71,8 @@
  *
  * Todos:
  *   todo complete <filename>           Move todo from pending to completed
+ *   todo set-status <filename>         Set todo status (frontmatter)
+ *     --status <pending|done>
  *
  * Scaffolding:
  *   scaffold context --phase <N>       Create CONTEXT.md template
@@ -72,6 +83,7 @@
  *
  * Migration:
  *   migrate --layout root              Migrate .planning/ to root layout
+ *   migrate --layout flat [--apply]    Migrate to flat status directories
  *     [--dry-run]                       Show what would change without modifying
  *     [--raw]                           JSON output for scripting
  *
@@ -182,6 +194,18 @@
  *   sync workflow-push <workflow>      Workflow-level push check/execute
  *     [--check-only] [--mid-workflow] [--record-yes]
  *
+ * Worktrees:
+ *   worktrees create <slug>            Create worktrees for project repos
+ *     --type milestone|quick
+ *     [--mode full|debug]
+ *     [--repo <name>]
+ *   worktrees remove <slug>            Remove worktree and clean up
+ *   worktrees list                     List tracked worktrees (JSON)
+ *   worktrees setup <slug>             Re-run setup command for worktree
+ *   worktrees prune                    Remove orphaned worktree entries
+ *   worktrees rebase-and-merge <slug> --repo <name>  Rebase and merge worktree branch
+ *   worktrees health <slug>            Check worktree health
+ *
  * Ideas Operations:
  *   ideas create --title T --body B     Create new idea with auto-assigned ID
  *     [--tags "t1,t2"]
@@ -193,6 +217,7 @@
  *   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 set-status --id N --status S  Set idea status (frontmatter)
  *   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
@@ -237,6 +262,8 @@
  *     [--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
+ *   jobs set-status <version>         Set job status (frontmatter + header)
+ *     --status <pending|in-progress|completed|failed|rolled_back>
  *
  * Search Operations:
  *   search <query> [--flags]          Search across ideas, specs, docs, projects
@@ -257,6 +284,7 @@
  *   init milestone-op                  All context for milestone operations
  *   init map-codebase                  All context for map-codebase workflow
  *   init progress                      All context for progress workflow
+ *   init progress-all                  Product-level dashboard across all active projects
  */
 
 const { error, loadConfig } = require('./lib/core.cjs');
@@ -283,7 +311,7 @@ const mergeConflicts = require('./lib/merge-conflicts.cjs');
 const conflictAgent = require('./lib/conflict-agent.cjs');
 const { requireGitIdentity, formatAuthorString, cmdIdentityResolve } = require('./lib/identity.cjs');
 const { pullAll, pushAll, getCadence, checkStaleState, shouldShowFirstRunHint, markFirstRunHintShown, isWithinSuppressionWindow, recordPromptYes } = require('./lib/sync.cjs');
-const { migrateDotPlanningToRoot, rejectV1Install } = require('./lib/migration.cjs');
+const { migrateDotPlanningToRoot, rejectV1Install, migrateBranchingConfig, migrateFlatStatus } = require('./lib/migration.cjs');
 
 // ─── Identity Gate ────────────────────────────────────────────────────────────
 
@@ -593,6 +621,23 @@ async function main() {
     // fails for unexpected reasons (defensive, should not normally trigger).
   }
 
+  // Run lazy branching config migration (best-effort, non-blocking)
+  try {
+    migrateBranchingConfig(cwd);
+  } catch (e) {
+    process.stderr.write('Warning: Migration check failed: ' + (e.message || String(e)) + '\n');
+  }
+
+  // Run flat status migration auto-detect (best-effort, non-blocking)
+  // Same pattern as branching config: detect legacy layout, log if found, apply on explicit command
+  if (command !== 'migrate') try {
+    const flatResult = migrateFlatStatus(cwd);
+    // In auto-detect mode (dryRun=true by default), just check if migration is needed
+    if (flatResult.dryRun && flatResult.actions.length > 0) {
+      process.stderr.write('[DGS] Legacy directory-based state detected (' + flatResult.filesMoved + ' file(s) to migrate). Run: dgs-tools migrate --layout flat --apply\n');
+    }
+  } catch { /* ignore auto-detect errors */ }
+
   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, migrate');
   }
@@ -659,6 +704,8 @@ async function main() {
         }, raw);
       } else if (subcommand === 'archive-quick-tasks') {
         state.cmdStateArchiveQuickTasks(cwd, raw);
+      } else if (subcommand === 'mark-milestone-complete') {
+        state.cmdMarkMilestoneComplete(cwd, raw);
       } else {
         state.cmdStateLoad(cwd, raw);
       }
@@ -736,10 +783,96 @@ async function main() {
       // 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, push);
+      // Parse --repo-cwd flag: runs git ops in the target dir while loading
+      // config from cwd (mirrors the --cwd flag pattern on auto-test).
+      const repoCwdIdx = args.indexOf('--repo-cwd');
+      const repoCwd = repoCwdIdx !== -1 ? args[repoCwdIdx + 1] : undefined;
+      commands.cmdCommit(cwd, message, files, raw, amend, push, repoCwd);
       break;
     }
 
+    case 'final-commit-precondition': {
+      // REL-08 (Phase 157): pre-commit precondition gate. Aborts with
+      // `summary-frontmatter-mismatch` label when PLAN.md `requirements:` is
+      // non-empty AND SUMMARY.md `requirements_completed:` is empty. Read-only —
+      // never writes to the working tree.
+      const planIdx = args.indexOf('--plan');
+      const summaryIdx = args.indexOf('--summary');
+      const opts = {
+        plan: planIdx !== -1 ? args[planIdx + 1] : undefined,
+        summary: summaryIdx !== -1 ? args[summaryIdx + 1] : undefined,
+      };
+      return commands.cmdFinalCommitPrecondition(cwd, opts);
+    }
+
+    case 'commit-verify-plan': {
+      // REL-01 (Phase 156): orchestrator-side commit + verification helper
+      // for /dgs:plan-phase. Commits a planner-emitted createdFiles list and
+      // verifies every reported path appears in HEAD; on mismatch, returns
+      // plan-commit-incomplete with working tree unchanged.
+      gateIdentity();
+      const message = args[1];
+      // --files <paths...> (collect args after --files until next --flag)
+      const filesIndex = args.indexOf('--files');
+      const createdFiles = filesIndex !== -1
+        ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--'))
+        : [];
+      // --extra-files <paths...> (e.g. ROADMAP.md)
+      const extraIdx = args.indexOf('--extra-files');
+      const extraFiles = extraIdx !== -1
+        ? args.slice(extraIdx + 1).filter(a => !a.startsWith('--'))
+        : [];
+      // --repo-cwd <path>
+      const repoCwdIdxV = args.indexOf('--repo-cwd');
+      const repoCwdV = repoCwdIdxV !== -1 ? args[repoCwdIdxV + 1] : undefined;
+      const pushV = args.includes('--push');
+      const result = commands.verifyPlanCommit(cwd, {
+        message,
+        createdFiles,
+        extraFiles,
+        repoCwd: repoCwdV,
+        push: pushV,
+      }, raw);
+      // verifyPlanCommit is a pure helper — emit output and exit non-zero
+      // on plan-commit-incomplete so the calling workflow can detect failure.
+      if (raw) {
+        process.stdout.write(JSON.stringify(result));
+      } else {
+        if (result.ok) {
+          process.stdout.write(result.hash || result.reason || 'ok');
+        } else {
+          process.stdout.write(`[${result.exitLabel}] ${result.reason}`);
+        }
+      }
+      process.exit(result.ok ? 0 : 1);
+    }
+
+    case 'compute-phase-sweep': {
+      // REL-02 (Phase 156): scope-bounded executor sweep helper.
+      // Returns the UNION of git-discovered phase-dir paths and the
+      // executor-reported modified_files list, scope-filtered to
+      // ${phasesDir}/${phaseDir}/ only.
+      const phasesDirIdx = args.indexOf('--phases-dir');
+      const phaseDirIdx = args.indexOf('--phase-dir');
+      const modifiedIdx = args.indexOf('--modified-files');
+      const phasesDirV = phasesDirIdx !== -1 ? args[phasesDirIdx + 1] : undefined;
+      const phaseDirV = phaseDirIdx !== -1 ? args[phaseDirIdx + 1] : undefined;
+      const modifiedFiles = modifiedIdx !== -1
+        ? args.slice(modifiedIdx + 1).filter(a => !a.startsWith('--'))
+        : [];
+      const result = commands.computePhaseSweep(cwd, {
+        phasesDir: phasesDirV,
+        phaseDir: phaseDirV,
+        modifiedFiles,
+      }, raw);
+      if (raw) {
+        process.stdout.write(JSON.stringify(result));
+      } else {
+        process.stdout.write(`Swept: ${result.swept.length} | Dropped: ${result.dropped.length}`);
+      }
+      process.exit(result.error ? 1 : 0);
+    }
+
     case 'verify-summary': {
       const summaryPath = args[1];
       const countIndex = args.indexOf('--check-count');
@@ -856,6 +989,11 @@ async function main() {
       break;
     }
 
+    case 'config-local-set': {
+      config.cmdConfigLocalSet(cwd, args[1], args[2], raw);
+      break;
+    }
+
     case 'config-get': {
       config.cmdConfigGet(cwd, args[1], raw);
       break;
@@ -1025,7 +1163,7 @@ async function main() {
     case 'phase': {
       const subcommand = args[1];
       // Gate write subcommands
-      if (subcommand === 'add' || subcommand === 'insert' || subcommand === 'remove' || subcommand === 'complete') {
+      if (subcommand === 'add' || subcommand === 'insert' || subcommand === 'remove' || subcommand === 'complete' || subcommand === 'finalize') {
         gateIdentity();
       }
       if (subcommand === 'next-decimal') {
@@ -1039,8 +1177,25 @@ async function main() {
         phase.cmdPhaseRemove(cwd, args[2], { force: forceFlag }, raw);
       } else if (subcommand === 'complete') {
         phase.cmdPhaseComplete(cwd, args[2], raw);
+      } else if (subcommand === 'finalize') {
+        const push = args.includes('--push');
+        phase.cmdPhaseFinalize(cwd, args[2], { push }, raw);
       } else {
-        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete');
+        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete, finalize');
+      }
+      break;
+    }
+
+    case 'plan': {
+      const subcommand = args[1];
+      if (subcommand === 'finalize') {
+        gateIdentity();
+        const push = args.includes('--push');
+        const planNameIdx = args.indexOf('--plan-name');
+        const planName = planNameIdx !== -1 ? args[planNameIdx + 1] : null;
+        commands.cmdPlanFinalize(cwd, args[2], args[3], { push, planName }, raw);
+      } else {
+        error('Unknown plan subcommand. Available: finalize');
       }
       break;
     }
@@ -1051,6 +1206,7 @@ async function main() {
       if (subcommand === 'complete') {
         const nameIndex = args.indexOf('--name');
         const archivePhases = args.includes('--archive-phases');
+        const force = args.includes('--force');
         // Collect --name value (everything after --name until next flag or end)
         let milestoneName = null;
         if (nameIndex !== -1) {
@@ -1061,7 +1217,7 @@ async function main() {
           }
           milestoneName = nameArgs.join(' ') || null;
         }
-        milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases }, raw);
+        milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases, force }, raw);
       } else {
         error('Unknown milestone subcommand. Available: complete');
       }
@@ -1090,13 +1246,28 @@ async function main() {
     case 'todo': {
       const subcommand = args[1];
       // Gate write subcommand
-      if (subcommand === 'complete') {
+      if (subcommand === 'complete' || subcommand === 'set-status') {
         gateIdentity();
       }
       if (subcommand === 'complete') {
         commands.cmdTodoComplete(cwd, args[2], raw);
+      } else if (subcommand === 'set-status') {
+        const filename = args[2];
+        const statusIdx = args.indexOf('--status');
+        const status = statusIdx !== -1 ? args[statusIdx + 1] : null;
+        if (!filename || !status) {
+          error('Usage: todo set-status <filename> --status <pending|done>');
+        }
+        const { setTodoStatus } = require('./lib/commands.cjs');
+        try {
+          const result = setTodoStatus(cwd, filename, status);
+          const { output: out } = require('./lib/core.cjs');
+          out(result, raw);
+        } catch (err) {
+          error(err.message);
+        }
       } else {
-        error('Unknown todo subcommand. Available: complete');
+        error('Unknown todo subcommand. Available: complete, set-status');
       }
       break;
     }
@@ -1124,7 +1295,7 @@ async function main() {
           init.cmdInitPlanPhase(cwd, args[2], raw);
           break;
         case 'new-project':
-          init.cmdInitNewProject(cwd, raw);
+          init.cmdInitNewProject(cwd, args[2], raw);
           break;
         case 'new-milestone':
           init.cmdInitNewMilestone(cwd, raw);
@@ -1168,8 +1339,11 @@ async function main() {
         case 'progress':
           init.cmdInitProgress(cwd, raw);
           break;
+        case 'progress-all':
+          init.cmdInitProgressAll(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`);
+          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, progress-all`);
       }
       break;
     }
@@ -1328,8 +1502,18 @@ async function main() {
           raw,
           author
         );
+      } else if (subcommand === 'set-status') {
+        // Alias for move-state (frontmatter-based)
+        const idIdx = args.indexOf('--id');
+        const statusIdx = args.indexOf('--status');
+        const id = idIdx !== -1 ? args[idIdx + 1] : null;
+        const status = statusIdx !== -1 ? args[statusIdx + 1] : null;
+        if (!id || !status) {
+          error('Usage: ideas set-status --id <N> --status <pending|done|rejected|consolidated>');
+        }
+        ideas.cmdIdeasMoveState(cwd, id, status, raw, author);
       } else {
-        error('Unknown ideas subcommand: ' + subcommand);
+        error('Unknown ideas subcommand: ' + (subcommand || '(none)') + '. Available: create, list, update, append-note, discuss-save, research-save, consolidate, find-related, undo-consolidation, move-state, set-status, reject, restore');
       }
       break;
     }
@@ -1597,6 +1781,7 @@ async function main() {
         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>');
+        process.stderr.write('[DGS] Deprecation: "jobs move" is deprecated. Use "jobs set-status <version> --status <status>" for state transitions.\n');
         jobs.cmdJobsMove(cwd, args[2], args[3], raw);
       } else if (subcommand === 'create-milestone') {
         const noCheckIdx = args.indexOf('--no-check');
@@ -1669,8 +1854,28 @@ async function main() {
       } else if (subcommand === 'rollback') {
         if (!args[2]) error('Usage: jobs rollback <version>');
         jobs.cmdJobsRollback(cwd, args[2], raw);
+      } else if (subcommand === 'generate-review') {
+        const review = require('./lib/review.cjs');
+        const detailed = args.includes('--detailed');
+        const versionArg = args.slice(2).filter(a => a !== '--detailed' && a !== '--raw')[0];
+        review.cmdJobsGenerateReview(cwd, versionArg, raw, detailed);
+      } else if (subcommand === 'set-status') {
+        const version = args[2];
+        const statusIdx = args.indexOf('--status');
+        const status = statusIdx !== -1 ? args[statusIdx + 1] : null;
+        if (!version || !status) {
+          error('Usage: jobs set-status <version> --status <pending|in-progress|completed|failed|rolled_back>');
+        }
+        const { setJobStatus } = require('./lib/jobs.cjs');
+        try {
+          const result = setJobStatus(cwd, version, status);
+          const { output: out } = require('./lib/core.cjs');
+          out(result, raw);
+        } catch (err) {
+          error(err.message);
+        }
       } 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');
+        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, generate-review, record-start-shas, rollback, set-status');
       }
       break;
     }
@@ -1708,6 +1913,12 @@ async function main() {
       break;
     }
 
+    case 'package-scan': {
+      const packageScan = require('./lib/package-scan.cjs');
+      packageScan.cmdPackageScan(cwd, args, raw);
+      break;
+    }
+
     case 'phase-uat-status': {
       const autoTest = require('./lib/auto-test.cjs');
       autoTest.cmdPhaseUatStatus(cwd, args[1], raw);
@@ -1747,38 +1958,196 @@ async function main() {
       break;
     }
 
+    case 'worktrees': {
+      const subcommand = args[1];
+      const worktrees = require('./lib/worktrees.cjs');
+      const { output: wtOutput } = require('./lib/core.cjs');
+      if (subcommand === 'create') {
+        worktrees.cmdWorktreesCreate(cwd, args.slice(2));
+      } else if (subcommand === 'remove') {
+        worktrees.cmdWorktreesRemove(cwd, args.slice(2));
+      } else if (subcommand === 'list') {
+        worktrees.cmdWorktreesList(cwd, args.slice(2));
+      } else if (subcommand === 'setup') {
+        worktrees.cmdWorktreesSetup(cwd, args.slice(2));
+      } else if (subcommand === 'prune') {
+        worktrees.cmdWorktreesPrune(cwd, args.slice(2));
+      } else if (subcommand === 'rebase-and-merge') {
+        const slug = args[2];
+        if (!slug) error('Usage: worktrees rebase-and-merge <slug> --repo <name>');
+        const repoIdx = args.indexOf('--repo');
+        const repoName = repoIdx !== -1 ? args[repoIdx + 1] : null;
+        if (!repoName) error('--repo required for rebase-and-merge');
+        const noPush = args.includes('--no-push');
+        const result = worktrees.rebaseAndMerge(cwd, repoName, slug, { push: !noPush });
+        wtOutput(result);
+      } else if (subcommand === 'health') {
+        const slug = args[2];
+        if (!slug) error('Usage: worktrees health <slug>');
+        const result = worktrees.checkWorktreeHealth(cwd, slug);
+        wtOutput(result);
+      } else {
+        error('Unknown worktrees subcommand: ' + subcommand + '. Available: create, remove, list, setup, prune, rebase-and-merge, health');
+      }
+      break;
+    }
+
     case 'migrate': {
       const layoutIdx = args.indexOf('--layout');
       const layout = layoutIdx !== -1 ? args[layoutIdx + 1] : null;
-      if (layout !== 'root') {
-        error('Usage: dgs-tools migrate --layout root [--dry-run] [--raw]');
-      }
-      const dryRun = args.includes('--dry-run');
-      const result = migrateDotPlanningToRoot(cwd, { dryRun });
-      if (raw) {
-        const { output: out } = require('./lib/core.cjs');
-        out(result, raw);
-      } else if (result.dryRun) {
-        if (result.actions.length === 0) {
-          process.stderr.write('Nothing to migrate. Already in root layout.\n');
+
+      if (layout === 'root') {
+        // Existing .planning/ to root migration
+        const dryRun = args.includes('--dry-run');
+        const result = migrateDotPlanningToRoot(cwd, { dryRun });
+        if (raw) {
+          const { output: out } = require('./lib/core.cjs');
+          out(result, raw);
+        } else if (result.dryRun) {
+          if (result.actions.length === 0) {
+            process.stderr.write('Nothing to migrate. Already in root layout.\n');
+          } else {
+            process.stderr.write('Dry run — the following changes would be made:\n');
+            for (const action of result.actions) {
+              const label = action.type === 'identical' ? '(identical, delete .planning copy)' : '';
+              process.stderr.write(`  ${action.from} -> ${action.to} ${label}\n`);
+            }
+            process.stderr.write(`\n${result.filesMoved} file(s) to move, ${result.identicalResolved} identical conflict(s) to resolve.\n`);
+          }
+        } else if (result.migrated) {
+          process.stderr.write(`Migration complete. ${result.filesMoved} file(s) moved.`);
+          if (result.commitHash) process.stderr.write(` Commit: ${result.commitHash}`);
+          process.stderr.write('\n');
         } else {
-          process.stderr.write('Dry run — the following changes would be made:\n');
-          for (const action of result.actions) {
-            const label = action.type === 'identical' ? '(identical, delete .planning copy)' : '';
-            process.stderr.write(`  ${action.from} -> ${action.to} ${label}\n`);
+          process.stderr.write('Nothing to migrate. Already in root layout.\n');
+        }
+      } else if (layout === 'flat') {
+        // Flat status migration (v20.0)
+        const apply = args.includes('--apply');
+        const result = migrateFlatStatus(cwd, { apply });
+        if (raw) {
+          const { output: out } = require('./lib/core.cjs');
+          out(result, raw);
+        } else if (!apply) {
+          // Dry-run mode (default)
+          if (result.actions.length === 0) {
+            process.stderr.write('Nothing to migrate. All files already in flat layout (or migration already done).\n');
+          } else {
+            process.stderr.write('Dry run — the following changes would be made:\n\n');
+            // Group by subsystem
+            const grouped = {};
+            for (const action of result.actions) {
+              const key = action.subsystem || 'research';
+              if (!grouped[key]) grouped[key] = [];
+              grouped[key].push(action);
+            }
+            for (const [sub, subActions] of Object.entries(grouped)) {
+              process.stderr.write(`  ${sub}:\n`);
+              for (const action of subActions) {
+                const statusNote = action.mappedStatus ? ` (status: ${action.mappedStatus})` : '';
+                process.stderr.write(`    ${action.from} -> ${action.to}${statusNote}\n`);
+              }
+            }
+            process.stderr.write(`\n${result.filesMoved} file(s) to move, ${result.statusFieldsAdded} status field(s) to add.\n`);
+            process.stderr.write('\nTo apply: dgs-tools migrate --layout flat --apply\n');
           }
-          process.stderr.write(`\n${result.filesMoved} file(s) to move, ${result.identicalResolved} identical conflict(s) to resolve.\n`);
+        } else if (result.migrated) {
+          process.stderr.write(`Flat status migration complete. ${result.filesMoved} file(s) moved, ${result.statusFieldsAdded} status field(s) added, ${result.pathsNormalized} path(s) normalized.`);
+          if (result.commitHash) process.stderr.write(` Commit: ${result.commitHash}`);
+          process.stderr.write('\n');
+        } else {
+          process.stderr.write('Nothing to migrate. All files already in flat layout (or migration already done).\n');
         }
-      } else if (result.migrated) {
-        process.stderr.write(`Migration complete. ${result.filesMoved} file(s) moved.`);
-        if (result.commitHash) process.stderr.write(` Commit: ${result.commitHash}`);
-        process.stderr.write('\n');
       } else {
-        process.stderr.write('Nothing to migrate. Already in root layout.\n');
+        error('Usage: dgs-tools migrate --layout root|flat [--dry-run] [--apply] [--raw]');
       }
       break;
     }
 
+    case 'complete-quick':
+    case 'quick-complete': {
+      const { cmdQuickComplete } = require('./lib/quick.cjs');
+      cmdQuickComplete(cwd, args);
+      break;
+    }
+
+    case 'abandon-quick':
+    case 'quick-abandon': {
+      const { cmdQuickAbandon } = require('./lib/quick.cjs');
+      cmdQuickAbandon(cwd, args.slice(1));
+      break;
+    }
+
+    case 'quick': {
+      const subcommand = args[1];
+      if (subcommand === 'generate-review') {
+        const review = require('./lib/review.cjs');
+        const detailed = args.includes('--detailed');
+        const slugArg = args.slice(2).filter(a => a !== '--detailed' && a !== '--raw')[0];
+        review.cmdQuickGenerateReview(cwd, slugArg, raw, detailed);
+        break;
+      }
+      if (subcommand !== 'finalize') {
+        error('Usage: dgs-tools quick <generate-review [slug]|finalize <quick_id> [options]>');
+        return;
+      }
+      gateIdentity();
+      const quickId = args[2];
+      if (!quickId) {
+        error('quick_id required');
+        return;
+      }
+
+      // Parse flags starting at args[3]
+      let description = null;
+      let quickDir = null;
+      let statePath = null;
+      let push = false;
+      let repoCwd = null;
+      let fast = false;
+
+      for (let i = 3; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--description') {
+          // Multi-word: consume args until next --flag or end
+          const parts = [];
+          let j = i + 1;
+          while (j < args.length && !args[j].startsWith('--')) {
+            parts.push(args[j]);
+            j++;
+          }
+          description = parts.join(' ');
+          i = j - 1;
+        } else if (a === '--quick-dir') {
+          quickDir = args[++i];
+        } else if (a === '--state-path') {
+          statePath = args[++i];
+        } else if (a === '--push') {
+          push = true;
+        } else if (a === '--repo-cwd') {
+          repoCwd = args[++i];
+        } else if (a === '--fast') {
+          fast = true;
+        }
+      }
+
+      const { cmdQuickFinalize } = require('./lib/quick.cjs');
+      cmdQuickFinalize(cwd, quickId, { description, quickDir, statePath, push, repoCwd, fast }, raw);
+      break;
+    }
+
+    case 'fast-route': {
+      // REL-05/06: fast-mode commit routing helper. Surveys planning root +
+      // registered sub-repos for dirty state, then computes a routing decision.
+      // Used by /dgs:fast workflow F0.5 (pre-edit dirt check, REL-06) and F4/F5
+      // (post-edit routing, REL-05). Exits 1 if action == 'fail'.
+      const { surveyDirty, decideRouting } = require('./lib/fast-routing.cjs');
+      const survey = surveyDirty(cwd);
+      const decision = decideRouting(survey);
+      process.stdout.write(JSON.stringify({ survey, decision }, null, 2));
+      process.exit(decision.action === 'fail' ? 1 : 0);
+    }
+
     default:
       error(`Unknown command: ${command}`);
   }