@jokerized/getresearchdone 0.4.1

package/dist/lib/utils.js

@@ -0,0 +1,1363 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+const { detectBackend, resolveBackendModel, resolveEffortLevel, getBackendCapabilities, VALID_BACKENDS, } = require('./backend');
+const { phasesDir: getPhasesDirPath } = require('./paths');
+// ─── Git Operation Whitelist ────────────────────────────────────────────────
+const GIT_ALLOWED_COMMANDS = new Set([
+    'add',
+    'commit',
+    'log',
+    'status',
+    'diff',
+    'show',
+    'rev-parse',
+    'cat-file',
+    'check-ignore',
+    'ls-files',
+    'branch',
+    'checkout',
+    'merge',
+    'rebase',
+    'cherry-pick',
+    'tag',
+    'stash',
+    'remote',
+    'fetch',
+    'pull',
+]);
+const GIT_BLOCKED_COMMANDS = new Set(['config', 'push', 'clean']);
+const GIT_BLOCKED_FLAGS = new Set(['--force', '-f', '--hard', '--delete', '-D']);
+// ─── Model Profile Table ─────────────────────────────────────────────────────
+const MODEL_PROFILES = {
+    'grd-planner': { quality: 'opus', balanced: 'opus', budget: 'sonnet' },
+    'grd-roadmapper': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+    'grd-executor': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+    'grd-phase-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+    'grd-project-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+    'grd-research-synthesizer': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+    'grd-debugger': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+    'grd-codebase-mapper': { quality: 'sonnet', balanced: 'haiku', budget: 'haiku' },
+    'grd-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+    // NERFIFY refinement-loop critic (codex r43 P2: was routed through
+    // grd-verifier, which never loaded the agent definition).
+    'grd-critique-agent': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+    'grd-plan-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+    'grd-integration-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+    // R&D-specific agents
+    'grd-surveyor': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+    'grd-deep-diver': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+    'grd-feasibility-analyst': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+    'grd-eval-planner': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+    'grd-eval-reporter': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+    'grd-product-owner': { quality: 'opus', balanced: 'opus', budget: 'sonnet' },
+    'grd-baseline-assessor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+    // Development practice agents
+    'grd-code-reviewer': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+};
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Parse --include flag from CLI args into a Set of included items.
+ * @param args - CLI argument array
+ * @returns Set of comma-separated include values, or empty Set if not present
+ */
+function parseIncludeFlag(args) {
+    const includeIndex = args.indexOf('--include');
+    if (includeIndex === -1)
+        return new Set();
+    const includeValue = args[includeIndex + 1];
+    if (!includeValue)
+        return new Set();
+    return new Set(includeValue.split(',').map((s) => s.trim()));
+}
+/**
+ * Read file returning content or null on error.
+ * @param filePath - Absolute path to the file
+ * @returns File content as UTF-8 string, or null if read fails
+ */
+function safeReadFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read a markdown file, transparently handling GRD split-format index files.
+ * If the file is a GRD index (contains <!-- GRD-INDEX --> marker), partials are
+ * automatically reassembled. Otherwise, returns the file content as-is.
+ * @param filePath - Absolute path to the markdown file
+ * @returns File content (reassembled if split), or null on error
+ */
+function safeReadMarkdown(filePath) {
+    try {
+        // Lazy require to avoid circular dependency (markdown-split.js imports safeReadFile from utils.js)
+        const { readMarkdownWithPartials } = require('./markdown-split');
+        return readMarkdownWithPartials(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read and parse a JSON file, returning the default value on any error.
+ * @param filePath - Absolute path to the JSON file
+ * @param defaultValue - Value to return if read or parse fails
+ * @returns Parsed JSON object, or defaultValue on error
+ */
+function safeReadJSON(filePath, defaultValue = null) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return defaultValue;
+    }
+}
+/**
+ * Extract content under a markdown heading (## or ### level).
+ * @param content - Full markdown content
+ * @param heading - Heading text to find (case-insensitive)
+ * @param level - Heading level (2 for ##, 3 for ###)
+ * @returns Section content (without the heading line), or null if not found
+ */
+function extractMarkdownSection(content, heading, level = 2) {
+    const prefix = '#'.repeat(level);
+    const regex = new RegExp(`${prefix}\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\n([\\s\\S]*?)(?=\\n${prefix}\\s|$)`, 'i');
+    const match = content.match(regex);
+    return match ? match[1] : null;
+}
+// ─── Levenshtein Distance ────────────────────────────────────────────────────
+/**
+ * Compute the Levenshtein edit distance between two strings.
+ * @param s1 - First string
+ * @param s2 - Second string
+ * @returns Edit distance
+ */
+function levenshteinDistance(s1, s2) {
+    const m = s1.length;
+    const n = s2.length;
+    const dp = [];
+    for (let i = 0; i <= m; i++) {
+        dp[i] = [i];
+        for (let j = 1; j <= n; j++) {
+            if (i === 0) {
+                dp[i][j] = j;
+            }
+            else {
+                dp[i][j] = 0;
+            }
+        }
+    }
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (s1[i - 1] === s2[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1];
+            }
+            else {
+                dp[i][j] = 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+            }
+        }
+    }
+    return dp[m][n];
+}
+/**
+ * Find the closest command name from a list of commands using Levenshtein distance.
+ * Returns null if no command is close enough (distance > threshold) or if input is invalid.
+ * @param input - User input to match
+ * @param commands - List of valid command names
+ * @returns The closest command name, or null if too different
+ */
+function findClosestCommand(input, commands) {
+    if (!input || !commands || commands.length === 0)
+        return null;
+    const lower = input.toLowerCase();
+    let best = null;
+    let bestDist = Infinity;
+    for (const cmd of commands) {
+        const dist = levenshteinDistance(lower, cmd.toLowerCase());
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = cmd;
+        }
+    }
+    // Threshold: only suggest if distance is at most 3 (reasonable typo range)
+    const threshold = Math.max(3, Math.floor(best ? best.length / 3 : 3));
+    if (bestDist > threshold)
+        return null;
+    return best;
+}
+// ─── Phase Cache ─────────────────────────────────────────────────────────────
+const _phaseCache = new Map();
+/**
+ * Clear the internal phase directory cache.
+ */
+function clearPhaseCache() {
+    _phaseCache.clear();
+}
+/**
+ * Known top-level config keys (used for unrecognized key warnings).
+ */
+const KNOWN_CONFIG_KEYS = new Set([
+    'model_profile',
+    'commit_docs',
+    'search_gitignored',
+    'branching_strategy',
+    'phase_branch_template',
+    'milestone_branch_template',
+    'base_branch',
+    'research',
+    'plan_checker',
+    'verifier',
+    'parallelization',
+    'code_review_enabled',
+    'code_review_timing',
+    'code_review_severity_gate',
+    'code_review_auto_fix_warnings',
+    'use_teams',
+    'team_timeout_minutes',
+    'max_concurrent_teammates',
+    'backend',
+    'backend_models',
+    'autonomous_mode',
+    // Nested section keys (objects)
+    'code_review',
+    'execution',
+    'git',
+    'planning',
+    'workflow',
+    'tracker',
+    'eval_config',
+    'ceremony',
+    'phase_cleanup',
+    'research_gates',
+    'confirmation_gates',
+    'timeouts',
+    'evolve',
+    // New-project command keys
+    'mode',
+    'depth',
+    // YOLO saved state keys
+    '_saved_research_gates',
+    '_saved_confirmation_gates',
+    'yolo_decision_log',
+    // Backend-specific keys
+    'overstory',
+    // Scheduler config
+    'scheduler',
+    // Superpowers config
+    'superpowers',
+    // Discussion config
+    'backend_roles',
+    'discussion',
+    // Citation gate
+    'citation_gate',
+    // Transitive citation gate
+    'transitive_citation_gate',
+    // Refinement loop
+    'refinement_loop',
+    // LLM fallback for phase completion (Spec 3B)
+    'phase_complete_llm_fallback',
+    // LLM fallback retry count with exponential backoff
+    'phase_complete_llm_fallback_retries',
+    // Drift score (Tier-2 #7 of Ouroboros integration)
+    'drift',
+    // Autopilot termination knobs (Tier-3 #10 of Ouroboros integration)
+    'autopilot',
+    // Evolve r9 + r14: surface-level keys consumed by Ouroboros r9 CLIs.
+    // research_staleness_days drives `gd health`'s STALE_RESEARCH blocker;
+    // `survey` carries staleness_days for `gd progress`'s freshness warn.
+    'research_staleness_days',
+    'survey',
+    // Plug-in / context-mode knowledge stats path
+    'token_profile',
+    // v0.4 Phase 1: orthogonal effort axis
+    'effort',
+]);
+// ─── Effort Axis (v0.4 Phase 1) ─────────────────────────────────────────────
+/**
+ * v0.4 effort-scaled knobs. Single-knob scope by design (codex r6) — only
+ * `candidates_per_plan_phase` is wired in v0.4. The table is structured
+ * (object keyed by knob name) so v0.5+ can add knobs without changing the
+ * `resolveEffortKnob` signature.
+ */
+const EFFORT_PROFILES = {
+    thrifty: { candidates_per_plan_phase: 1 },
+    balanced: { candidates_per_plan_phase: 3 },
+    deep: { candidates_per_plan_phase: 7 },
+};
+/**
+ * Return the integer value of an effort-scaled knob for the current
+ * `effort` setting in config. Defaults to 'balanced' when unset.
+ *
+ * @param config - GrdConfig (effort field optional, defaults to 'balanced')
+ * @param knob - Name of the effort-scaled knob to resolve
+ * @returns Integer value for the knob under the active effort level
+ */
+function resolveEffortKnob(config, knob) {
+    // Codex review P2: loadConfig preserves invalid `effort` values (warns but
+    // keeps them), so guard against EFFORT_PROFILES[level] being undefined.
+    // An unrecognized level falls back to 'balanced' rather than crashing.
+    const raw = config.effort;
+    const level = raw !== undefined && Object.prototype.hasOwnProperty.call(EFFORT_PROFILES, raw)
+        ? raw
+        : 'balanced';
+    return EFFORT_PROFILES[level][knob];
+}
+/**
+ * Load and merge .planning/config.json with default configuration values.
+ * @param cwd - Project working directory
+ * @returns Merged configuration object with all fields populated
+ */
+function loadConfig(cwd) {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    const defaultTimeouts = {
+        jest_ms: 120000,
+        lint_ms: 60000,
+        format_ms: 60000,
+        consistency_ms: 30000,
+        tracker_gh_ms: 30000,
+        tracker_auth_ms: 10000,
+        backend_detect_ms: 10000,
+        autopilot_check_ms: 5000,
+        autoresearch_test_ms: 120000,
+        autoresearch_coverage_ms: 180000,
+        autoresearch_lint_ms: 60000,
+        backend_probe_ms: 5000,
+        discussion_git_ms: 10000,
+        overstory_probe_ms: 5000,
+        overstory_install_ms: 120000,
+    };
+    const defaults = {
+        model_profile: 'balanced',
+        commit_docs: true,
+        search_gitignored: false,
+        branching_strategy: 'none',
+        phase_branch_template: 'grd/{milestone}/{phase}-{slug}',
+        milestone_branch_template: 'grd/{milestone}-{slug}',
+        base_branch: 'main',
+        research: true,
+        plan_checker: true,
+        verifier: true,
+        parallelization: true,
+        // Code review defaults
+        code_review_enabled: true,
+        code_review_timing: 'per_wave',
+        code_review_severity_gate: 'blocker',
+        code_review_auto_fix_warnings: false,
+        // Execution defaults
+        use_teams: false,
+        team_timeout_minutes: 30,
+        max_concurrent_teammates: 4,
+        // Backend config (pass-through, no defaults)
+        backend: undefined,
+        backend_models: undefined,
+        // Autonomous mode
+        autonomous_mode: false,
+        // Ceremony config
+        ceremony: undefined,
+        // Timeout defaults (ms)
+        timeouts: defaultTimeouts,
+        // Evolve config
+        evolve: undefined,
+    };
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // Warn about unrecognized top-level config keys
+        for (const key of Object.keys(parsed)) {
+            if (!KNOWN_CONFIG_KEYS.has(key)) {
+                process.stderr.write(`Warning: Unrecognized config key "${key}" in .planning/config.json\n`);
+            }
+        }
+        // Warn about invalid model_profile values
+        const validProfiles = ['quality', 'balanced', 'budget'];
+        if (parsed.model_profile !== undefined &&
+            !validProfiles.includes(parsed.model_profile)) {
+            process.stderr.write(`Warning: Invalid model_profile value "${parsed.model_profile}" in .planning/config.json. Valid values: ${validProfiles.join(', ')}\n`);
+        }
+        // Warn about invalid effort values (v0.4 Phase 1)
+        const validEffortLevels = ['thrifty', 'balanced', 'deep'];
+        if (parsed.effort !== undefined &&
+            !validEffortLevels.includes(parsed.effort)) {
+            process.stderr.write(`Warning: Invalid effort value "${parsed.effort}" in .planning/config.json. Valid values: ${validEffortLevels.join(', ')}\n`);
+        }
+        const get = (key, nested) => {
+            if (parsed[key] !== undefined)
+                return parsed[key];
+            if (nested) {
+                const section = parsed[nested.section];
+                if (section && section[nested.field] !== undefined) {
+                    return section[nested.field];
+                }
+            }
+            return undefined;
+        };
+        const parallelization = (() => {
+            const val = get('parallelization');
+            if (typeof val === 'boolean')
+                return val;
+            if (typeof val === 'object' && val !== null && 'enabled' in val)
+                return val.enabled;
+            return defaults.parallelization;
+        })();
+        return {
+            model_profile: (get('model_profile') ?? defaults.model_profile),
+            // v0.4 Phase 1: effort axis. Invalid values pass through as warnings
+            // above; we keep raw here so resolveEffortKnob's default ('balanced')
+            // takes effect when the field is absent.
+            ...(parsed.effort !== undefined ? { effort: parsed.effort } : {}),
+            commit_docs: (get('commit_docs', { section: 'planning', field: 'commit_docs' }) ??
+                defaults.commit_docs),
+            search_gitignored: (get('search_gitignored', {
+                section: 'planning',
+                field: 'search_gitignored',
+            }) ?? defaults.search_gitignored),
+            branching_strategy: (get('branching_strategy', {
+                section: 'git',
+                field: 'branching_strategy',
+            }) ?? defaults.branching_strategy),
+            phase_branch_template: (get('phase_branch_template', {
+                section: 'git',
+                field: 'phase_branch_template',
+            }) ?? defaults.phase_branch_template),
+            milestone_branch_template: (get('milestone_branch_template', {
+                section: 'git',
+                field: 'milestone_branch_template',
+            }) ?? defaults.milestone_branch_template),
+            base_branch: (get('base_branch', { section: 'git', field: 'base_branch' }) ??
+                defaults.base_branch),
+            research: (get('research', { section: 'workflow', field: 'research' }) ??
+                defaults.research),
+            plan_checker: (get('plan_checker', { section: 'workflow', field: 'plan_check' }) ??
+                defaults.plan_checker),
+            verifier: (get('verifier', { section: 'workflow', field: 'verifier' }) ??
+                defaults.verifier),
+            parallelization,
+            // Code review config
+            code_review_enabled: (get('code_review_enabled', {
+                section: 'code_review',
+                field: 'enabled',
+            }) ?? defaults.code_review_enabled),
+            code_review_timing: (get('code_review_timing', { section: 'code_review', field: 'timing' }) ??
+                defaults.code_review_timing),
+            code_review_severity_gate: (get('code_review_severity_gate', {
+                section: 'code_review',
+                field: 'severity_gate',
+            }) ?? defaults.code_review_severity_gate),
+            code_review_auto_fix_warnings: (get('code_review_auto_fix_warnings', {
+                section: 'code_review',
+                field: 'auto_fix_warnings',
+            }) ?? defaults.code_review_auto_fix_warnings),
+            // Execution config
+            use_teams: (get('use_teams', { section: 'execution', field: 'use_teams' }) ??
+                defaults.use_teams),
+            team_timeout_minutes: (get('team_timeout_minutes', {
+                section: 'execution',
+                field: 'team_timeout_minutes',
+            }) ?? defaults.team_timeout_minutes),
+            max_concurrent_teammates: (get('max_concurrent_teammates', {
+                section: 'execution',
+                field: 'max_concurrent_teammates',
+            }) ?? defaults.max_concurrent_teammates),
+            // Backend config (pass-through, no defaults)
+            backend: (parsed.backend || undefined),
+            backend_models: (parsed.backend_models || undefined),
+            // Autonomous mode
+            autonomous_mode: (get('autonomous_mode') ?? false),
+            // Ceremony config (pass-through)
+            ceremony: (parsed.ceremony || undefined),
+            // Evolve config
+            evolve: (() => {
+                const e = parsed.evolve && typeof parsed.evolve === 'object'
+                    ? parsed.evolve
+                    : null;
+                if (!e)
+                    return undefined;
+                return {
+                    auto_commit: (e.auto_commit ?? true),
+                    create_pr: (e.create_pr ?? true),
+                    // Tier-2 #8 auto-genome follow-up. Default off — opt-in.
+                    auto_genome_snapshot: (e.auto_genome_snapshot ?? false),
+                };
+            })(),
+            // Scheduler config (pass-through)
+            scheduler: (parsed.scheduler || undefined),
+            // Superpowers config (pass-through)
+            superpowers: (parsed.superpowers || undefined),
+            // Drift score config (pass-through; defaults applied in lib/drift.ts)
+            drift: (parsed.drift || undefined),
+            // Autopilot termination knobs (pass-through; Tier-3 #10)
+            autopilot: (parsed.autopilot || undefined),
+            // Codex r14 P2/P3: Ouroboros r9 staleness knobs need to survive
+            // loadConfig so cmdHealth + cmdProgress can read them. Cast the
+            // whole return at the bottom to widen the type.
+            ...(parsed.research_staleness_days !== undefined
+                ? { research_staleness_days: parsed.research_staleness_days }
+                : {}),
+            ...(parsed.survey !== undefined ? { survey: parsed.survey } : {}),
+            // Backend roles config: validate each value against VALID_BACKENDS
+            backend_roles: (() => {
+                const raw = parsed.backend_roles;
+                if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                    return undefined;
+                const rawRoles = raw;
+                const validRoles = ['reviewer', 'brainstormer', 'verifier', 'executor'];
+                const result = {};
+                for (const [role, backendVal] of Object.entries(rawRoles)) {
+                    if (!validRoles.includes(role)) {
+                        process.stderr.write(`Warning: Unrecognized backend_roles role "${role}" in .planning/config.json\n`);
+                        continue;
+                    }
+                    if (typeof backendVal !== 'string' ||
+                        !VALID_BACKENDS.includes(backendVal)) {
+                        process.stderr.write(`Warning: Invalid backend "${String(backendVal)}" for role "${role}" in backend_roles — must be a valid BackendId\n`);
+                        continue;
+                    }
+                    result[role] = backendVal;
+                }
+                return Object.keys(result).length > 0 ? result : undefined;
+            })(),
+            // Discussion config: validate fields, apply defaults
+            discussion: (() => {
+                const raw = parsed.discussion;
+                if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                    return undefined;
+                const d = raw;
+                const enabled = typeof d.enabled === 'boolean' ? d.enabled : true;
+                if (!enabled) {
+                    return {
+                        enabled: false,
+                        before_planning: typeof d.before_planning === 'boolean' ? d.before_planning : true,
+                        before_execution: typeof d.before_execution === 'boolean' ? d.before_execution : false,
+                        max_rounds: 2,
+                        timeout_per_round_seconds: 180,
+                        synthesizer: 'claude',
+                    };
+                }
+                let max_rounds = typeof d.max_rounds === 'number' ? Math.round(d.max_rounds) : 2;
+                if (max_rounds < 1)
+                    max_rounds = 1;
+                if (max_rounds > 3)
+                    max_rounds = 3;
+                const timeout_per_round_seconds = typeof d.timeout_per_round_seconds === 'number' && d.timeout_per_round_seconds > 0
+                    ? d.timeout_per_round_seconds
+                    : 180;
+                const synthRaw = d.synthesizer;
+                const synthesizer = typeof synthRaw === 'string' && VALID_BACKENDS.includes(synthRaw)
+                    ? synthRaw
+                    : 'claude';
+                return {
+                    enabled,
+                    before_planning: typeof d.before_planning === 'boolean' ? d.before_planning : true,
+                    before_execution: typeof d.before_execution === 'boolean' ? d.before_execution : false,
+                    max_rounds,
+                    timeout_per_round_seconds,
+                    synthesizer: synthesizer,
+                };
+            })(),
+            // Citation gate (optional boolean, default: false)
+            citation_gate: typeof parsed.citation_gate === 'boolean' ? parsed.citation_gate : false,
+            // Transitive citation gate (optional boolean, default: false)
+            transitive_citation_gate: typeof parsed.transitive_citation_gate === 'boolean'
+                ? parsed.transitive_citation_gate
+                : false,
+            // Refinement loop (optional boolean, default: false)
+            refinement_loop: typeof parsed.refinement_loop === 'boolean' ? parsed.refinement_loop : false,
+            // LLM fallback for phase completion (Spec 3B, optional boolean, default: false)
+            phase_complete_llm_fallback: typeof parsed.phase_complete_llm_fallback === 'boolean'
+                ? parsed.phase_complete_llm_fallback
+                : undefined,
+            // LLM fallback retry count (optional number, default: 0)
+            phase_complete_llm_fallback_retries: typeof parsed.phase_complete_llm_fallback_retries === 'number'
+                ? Math.max(0, parsed.phase_complete_llm_fallback_retries)
+                : undefined,
+            // Timeouts config
+            timeouts: (() => {
+                const t = parsed.timeouts && typeof parsed.timeouts === 'object'
+                    ? parsed.timeouts
+                    : {};
+                const d = defaultTimeouts;
+                return {
+                    jest_ms: (t.jest_ms ?? d.jest_ms),
+                    lint_ms: (t.lint_ms ?? d.lint_ms),
+                    format_ms: (t.format_ms ?? d.format_ms),
+                    consistency_ms: (t.consistency_ms ?? d.consistency_ms),
+                    tracker_gh_ms: (t.tracker_gh_ms ?? d.tracker_gh_ms),
+                    tracker_auth_ms: (t.tracker_auth_ms ?? d.tracker_auth_ms),
+                    backend_detect_ms: (t.backend_detect_ms ?? d.backend_detect_ms),
+                    autopilot_check_ms: (t.autopilot_check_ms ?? d.autopilot_check_ms),
+                    autoresearch_test_ms: (t.autoresearch_test_ms ?? d.autoresearch_test_ms),
+                    autoresearch_coverage_ms: (t.autoresearch_coverage_ms ?? d.autoresearch_coverage_ms),
+                    autoresearch_lint_ms: (t.autoresearch_lint_ms ?? d.autoresearch_lint_ms),
+                    backend_probe_ms: (t.backend_probe_ms ?? d.backend_probe_ms),
+                    discussion_git_ms: (t.discussion_git_ms ?? d.discussion_git_ms),
+                    overstory_probe_ms: (t.overstory_probe_ms ?? d.overstory_probe_ms),
+                    overstory_install_ms: (t.overstory_install_ms ?? d.overstory_install_ms),
+                };
+            })(),
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * Check if a file path is git-ignored via git check-ignore.
+ * @param cwd - Project working directory
+ * @param targetPath - Path to check against .gitignore rules
+ * @returns True if the path is git-ignored, false otherwise
+ */
+function isGitIgnored(cwd, targetPath) {
+    if (targetPath.includes('\0'))
+        return false;
+    try {
+        execFileSync('git', ['check-ignore', '-q', '--', targetPath], {
+            cwd,
+            stdio: 'pipe',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Execute a git command with whitelist enforcement for security.
+ * @param cwd - Project working directory
+ * @param args - Git command arguments (first element is the subcommand)
+ * @param opts - Options object
+ * @returns Command result with exit code and output
+ */
+function execGit(cwd, args, opts = {}) {
+    // Git operation whitelist enforcement
+    const subcommand = args[0];
+    if (subcommand && GIT_BLOCKED_COMMANDS.has(subcommand) && !opts.allowBlocked) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `Blocked: "git ${subcommand}" is not allowed by the GRD security policy. Pass { allowBlocked: true } to override.`,
+        };
+    }
+    if (!opts.allowBlocked) {
+        for (const arg of args) {
+            if (GIT_BLOCKED_FLAGS.has(arg)) {
+                return {
+                    exitCode: 1,
+                    stdout: '',
+                    stderr: `Blocked: flag "${arg}" is not allowed by the GRD security policy. Pass { allowBlocked: true } to override.`,
+                };
+            }
+        }
+    }
+    try {
+        const stdout = execFileSync('git', args, {
+            cwd,
+            stdio: 'pipe',
+            encoding: 'utf-8',
+        });
+        return { exitCode: 0, stdout: stdout.trim(), stderr: '' };
+    }
+    catch (err) {
+        const gitErr = err;
+        return {
+            exitCode: gitErr.status ?? 1,
+            stdout: (gitErr.stdout ?? '').toString().trim(),
+            stderr: (gitErr.stderr ?? '').toString().trim(),
+        };
+    }
+}
+/**
+ * Normalize a phase identifier by zero-padding and validating format.
+ * @param phase - Phase identifier (e.g., "7", "07", "07.1")
+ * @returns Normalized phase name with zero-padded number (e.g., "07", "07.1")
+ * @throws If phase is not a string or contains path traversal/directory separators
+ */
+function normalizePhaseName(phase) {
+    if (typeof phase !== 'string')
+        throw new Error('Phase must be a string');
+    if (phase.includes('..'))
+        throw new Error('Phase name must not contain path traversal (..)');
+    if (phase.includes('/') || phase.includes('\\'))
+        throw new Error('Phase name must not contain directory separators');
+    const match = phase.match(/^(\d+(?:\.\d+)?)/);
+    if (!match)
+        return phase;
+    const num = match[1];
+    const parts = num.split('.');
+    const padded = parts[0].padStart(2, '0');
+    return parts.length > 1 ? `${padded}.${parts[1]}` : padded;
+}
+const CODE_EXTENSIONS = new Set([
+    '.ts',
+    '.js',
+    '.py',
+    '.go',
+    '.rs',
+    '.swift',
+    '.java',
+]);
+/**
+ * Recursively find code files up to a maximum depth, capped at 5 results.
+ * @param dir - Directory to search in
+ * @param maxDepth - Maximum directory depth to recurse into
+ * @param found - Accumulator array of found file paths
+ * @param depth - Current recursion depth
+ * @returns Array of absolute paths to code files found
+ */
+function findCodeFiles(dir, maxDepth, found, depth) {
+    if (depth > maxDepth || found.length >= 5)
+        return found;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return found;
+    }
+    for (const entry of entries) {
+        if (found.length >= 5)
+            break;
+        if (entry.name === 'node_modules' || entry.name === '.git')
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            findCodeFiles(fullPath, maxDepth, found, depth + 1);
+        }
+        else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if (CODE_EXTENSIONS.has(ext)) {
+                found.push(fullPath);
+            }
+        }
+    }
+    return found;
+}
+// ─── Input Validation ────────────────────────────────────────────────────────
+/**
+ * Validate phase name format strictly, rejecting path traversal and invalid characters.
+ * @param phase - Phase name to validate
+ * @returns The validated phase name if valid
+ * @throws If phase format is invalid, contains traversal, null bytes, or separators
+ */
+function validatePhaseName(phase) {
+    if (typeof phase !== 'string')
+        throw new Error('Phase must be a string');
+    if (phase.includes('..'))
+        throw new Error('Phase name must not contain path traversal (..)');
+    if (phase.includes('/') || phase.includes('\\'))
+        throw new Error('Phase name must not contain directory separators');
+    if (phase.includes('\0'))
+        throw new Error('Phase name must not contain null bytes');
+    if (!/^\d+(?:\.\d+)?(?:-[a-zA-Z0-9-]+)?$/.test(phase)) {
+        throw new Error('Invalid phase name format: must be digits with optional decimal and kebab-case suffix');
+    }
+    return phase;
+}
+/**
+ * Validate that a file path does not escape the project directory.
+ * @param filePath - File path to validate (relative or absolute)
+ * @param cwd - Project working directory used as security boundary
+ * @returns The validated file path if safe
+ * @throws If path is not a string, contains null bytes, or escapes project directory
+ */
+function validateFilePath(filePath, cwd) {
+    if (typeof filePath !== 'string')
+        throw new Error('File path must be a string');
+    if (filePath.includes('\0'))
+        throw new Error('File path must not contain null bytes');
+    const resolved = path.resolve(cwd, filePath);
+    if (!resolved.startsWith(cwd))
+        throw new Error('File path must not escape project directory');
+    return filePath;
+}
+/**
+ * Validate git ref format, preventing flag injection and path traversal.
+ * @param ref - Git reference to validate (commit hash, branch name, tag)
+ * @returns The validated git ref if valid
+ * @throws If ref is invalid, starts with dash, contains traversal, or has invalid characters
+ */
+function validateGitRef(ref) {
+    if (typeof ref !== 'string')
+        throw new Error('Git ref must be a string');
+    if (ref.startsWith('-'))
+        throw new Error('Git ref must not start with a dash (flag injection)');
+    if (ref.includes('..'))
+        throw new Error('Git ref must not contain path traversal (..)');
+    if (!/^[a-zA-Z0-9._\-/~^]+$/.test(ref))
+        throw new Error('Git ref contains invalid characters');
+    if (ref.length > 256)
+        throw new Error('Git ref too long');
+    return ref;
+}
+// ─── CLI Argument Validation ──────────────────────────────────────────────────
+/**
+ * Validate CLI phase number argument, ensuring it is present and well-formed.
+ * @param phase - Phase number from CLI arguments
+ * @returns The validated phase number
+ * @throws If phase is missing or not in valid format (digits with optional decimal)
+ */
+function validatePhaseArg(phase) {
+    if (phase == null || phase === '')
+        throw new Error('Phase number is required');
+    if (typeof phase !== 'string')
+        throw new Error('Phase number is required');
+    if (!/^\d+(?:\.\d+)?(?:-[a-zA-Z0-9-]+)?$/.test(phase)) {
+        throw new Error('Invalid phase number: must be digits with optional decimal (e.g., 01, 02.1)');
+    }
+    return phase;
+}
+/**
+ * Validate CLI file path argument, ensuring it is present and does not escape project.
+ * @param filePath - File path from CLI arguments
+ * @param cwd - Project working directory used as security boundary
+ * @returns The validated file path
+ * @throws If file path is missing or escapes project directory
+ */
+function validateFileArg(filePath, cwd) {
+    if (filePath == null || filePath === '')
+        throw new Error('File path is required');
+    return validateFilePath(filePath, cwd);
+}
+/**
+ * Validate CLI subcommand against a list of valid subcommands.
+ * @param sub - Subcommand string from CLI arguments
+ * @param validSubs - Array of valid subcommand names
+ * @param parentCmd - Parent command name for error messages
+ * @returns The validated subcommand
+ * @throws If subcommand is missing or not in the valid list
+ */
+function validateSubcommand(sub, validSubs, parentCmd) {
+    if (sub == null || sub === '') {
+        throw new Error(`Subcommand required for '${parentCmd}'. Available: ${validSubs.join(', ')}`);
+    }
+    if (!validSubs.includes(sub)) {
+        throw new Error(`Unknown ${parentCmd} subcommand: '${sub}'. Available: ${validSubs.join(', ')}`);
+    }
+    return sub;
+}
+/**
+ * Validate that a required CLI argument is present and non-empty.
+ * @param value - Argument value to check
+ * @param argName - Name of the argument for error messages
+ * @returns The validated value
+ * @throws If value is null, undefined, or empty string
+ */
+function validateRequiredArg(value, argName) {
+    if (value == null || value === '')
+        throw new Error(`${argName} is required`);
+    return value;
+}
+// ─── Output ──────────────────────────────────────────────────────────────────
+/**
+ * Write JSON or raw output to stdout and exit with code 0.
+ * @param result - Result object to serialize as JSON
+ * @param raw - If true, output rawValue as plain text instead of JSON
+ * @param rawValue - Plain text value to output when raw is true
+ */
+function output(result, raw, rawValue) {
+    if (raw && rawValue !== undefined) {
+        process.stdout.write(String(rawValue));
+    }
+    else {
+        process.stdout.write(JSON.stringify(result, null, 2));
+    }
+    process.exit(0);
+}
+/**
+ * Write error message to stderr and exit with code 1.
+ * @param message - Error message to display
+ */
+function error(message) {
+    process.stderr.write('Error: ' + message + '\n');
+    process.exit(1);
+}
+/**
+ * Write debug message to stderr when GRD_DEBUG environment variable is set.
+ * No-op in normal operation; enabled by setting GRD_DEBUG=1 (or any truthy value).
+ * @param message - Debug message to display
+ * @param data - Optional data to JSON-stringify alongside the message
+ */
+function debugLog(message, data) {
+    if (!process.env.GRD_DEBUG)
+        return;
+    const prefix = '[grd:debug] ';
+    if (data !== undefined) {
+        process.stderr.write(prefix + message + ' ' + JSON.stringify(data) + '\n');
+    }
+    else {
+        process.stderr.write(prefix + message + '\n');
+    }
+}
+// ─── Shared Cache Factory ─────────────────────────────────────────────────────
+/**
+ * Create a run-scoped file content cache.
+ * Returns a cache object with `get`, `init`, and `reset` methods.
+ * Modules can use this to avoid redundant disk reads within a single CLI invocation.
+ *
+ * Usage pattern:
+ *   const cache = createRunCache();
+ *   cache.init();           // activate caching for this run
+ *   cache.get(p, reader)   // returns cached value or calls reader(p) and stores result
+ *   cache.reset();          // deactivate and clear
+ *
+ * @returns Cache object with init, reset, and get methods
+ */
+function createRunCache() {
+    let _map = null;
+    return {
+        /** Activate the cache (creates a new Map). */
+        init() {
+            _map = new Map();
+        },
+        /** Deactivate and clear the cache. */
+        reset() {
+            _map = null;
+        },
+        /**
+         * Get a cached value, or compute it with `reader(key)` and store the result.
+         * Falls back to calling `reader(key)` directly if the cache is not active.
+         * @param key - Cache key (typically a file path)
+         * @param reader - Function to produce the value if not cached
+         * @returns The cached or freshly computed value
+         */
+        get(key, reader) {
+            if (!_map)
+                return reader(key);
+            if (!_map.has(key))
+                _map.set(key, reader(key));
+            return _map.get(key);
+        },
+    };
+}
+// ─── Phase Directory Utilities ────────────────────────────────────────────────
+/**
+ * Find a phase directory name inside `phasesDir` that matches `phaseArg`.
+ * Matches by exact normalized name or by prefix `<normalized>-`.
+ * @param phasesDir - Absolute path to the phases directory
+ * @param phaseArg - Phase identifier (e.g., '1', '01', '1.1')
+ * @returns The matching directory name, or null if not found
+ */
+function findPhaseDir(phasesDir, phaseArg) {
+    const normalized = normalizePhaseName(phaseArg);
+    try {
+        const entries = fs.readdirSync(phasesDir, {
+            withFileTypes: true,
+        });
+        const dirs = entries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+        return dirs.find((d) => d.startsWith(normalized + '-') || d === normalized) || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse a phase number from a directory name or plain string.
+ * Handles formats like '01-feature-name', '1.2-sub', '1', etc.
+ * @param str - Directory name or phase string to parse
+ * @returns The numeric phase number as a string (e.g. '1', '1.2'), or null
+ */
+function parsePhaseNumber(str) {
+    if (!str)
+        return null;
+    const match = str.match(/^(\d+(?:\.\d+)?)/);
+    return match ? match[1] : null;
+}
+// ─── Directory Walking ────────────────────────────────────────────────────────
+/**
+ * Recursively collect JavaScript file paths under `rootDir`.
+ * Skips `node_modules`, `.git`, `.planning`, and any paths matching `excludePatterns`.
+ * @param rootDir - Root directory to walk (returned paths are relative to this)
+ * @param excludePatterns - Substrings; any relative path containing one is skipped
+ * @returns Relative paths of all .js files found
+ */
+function walkJsFiles(rootDir, excludePatterns = []) {
+    const results = [];
+    _walkJsDir(rootDir, rootDir, results, excludePatterns);
+    return results;
+}
+function _walkJsDir(rootDir, currentDir, results, excludePatterns) {
+    let entries;
+    try {
+        entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+        const relPath = path.relative(rootDir, fullPath);
+        if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.planning') {
+            continue;
+        }
+        if (excludePatterns.some((p) => relPath.includes(p)))
+            continue;
+        if (entry.isDirectory()) {
+            _walkJsDir(rootDir, fullPath, results, excludePatterns);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.js')) {
+            results.push(relPath);
+        }
+    }
+}
+// ─── Compound Helpers ────────────────────────────────────────────────────────
+/**
+ * Resolve the model name for a given agent type from project configuration.
+ * @param cwd - Project working directory
+ * @param agentType - Agent type key (e.g., 'grd-executor', 'grd-planner')
+ * @returns Model name (e.g., 'opus', 'sonnet', 'haiku')
+ */
+function resolveModelInternal(cwd, agentType) {
+    const config = loadConfig(cwd);
+    const profile = config.model_profile || 'balanced';
+    const agentModels = MODEL_PROFILES[agentType];
+    if (!agentModels) {
+        // Unknown agent type: resolve 'sonnet' tier through backend
+        const backend = detectBackend(cwd);
+        return resolveBackendModel(backend, 'sonnet', config, cwd);
+    }
+    const tier = agentModels[profile] || agentModels['balanced'] || 'sonnet';
+    const backend = detectBackend(cwd);
+    return resolveBackendModel(backend, tier, config, cwd);
+}
+/**
+ * Find a phase directory and enumerate its plans, summaries, and metadata.
+ * @param cwd - Project working directory
+ * @param phase - Phase identifier to search for
+ * @returns Phase info object with directory, plans, summaries, and flags, or null if not found
+ */
+function findPhaseInternal(cwd, phase) {
+    if (!phase)
+        return null;
+    const phasesDir = getPhasesDirPath(cwd);
+    const normalized = normalizePhaseName(phase);
+    try {
+        const entries = fs.readdirSync(phasesDir, {
+            withFileTypes: true,
+        });
+        const dirs = entries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+        const match = dirs.find((d) => d.startsWith(normalized + '-') || d === normalized);
+        if (!match)
+            return null;
+        const dirMatch = match.match(/^(\d+(?:\.\d+)?)-?(.*)/);
+        const phaseNumber = dirMatch ? dirMatch[1] : normalized;
+        const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
+        const phaseDir = path.join(phasesDir, match);
+        const phaseFiles = fs.readdirSync(phaseDir);
+        const plans = phaseFiles
+            .filter((f) => f.endsWith('-PLAN.md') || f === 'PLAN.md')
+            .sort();
+        const summaries = phaseFiles
+            .filter((f) => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md')
+            .sort();
+        const hasResearch = phaseFiles.some((f) => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md');
+        const hasContext = phaseFiles.some((f) => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md');
+        const hasVerification = phaseFiles.some((f) => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md');
+        // Determine incomplete plans (plans without matching summaries)
+        const completedPlanIds = new Set(summaries.map((s) => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '')));
+        const incompletePlans = plans.filter((p) => {
+            const planId = p.replace('-PLAN.md', '').replace('PLAN.md', '');
+            return !completedPlanIds.has(planId);
+        });
+        // Check if phase exists in ROADMAP.md (non-blocking consistency check)
+        let consistencyWarning = null;
+        try {
+            const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+            const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+            const unpadded = String(parseInt(phaseNumber, 10));
+            const phasePattern = new RegExp(`#{2,}\\s*Phase\\s+(?:${phaseNumber}|${unpadded})\\s*:`, 'i');
+            if (!phasePattern.test(roadmapContent)) {
+                consistencyWarning = `Phase ${phaseNumber} found on disk but not in ROADMAP.md — may be from a previous milestone`;
+            }
+        }
+        catch {
+            // ROADMAP.md may not exist yet; skip check
+        }
+        return {
+            found: true,
+            directory: path.relative(cwd, path.join(phasesDir, match)),
+            phase_number: phaseNumber,
+            phase_name: phaseName,
+            phase_slug: phaseName
+                ? phaseName
+                    .toLowerCase()
+                    .replace(/[^a-z0-9]+/g, '-')
+                    .replace(/^-+|-+$/g, '')
+                : null,
+            plans,
+            summaries,
+            incomplete_plans: incompletePlans,
+            has_research: hasResearch,
+            has_context: hasContext,
+            has_verification: hasVerification,
+            consistency_warning: consistencyWarning,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a path exists on the filesystem.
+ * @param cwd - Project working directory (used for resolving relative paths)
+ * @param targetPath - Path to check, relative or absolute
+ * @returns True if the path exists, false otherwise
+ */
+function pathExistsInternal(cwd, targetPath) {
+    const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(cwd, targetPath);
+    try {
+        fs.statSync(fullPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate a kebab-case slug from text, stripping non-alphanumeric characters.
+ * @param text - Input text to slugify
+ * @returns Kebab-case slug, or null if text is falsy
+ */
+function generateSlugInternal(text) {
+    if (!text)
+        return null;
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Strip shipped milestone sections wrapped in <details> blocks.
+ * These contain archived milestone content that should not contaminate
+ * active milestone parsing (phase numbers, version detection, etc.).
+ * @param content - Raw ROADMAP.md content
+ * @returns Content with <details>...</details> blocks removed
+ */
+function stripShippedSections(content) {
+    if (!content)
+        return content;
+    return content.replace(/<details>[\s\S]*?<\/details>/gi, '');
+}
+/**
+ * Extract milestone version and name from ROADMAP.md.
+ * @param cwd - Project working directory
+ * @returns Milestone info with version (e.g., 'v1.0') and name
+ */
+function getMilestoneInfo(cwd) {
+    try {
+        const roadmap = fs.readFileSync(path.join(cwd, '.planning', 'ROADMAP.md'), 'utf-8');
+        const active = stripShippedSections(roadmap);
+        // Strategy 1: Find "(in progress)" milestone from bullet list
+        const inProgressMatch = active.match(/-\s+(v[\d.]+)\s+([^\n(]+?)\s*\(in progress\)/im);
+        if (inProgressMatch) {
+            return { version: inProgressMatch[1], name: inProgressMatch[2].trim() };
+        }
+        // Strategy 2: Last non-shipped milestone bullet
+        const bulletRegex = /-\s+(v[\d.]+)\s+([^\n(]+?)(?:\s*\(([^)]*)\))?\s*$/gim;
+        let lastNonShipped = null;
+        let bm;
+        while ((bm = bulletRegex.exec(active)) !== null) {
+            const status = bm[3] || '';
+            if (!/shipped/i.test(status)) {
+                lastNonShipped = { version: bm[1], name: bm[2].trim() };
+            }
+        }
+        if (lastNonShipped)
+            return lastNonShipped;
+        // Strategy 3: Active heading "## ... vX.Y.Z ... (In Progress)"
+        const headingMatch = active.match(/##\s*.*?(v\d+\.\d+(?:\.\d+)?)\s*[:\s]+([^\n(]+)/);
+        if (headingMatch) {
+            return { version: headingMatch[1], name: headingMatch[2].trim() };
+        }
+        // Strategy 4: Fallback -- first version found (with 3-part support)
+        const versionMatch = active.match(/v(\d+\.\d+(?:\.\d+)?)/);
+        return {
+            version: versionMatch ? versionMatch[0] : 'v1.0',
+            name: 'milestone',
+        };
+    }
+    catch {
+        return { version: 'v1.0', name: 'milestone' };
+    }
+}
+/**
+ * Resolve model name from a config object without disk I/O.
+ * When cwd is provided, resolves to backend-specific model name.
+ * When cwd is omitted, returns abstract tier name (backward compatible).
+ * @param config - Configuration object with model_profile field
+ * @param agentType - Agent type key to look up in MODEL_PROFILES
+ * @param cwd - Optional project working directory for backend-specific resolution
+ * @param options - Optional overrides. When options.effectiveTierOverride is set,
+ *   it replaces the MODEL_PROFILES lookup entirely. Callers that omit this parameter
+ *   get identical behavior to before (backward compatible).
+ * @returns Model name (e.g., 'opus', 'sonnet', 'haiku', or backend-specific name)
+ */
+function resolveModelForAgent(config, agentType, cwd, options) {
+    const profile = (config.model_profile || 'balanced').toLowerCase();
+    const agentModels = MODEL_PROFILES[agentType];
+    const baseTier = agentModels
+        ? agentModels[profile] || agentModels['balanced'] || 'sonnet'
+        : 'sonnet';
+    // Use override when provided; otherwise fall back to MODEL_PROFILES lookup
+    const tier = options?.effectiveTierOverride || baseTier;
+    // If cwd provided, resolve to backend-specific model name
+    if (cwd) {
+        const backend = detectBackend(cwd);
+        return resolveBackendModel(backend, tier, config, cwd);
+    }
+    // Backward compatible: no cwd means return tier name (existing behavior)
+    return tier;
+}
+/**
+ * Resolve effort level for a given agent type from project configuration.
+ * Returns null if the backend does not support effort levels.
+ * @param config - Project configuration
+ * @param agentType - Agent type key (e.g., 'grd-executor', 'grd-planner')
+ * @param cwd - Optional project working directory for backend detection
+ * @returns Effort level string ('low', 'medium', 'high') or null if unsupported
+ */
+function resolveEffortForAgent(config, agentType, cwd) {
+    const backend = cwd ? detectBackend(cwd) : 'claude';
+    const caps = getBackendCapabilities(backend);
+    if (!caps.effort)
+        return null;
+    const profile = (config.model_profile || 'balanced');
+    return resolveEffortLevel(agentType, profile);
+}
+// ─── Config Drift Validator ───────────────────────────────────────────────────
+/**
+ * Known config keys with their default values, organized for drift detection.
+ * Each entry has: key (dot-path for nested keys), default value, and the gd settings
+ * command to fix it.
+ */
+// Codex r2 P2: `gd settings` tool-mode only accepts token_profile and
+// phase_complete_llm_fallback. All other keys must use `gd config-set
+// <dot.path> <value>` (canonical route at lib/cli/index.ts:42), so emit
+// runnable commands for those instead of broken `gd settings ...` hints.
+const CONFIG_DRIFT_KEYS = [
+    { key: 'token_profile', default: 'balanced', fix: 'gd settings token_profile balanced' },
+    // v0.4 Phase 1: effort axis (tool-mode settings key, alongside the other two).
+    { key: 'effort', default: 'balanced', fix: 'gd settings effort balanced' },
+    { key: 'phase_complete_llm_fallback', default: false, fix: 'gd settings phase_complete_llm_fallback false' },
+    { key: 'autonomous_mode', default: false, fix: 'gd config-set autonomous_mode false' },
+    { key: 'branching_strategy', default: 'none', fix: 'gd config-set branching_strategy none' },
+    { key: 'scheduler.idle_timeout_seconds', default: 900, fix: 'gd config-set scheduler.idle_timeout_seconds 900' },
+    { key: 'scheduler.budget_pressure_thresholds', default: { warning: 0.6, high: 0.8, critical: 0.95 }, fix: 'gd config-set scheduler.budget_pressure_thresholds \'{"warning":0.6,"high":0.8,"critical":0.95}\'' },
+    // Codex r27 P2: cmdHealth uses DEFAULT_WEIGHTS from lib/drift.ts
+    // (0.5/0.3/0.2) when `drift` is missing. The fix command must
+    // materialize the same runtime default so users don't accidentally
+    // change drift-scoring semantics by applying it.
+    { key: 'drift', default: { weights: { goal: 0.5, constraint: 0.3, ontology: 0.2 }, threshold: 0.3 }, fix: 'gd config-set drift \'{"weights":{"goal":0.5,"constraint":0.3,"ontology":0.2},"threshold":0.3}\'' },
+    { key: 'autopilot', default: {}, fix: 'gd config-set autopilot \'{}\'' },
+];
+/**
+ * Validate config.json against the current schema defaults, identifying keys that
+ * were added after initial `gd init` and are missing from the user's config.
+ *
+ * @param cwd - Project working directory
+ * @returns DriftReport with missing keys, fix commands, and deprecated keys
+ */
+function validateConfigDrift(cwd) {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    let parsed = {};
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Config doesn't exist or is malformed — all keys are "missing"
+    }
+    const missing = [];
+    for (const entry of CONFIG_DRIFT_KEYS) {
+        // Support dot-path for nested keys (e.g. "scheduler.idle_timeout_seconds")
+        const parts = entry.key.split('.');
+        let cur = parsed;
+        for (const part of parts) {
+            if (cur === null || typeof cur !== 'object') {
+                cur = undefined;
+                break;
+            }
+            cur = cur[part];
+        }
+        if (cur === undefined) {
+            missing.push({ key: entry.key, default: entry.default, fix_command: entry.fix });
+        }
+    }
+    return {
+        missing_keys: missing,
+        deprecated_keys: [],
+        total_checks: CONFIG_DRIFT_KEYS.length,
+    };
+}
+// ─── Exports ─────────────────────────────────────────────────────────────────
+module.exports = {
+    // Node built-ins (re-exported for convenience)
+    fs,
+    path,
+    os,
+    execFileSync,
+    // Constants
+    GIT_ALLOWED_COMMANDS,
+    GIT_BLOCKED_COMMANDS,
+    GIT_BLOCKED_FLAGS,
+    MODEL_PROFILES,
+    CODE_EXTENSIONS,
+    // Helpers
+    parseIncludeFlag,
+    safeReadFile,
+    safeReadMarkdown,
+    safeReadJSON,
+    extractMarkdownSection,
+    loadConfig,
+    isGitIgnored,
+    execGit,
+    normalizePhaseName,
+    findCodeFiles,
+    // Input validation
+    validatePhaseName,
+    validateFilePath,
+    validateGitRef,
+    // CLI argument validation
+    validatePhaseArg,
+    validateFileArg,
+    validateSubcommand,
+    validateRequiredArg,
+    // Caching
+    createRunCache,
+    // Phase directory utilities
+    findPhaseDir,
+    parsePhaseNumber,
+    // Directory walking
+    walkJsFiles,
+    // Output
+    output,
+    error,
+    debugLog,
+    // Compound helpers
+    resolveModelInternal,
+    findPhaseInternal,
+    pathExistsInternal,
+    generateSlugInternal,
+    getMilestoneInfo,
+    stripShippedSections,
+    resolveModelForAgent,
+    resolveEffortForAgent,
+    levenshteinDistance,
+    findClosestCommand,
+    clearPhaseCache,
+    validateConfigDrift,
+    // v0.4 Phase 1: effort axis
+    EFFORT_PROFILES,
+    resolveEffortKnob,
+};
+//# sourceMappingURL=utils.js.map