@jokerized/getresearchdone 0.4.1

package/dist/lib/commands/select-candidate.d.ts

@@ -0,0 +1,128 @@
+export interface DeadEndEntry {
+    slug: string;
+    hypothesis: string;
+    forbidden_terms: string[];
+}
+export interface ExtendedAxes {
+    must_haves_coverage: number;
+    verification_commands: number;
+    estimated_tokens: number;
+}
+export interface AdvisoryWarning {
+    dead_end_slug: string;
+    jaccard: number;
+}
+export interface HardFailReason {
+    kind: 'slug_citation' | 'forbidden_term';
+    dead_end_slug: string;
+    matched: string;
+}
+export interface ClusterInfo {
+    /** Cluster index (assigned among DEAD-ENDS survivors only). */
+    cluster_id: number;
+    /** True if this candidate is its cluster's representative (highest score). */
+    is_representative: boolean;
+    /**
+     * relPath of the representative this candidate was merged into. null when
+     * this candidate IS the representative. Hard-failed candidates are not
+     * clustered and carry no ClusterInfo.
+     */
+    merged_into: string | null;
+}
+export interface ExtendedCandidateResult {
+    path: string;
+    relPath: string;
+    base_score: number;
+    total_score: number;
+    base_breakdown: import('../plan-tournament').ScoreBreakdown;
+    extended: ExtendedAxes;
+    hard_fail: HardFailReason | null;
+    advisory_warnings: AdvisoryWarning[];
+    /** v0.4 Phase 4: set for DEAD-ENDS survivors after proximity clustering. */
+    cluster?: ClusterInfo;
+}
+export interface SelectionResult {
+    phase: string;
+    phaseDir: string;
+    candidates: ExtendedCandidateResult[];
+    winner: ExtendedCandidateResult | null;
+    promoted_to: string | null;
+    audit_trail_path: string;
+}
+export interface SelectCandidateOptions {
+    /** Skip the rename PLAN-N.md → PLAN.md and the audit-trail write. */
+    dryRun?: boolean;
+    /** Override the milestone (default: read from STATE.md). */
+    milestone?: string;
+    /**
+     * Allow the verification_commands axis to execute commands. Default
+     * false (codex review P1) — the axis would otherwise run
+     * planner-authored commands during selection, before a plan is chosen.
+     */
+    runVerificationCommands?: boolean;
+    /**
+     * Overwrite an existing resolved PLAN.md when promoting the winner.
+     * Default false (codex review P2) — refuse to clobber a PLAN.md that
+     * a human or a prior selection already resolved.
+     */
+    force?: boolean;
+}
+/**
+ * Parse DEAD-ENDS.md into structured entries. Format: per-entry
+ * `## <slug>` header followed by a fenced YAML block. We only need
+ * slug, hypothesis, and forbidden_terms for selector input.
+ */
+export declare function parseDeadEnds(content: string): DeadEndEntry[];
+/**
+ * Scan a candidate's text content for DEAD-ENDS violations. Returns the
+ * first hard-fail reason found (slug citation OR forbidden_term exact
+ * match) and any advisory Jaccard warnings.
+ */
+export declare function checkDeadEnds(candidateText: string, deadEnds: DeadEndEntry[]): {
+    hardFail: HardFailReason | null;
+    advisory: AdvisoryWarning[];
+};
+/**
+ * Score the candidate's coverage of REQUIREMENTS.md must_haves artifacts.
+ * Each found artifact = +1, each missing = -10. Negative scores remain
+ * finite — they're NOT a hard-fail (DEAD-ENDS is the only hard-fail path).
+ */
+export declare function scoreMustHavesCoverage(candidateText: string, candidateFm: Record<string, unknown>, requirementsText: string | null): number;
+/**
+ * Run each command from the candidate's `verification_commands:` YAML
+ * frontmatter and return pass-rate as a score in [0, 10].
+ *
+ * SECURITY (codex review P1): verification commands are planner-authored
+ * input that would otherwise execute during candidate *selection* —
+ * before a plan is even chosen, so a candidate that will be REJECTED
+ * could still run code. Two guards:
+ *   1. The axis is OFF unless `enabled` is true (selectCandidate reads
+ *      `plan_selection.run_verification_commands` from config, default
+ *      false). When off, returns 0 and runs nothing.
+ *   2. When on, only allowlisted executables run, and argv[0] must be a
+ *      bare name (no `/` or `\\`) so `/bin/rm` / `./rm` cannot bypass.
+ *
+ * Each command is split on whitespace; argv[0] is the binary, the rest
+ * positional args. No shell — no pipes, redirects, or glob expansion.
+ * Per-command 10s timeout with SIGKILL (codex review P2: SIGTERM lets a
+ * child ignore the signal and hang selection).
+ */
+export declare function scoreVerificationCommands(candidateFm: Record<string, unknown>, cwd: string, enabled: boolean): number;
+/**
+ * Cheap token estimate: whitespace-separated words × 1.3. Used only
+ * as a tiebreaker when total scores tie exactly.
+ */
+export declare function estimateTokens(text: string): number;
+export declare function scoreExtendedCandidate(candidatePath: string, cwd: string, phase: string, context: {
+    deadEnds: DeadEndEntry[];
+    requirementsText: string | null;
+    /** Whether the verification_commands axis may execute commands. */
+    runVerificationCommands: boolean;
+}): ExtendedCandidateResult;
+export declare function selectCandidate(cwd: string, phaseNum: string, opts?: SelectCandidateOptions): SelectionResult;
+export declare function cmdSelectCandidate(cwd: string, phaseNum: string, opts: {
+    dryRun?: boolean;
+    force?: boolean;
+    runVerificationCommands?: boolean;
+}, raw: boolean): void;
+//# sourceMappingURL=select-candidate.d.ts.map

