@jokerized/getresearchdone 0.4.1

package/dist/bin/grd-tools.js

@@ -0,0 +1,1680 @@
+#!/usr/bin/env node
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * GRD Tools -- Thin CLI router. All business logic lives in lib/ modules.
+ * Usage: node grd-tools.js <command> [args] [--raw]
+ */
+const fs = require('fs');
+const path = require('path');
+// ─── Typed Imports ──────────────────────────────────────────────────────────
+const { parseIncludeFlag, output, error, loadConfig, validatePhaseArg, validateFileArg, validateSubcommand, validateGitRef, findClosestCommand, } = require('../lib/utils');
+const { cmdFrontmatterGet, cmdFrontmatterSet, cmdFrontmatterMerge, cmdFrontmatterValidate, } = require('../lib/frontmatter');
+const { cmdStateLoad, cmdStateGet, cmdStatePatch, cmdStateUpdate, cmdStateAdvancePlan, cmdStateRecordMetric, cmdStateUpdateProgress, cmdStateAddDecision, cmdStateAddBlocker, cmdStateResolveBlocker, cmdStateRecordSession, cmdStateSnapshot, } = require('../lib/state');
+const { cmdRoadmapGetPhase, cmdPhaseNextDecimal, cmdRoadmapAnalyze, } = require('../lib/roadmap');
+const { cmdTemplateSelect, cmdTemplateFill, cmdScaffold, } = require('../lib/scaffold');
+const { cmdVerifySummary, cmdVerifyPlanStructure, cmdVerifyPhaseCompleteness, cmdVerifyReferences, cmdVerifyCommits, cmdVerifyArtifacts, cmdVerifyKeyLinks, cmdVerifyMechanical, } = require('../lib/verify');
+const { cmdPhasesList, cmdPhaseAdd, cmdPhaseInsert, cmdPhaseRemove, cmdPhaseComplete, cmdMilestoneComplete, cmdValidateConsistency, cmdVersionBump, } = require('../lib/phase');
+const { cmdTracker, } = require('../lib/tracker');
+const { cmdWorktreeCreate, cmdWorktreeRemove, cmdWorktreeList, cmdWorktreeRemoveStale, cmdWorktreePushAndPR, cmdWorktreeEnsureMilestoneBranch, cmdWorktreeMerge, cmdWorktreeHookCreate, cmdWorktreeHookRemove, cmdTeammateIdleHook, cmdTaskCompletedHook, cmdInstructionsLoadedHook, cmdStopFailureHook, cmdPostCompactHook, } = require('../lib/worktree');
+const { cmdPhaseAnalyzeDeps, } = require('../lib/deps');
+const { detectOverstory, installOverstory, } = require('../lib/overstory');
+const { cmdAutopilot, cmdInitAutopilot, cmdMultiMilestoneAutopilot, cmdInitMultiMilestoneAutopilot, } = require('../lib/autopilot');
+const { cmdAutoplan, cmdInitAutoplan, } = require('../lib/autoplan');
+const { createScheduler, } = require('../lib/scheduler');
+const { cmdAutoResearch, cmdInitAutoResearch, } = require('../lib/autoresearch');
+const { cmdEvolve, cmdEvolveDiscover, cmdEvolveState, cmdEvolveAdvance, cmdEvolveReset, cmdInitEvolve, } = require('../lib/evolve/index');
+const { cmdInitExecuteParallel, cmdParallelProgress, } = require('../lib/parallel');
+const { cmdWireup, cmdInitWireup, } = require('../lib/wireup/index');
+const { splitMarkdown, isIndexFile, estimateTokens, } = require('../lib/markdown-split');
+const { cmdInitExecutePhase, cmdInitPlanPhase, cmdInitNewProject, cmdInitNewMilestone, cmdInitQuick, cmdInitResume, cmdInitVerifyWork, cmdInitPhaseOp, cmdInitTodos, cmdInitMilestoneOp, cmdInitMapCodebase, cmdInitProgress, cmdInitResearchWorkflow, cmdInitPlanMilestoneGaps, cmdInitDebug, cmdInitIntegrationCheck, cmdInitMigrate, cmdInitPlanCheck, cmdInitPhaseResearch, cmdInitCodeReview, cmdInitAssessBaseline, cmdInitDeepDive, cmdInitEvalPlan, cmdInitEvalReport, cmdInitFeasibility, cmdInitProductOwner, cmdInitProjectResearcher, cmdInitResearchSynthesizer, cmdInitRoadmapper, cmdInitSurveyor, cmdInitVerifier, } = require('../lib/context/index');
+const { cmdGenerateSlug, cmdCurrentTimestamp, cmdListTodos, cmdTodoComplete, cmdVerifyPathExists, cmdConfigEnsureSection, cmdConfigSet, cmdHistoryDigest, cmdResolveModel, cmdFindPhase, cmdCommit, cmdPhasePlanIndex, cmdSummaryExtract, cmdProgressRender, cmdDashboard, cmdPhaseDetail, cmdHealth, cmdDetectBackend, cmdLongTermRoadmap, cmdQualityAnalysis, cmdSetup, cmdRequirementGet, cmdRequirementList, cmdRequirementTraceability, cmdRequirementUpdateStatus, cmdSearch, cmdMigrateDirs, cmdCoverageReport, cmdHealthCheck, cmdPhaseRiskAssessment, cmdCitationBacklinks, cmdEvalRegressionCheck, cmdPhaseTimeBudget, cmdConfigDiff, cmdPhaseReadiness, cmdMilestoneHealth, cmdDecisionTimeline, cmdImportKnowledge, cmdTodoDuplicates, cmdKnowhowList, cmdCitationGraph, cmdArtifactDAG, cmdBenchmarkReport, cmdKnowhowSearch, cmdCheckPlans, cmdEvalDiff, cmdTail, cmdEstimatePhase, cmdImpact, cmdCheckAssumptions, } = require('../lib/commands/index');
+const { cmdDeadEndAdd, cmdDeadEndPromoteFromPhase, } = require('../lib/dead-ends');
+const { cmdPlanTournament, } = require('../lib/plan-tournament');
+const { cmdThink, } = require('../lib/think');
+const { cmdExportResearch, cmdImportResearch, } = require('../lib/research-bundle');
+const { cmdDiagnosePhase, } = require('../lib/verify');
+const { cmdKnowhowAudit, cmdKnowhowDedup, cmdKnowhowRank, } = require('../lib/knowledge');
+const { cmdPhaseDepsVisualize, cmdExecutePhaseDryRun, } = require('../lib/deps');
+const { cmdTodosRank, } = require('../lib/commands/todo');
+const { cmdRollback, } = require('../lib/commands/rollback');
+const { cmdEstimate, } = require('../lib/commands/estimate');
+const { cmdBudget, } = require('../lib/commands/budget');
+const { cmdBlame, } = require('../lib/commands/blame');
+const { cmdKnowhowAggregate, cmdImportKnowhow, } = require('../lib/commands/knowhow-aggregator');
+const { cmdFreshness, } = require('../lib/commands/freshness');
+const { cmdGenomeInit, cmdGenomeShow, cmdGenomeSnapshot, cmdGenomePromoteSuggestion, } = require('../lib/genome');
+const { cmdResearchGaps, } = require('../lib/commands/progress');
+const { cmdDepsRisk, } = require('../lib/commands/phase-info');
+const { cmdWatch, } = require('../lib/commands/watch');
+const { cmdSingularity, } = require('../lib/commands/singularity');
+const { cmdPlanLint, } = require('../lib/commands/plan-lint');
+const { cmdPlanPhase, } = require('../lib/commands/plan-phase');
+const { cmdSelectCandidate, } = require('../lib/commands/select-candidate');
+const { cmdPatterns, } = require('../lib/commands/patterns');
+const { cmdInstall, } = require('../lib/commands/install');
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/** Extract --flag value from args, returns value or fallback */
+function flag(args, name, fallback) {
+    const i = args.indexOf(name);
+    return i !== -1 ? args[i + 1] : fallback;
+}
+/**
+ * Print a deprecation warning to stderr. See docs/DEPRECATIONS.md for the
+ * v0.4.x trim plan. Commands listed in DEPRECATED_COMMANDS will be removed
+ * in v0.4.0; this helper fires once per invocation.
+ */
+const DEPRECATED_COMMANDS = {
+    dashboard: 'Use `gd health` + `gd think` instead',
+    'health-check': 'Subset of `gd health`',
+    'coverage-report': 'Use `npx jest --coverage` directly',
+    'phase-time-budget': 'Subsumed by `gd estimate-phase`',
+    'todo-duplicates': 'One-off helper; rarely used',
+    'markdown-split': 'Internal infrastructure — surfaced by accident',
+    setup: '`gd init` does this',
+};
+function _warnDeprecated(cmd) {
+    const replacement = DEPRECATED_COMMANDS[cmd];
+    if (!replacement)
+        return;
+    process.stderr.write(`Warning: \`gd ${cmd}\` is DEPRECATED and will be removed in v0.4.0.\n` +
+        `         ${replacement}.\n` +
+        `         See docs/DEPRECATIONS.md.\n`);
+}
+// ─── Descriptor-Based Dispatch Table ────────────────────────────────────────
+/**
+ * Descriptor-based dispatch table for simple top-level commands.
+ * Each entry maps a command string to a handler function.
+ * routeCommand() checks this table first before falling through to the switch.
+ */
+const ROUTE_DESCRIPTORS = [
+    { command: 'generate-slug', handler: (args, _cwd, raw) => cmdGenerateSlug(args[1], raw) },
+    {
+        command: 'current-timestamp',
+        handler: (args, _cwd, raw) => cmdCurrentTimestamp(args[1] || 'full', raw),
+    },
+    { command: 'list-todos', handler: (args, cwd, raw) => cmdListTodos(cwd, args[1], raw) },
+    {
+        command: 'verify-path-exists',
+        handler: (args, cwd, raw) => cmdVerifyPathExists(cwd, args[1], raw, args.includes('--dry-run')),
+    },
+    {
+        command: 'config-ensure-section',
+        handler: (args, cwd, raw) => cmdConfigEnsureSection(cwd, raw, args.includes('--dry-run')),
+    },
+    {
+        command: 'config-set',
+        handler: (args, cwd, raw) => cmdConfigSet(cwd, args[1], args[2], raw, args.includes('--dry-run')),
+    },
+    { command: 'history-digest', handler: (_args, cwd, raw) => cmdHistoryDigest(cwd, raw) },
+    {
+        command: 'progress',
+        handler: (args, cwd, raw) => cmdProgressRender(cwd, args[1] || 'json', raw),
+    },
+    {
+        command: 'migrate-dirs',
+        handler: (args, cwd, raw) => cmdMigrateDirs(cwd, raw, args.includes('--dry-run')),
+    },
+    {
+        command: 'dashboard',
+        handler: (_args, cwd, raw) => {
+            _warnDeprecated('dashboard');
+            cmdDashboard(cwd, raw);
+        },
+    },
+    { command: 'health', handler: (_args, cwd, raw) => cmdHealth(cwd, raw) },
+    { command: 'detect-backend', handler: (_args, cwd, raw) => cmdDetectBackend(cwd, raw) },
+    {
+        command: 'quality-analysis',
+        handler: (args, cwd, raw) => cmdQualityAnalysis(cwd, args.slice(1), raw),
+    },
+    {
+        command: 'setup',
+        handler: (_args, cwd, raw) => {
+            _warnDeprecated('setup');
+            cmdSetup(cwd, raw);
+        },
+    },
+    {
+        command: 'parallel-progress',
+        handler: (args, _cwd, raw) => cmdParallelProgress(args.slice(1), raw),
+    },
+    { command: 'resolve-model', handler: (args, cwd, raw) => cmdResolveModel(cwd, args[1], raw) },
+    { command: 'find-phase', handler: (args, cwd, raw) => cmdFindPhase(cwd, args[1], raw) },
+    {
+        command: 'coverage-report',
+        handler: (args, cwd, raw) => {
+            _warnDeprecated('coverage-report');
+            return cmdCoverageReport(cwd, { threshold: parseInt(flag(args, '--threshold', '85'), 10) }, raw);
+        },
+    },
+    {
+        command: 'health-check',
+        handler: (args, cwd, raw) => {
+            _warnDeprecated('health-check');
+            return cmdHealthCheck(cwd, { fix: args.includes('--fix') }, raw);
+        },
+    },
+    {
+        command: 'phase-detail',
+        handler: (args, cwd, raw) => {
+            validatePhaseArg(args[1]);
+            return cmdPhaseDetail(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'phase-plan-index',
+        handler: (args, cwd, raw) => {
+            validatePhaseArg(args[1]);
+            return cmdPhasePlanIndex(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'search',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('Search query is required');
+            return cmdSearch(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'phase-risk',
+        handler: (args, cwd, raw) => {
+            validatePhaseArg(args[1]);
+            return cmdPhaseRiskAssessment(cwd, args[1], raw);
+        },
+    },
+    { command: 'citation-backlinks', handler: (_args, cwd, raw) => cmdCitationBacklinks(cwd, raw) },
+    {
+        command: 'eval-regression-check',
+        handler: (args, cwd, raw) => {
+            validatePhaseArg(args[1]);
+            const t = flag(args, '--threshold');
+            return cmdEvalRegressionCheck(cwd, args[1], raw, t ? parseFloat(t) : undefined);
+        },
+    },
+    {
+        command: 'phase-time-budget',
+        handler: (_args, cwd, raw) => {
+            _warnDeprecated('phase-time-budget');
+            cmdPhaseTimeBudget(cwd, raw);
+        },
+    },
+    {
+        command: 'config-diff',
+        handler: (args, cwd, raw) => cmdConfigDiff(cwd, raw, args.includes('--reset'), args.includes('--dry-run')),
+    },
+    {
+        command: 'phase-readiness',
+        handler: (args, cwd, raw) => {
+            validatePhaseArg(args[1]);
+            return cmdPhaseReadiness(cwd, args[1], raw);
+        },
+    },
+    { command: 'milestone-health', handler: (_args, cwd, raw) => cmdMilestoneHealth(cwd, raw) },
+    { command: 'decision-timeline', handler: (_args, cwd, raw) => cmdDecisionTimeline(cwd, raw) },
+    {
+        command: 'import-knowledge',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('Source path required');
+            return cmdImportKnowledge(cwd, args[1], flag(args, '--types') || 'all', raw, args.includes('--force'), args.includes('--dry-run'));
+        },
+    },
+    {
+        command: 'todo-duplicates',
+        handler: (args, cwd, raw) => {
+            _warnDeprecated('todo-duplicates');
+            const t = flag(args, '--threshold');
+            return cmdTodoDuplicates(cwd, raw, t ? parseFloat(t) : undefined);
+        },
+    },
+    { command: 'teammate-idle-hook', handler: (_args, cwd, raw) => cmdTeammateIdleHook(cwd, raw) },
+    { command: 'task-completed-hook', handler: (_args, cwd, raw) => cmdTaskCompletedHook(cwd, raw) },
+    {
+        command: 'instructions-loaded-hook',
+        handler: (_args, cwd, raw) => cmdInstructionsLoadedHook(cwd, raw),
+    },
+    { command: 'stop-failure-hook', handler: (_args, cwd, raw) => cmdStopFailureHook(cwd, raw) },
+    { command: 'post-compact-hook', handler: (_args, cwd, raw) => cmdPostCompactHook(cwd, raw) },
+    {
+        command: 'citation-graph',
+        handler: (args, cwd, raw) => cmdCitationGraph(cwd, raw, args.includes('--unresolved')),
+    },
+    {
+        command: 'artifact-dag',
+        handler: (args, cwd, raw) => {
+            validatePhaseArg(args[1]);
+            return cmdArtifactDAG(cwd, args[1], raw);
+        },
+    },
+    { command: 'benchmark-report', handler: (_args, cwd, raw) => cmdBenchmarkReport(cwd, raw) },
+    {
+        command: 'diagnose',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('phase required. Usage: gd diagnose <phase>');
+            validatePhaseArg(args[1]);
+            return cmdDiagnosePhase(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'export-research',
+        handler: (args, cwd, raw) => cmdExportResearch(cwd, flag(args, '--output') ?? null, raw),
+    },
+    {
+        command: 'import-research',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('bundle path required. Usage: gd import-research <bundle.tar.gz>');
+            return cmdImportResearch(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'deps',
+        handler: (args, cwd, raw) => cmdPhaseDepsVisualize(cwd, { milestone: flag(args, '--milestone') ?? null, format: flag(args, '--format') ?? null }, raw),
+    },
+    {
+        command: 'todos',
+        handler: (args, cwd, raw) => {
+            const sub = args[1];
+            if (sub === 'rank') {
+                const topStr = flag(args, '--top');
+                const topN = topStr ? parseInt(topStr, 10) : undefined;
+                if (topN !== undefined && (isNaN(topN) || topN < 0)) {
+                    error('--top must be a non-negative integer');
+                }
+                return cmdTodosRank(cwd, raw, topN);
+            }
+            error(`Unknown todos subcommand: ${sub || '(none)'}. Valid: rank`);
+        },
+    },
+    {
+        command: 'knowhow',
+        handler: (args, cwd, raw) => {
+            const sub = args[1];
+            if (sub === 'audit')
+                return cmdKnowhowAudit(cwd, raw);
+            if (sub === 'aggregate' || sub === 'agg')
+                return cmdKnowhowAggregate(cwd, raw, args.includes('--export'), args.includes('--dry-run'));
+            if (sub === 'dedup') {
+                const t = flag(args, '--threshold');
+                return cmdKnowhowDedup(cwd, raw, t ? parseFloat(t) : undefined);
+            }
+            if (sub === 'rank') {
+                const query = args[2];
+                if (!query)
+                    error('query required. Usage: gd knowhow rank "<query>"');
+                const topStr = flag(args, '--top');
+                const topN = topStr ? parseInt(topStr, 10) : 5;
+                if (isNaN(topN) || topN <= 0)
+                    error('--top must be a positive integer');
+                return cmdKnowhowRank(cwd, query, topN, raw);
+            }
+            return cmdKnowhowList(cwd, raw, flag(args, '--module'), flag(args, '--limit') ? parseInt(flag(args, '--limit'), 10) : undefined);
+        },
+    },
+    {
+        command: 'budget',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('phase required. Usage: gd budget <phase>');
+            return cmdBudget(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'blame',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('phase required. Usage: gd blame <phase>');
+            return cmdBlame(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'freshness',
+        handler: (args, cwd, raw) => cmdFreshness(cwd, args[1] ?? null, raw),
+    },
+    {
+        command: 'rollback',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('phase required. Usage: gd rollback <phase>');
+            validatePhaseArg(args[1]);
+            return cmdRollback(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'estimate',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('phase required. Usage: gd estimate <phase>');
+            validatePhaseArg(args[1]);
+            return cmdEstimate(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'estimate-phase',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('phase required. Usage: gd estimate-phase <phase>');
+            validatePhaseArg(args[1]);
+            return cmdEstimatePhase(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'impact',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('phase required. Usage: gd impact <phase>');
+            validatePhaseArg(args[1]);
+            return cmdImpact(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'check-assumptions',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('phase required. Usage: gd check-assumptions <phase>');
+            validatePhaseArg(args[1]);
+            return cmdCheckAssumptions(cwd, args[1], raw, args.includes('--skip-assumption-check'));
+        },
+    },
+    {
+        command: 'execute-phase',
+        handler: (args, cwd, raw) => {
+            if (args.includes('--dry-run')) {
+                if (!args[1] || args[1].startsWith('--'))
+                    error('phase required. Usage: gd execute-phase <phase> --dry-run');
+                validatePhaseArg(args[1]);
+                return cmdExecutePhaseDryRun(cwd, args[1], raw);
+            }
+            // Non-dry-run execute-phase falls through to init workflow
+            const includes = parseIncludeFlag(args);
+            const phase = args[1];
+            if (!phase || phase.startsWith('--'))
+                error('phase required. Usage: gd execute-phase <phase>');
+            validatePhaseArg(phase);
+            const { cmdInitExecutePhase } = require('../lib/context/index');
+            return cmdInitExecutePhase(cwd, phase, includes, raw);
+        },
+    },
+    {
+        command: 'knowledge',
+        handler: (args, cwd, raw) => {
+            const sub = args[1];
+            if (sub === 'search') {
+                // Codex r3 P2: skip both the flag and its value so e.g.
+                // `gd knowledge search cache --top 5` searches for "cache",
+                // not "cache 5". Walks the slice, skipping flags and the
+                // token immediately following any value-bearing flag.
+                const FLAGS_WITH_VALUE = new Set(['--top']);
+                const queryParts = [];
+                const rest = args.slice(2);
+                for (let i = 0; i < rest.length; i++) {
+                    const a = rest[i];
+                    if (a.startsWith('--')) {
+                        if (FLAGS_WITH_VALUE.has(a))
+                            i++;
+                        continue;
+                    }
+                    queryParts.push(a);
+                }
+                const query = queryParts.join(' ');
+                if (!query)
+                    error('query required. Usage: gd knowledge search <query>');
+                const topN = parseInt(flag(args, '--top') ?? '10', 10);
+                return cmdKnowhowSearch(cwd, query, topN, raw);
+            }
+            error(`Unknown knowledge subcommand: ${sub || '(none)'}. Valid: search`);
+        },
+    },
+    {
+        command: 'check-plans',
+        handler: (args, cwd, raw) => {
+            const phase = flag(args, '--phase') ?? null;
+            const milestone = flag(args, '--milestone') ?? null;
+            return cmdCheckPlans(cwd, { phase, milestone }, raw);
+        },
+    },
+    {
+        command: 'eval',
+        handler: (args, cwd, raw) => {
+            const sub = args[1];
+            if (sub === 'diff') {
+                const phaseA = args[2];
+                const phaseB = args[3] ?? 'latest';
+                if (!phaseA)
+                    error('Usage: gd eval diff <phaseA> <phaseB> — or: gd eval diff latest');
+                if (phaseA !== 'latest')
+                    validatePhaseArg(phaseA);
+                if (phaseB !== 'latest')
+                    validatePhaseArg(phaseB);
+                return cmdEvalDiff(cwd, phaseA, phaseB, raw);
+            }
+            error(`Unknown eval subcommand: ${sub || '(none)'}. Valid: diff`);
+        },
+    },
+    {
+        command: 'tail',
+        handler: (args, cwd, raw) => {
+            const phaseFilter = flag(args, '--phase') ?? null;
+            const follow = args.includes('-f') || args.includes('--follow');
+            return cmdTail(cwd, phaseFilter, follow, raw);
+        },
+    },
+    {
+        command: 'forecast-phase',
+        handler: (args, cwd, raw) => {
+            const phase = args[1];
+            if (!phase)
+                error('phase required. Usage: gd forecast-phase <phase>');
+            validatePhaseArg(phase);
+            const { phasesDir: _phasesDir } = require('../lib/paths');
+            const { safeReadFile: _safeRead, execGit: _execGit } = require('../lib/utils');
+            const phasesBase = _phasesDir(cwd);
+            let phaseDir = null;
+            try {
+                // Codex r15 P2: match the canonical zero-padded form too so
+                // `gd forecast-phase 1` resolves to `01-test/`.
+                const padded = /^\d+$/.test(phase) ? phase.padStart(2, '0') : phase;
+                const dirs = fs.readdirSync(phasesBase);
+                const match = dirs.find((d) => d === phase || d === padded ||
+                    d.startsWith(`${phase}-`) || d.startsWith(`${padded}-`));
+                if (match)
+                    phaseDir = path.join(phasesBase, match);
+            }
+            catch { /* phases dir not found */ }
+            if (!phaseDir) {
+                output({ phase, error: `Phase ${phase} not found`, files: [] }, raw, `Phase ${phase} not found`);
+                return;
+            }
+            // Extract file paths from all PLAN.md files via regex
+            const fileRegex = /(?:^|[\s`"'(,])([a-zA-Z][a-zA-Z0-9_/-]*\.[a-zA-Z]{1,5})(?=$|[\s`"',):])/gm;
+            const fileCounts = new Map();
+            let planFiles = [];
+            try {
+                planFiles = fs.readdirSync(phaseDir).filter((f) => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+            }
+            catch { /* ignore */ }
+            for (const pf of planFiles) {
+                const content = _safeRead(path.join(phaseDir, pf));
+                if (!content)
+                    continue;
+                let m;
+                fileRegex.lastIndex = 0;
+                while ((m = fileRegex.exec(content)) !== null) {
+                    const fp = m[1];
+                    if (fp && fp.length > 3 && fp.includes('.') && !fp.startsWith('.')) {
+                        fileCounts.set(fp, (fileCounts.get(fp) ?? 0) + 1);
+                    }
+                }
+            }
+            const fileScores = [];
+            for (const [fp, mentions] of fileCounts) {
+                const logResult = _execGit(cwd, ['log', '--oneline', '--', fp]);
+                const gitTouches = logResult.exitCode === 0 ? logResult.stdout.trim().split('\n').filter(Boolean).length : 0;
+                const lastResult = _execGit(cwd, ['log', '-1', '--format=%ci', '--', fp]);
+                const lastModified = lastResult.exitCode === 0 ? lastResult.stdout.trim().slice(0, 10) : '';
+                const confidence = Math.round(Math.min(1, mentions * 0.4 + Math.min(gitTouches, 10) * 0.06) * 100) / 100;
+                fileScores.push({ file: fp, mentions, git_touches: gitTouches, confidence, last_modified: lastModified });
+            }
+            fileScores.sort((a, b) => b.confidence - a.confidence || b.mentions - a.mentions);
+            const top = fileScores.slice(0, 20);
+            // Write FORECAST.md to phase dir
+            let forecastPath = null;
+            try {
+                const lines = [
+                    `# File Touch Forecast — Phase ${phase}`,
+                    '',
+                    `Generated: ${new Date().toISOString().slice(0, 10)}`,
+                    '',
+                    '| File | Mentions | Git Touches | Confidence | Last Modified |',
+                    '|------|----------|-------------|------------|---------------|',
+                    ...top.map((r) => `| \`${r.file}\` | ${r.mentions} | ${r.git_touches} | ${r.confidence} | ${r.last_modified || 'n/a'} |`),
+                ];
+                const fp = path.join(phaseDir, 'FORECAST.md');
+                fs.writeFileSync(fp, lines.join('\n') + '\n', 'utf-8');
+                forecastPath = path.relative(cwd, fp);
+            }
+            catch { /* non-fatal */ }
+            const summary = top.length > 0
+                ? `Top predicted files:\n${top.slice(0, 5).map((r, i) => `  ${i + 1}. ${r.file} (confidence: ${r.confidence})`).join('\n')}`
+                : 'No file paths found in plan descriptions';
+            output({ phase, files_found: fileScores.length, top_files: top, forecast_path: forecastPath }, raw, summary);
+        },
+    },
+    {
+        command: 'import-knowhow',
+        handler: (args, cwd, raw) => {
+            if (!args[1])
+                error('source project directory required. Usage: gd import-knowhow <source-dir>');
+            const topStr = flag(args, '--top');
+            const topN = topStr ? parseInt(topStr, 10) : undefined;
+            return cmdImportKnowhow(cwd, args[1], raw, topN, args.includes('--all'), args.includes('--dry-run'));
+        },
+    },
+    { command: 'research-gaps', handler: (_args, cwd, raw) => cmdResearchGaps(cwd, raw) },
+    {
+        command: 'deps-risk',
+        handler: (args, cwd, raw) => cmdDepsRisk(cwd, args[1] ?? null, raw),
+    },
+    { command: 'watch', handler: (_args, cwd, raw) => cmdWatch(cwd, raw) },
+    {
+        command: 'singularity',
+        handler: (args, cwd, raw) => {
+            const since = flag(args, '--since') ?? null;
+            const all = args.includes('--all');
+            const byIteration = args.includes('--by-iteration');
+            cmdSingularity(cwd, { since, all, byIteration }, raw);
+        },
+    },
+    {
+        command: 'plan-lint',
+        handler: (args, cwd, raw) => {
+            if (!args[1]) {
+                error('milestone name required. Usage: gd plan-lint <milestone>');
+            }
+            cmdPlanLint(cwd, args[1], raw);
+        },
+    },
+    {
+        command: 'plan-candidates',
+        handler: (args, cwd, raw) => {
+            if (!args[1]) {
+                error('phase number required. Usage: gd plan-candidates <N> --candidates K [--input FILE] [--allow-partial-candidates]');
+            }
+            const phaseNum = args[1];
+            const candidatesArg = flag(args, '--candidates');
+            const inputFile = flag(args, '--input');
+            const allowPartial = args.includes('--allow-partial-candidates');
+            const candidates = candidatesArg ? parseInt(candidatesArg, 10) : 0;
+            if (candidatesArg && (!Number.isInteger(candidates) || candidates < 1)) {
+                error(`--candidates must be a positive integer, got "${candidatesArg}"`);
+            }
+            cmdPlanPhase(cwd, phaseNum, { candidates, inputFile, allowPartial }, raw);
+        },
+    },
+    {
+        command: 'select-candidate',
+        handler: (args, cwd, raw) => {
+            if (!args[1]) {
+                error('phase number required. Usage: gd select-candidate <N> [--dry-run] [--force] [--run-verification-commands]');
+            }
+            const phaseNum = args[1];
+            const dryRun = args.includes('--dry-run');
+            const force = args.includes('--force');
+            const runVerificationCommands = args.includes('--run-verification-commands');
+            cmdSelectCandidate(cwd, phaseNum, { dryRun, force, runVerificationCommands }, raw);
+        },
+    },
+    {
+        command: 'patterns',
+        handler: (args, cwd, raw) => {
+            // --dry-run is the default; --apply requires --yes (never-auto-write).
+            const apply = args.includes('--apply');
+            const yes = args.includes('--yes');
+            const minOcc = flag(args, '--min-occurrences');
+            const effSize = flag(args, '--effect-size');
+            const fdr = flag(args, '--fdr-q');
+            cmdPatterns(cwd, {
+                apply,
+                yes,
+                minOccurrences: minOcc !== undefined ? parseInt(minOcc, 10) : undefined,
+                effectSize: effSize !== undefined ? parseFloat(effSize) : undefined,
+                fdrQ: fdr !== undefined ? parseFloat(fdr) : undefined,
+            }, raw);
+        },
+    },
+    {
+        command: 'install',
+        handler: (args, cwd, raw) => {
+            // Positional harness names (everything after `install` that isn't a flag).
+            const harnesses = args
+                .slice(1)
+                .filter((a) => !a.startsWith('--'));
+            cmdInstall(cwd, {
+                harnesses,
+                all: args.includes('--all'),
+                list: args.includes('--list'),
+                dryRun: args.includes('--dry-run'),
+            }, raw);
+        },
+    },
+];
+// ─── Subcommand Arrays ──────────────────────────────────────────────────────
+const STATE_SUBS = [
+    'load',
+    'get',
+    'patch',
+    'update',
+    'advance-plan',
+    'record-metric',
+    'update-progress',
+    'add-decision',
+    'add-blocker',
+    'resolve-blocker',
+    'record-session',
+];
+const TEMPLATE_SUBS = ['select', 'fill'];
+const FRONTMATTER_SUBS = ['get', 'set', 'merge', 'validate'];
+const VERIFY_SUBS = [
+    'plan-structure',
+    'phase-completeness',
+    'references',
+    'commits',
+    'artifacts',
+    'key-links',
+    'mechanical',
+];
+const PHASES_SUBS = ['list'];
+const ROADMAP_SUBS = ['get-phase', 'analyze'];
+const PHASE_SUBS = [
+    'next-decimal',
+    'add',
+    'insert',
+    'remove',
+    'complete',
+    'analyze-deps',
+];
+const MILESTONE_SUBS = ['complete'];
+const VALIDATE_SUBS = ['consistency'];
+const TODO_SUBS = ['complete'];
+const TRACKER_SUBS = [
+    'get-config',
+    'sync-roadmap',
+    'sync-phase',
+    'update-status',
+    'add-comment',
+    'sync-status',
+    'schedule',
+    'prepare-reschedule',
+    'prepare-roadmap-sync',
+    'prepare-phase-sync',
+    'record-mapping',
+    'record-status',
+];
+const REQUIREMENT_SUBS = ['get', 'list', 'traceability', 'update-status'];
+const WORKTREE_SUBS = [
+    'create',
+    'remove',
+    'list',
+    'push-pr',
+    'ensure-milestone-branch',
+    'merge',
+    'hook',
+];
+const { INIT_WORKFLOWS } = require('../lib/cli/index');
+// ─── Main ───────────────────────────────────────────────────────────────────
+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: grd-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, tracker, init, dashboard, phase-detail, health, detect-backend, long-term-roadmap, quality-analysis, setup, search, requirement, worktree, migrate-dirs, coverage-report, health-check, dead-end');
+    }
+    try {
+        await routeCommand(command, args, cwd, raw);
+    }
+    catch (e) {
+        error(e.stack || String(e));
+    }
+}
+// ─── Route Command ──────────────────────────────────────────────────────────
+/** Validate and route CLI commands */
+async function routeCommand(command, args, cwd, raw) {
+    // Descriptor-based dispatch: check ROUTE_DESCRIPTORS before falling through to switch
+    const descriptor = ROUTE_DESCRIPTORS.find((d) => d.command === command);
+    if (descriptor) {
+        return descriptor.handler(args, cwd, raw);
+    }
+    switch (command) {
+        case 'state': {
+            const sub = args[1];
+            // No subcommand defaults to load -- only validate if provided
+            if (sub)
+                validateSubcommand(sub, STATE_SUBS, 'state');
+            if (sub === 'update')
+                cmdStateUpdate(cwd, args[2], args[3]);
+            else if (sub === 'get')
+                cmdStateGet(cwd, args[2], raw);
+            else if (sub === 'patch') {
+                const patches = {};
+                for (let i = 2; i < args.length; i += 2) {
+                    const k = args[i].replace(/^--/, '');
+                    if (k && args[i + 1] !== undefined)
+                        patches[k] = args[i + 1];
+                }
+                cmdStatePatch(cwd, patches, raw);
+            }
+            else if (sub === 'advance-plan')
+                cmdStateAdvancePlan(cwd, raw);
+            else if (sub === 'record-metric') {
+                cmdStateRecordMetric(cwd, {
+                    phase: flag(args, '--phase') ?? null,
+                    plan: flag(args, '--plan') ?? null,
+                    duration: flag(args, '--duration') ?? null,
+                    tasks: flag(args, '--tasks') ?? null,
+                    files: flag(args, '--files') ?? null,
+                }, raw);
+            }
+            else if (sub === 'update-progress')
+                cmdStateUpdateProgress(cwd, raw);
+            else if (sub === 'add-decision') {
+                cmdStateAddDecision(cwd, {
+                    phase: flag(args, '--phase') ?? null,
+                    summary: flag(args, '--summary') ?? null,
+                    rationale: flag(args, '--rationale') ?? '',
+                }, raw);
+            }
+            else if (sub === 'add-blocker')
+                cmdStateAddBlocker(cwd, flag(args, '--text') ?? '', raw);
+            else if (sub === 'resolve-blocker')
+                cmdStateResolveBlocker(cwd, flag(args, '--text') ?? '', raw);
+            else if (sub === 'record-session') {
+                cmdStateRecordSession(cwd, {
+                    stopped_at: flag(args, '--stopped-at') ?? null,
+                    resume_file: flag(args, '--resume-file') ?? 'None',
+                }, raw);
+            }
+            else
+                cmdStateLoad(cwd, raw);
+            break;
+        }
+        case 'resolve-model':
+            cmdResolveModel(cwd, args[1], raw);
+            break;
+        case 'find-phase':
+            cmdFindPhase(cwd, args[1], raw);
+            break;
+        case 'commit': {
+            const filesIndex = args.indexOf('--files');
+            cmdCommit(cwd, args[1], filesIndex !== -1
+                ? args.slice(filesIndex + 1).filter((a) => !a.startsWith('--'))
+                : [], raw, args.includes('--amend'));
+            break;
+        }
+        case 'verify-summary': {
+            validateFileArg(args[1], cwd);
+            const cc = args.indexOf('--check-count');
+            cmdVerifySummary(cwd, args[1], cc !== -1 ? parseInt(args[cc + 1], 10) : 2, raw);
+            break;
+        }
+        case 'template': {
+            const sub = args[1];
+            validateSubcommand(sub, TEMPLATE_SUBS, 'template');
+            if (sub === 'select')
+                cmdTemplateSelect(cwd, args[2], raw);
+            else if (sub === 'fill') {
+                cmdTemplateFill(cwd, args[2], {
+                    phase: flag(args, '--phase') ?? null,
+                    plan: flag(args, '--plan') ?? null,
+                    name: flag(args, '--name') ?? null,
+                    type: flag(args, '--type') ?? 'execute',
+                    wave: flag(args, '--wave') ?? '1',
+                    fields: flag(args, '--fields') ? JSON.parse(flag(args, '--fields')) : {},
+                }, raw);
+            }
+            break;
+        }
+        case 'frontmatter': {
+            const sub = args[1];
+            validateSubcommand(sub, FRONTMATTER_SUBS, 'frontmatter');
+            const file = args[2];
+            validateFileArg(file, cwd);
+            if (sub === 'get')
+                cmdFrontmatterGet(cwd, file, flag(args, '--field') ?? null, raw);
+            else if (sub === 'set')
+                cmdFrontmatterSet(cwd, file, flag(args, '--field') ?? '', flag(args, '--value') ?? '', raw);
+            else if (sub === 'merge')
+                cmdFrontmatterMerge(cwd, file, flag(args, '--data') ?? '', raw);
+            else if (sub === 'validate')
+                cmdFrontmatterValidate(cwd, file, flag(args, '--schema') ?? '', raw);
+            break;
+        }
+        case 'verify': {
+            const sub = args[1];
+            validateSubcommand(sub, VERIFY_SUBS, 'verify');
+            if (sub === 'commits') {
+                for (const ref of args.slice(2))
+                    validateGitRef(ref);
+                cmdVerifyCommits(cwd, args.slice(2), raw);
+            }
+            else if (sub === 'mechanical') {
+                // Bundle: arg is a phase number/name, not a file path
+                cmdVerifyMechanical(cwd, args[2], raw);
+            }
+            else {
+                validateFileArg(args[2], cwd);
+                if (sub === 'plan-structure')
+                    cmdVerifyPlanStructure(cwd, args[2], raw);
+                else if (sub === 'phase-completeness')
+                    cmdVerifyPhaseCompleteness(cwd, args[2], raw);
+                else if (sub === 'references')
+                    cmdVerifyReferences(cwd, args[2], raw);
+                else if (sub === 'artifacts')
+                    cmdVerifyArtifacts(cwd, args[2], raw);
+                else if (sub === 'key-links')
+                    cmdVerifyKeyLinks(cwd, args[2], raw);
+            }
+            break;
+        }
+        case 'generate-slug':
+            cmdGenerateSlug(args[1], raw);
+            break;
+        case 'current-timestamp':
+            cmdCurrentTimestamp(args[1] || 'full', raw);
+            break;
+        case 'list-todos':
+            cmdListTodos(cwd, args[1], raw);
+            break;
+        case 'verify-path-exists':
+            cmdVerifyPathExists(cwd, args[1], raw, args.includes('--dry-run'));
+            break;
+        case 'config-ensure-section':
+            cmdConfigEnsureSection(cwd, raw, args.includes('--dry-run'));
+            break;
+        case 'config-set':
+            cmdConfigSet(cwd, args[1], args[2], raw, args.includes('--dry-run'));
+            break;
+        case 'history-digest':
+            cmdHistoryDigest(cwd, raw);
+            break;
+        case 'dead-end': {
+            const sub = args[1];
+            if (sub === 'add') {
+                // Collect all --evidence flags (repeatable)
+                const evidence = [];
+                for (let i = 0; i < args.length; i++) {
+                    if (args[i] === '--evidence' && args[i + 1])
+                        evidence.push(args[i + 1]);
+                }
+                cmdDeadEndAdd(cwd, {
+                    approach: flag(args, '--approach') ?? '',
+                    phase: flag(args, '--phase') ?? '',
+                    verdict: flag(args, '--verdict'),
+                    evidence,
+                    notes: flag(args, '--notes'),
+                }, raw);
+            }
+            else if (sub === 'promote-from-phase') {
+                // Prefer the explicit --phase flag when present. Fall back to
+                // positional args[2], but only if it is NOT itself a flag —
+                // otherwise `promote-from-phase --phase 1` would pass the literal
+                // string "--phase" to findPhaseInternal (codex r1 P2 on PR #37).
+                const flagPhase = flag(args, '--phase');
+                const positional = args[2] && !args[2].startsWith('--') ? args[2] : undefined;
+                const phaseArg = flagPhase ?? positional ?? '';
+                cmdDeadEndPromoteFromPhase(cwd, phaseArg, raw);
+            }
+            else {
+                error(`Unknown dead-end subcommand: ${sub}. Valid: add, promote-from-phase`);
+            }
+            break;
+        }
+        case 'genome': {
+            const sub = args[1];
+            if (sub === 'init') {
+                cmdGenomeInit(cwd, raw);
+            }
+            else if (sub === 'show') {
+                cmdGenomeShow(cwd, raw);
+            }
+            else if (sub === 'snapshot') {
+                cmdGenomeSnapshot(cwd, raw);
+            }
+            else if (sub === 'promote-suggestion') {
+                const slug = args[2] && !args[2].startsWith('--') ? args[2] : '';
+                cmdGenomePromoteSuggestion(cwd, slug, raw);
+            }
+            else {
+                error(`Unknown genome subcommand: ${sub}. Valid: init, show, snapshot, promote-suggestion`);
+            }
+            break;
+        }
+        case 'think': {
+            // Tier-3 #11 of the Ouroboros integration. One-shot project-state
+            // aggregator. No daemon, no LLM, writes only to .planning/thoughts/.
+            //
+            // codex r1 P3 on PR #42: strictly validate --limit. Pre-fix:
+            //   `--limit 1.5` parseInt → 1 (silent truncation)
+            //   `--limit 3abc` parseInt → 3 (silent truncation)
+            //   `--limit` (no value) → silently defaulted
+            // All three slipped past the positive-integer check downstream.
+            let limit;
+            if (args.indexOf('--limit') !== -1) {
+                const limitRaw = flag(args, '--limit');
+                if (limitRaw === undefined || !/^\d+$/.test(limitRaw)) {
+                    error(`--limit requires a positive integer value (got ${limitRaw === undefined ? '<missing>' : `"${limitRaw}"`})`);
+                }
+                limit = parseInt(limitRaw, 10);
+            }
+            cmdThink(cwd, { limit }, raw);
+            break;
+        }
+        case 'plan-tournament': {
+            // Tier-3 #9 of the Ouroboros integration. Scoring + selection over
+            // N candidate PLAN.md files. Caller supplies paths; this command
+            // does NOT auto-generate candidates (that's a deliberate follow-up
+            // to avoid worktree orchestration + backend variance per the
+            // proposal's caveat).
+            const rawCandidates = [];
+            for (let i = 0; i < args.length; i++) {
+                if (args[i] === '--candidate' && args[i + 1])
+                    rawCandidates.push(args[i + 1]);
+            }
+            // Also accept comma-separated list via --candidates "a.md,b.md"
+            const csv = flag(args, '--candidates');
+            if (csv) {
+                for (const p of csv.split(',')) {
+                    const trimmed = p.trim();
+                    if (trimmed)
+                        rawCandidates.push(trimmed);
+                }
+            }
+            // codex r4 P2 on PR #41: validate each candidate path against the
+            // project boundary before passing it to the scorer. Without this
+            // guard, absolute paths or `../` traversal could read files
+            // outside the repo when gd is invoked via automation / MCP.
+            //
+            // codex r5 P2 on PR #41: validateFileArg's underlying check is
+            // prefix-based, so a sibling like `${cwd}-secrets/PLAN.md` would
+            // squeak through. Tighten with a path.relative containment check.
+            const path_lib = require('path');
+            const candidates = rawCandidates.map((p) => {
+                const validated = validateFileArg(p, cwd);
+                const rel = path_lib.relative(cwd, validated);
+                if (rel === '' || rel.startsWith('..') || path_lib.isAbsolute(rel)) {
+                    error(`Candidate path "${p}" is outside the project directory`);
+                }
+                return validated;
+            });
+            // codex r5 P3: validate phase format before interpolating into
+            // _extractRoadmapGoal's regex, where a malformed value would
+            // crash with a regex syntax error.
+            const phaseArg = flag(args, '--phase') ?? '';
+            if (phaseArg)
+                validatePhaseArg(phaseArg);
+            cmdPlanTournament(cwd, { phase: phaseArg, candidates }, raw);
+            break;
+        }
+        case 'phases': {
+            const sub = args[1];
+            validateSubcommand(sub, PHASES_SUBS, 'phases');
+            cmdPhasesList(cwd, { type: flag(args, '--type') ?? null, phase: flag(args, '--phase') ?? null }, raw);
+            break;
+        }
+        case 'roadmap': {
+            const sub = args[1];
+            validateSubcommand(sub, ROADMAP_SUBS, 'roadmap');
+            if (sub === 'get-phase') {
+                validatePhaseArg(args[2]);
+                cmdRoadmapGetPhase(cwd, args[2], raw);
+            }
+            else if (sub === 'analyze')
+                cmdRoadmapAnalyze(cwd, raw);
+            break;
+        }
+        case 'phase': {
+            const sub = args[1];
+            validateSubcommand(sub, PHASE_SUBS, 'phase');
+            if (sub === 'next-decimal') {
+                validatePhaseArg(args[2]);
+                cmdPhaseNextDecimal(cwd, args[2], raw);
+            }
+            else if (sub === 'add') {
+                const ctxIdx = args.indexOf('--context');
+                let context;
+                if (ctxIdx !== -1) {
+                    context = args.slice(ctxIdx + 1).join(' ');
+                    args.splice(ctxIdx);
+                }
+                cmdPhaseAdd(cwd, args.slice(2).join(' '), raw, context);
+            }
+            else if (sub === 'insert') {
+                validatePhaseArg(args[2]);
+                cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw);
+            }
+            else if (sub === 'remove') {
+                validatePhaseArg(args[2]);
+                cmdPhaseRemove(cwd, args[2], { force: args.includes('--force'), dryRun: args.includes('--dry-run') }, raw);
+            }
+            else if (sub === 'complete') {
+                validatePhaseArg(args[2]);
+                await cmdPhaseComplete(cwd, args[2], raw, { dryRun: args.includes('--dry-run') });
+            }
+            else if (sub === 'analyze-deps') {
+                cmdPhaseAnalyzeDeps(cwd, raw);
+            }
+            break;
+        }
+        case 'milestone': {
+            const sub = args[1];
+            validateSubcommand(sub, MILESTONE_SUBS, 'milestone');
+            if (sub === 'complete') {
+                const ni = args.indexOf('--name');
+                const version = args.slice(2).find((a) => !a.startsWith('--')) || null;
+                cmdMilestoneComplete(cwd, version, {
+                    name: ni !== -1 ? args[ni + 1] : null,
+                    dryRun: args.includes('--dry-run'),
+                }, raw);
+            }
+            break;
+        }
+        case 'version': {
+            const VERSION_SUBS = ['bump'];
+            validateSubcommand(args[1], VERSION_SUBS, 'version');
+            if (args[1] === 'bump') {
+                if (!args[2])
+                    error('version string required (e.g., v1.0.0)');
+                cmdVersionBump(cwd, args[2], raw);
+            }
+            break;
+        }
+        case 'validate': {
+            validateSubcommand(args[1], VALIDATE_SUBS, 'validate');
+            cmdValidateConsistency(cwd, raw);
+            break;
+        }
+        case 'progress':
+            cmdProgressRender(cwd, args[1] || 'json', raw);
+            break;
+        case 'todo': {
+            validateSubcommand(args[1], TODO_SUBS, 'todo');
+            cmdTodoComplete(cwd, args[2], raw, args.includes('--dry-run'));
+            break;
+        }
+        case 'scaffold': {
+            const pi = args.indexOf('--phase');
+            const ni = args.indexOf('--name');
+            cmdScaffold(cwd, args[1], {
+                phase: pi !== -1 ? args[pi + 1] : null,
+                name: ni !== -1 ? args.slice(ni + 1).join(' ') : null,
+            }, raw);
+            break;
+        }
+        case 'migrate-dirs':
+            cmdMigrateDirs(cwd, raw, args.includes('--dry-run'));
+            break;
+        case 'init': {
+            const wf = args[1];
+            const includes = parseIncludeFlag(args);
+            validateSubcommand(wf, INIT_WORKFLOWS, 'init');
+            switch (wf) {
+                case 'execute-phase':
+                    validatePhaseArg(args[2]);
+                    cmdInitExecutePhase(cwd, args[2], includes, raw);
+                    break;
+                case 'execute-parallel': {
+                    const phases = args.slice(2).filter((a) => !a.startsWith('--'));
+                    if (phases.length === 0)
+                        error('At least one phase number required for init execute-parallel');
+                    for (const p of phases)
+                        validatePhaseArg(p);
+                    cmdInitExecuteParallel(cwd, phases, includes, raw);
+                    break;
+                }
+                case 'plan-phase':
+                    validatePhaseArg(args[2]);
+                    cmdInitPlanPhase(cwd, args[2], includes, raw);
+                    break;
+                case 'new-project':
+                    cmdInitNewProject(cwd, raw);
+                    break;
+                case 'new-milestone':
+                    cmdInitNewMilestone(cwd, raw);
+                    break;
+                case 'quick':
+                    cmdInitQuick(cwd, args.slice(2).join(' '), raw);
+                    break;
+                case 'resume':
+                    cmdInitResume(cwd, raw);
+                    break;
+                case 'verify-work':
+                    validatePhaseArg(args[2]);
+                    cmdInitVerifyWork(cwd, args[2], raw);
+                    break;
+                case 'phase-op':
+                    validatePhaseArg(args[2]);
+                    cmdInitPhaseOp(cwd, args[2], raw);
+                    break;
+                case 'todos':
+                    cmdInitTodos(cwd, args[2], raw);
+                    break;
+                case 'milestone-op':
+                    cmdInitMilestoneOp(cwd, raw);
+                    break;
+                case 'plan-milestone-gaps':
+                    cmdInitPlanMilestoneGaps(cwd, raw);
+                    break;
+                case 'map-codebase':
+                    cmdInitMapCodebase(cwd, raw);
+                    break;
+                case 'progress':
+                    cmdInitProgress(cwd, includes, raw, args.includes('--refresh'));
+                    break;
+                case 'survey':
+                    cmdInitSurveyor(cwd, args.slice(2).join(' ') || '', raw);
+                    break;
+                case 'deep-dive':
+                    cmdInitDeepDive(cwd, args.slice(2).join(' ') || '', raw);
+                    break;
+                case 'feasibility':
+                    cmdInitFeasibility(cwd, args.slice(2).join(' ') || '', raw);
+                    break;
+                case 'eval-plan':
+                    cmdInitEvalPlan(cwd, args[2] || null, raw);
+                    break;
+                case 'eval-report':
+                    cmdInitEvalReport(cwd, args[2] || null, raw);
+                    break;
+                case 'assess-baseline':
+                    cmdInitAssessBaseline(cwd, raw);
+                    break;
+                case 'product-plan':
+                    cmdInitProductOwner(cwd, raw);
+                    break;
+                case 'iterate':
+                    cmdInitResearchWorkflow(cwd, 'iterate', args.slice(2).join(' '), includes, raw);
+                    break;
+                case 'project-researcher':
+                    cmdInitProjectResearcher(cwd, args.slice(2).join(' ') || '', raw);
+                    break;
+                case 'research-synthesizer':
+                    cmdInitResearchSynthesizer(cwd, raw);
+                    break;
+                case 'roadmapper':
+                    cmdInitRoadmapper(cwd, raw);
+                    break;
+                case 'verifier':
+                    cmdInitVerifier(cwd, args[2] || null, raw);
+                    break;
+                case 'autopilot':
+                    cmdInitAutopilot(cwd, raw);
+                    break;
+                case 'multi-milestone-autopilot':
+                    cmdInitMultiMilestoneAutopilot(cwd, raw);
+                    break;
+                case 'autoplan':
+                    cmdInitAutoplan(cwd, raw);
+                    break;
+                case 'autoresearch':
+                    cmdInitAutoResearch(cwd, raw);
+                    break;
+                case 'evolve':
+                    cmdInitEvolve(cwd, raw);
+                    break;
+                case 'wireup':
+                    cmdInitWireup(cwd, raw);
+                    break;
+                case 'debug':
+                    cmdInitDebug(cwd, args[2] || null, raw);
+                    break;
+                case 'integration-check':
+                    cmdInitIntegrationCheck(cwd, args[2] || null, raw);
+                    break;
+                case 'migrate':
+                    cmdInitMigrate(cwd, raw);
+                    break;
+                case 'plan-check':
+                    validatePhaseArg(args[2]);
+                    cmdInitPlanCheck(cwd, args[2], raw);
+                    break;
+                case 'phase-research':
+                    validatePhaseArg(args[2]);
+                    cmdInitPhaseResearch(cwd, args[2], includes, raw);
+                    break;
+                case 'code-review':
+                    validatePhaseArg(args[2]);
+                    cmdInitCodeReview(cwd, args[2], raw);
+                    break;
+            }
+            break;
+        }
+        case 'phase-plan-index':
+            validatePhaseArg(args[1]);
+            cmdPhasePlanIndex(cwd, args[1], raw);
+            break;
+        case 'state-snapshot': {
+            const sinceIdx = args.indexOf('--since');
+            const snapshotOptions = sinceIdx !== -1 ? { since: args[sinceIdx + 1] } : {};
+            cmdStateSnapshot(cwd, raw, snapshotOptions);
+            break;
+        }
+        case 'summary-extract': {
+            validateFileArg(args[1], cwd);
+            const fi = args.indexOf('--fields');
+            cmdSummaryExtract(cwd, args[1], fi !== -1 ? args[fi + 1].split(',') : null, raw);
+            break;
+        }
+        case 'tracker': {
+            validateSubcommand(args[1], TRACKER_SUBS, 'tracker');
+            await cmdTracker(cwd, args[1], args.slice(2), raw);
+            break;
+        }
+        case 'dashboard':
+            cmdDashboard(cwd, raw);
+            break;
+        case 'phase-detail':
+            validatePhaseArg(args[1]);
+            cmdPhaseDetail(cwd, args[1], raw);
+            break;
+        case 'health':
+            cmdHealth(cwd, raw);
+            break;
+        case 'detect-backend':
+            cmdDetectBackend(cwd, raw);
+            break;
+        case 'long-term-roadmap': {
+            const sub = args[1];
+            if (!sub)
+                error('subcommand required: list, add, remove, update, refine, link, unlink, display, init, history, parse, validate');
+            const subArgs = args.slice(2);
+            cmdLongTermRoadmap(cwd, sub, subArgs, raw);
+            break;
+        }
+        case 'quality-analysis':
+            cmdQualityAnalysis(cwd, args.slice(1), raw);
+            break;
+        case 'setup':
+            cmdSetup(cwd, raw);
+            break;
+        case 'search':
+            if (!args[1])
+                error('Search query is required');
+            cmdSearch(cwd, args[1], raw);
+            break;
+        case 'requirement': {
+            const sub = args[1];
+            validateSubcommand(sub, REQUIREMENT_SUBS, 'requirement');
+            if (sub === 'get') {
+                if (!args[2])
+                    error('REQ-ID required');
+                cmdRequirementGet(cwd, args[2], raw);
+            }
+            else if (sub === 'list') {
+                cmdRequirementList(cwd, {
+                    phase: flag(args, '--phase') ?? null,
+                    priority: flag(args, '--priority') ?? null,
+                    status: flag(args, '--status') ?? null,
+                    category: flag(args, '--category') ?? null,
+                    all: args.includes('--all'),
+                }, raw);
+            }
+            else if (sub === 'traceability') {
+                cmdRequirementTraceability(cwd, {
+                    phase: flag(args, '--phase') ?? null,
+                }, raw);
+            }
+            else if (sub === 'update-status') {
+                if (!args[2])
+                    error('REQ-ID required');
+                if (!args[3])
+                    error('Status required (Pending, In Progress, Done, Deferred)');
+                // Handle multi-word status "In Progress" -- args[3] might be "In" and args[4] "Progress"
+                let status = args[3];
+                if (args[3] === 'In' && args[4] === 'Progress') {
+                    status = 'In Progress';
+                }
+                cmdRequirementUpdateStatus(cwd, args[2], status, raw, args.includes('--dry-run'));
+            }
+            break;
+        }
+        case 'worktree': {
+            const sub = args[1];
+            validateSubcommand(sub, WORKTREE_SUBS, 'worktree');
+            if (sub === 'create') {
+                cmdWorktreeCreate(cwd, {
+                    phase: flag(args, '--phase') ?? null,
+                    milestone: flag(args, '--milestone') ?? null,
+                    slug: flag(args, '--slug') ?? null,
+                    startPoint: flag(args, '--start-point') ?? null,
+                }, raw);
+            }
+            else if (sub === 'remove') {
+                if (args.includes('--stale')) {
+                    cmdWorktreeRemoveStale(cwd, raw);
+                }
+                else {
+                    cmdWorktreeRemove(cwd, {
+                        phase: flag(args, '--phase') ?? null,
+                        path: flag(args, '--path') ?? null,
+                        milestone: flag(args, '--milestone') ?? null,
+                    }, raw);
+                }
+            }
+            else if (sub === 'list') {
+                cmdWorktreeList(cwd, raw);
+            }
+            else if (sub === 'push-pr') {
+                cmdWorktreePushAndPR(cwd, {
+                    phase: flag(args, '--phase') ?? null,
+                    milestone: flag(args, '--milestone') ?? null,
+                    title: flag(args, '--title') ?? null,
+                    body: flag(args, '--body') ?? null,
+                    base: flag(args, '--base') ?? null,
+                }, raw);
+            }
+            else if (sub === 'ensure-milestone-branch') {
+                cmdWorktreeEnsureMilestoneBranch(cwd, {
+                    milestone: flag(args, '--milestone') ?? null,
+                    baseBranch: flag(args, '--base-branch') ?? null,
+                }, raw);
+            }
+            else if (sub === 'merge') {
+                cmdWorktreeMerge(cwd, {
+                    phase: flag(args, '--phase') ?? null,
+                    milestone: flag(args, '--milestone') ?? null,
+                    slug: flag(args, '--slug') ?? null,
+                    base: flag(args, '--base') ?? null,
+                    branch: flag(args, '--branch') ?? null,
+                    deleteBranch: args.includes('--delete-branch'),
+                }, raw);
+            }
+            else if (sub === 'hook') {
+                const hookSub = args[2];
+                if (hookSub === 'create') {
+                    cmdWorktreeHookCreate(cwd, args[3], args[4], raw);
+                }
+                else if (hookSub === 'remove') {
+                    cmdWorktreeHookRemove(cwd, args[3], args[4], raw);
+                }
+                else {
+                    error(`Unknown worktree hook subcommand: ${hookSub}. Use 'create' or 'remove'.`);
+                }
+            }
+            break;
+        }
+        case 'settings': {
+            const sub = args[1];
+            if (sub === 'token_profile') {
+                const value = args[2];
+                const validProfiles = ['frugal', 'balanced', 'quality'];
+                if (!value || !validProfiles.includes(value)) {
+                    error(`Invalid token_profile value "${value || ''}". Valid values: ${validProfiles.join(', ')}`);
+                }
+                cmdConfigSet(cwd, 'token_profile', value, raw);
+            }
+            else if (sub === 'phase_complete_llm_fallback') {
+                const value = args[2];
+                if (value !== 'true' && value !== 'false') {
+                    error(`Invalid phase_complete_llm_fallback value "${value || ''}". Valid values: true, false`);
+                }
+                cmdConfigSet(cwd, 'phase_complete_llm_fallback', value, raw);
+            }
+            else if (sub === 'effort') {
+                // v0.4 Phase 1: effort axis
+                const value = args[2];
+                const validEffortLevels = ['thrifty', 'balanced', 'deep'];
+                if (!value || !validEffortLevels.includes(value)) {
+                    error(`Invalid effort value "${value || ''}". Valid values: ${validEffortLevels.join(', ')}`);
+                }
+                cmdConfigSet(cwd, 'effort', value, raw);
+            }
+            else {
+                error(`Unknown settings subcommand "${sub || ''}". Tool-mode settings subcommands: token_profile, effort, phase_complete_llm_fallback`);
+            }
+            break;
+        }
+        case 'evolve': {
+            const sub = args[1];
+            validateSubcommand(sub, ['run', 'discover', 'state', 'advance', 'reset'], 'evolve');
+            switch (sub) {
+                case 'run':
+                    await cmdEvolve(cwd, args.slice(2), raw);
+                    return;
+                case 'discover':
+                    await cmdEvolveDiscover(cwd, args.slice(2), raw);
+                    return;
+                case 'state':
+                    cmdEvolveState(cwd, args.slice(2), raw);
+                    return;
+                case 'advance':
+                    cmdEvolveAdvance(cwd, args.slice(2), raw);
+                    return;
+                case 'reset':
+                    cmdEvolveReset(cwd, args.slice(2), raw);
+                    return;
+            }
+            break;
+        }
+        case 'wireup': {
+            const sub = args[1];
+            validateSubcommand(sub, ['run'], 'wireup');
+            if (sub === 'run') {
+                await cmdWireup(cwd, args.slice(2), raw);
+                return;
+            }
+            break;
+        }
+        case 'autopilot':
+            await cmdAutopilot(cwd, args.slice(1), raw);
+            break;
+        case 'multi-milestone-autopilot':
+            await cmdMultiMilestoneAutopilot(cwd, args.slice(1), raw);
+            break;
+        case 'autoplan':
+            await cmdAutoplan(cwd, args.slice(1), raw);
+            break;
+        case 'autoresearch': {
+            const arConfig = loadConfig(cwd);
+            const arScheduler = createScheduler(arConfig.scheduler, arConfig.superpowers);
+            if (arScheduler) {
+                arScheduler.loadPersistedState(path.join(cwd, '.planning'));
+            }
+            await cmdAutoResearch(cwd, args.slice(1), raw, arScheduler);
+            break;
+        }
+        case 'worktree-hook-create':
+            cmdWorktreeHookCreate(cwd, args[1], args[2], raw);
+            break;
+        case 'worktree-hook-remove':
+            cmdWorktreeHookRemove(cwd, args[1], args[2], raw);
+            break;
+        case 'coverage-report':
+            cmdCoverageReport(cwd, { threshold: parseInt(flag(args, '--threshold', '85'), 10) }, raw);
+            break;
+        case 'health-check':
+            cmdHealthCheck(cwd, { fix: args.includes('--fix') }, raw);
+            break;
+        case 'markdown-split': {
+            _warnDeprecated('markdown-split');
+            const sub = args[1];
+            validateSubcommand(sub, ['split', 'check'], 'markdown-split');
+            switch (sub) {
+                case 'split': {
+                    const filePath = args[2];
+                    if (!filePath)
+                        error('file path required for markdown-split split');
+                    const absPath = path.resolve(cwd, filePath);
+                    if (!fs.existsSync(absPath))
+                        error(`File not found: ${absPath}`);
+                    const thresholdIdx = args.indexOf('--threshold');
+                    const threshold = thresholdIdx !== -1 ? parseInt(args[thresholdIdx + 1], 10) : undefined;
+                    const content = fs.readFileSync(absPath, 'utf-8');
+                    const basename = path.basename(absPath, '.md');
+                    const dir = path.dirname(absPath);
+                    const result = splitMarkdown(content, { threshold, basename });
+                    if (!result.split_performed) {
+                        output({ split_performed: false, reason: result.reason, file: absPath }, raw);
+                        break;
+                    }
+                    // Write index file (overwrite original)
+                    fs.writeFileSync(absPath, result.index_content, 'utf-8');
+                    // Write partial files
+                    const partials = [];
+                    for (const part of result.parts || []) {
+                        const partPath = path.join(dir, part.filename);
+                        fs.writeFileSync(partPath, part.content, 'utf-8');
+                        partials.push(partPath);
+                    }
+                    output({
+                        split_performed: true,
+                        index_file: absPath,
+                        partials,
+                        part_count: (result.parts || []).length,
+                    }, raw);
+                    break;
+                }
+                case 'check': {
+                    const filePath = args[2];
+                    if (!filePath)
+                        error('file path required for markdown-split check');
+                    const absPath = path.resolve(cwd, filePath);
+                    if (!fs.existsSync(absPath))
+                        error(`File not found: ${absPath}`);
+                    const content = fs.readFileSync(absPath, 'utf-8');
+                    const tokens = estimateTokens(content);
+                    const is_index = isIndexFile(content);
+                    output({
+                        file: absPath,
+                        is_index,
+                        estimated_tokens: tokens,
+                        exceeds_threshold: tokens > 25000,
+                    }, raw);
+                    break;
+                }
+            }
+            break;
+        }
+        case 'parallel-progress':
+            cmdParallelProgress(args.slice(1), raw);
+            break;
+        case 'overstory': {
+            const sub = validateSubcommand(args[1] || '', ['detect', 'install'], 'overstory');
+            if (sub === 'detect') {
+                const result = detectOverstory(cwd);
+                output(result || { available: false, reason: 'Overstory not detected' }, raw);
+            }
+            else if (sub === 'install') {
+                try {
+                    installOverstory(cwd);
+                    output({ ok: true, message: 'Overstory installed and initialized' }, raw);
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    output({ ok: false, error: msg }, raw);
+                }
+            }
+            break;
+        }
+        case 'metrics': {
+            const { getCounters } = require('../lib/metrics');
+            const counters = getCounters();
+            output(counters, raw, JSON.stringify(counters, null, 2));
+            break;
+        }
+        default: {
+            const TOP_LEVEL_COMMANDS = [
+                'state',
+                'resolve-model',
+                'find-phase',
+                'commit',
+                'verify-summary',
+                'template',
+                'frontmatter',
+                'verify',
+                'generate-slug',
+                'current-timestamp',
+                'list-todos',
+                'verify-path-exists',
+                'config-ensure-section',
+                'config-set',
+                'history-digest',
+                'phases',
+                'roadmap',
+                'phase',
+                'milestone',
+                'version',
+                'validate',
+                'progress',
+                'todo',
+                'scaffold',
+                'migrate-dirs',
+                'init',
+                'phase-plan-index',
+                'state-snapshot',
+                'summary-extract',
+                'tracker',
+                'dashboard',
+                'phase-detail',
+                'health',
+                'detect-backend',
+                'long-term-roadmap',
+                'quality-analysis',
+                'setup',
+                'search',
+                'requirement',
+                'worktree',
+                'settings',
+                'evolve',
+                'autopilot',
+                'multi-milestone-autopilot',
+                'autoplan',
+                'worktree-hook-create',
+                'worktree-hook-remove',
+                'teammate-idle-hook',
+                'task-completed-hook',
+                'instructions-loaded-hook',
+                'stop-failure-hook',
+                'post-compact-hook',
+                'coverage-report',
+                'health-check',
+                'markdown-split',
+                'parallel-progress',
+                'overstory',
+                'metrics',
+                'diagnose',
+                'export-research',
+                'import-research',
+                'deps',
+                'todos',
+                'knowhow',
+                'budget',
+                'blame',
+                'freshness',
+                'rollback',
+                'estimate',
+                'estimate-phase',
+                'impact',
+                'check-assumptions',
+                'execute-phase',
+                'phase-risk',
+                'citation-backlinks',
+                'eval-regression-check',
+                'phase-time-budget',
+                'config-diff',
+                'phase-readiness',
+                'milestone-health',
+                'decision-timeline',
+                'import-knowledge',
+                'todo-duplicates',
+                'citation-graph',
+                'artifact-dag',
+                'benchmark-report',
+                'forecast-phase',
+                'tail',
+                'eval',
+                'check-plans',
+                'knowledge',
+                'autoresearch',
+                'wireup',
+                'watch',
+                'research-gaps',
+                'deps-risk',
+                'import-knowhow',
+            ];
+            const suggestion = findClosestCommand(command, TOP_LEVEL_COMMANDS);
+            const hint = suggestion ? ` Did you mean "${suggestion}"?` : '';
+            error(`Unknown command: "${command}".${hint}`);
+        }
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`[grd] fatal error: ${err.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=grd-tools.js.map