package/dist/lib/commands/select-candidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-candidate.d.ts","sourceRoot":"","sources":["../../../lib/commands/select-candidate.ts"],"names":[],"mappings":"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"}

package/dist/lib/commands/select-candidate.js

@@ -0,0 +1,518 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDeadEnds = parseDeadEnds;
+exports.checkDeadEnds = checkDeadEnds;
+exports.scoreMustHavesCoverage = scoreMustHavesCoverage;
+exports.scoreVerificationCommands = scoreVerificationCommands;
+exports.estimateTokens = estimateTokens;
+exports.scoreExtendedCandidate = scoreExtendedCandidate;
+exports.selectCandidate = selectCandidate;
+exports.cmdSelectCandidate = cmdSelectCandidate;
+/**
+ * GRD Commands/SelectCandidate — v0.4 Phase 3 deterministic selector.
+ *
+ * Picks one PLAN-N.md candidate from a phase directory and promotes it
+ * to canonical PLAN.md. Extends the v0.3.x lib/plan-tournament.ts
+ * scorer with four real-cost / real-signal axes per
+ * .planning/milestones/v0.4/phases/03-deterministic-selector/PLAN.md:
+ *
+ *   1. must_haves coverage — REQUIREMENTS.md artifacts referenced by
+ *      the candidate's files_modified + task body
+ *   2. DEAD-ENDS hard-fail — slug citation OR forbidden_terms exact
+ *      case-insensitive match; Jaccard advisory only
+ *   3. verification_commands axis — runs deterministic checks declared
+ *      in the candidate's frontmatter (defaults to 0 when absent)
+ *   4. cost tiebreaker — fewer estimated tokens wins on score parity
+ *
+ * Pipeline:
+ *   1. Find PLAN-N.md files in phase dir.
+ *   2. Score each with the extended axes.
+ *   3. Filter out -Infinity (DEAD-ENDS violations).
+ *   4. Sort by total score; cost tiebreaker on parity.
+ *   5. Rename winner to PLAN.md.
+ *   6. Write PLAN-SELECTION.json audit trail (all candidates, all
+ *      axis scores, hard-fail reasons, Jaccard advisory warnings).
+ *
+ * No LLM call anywhere. GENOME heuristic "no LLM-judged scoring on the
+ * core execution path" honored.
+ *
+ * Security: verification_commands run via argv-array spawnSync (no
+ * shell). Commands are split on whitespace; pipes / redirects / glob
+ * expansion are NOT supported (planner declares one binary + args
+ * per command).
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync, } = require('child_process');
+const { findPhaseDir, getMilestoneInfo, safeReadFile, safeReadMarkdown, output, error, } = require('../utils');
+const { extractFrontmatter, } = require('../frontmatter');
+const { scorePlanCandidate, DEFAULT_WEIGHTS, extractPlanVocabulary, clusterByJaccard, PROXIMITY_THRESHOLD, } = require('../plan-tournament');
+const { atomicWriteFileSync, } = require('../autopilot-waves');
+// ─── DEAD-ENDS parsing ────────────────────────────────────────────────────
+/**
+ * Parse DEAD-ENDS.md into structured entries. Format: per-entry
+ * `## <slug>` header followed by a fenced YAML block. We only need
+ * slug, hypothesis, and forbidden_terms for selector input.
+ */
+function parseDeadEnds(content) {
+    const entries = [];
+    const sectionRe = /^## ([a-z0-9][a-z0-9-]*)\s*$/gm;
+    const matches = [];
+    let m;
+    while ((m = sectionRe.exec(content)) !== null) {
+        matches.push({ slug: m[1], start: m.index });
+    }
+    for (let i = 0; i < matches.length; i++) {
+        const start = matches[i].start;
+        const end = i + 1 < matches.length ? matches[i + 1].start : content.length;
+        const section = content.slice(start, end);
+        const yamlMatch = section.match(/```yaml\s*\n([\s\S]*?)\n```/);
+        if (!yamlMatch)
+            continue;
+        const yaml = yamlMatch[1];
+        const slug = matches[i].slug;
+        const hypothesis = extractScalar(yaml, 'hypothesis') ?? '';
+        const forbidden_terms = extractStringList(yaml, 'forbidden_terms');
+        entries.push({ slug, hypothesis, forbidden_terms });
+    }
+    return entries;
+}
+function extractScalar(yaml, key) {
+    const re = new RegExp(`^${key}:\\s*"([^"\\\\]*(?:\\\\.[^"\\\\]*)*)"\\s*$`, 'm');
+    const m = yaml.match(re);
+    if (!m)
+        return null;
+    return m[1].replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+function extractStringList(yaml, key) {
+    const re = new RegExp(`^${key}:\\s*\\n((?: {2}- .*\\n?)+)`, 'm');
+    const m = yaml.match(re);
+    if (!m)
+        return [];
+    const out = [];
+    for (const line of m[1].split('\n')) {
+        const item = line.match(/^ {2}- "([^"\\]*(?:\\.[^"\\]*)*)"\s*$/);
+        if (item)
+            out.push(item[1].replace(/\\"/g, '"').replace(/\\\\/g, '\\'));
+    }
+    return out;
+}
+// ─── DEAD-ENDS hard-fail check ────────────────────────────────────────────
+/**
+ * Scan a candidate's text content for DEAD-ENDS violations. Returns the
+ * first hard-fail reason found (slug citation OR forbidden_term exact
+ * match) and any advisory Jaccard warnings.
+ */
+function checkDeadEnds(candidateText, deadEnds) {
+    const lower = candidateText.toLowerCase();
+    const advisory = [];
+    let hardFail = null;
+    for (const entry of deadEnds) {
+        if (!hardFail) {
+            // Codex review P2: match the slug case-insensitively and on word
+            // boundaries so `Elo-Rated-Plan-Tournament` still confesses while an
+            // unrelated longer token merely *containing* the slug does not
+            // false-positive.
+            if (slugCited(lower, entry.slug)) {
+                hardFail = { kind: 'slug_citation', dead_end_slug: entry.slug, matched: entry.slug };
+            }
+            else {
+                for (const term of entry.forbidden_terms) {
+                    if (lower.includes(term.toLowerCase())) {
+                        hardFail = { kind: 'forbidden_term', dead_end_slug: entry.slug, matched: term };
+                        break;
+                    }
+                }
+            }
+        }
+        // Advisory Jaccard always computed for the audit trail (regardless of
+        // hard-fail). Threshold 0.6 is a v0.4 guess; Phase 5 may tune from data.
+        const j = jaccard(tokens(candidateText), tokens(entry.hypothesis));
+        if (j >= 0.6) {
+            advisory.push({ dead_end_slug: entry.slug, jaccard: j });
+        }
+    }
+    return { hardFail, advisory };
+}
+const STOP = new Set([
+    'the', 'and', 'for', 'with', 'from', 'into', 'over', 'this', 'that',
+    'are', 'was', 'were', 'has', 'have', 'had', 'will', 'would', 'should',
+    'phase', 'plan', 'summary', 'roadmap', 'task', 'goal',
+]);
+/**
+ * True when `slug` appears in `lowerText` (already lower-cased) bounded by
+ * non-slug-characters on both sides. Slug chars are [a-z0-9-]; a boundary
+ * is any character outside that class (or string edge). This avoids the
+ * substring false-positive where a slug is a fragment of a longer token.
+ */
+function slugCited(lowerText, slug) {
+    const slugLower = slug.toLowerCase();
+    let from = 0;
+    for (;;) {
+        const idx = lowerText.indexOf(slugLower, from);
+        if (idx === -1)
+            return false;
+        const before = idx === 0 ? '' : lowerText[idx - 1];
+        const after = idx + slugLower.length >= lowerText.length ? '' : lowerText[idx + slugLower.length];
+        const isSlugChar = (c) => c !== '' && /[a-z0-9-]/.test(c);
+        if (!isSlugChar(before) && !isSlugChar(after))
+            return true;
+        from = idx + 1;
+    }
+}
+function tokens(text) {
+    const set = new Set();
+    const matches = text.toLowerCase().match(/[a-z0-9][a-z0-9_-]{2,}/g);
+    if (!matches)
+        return set;
+    for (const t of matches) {
+        if (STOP.has(t))
+            continue;
+        set.add(t);
+    }
+    return set;
+}
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const x of a)
+        if (b.has(x))
+            intersection++;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+// ─── must_haves coverage axis ─────────────────────────────────────────────
+/**
+ * Score the candidate's coverage of REQUIREMENTS.md must_haves artifacts.
+ * Each found artifact = +1, each missing = -10. Negative scores remain
+ * finite — they're NOT a hard-fail (DEAD-ENDS is the only hard-fail path).
+ */
+function scoreMustHavesCoverage(candidateText, candidateFm, requirementsText) {
+    if (!requirementsText)
+        return 0;
+    const required = extractRequiredArtifacts(requirementsText);
+    if (required.length === 0)
+        return 0;
+    const filesModified = Array.isArray(candidateFm['files_modified'])
+        ? candidateFm['files_modified'].map(String)
+        : [];
+    const haystack = candidateText + '\n' + filesModified.join('\n');
+    let score = 0;
+    for (const art of required) {
+        if (haystack.includes(art))
+            score += 1;
+        else
+            score -= 10;
+    }
+    return score;
+}
+function extractRequiredArtifacts(requirementsText) {
+    // Best-effort pull of `must_haves.artifacts:` YAML list.
+    const re = /must_haves:\s*\n(?:\s+\w+:\s*\n(?:\s+- .*\n)*)*\s+artifacts:\s*\n((?:\s+- .*\n)+)/;
+    const m = requirementsText.match(re);
+    const out = [];
+    if (m) {
+        for (const line of m[1].split('\n')) {
+            const item = line.match(/^\s+- ["']?([^"'\n]+?)["']?\s*$/);
+            if (item)
+                out.push(item[1].trim());
+        }
+    }
+    return out;
+}
+// ─── verification_commands axis ───────────────────────────────────────────
+/**
+ * Allowlist of permitted verification-command executables. Codex review
+ * P1: a blocklist of dangerous binaries is bypassable via absolute paths
+ * (`/bin/rm`), relative paths (`./rm`), and unlisted destructive tools.
+ * v0.4 uses an ALLOWLIST instead — only these deterministic check tools
+ * may run, and only when the bare name matches (no path separators).
+ */
+const VERIFICATION_ALLOWLIST = new Set([
+    'npx', 'npm', 'pnpm', 'yarn', 'node', 'tsx', 'tsc', 'eslint', 'jest', 'prettier',
+]);
+/**
+ * Run each command from the candidate's `verification_commands:` YAML
+ * frontmatter and return pass-rate as a score in [0, 10].
+ *
+ * SECURITY (codex review P1): verification commands are planner-authored
+ * input that would otherwise execute during candidate *selection* —
+ * before a plan is even chosen, so a candidate that will be REJECTED
+ * could still run code. Two guards:
+ *   1. The axis is OFF unless `enabled` is true (selectCandidate reads
+ *      `plan_selection.run_verification_commands` from config, default
+ *      false). When off, returns 0 and runs nothing.
+ *   2. When on, only allowlisted executables run, and argv[0] must be a
+ *      bare name (no `/` or `\\`) so `/bin/rm` / `./rm` cannot bypass.
+ *
+ * Each command is split on whitespace; argv[0] is the binary, the rest
+ * positional args. No shell — no pipes, redirects, or glob expansion.
+ * Per-command 10s timeout with SIGKILL (codex review P2: SIGTERM lets a
+ * child ignore the signal and hang selection).
+ */
+function scoreVerificationCommands(candidateFm, cwd, enabled) {
+    if (!enabled)
+        return 0;
+    const cmds = candidateFm['verification_commands'];
+    if (!Array.isArray(cmds) || cmds.length === 0)
+        return 0;
+    let passed = 0;
+    let total = 0;
+    for (const raw of cmds) {
+        if (typeof raw !== 'string' || !raw.trim())
+            continue;
+        total++;
+        const argv = raw.trim().split(/\s+/);
+        const exe = argv[0];
+        if (!exe)
+            continue;
+        // Reject path separators: an absolute / relative path bypasses the
+        // allowlist (e.g. `/bin/rm`, `./rm`, `..\\rm`).
+        if (exe.includes('/') || exe.includes('\\'))
+            continue;
+        if (!VERIFICATION_ALLOWLIST.has(exe))
+            continue;
+        try {
+            const result = spawnSync(exe, argv.slice(1), {
+                cwd,
+                timeout: 10000,
+                killSignal: 'SIGKILL',
+                stdio: 'pipe',
+            });
+            if (result.status === 0)
+                passed++;
+        }
+        catch {
+            // Treat exceptions as failure.
+        }
+    }
+    if (total === 0)
+        return 0;
+    return Math.round((passed / total) * 10);
+}
+// ─── Cost tiebreaker ──────────────────────────────────────────────────────
+/**
+ * Cheap token estimate: whitespace-separated words × 1.3. Used only
+ * as a tiebreaker when total scores tie exactly.
+ */
+function estimateTokens(text) {
+    const words = text.split(/\s+/).filter((s) => s.length > 0).length;
+    return Math.round(words * 1.3);
+}
+// ─── Per-candidate scoring ─────────────────────────────────────────────────
+function scoreExtendedCandidate(candidatePath, cwd, phase, context) {
+    const relPath = path.relative(cwd, candidatePath);
+    const content = safeReadFile(candidatePath);
+    if (!content) {
+        return {
+            path: candidatePath,
+            relPath,
+            base_score: 0,
+            total_score: -Infinity,
+            base_breakdown: {
+                completeness: 0,
+                goal_alignment: 0,
+                hypothesis_quality: 0,
+                conciseness: 0,
+            },
+            extended: { must_haves_coverage: 0, verification_commands: 0, estimated_tokens: 0 },
+            hard_fail: { kind: 'slug_citation', dead_end_slug: '(file-unreadable)', matched: '' },
+            advisory_warnings: [],
+        };
+    }
+    const base = scorePlanCandidate(candidatePath, cwd, phase, DEFAULT_WEIGHTS);
+    const fm = extractFrontmatter(content);
+    const { hardFail, advisory } = checkDeadEnds(content, context.deadEnds);
+    const mustHavesScore = scoreMustHavesCoverage(content, fm, context.requirementsText);
+    const verificationScore = scoreVerificationCommands(fm, cwd, context.runVerificationCommands);
+    const tokenEst = estimateTokens(content);
+    // Composition: base [0,1] + must_haves (potentially negative) + verification [0,1].
+    // Hard-fail short-circuits to -Infinity so the audit trail still records all axes.
+    const totalScore = hardFail
+        ? -Infinity
+        : base.score + mustHavesScore + verificationScore / 10;
+    return {
+        path: candidatePath,
+        relPath,
+        base_score: base.score,
+        total_score: totalScore,
+        base_breakdown: base.breakdown,
+        extended: {
+            must_haves_coverage: mustHavesScore,
+            verification_commands: verificationScore,
+            estimated_tokens: tokenEst,
+        },
+        hard_fail: hardFail,
+        advisory_warnings: advisory,
+    };
+}
+// ─── Pipeline orchestrator ─────────────────────────────────────────────────
+function selectCandidate(cwd, phaseNum, opts = {}) {
+    const milestone = opts.milestone ?? getMilestoneInfo(cwd).version;
+    const phasesDir = path.join(cwd, '.planning', 'milestones', milestone, 'phases');
+    const phaseDirName = findPhaseDir(phasesDir, phaseNum);
+    if (!phaseDirName) {
+        error(`phase ${phaseNum} not found under ${phasesDir}`);
+    }
+    const phaseDir = path.join(phasesDir, phaseDirName);
+    const candidates = listCandidateFiles(phaseDir);
+    if (candidates.length === 0) {
+        error(`no PLAN-N.md candidates found in ${phaseDir}`);
+    }
+    const deadEndsText = safeReadMarkdown(path.join(cwd, '.planning', 'DEAD-ENDS.md'));
+    const deadEnds = deadEndsText ? parseDeadEnds(deadEndsText) : [];
+    const requirementsText = safeReadMarkdown(path.join(phaseDir, 'REQUIREMENTS.md'));
+    const runVerificationCommands = opts.runVerificationCommands ?? false;
+    const scored = candidates.map((p) => scoreExtendedCandidate(p, cwd, phaseNum, {
+        deadEnds,
+        requirementsText,
+        runVerificationCommands,
+    }));
+    // v0.4 Phase 4 pipeline ordering (codex r1 P1 #4):
+    //   1. DEAD-ENDS hard-fail already happened during scoring (-Infinity).
+    //   2. Cluster the SURVIVORS by vocabulary Jaccard so near-clones don't
+    //      each consume a full scoring slot. Hard-failed candidates are never
+    //      clustered — a violator cannot eliminate an innocent clustermate.
+    //   3. Each cluster's representative = its highest-scoring member.
+    //   4. Winner = highest-scoring representative across clusters.
+    const survivorIdx = scored
+        .map((s, i) => (isFinite(s.total_score) ? i : -1))
+        .filter((i) => i >= 0);
+    // Compare two scored candidates: higher total_score wins; cheaper (fewer
+    // estimated tokens) breaks ties. Returns the index (into `scored`) of the
+    // better one.
+    const better = (a, b) => {
+        if (scored[a].total_score !== scored[b].total_score) {
+            return scored[a].total_score > scored[b].total_score ? a : b;
+        }
+        return scored[a].extended.estimated_tokens <= scored[b].extended.estimated_tokens ? a : b;
+    };
+    const representativeIdx = [];
+    if (survivorIdx.length > 0) {
+        const survivorVocabs = survivorIdx.map((i) => {
+            const content = safeReadFile(scored[i].path) ?? '';
+            return extractPlanVocabulary(content, extractFrontmatter(content));
+        });
+        const clusters = clusterByJaccard(survivorVocabs, PROXIMITY_THRESHOLD);
+        clusters.forEach((memberPositions, clusterId) => {
+            // memberPositions index into survivorIdx; map to scored indices.
+            const memberScoredIdx = memberPositions.map((p) => survivorIdx[p]);
+            let repScored = memberScoredIdx[0];
+            for (const m of memberScoredIdx)
+                repScored = better(repScored, m);
+            representativeIdx.push(repScored);
+            for (const m of memberScoredIdx) {
+                scored[m].cluster = {
+                    cluster_id: clusterId,
+                    is_representative: m === repScored,
+                    merged_into: m === repScored ? null : scored[repScored].relPath,
+                };
+            }
+        });
+    }
+    // Winner = best representative. (Representatives are the only candidates
+    // eligible to be promoted — merged-away members and hard-fails are out.)
+    let winner = null;
+    if (representativeIdx.length > 0) {
+        let best = representativeIdx[0];
+        for (const r of representativeIdx)
+            best = better(best, r);
+        winner = scored[best];
+    }
+    // Present `scored` deterministically for the audit: total_score desc,
+    // cheaper first on parity. -Infinity (hard-fails) sink to the bottom.
+    scored.sort((a, b) => {
+        if (a.total_score !== b.total_score) {
+            if (!isFinite(a.total_score) && isFinite(b.total_score))
+                return 1;
+            if (isFinite(a.total_score) && !isFinite(b.total_score))
+                return -1;
+            return b.total_score - a.total_score;
+        }
+        return a.extended.estimated_tokens - b.extended.estimated_tokens;
+    });
+    let promotedTo = null;
+    if (winner && !opts.dryRun) {
+        const planPath = path.join(phaseDir, 'PLAN.md');
+        // Codex review P2: refuse to clobber an already-resolved PLAN.md unless
+        // --force. Autopilot never hits this (hasMultipleCandidates requires no
+        // resolved PLAN.md), but the public CLI could otherwise destroy a plan.
+        if (fs.existsSync(planPath) && !opts.force) {
+            error(`${path.relative(cwd, planPath)} already exists. Refusing to overwrite a resolved plan. ` +
+                `Re-run with --force to replace it, or remove it first.`);
+        }
+        promotedTo = planPath;
+        const winnerContent = fs.readFileSync(winner.path, 'utf-8');
+        atomicWriteFileSync(promotedTo, winnerContent);
+    }
+    const auditPath = path.join(phaseDir, 'PLAN-SELECTION.json');
+    const audit = {
+        phase: phaseNum,
+        phase_dir: phaseDir,
+        milestone,
+        timestamp: new Date().toISOString(),
+        candidates: scored,
+        winner: winner ? winner.relPath : null,
+        promoted_to: promotedTo ? path.relative(cwd, promotedTo) : null,
+        dead_ends_loaded: deadEnds.length,
+        requirements_loaded: requirementsText !== null,
+        proximity_threshold: PROXIMITY_THRESHOLD,
+        hard_failed: scored.filter((s) => s.hard_fail !== null).map((s) => s.relPath),
+        clusters_formed: representativeIdx.length,
+    };
+    if (!opts.dryRun) {
+        atomicWriteFileSync(auditPath, JSON.stringify(audit, null, 2));
+    }
+    return {
+        phase: phaseNum,
+        phaseDir,
+        candidates: scored,
+        winner,
+        promoted_to: promotedTo,
+        audit_trail_path: auditPath,
+    };
+}
+function listCandidateFiles(phaseDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(phaseDir);
+    }
+    catch {
+        return [];
+    }
+    const candidateRe = /^PLAN-(\d+)\.md$/;
+    const matches = [];
+    for (const name of entries) {
+        const m = name.match(candidateRe);
+        if (m)
+            matches.push({ idx: parseInt(m[1], 10), name });
+    }
+    matches.sort((a, b) => a.idx - b.idx);
+    return matches.map((m) => path.join(phaseDir, m.name));
+}
+// ─── CLI entry ─────────────────────────────────────────────────────────────
+function cmdSelectCandidate(cwd, phaseNum, opts, raw) {
+    const result = selectCandidate(cwd, phaseNum, {
+        dryRun: opts.dryRun,
+        force: opts.force,
+        runVerificationCommands: opts.runVerificationCommands,
+    });
+    output(result, raw, result.winner
+        ? `winner: ${result.winner.relPath} (score ${result.winner.total_score.toFixed(3)})` +
+            (result.promoted_to
+                ? ` → promoted to ${path.relative(cwd, result.promoted_to)}`
+                : ' (dry-run, no promotion)')
+        : 'no viable winner (all candidates hard-failed)');
+}
+module.exports = {
+    parseDeadEnds,
+    checkDeadEnds,
+    scoreMustHavesCoverage,
+    scoreVerificationCommands,
+    estimateTokens,
+    scoreExtendedCandidate,
+    selectCandidate,
+    cmdSelectCandidate,
+};
+//# sourceMappingURL=select-candidate.js.map