@lsctech/polaris 0.5.8 → 0.5.9

package/dist/autoresearch/sol-run-health-bridge.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * SOL → run-health bridge.
+ *
+ * Evaluates SOL score reports against operator-configured thresholds and,
+ * when policy enables it, appends run-health symptoms so that Medic can be
+ * engaged even when no worker explicitly wrote symptoms.
+ *
+ * Design rules:
+ *   - SOL is ADVISORY by default. No symptoms are created unless the operator
+ *     sets `sol.thresholds.enabled = true` AND at least one policy flag
+ *     (`createRunHealthReport` or `requireMedic`) is true.
+ *   - Symptoms reference the SOL evidence file as their source; they do NOT
+ *     mutate raw metric artifacts.
+ *   - Each threshold crossing produces exactly one symptom per evaluation.
+ *     Re-evaluating the same run does not duplicate symptoms because the
+ *     symptom id encodes the threshold name.
+ *   - Never throws — threshold evaluation must not block the run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSolThresholdCrossings = detectSolThresholdCrossings;
+exports.evaluateSolThresholds = evaluateSolThresholds;
+const index_js_1 = require("../run-health/index.js");
+// ── Defaults ─────────────────────────────────────────────────────────────────
+const DEFAULT_LOW_COMPOSITE_SCORE = 0.4;
+const DEFAULT_QC_REPAIR_LOOP_FAILURE_STATUSES = [
+    "max-rounds",
+    "medic-referral",
+    "all-providers-failed",
+];
+const DEFAULT_REPEATED_PROVIDER_FAILURES = 3;
+const DEFAULT_FOREMAN_INTERVENTION_COUNT = 2;
+const DEFAULT_STALE_WRONG_RUN_TELEMETRY = true;
+const DEFAULT_VALIDATION_FAILURES = 2;
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function makeSolSourceActor() {
+    return { role: "sol" };
+}
+function makeSolSymptom(crossing) {
+    return {
+        // Deterministic id: code only (no UUID) so repeated evaluations of the
+        // same run are idempotent — the same threshold crossing produces the
+        // same id, and a caller that deduplicates by id will skip the duplicate.
+        // ponytail: when run-health supports upsert-by-id, switch to that.
+        id: `sol:${crossing.code}`,
+        severity: solThresholdSeverity(crossing.code),
+        code: crossing.code,
+        message: crossing.message,
+        source_actor: makeSolSourceActor(),
+        evidence_refs: crossing.evidenceRefs,
+        occurred_at: new Date().toISOString(),
+    };
+}
+function solThresholdSeverity(code) {
+    switch (code) {
+        case "sol-qc-repair-loop-failure":
+        case "sol-repeated-provider-failures":
+            return "high";
+        case "sol-low-composite-score":
+        case "sol-high-foreman-intervention":
+        case "sol-validation-failures":
+            return "medium";
+        case "sol-stale-wrong-run-telemetry":
+            return "high";
+        default:
+            return "medium";
+    }
+}
+function upsertSolSymptom(runId, clusterId, symptom, repoRoot) {
+    const existing = (0, index_js_1.readRunHealthReport)(runId, repoRoot);
+    if (!existing) {
+        (0, index_js_1.createRunHealthReport)({
+            runId,
+            clusterId,
+            firstSymptom: symptom,
+            sourceActor: makeSolSourceActor(),
+            repoRoot,
+        });
+    }
+    else {
+        // Deduplicate: skip if a symptom with the same id already exists
+        if (existing.symptoms.some((s) => s.id === symptom.id)) {
+            return;
+        }
+        (0, index_js_1.appendSymptom)(runId, symptom, repoRoot);
+    }
+}
+// ── Threshold evaluation ──────────────────────────────────────────────────────
+/**
+ * Detect which thresholds are crossed given the SOL score report.
+ * Returns an array of crossing descriptors without any I/O side effects.
+ */
+function detectSolThresholdCrossings(scoreReport, thresholdsConfig, evidencePaths) {
+    const crossings = [];
+    const lowCompositeThreshold = thresholdsConfig.low_composite_score ?? DEFAULT_LOW_COMPOSITE_SCORE;
+    const qcFailureStatuses = thresholdsConfig.qc_repair_loop_failure_statuses ?? DEFAULT_QC_REPAIR_LOOP_FAILURE_STATUSES;
+    const providerFailureThreshold = thresholdsConfig.repeated_provider_failures ?? DEFAULT_REPEATED_PROVIDER_FAILURES;
+    const interventionThreshold = thresholdsConfig.foreman_intervention_count ?? DEFAULT_FOREMAN_INTERVENTION_COUNT;
+    const checkStaleWrongRun = thresholdsConfig.stale_wrong_run_telemetry ?? DEFAULT_STALE_WRONG_RUN_TELEMETRY;
+    const validationFailureThreshold = thresholdsConfig.validation_failures ?? DEFAULT_VALIDATION_FAILURES;
+    // 1. Low composite score
+    if (scoreReport.run_composite_score !== null &&
+        scoreReport.run_composite_score < lowCompositeThreshold) {
+        crossings.push({
+            code: "sol-low-composite-score",
+            message: `SOL run composite score ${scoreReport.run_composite_score.toFixed(4)} is below ` +
+                `configured threshold ${lowCompositeThreshold} — run health may be degraded.`,
+            evidenceRefs: evidencePaths,
+        });
+    }
+    // 2. QC repair-loop failure state
+    const foremanReport = scoreReport.foreman;
+    const qcRepairLoopDetail = foremanReport.qc_repair_loop?.detail ?? "";
+    for (const status of qcFailureStatuses) {
+        if (qcRepairLoopDetail.includes(`status=${status}`)) {
+            crossings.push({
+                code: "sol-qc-repair-loop-failure",
+                message: `SOL evidence shows QC repair loop reached failure status "${status}" — ` +
+                    `Medic consultation is recommended.`,
+                evidenceRefs: evidencePaths,
+            });
+            break; // One symptom per run for QC repair-loop failures
+        }
+    }
+    // Also detect via qc_repair_loop score == 0
+    if (foremanReport.qc_repair_loop?.score !== null &&
+        foremanReport.qc_repair_loop?.score === 0 &&
+        crossings.every((c) => c.code !== "sol-qc-repair-loop-failure")) {
+        crossings.push({
+            code: "sol-qc-repair-loop-failure",
+            message: `SOL evidence shows QC repair loop score 0.0 (worst outcome) — ` +
+                `Medic consultation is recommended.`,
+            evidenceRefs: evidencePaths,
+        });
+    }
+    // 3. Repeated provider failures — inferred from worker composite scores ≤ 0
+    //    and workers_failed count (available through foreman scores proxy).
+    const failedWorkers = Object.values(scoreReport.workers).filter((w) => w.composite_score !== null && w.composite_score <= 0);
+    if (failedWorkers.length >= providerFailureThreshold) {
+        crossings.push({
+            code: "sol-repeated-provider-failures",
+            message: `SOL evidence shows ${failedWorkers.length} worker(s) with zero composite score ` +
+                `(threshold: ${providerFailureThreshold}) — possible repeated provider failures.`,
+            evidenceRefs: evidencePaths,
+        });
+    }
+    // 4. High Foreman intervention count
+    // intervention.score: 0.0 = user_intervened, 0.5 = foreman_intervened
+    const interventionScore = foremanReport.intervention?.score;
+    if (interventionScore !== null && interventionScore !== undefined) {
+        // pre_analysis dimension uses escalation_events as a proxy
+        // intervention score < 0.5 means foreman_intervened; 0.0 means user_intervened
+        // We use the foreman.pre_analysis detail to extract escalation_events
+        const preAnalysisDetail = foremanReport.pre_analysis?.detail ?? "";
+        const escalationMatch = /escalation_events=(\d+)/.exec(preAnalysisDetail);
+        const escalationEvents = escalationMatch ? parseInt(escalationMatch[1], 10) : 0;
+        if (escalationEvents > interventionThreshold) {
+            crossings.push({
+                code: "sol-high-foreman-intervention",
+                message: `SOL evidence shows ${escalationEvents} escalation event(s) ` +
+                    `(threshold: ${interventionThreshold}) — possible Foreman intervention loop.`,
+                evidenceRefs: evidencePaths,
+            });
+        }
+    }
+    // 5. Stale / wrong-run telemetry
+    // Detected via foreman.dispatch and foreman.duration dimension details
+    if (checkStaleWrongRun) {
+        const dispatchDetail = foremanReport.dispatch?.detail ?? "";
+        const durationDetail = foremanReport.duration?.detail ?? "";
+        const hasRedispatch = /redispatched=\d+\//.exec(dispatchDetail);
+        const redispatchCount = hasRedispatch
+            ? parseInt(/redispatched=(\d+)/.exec(dispatchDetail)?.[1] ?? "0", 10)
+            : 0;
+        // dispatch_epoch >> continue_epoch suggests wrong-run telemetry
+        const dispatchEpochMatch = /dispatch_epoch=(\d+)/.exec(durationDetail);
+        const continueEpochMatch = /continue_epoch=(\d+)/.exec(durationDetail);
+        const dispatchEpoch = dispatchEpochMatch ? parseInt(dispatchEpochMatch[1], 10) : 0;
+        const continueEpoch = continueEpochMatch ? parseInt(continueEpochMatch[1], 10) : 0;
+        const epochOverhead = dispatchEpoch > 0 ? dispatchEpoch - (continueEpoch + 1) : 0;
+        if (redispatchCount >= providerFailureThreshold || epochOverhead >= 3) {
+            crossings.push({
+                code: "sol-stale-wrong-run-telemetry",
+                message: `SOL evidence suggests stale or wrong-run telemetry: ` +
+                    `redispatched=${redispatchCount}, epoch_overhead=${epochOverhead}. ` +
+                    `This pattern is consistent with the POL-509 wrong-run failure mode.`,
+                evidenceRefs: evidencePaths,
+            });
+        }
+    }
+    // 6. Validation failures
+    const validationFailedWorkers = Object.values(scoreReport.workers).filter((w) => w.validation?.score !== null && w.validation?.score === 0);
+    if (validationFailedWorkers.length >= validationFailureThreshold) {
+        crossings.push({
+            code: "sol-validation-failures",
+            message: `SOL evidence shows ${validationFailedWorkers.length} worker(s) with validation failures ` +
+                `(threshold: ${validationFailureThreshold}).`,
+            evidenceRefs: evidencePaths,
+        });
+    }
+    return crossings;
+}
+/**
+ * Evaluate SOL score thresholds and, when policy enables it, append
+ * run-health symptoms for each crossing.
+ *
+ * Advisory only by default. To activate run-health writes:
+ *   `sol.thresholds.enabled = true` AND one of:
+ *   `sol.thresholds.policy.createRunHealthReport = true`
+ *   `sol.thresholds.policy.requireMedic = true`
+ *
+ * Never throws — threshold evaluation must not block the run.
+ */
+function evaluateSolThresholds(params) {
+    const { runId, clusterId, scoreReport, evidencePaths = [], thresholdsConfig, repoRoot } = params;
+    const crossings = detectSolThresholdCrossings(scoreReport, thresholdsConfig, evidencePaths);
+    const policyEnabled = thresholdsConfig.enabled === true;
+    const createReport = thresholdsConfig.policy?.createRunHealthReport === true;
+    const requireMedic = thresholdsConfig.policy?.requireMedic === true;
+    const shouldWrite = policyEnabled && (createReport || requireMedic);
+    if (!shouldWrite || crossings.length === 0) {
+        return { crossings, symptomsAppended: 0, medicRequired: false };
+    }
+    let symptomsAppended = 0;
+    let medicDecisionWritten = false;
+    try {
+        for (const crossing of crossings) {
+            upsertSolSymptom(runId, clusterId, makeSolSymptom(crossing), repoRoot);
+            symptomsAppended++;
+        }
+        // If requireMedic is true, set medic_consult to pending so finalize gate fires.
+        if (requireMedic && crossings.length > 0) {
+            (0, index_js_1.markMedicDecision)(runId, { status: "pending" }, repoRoot);
+            medicDecisionWritten = true;
+        }
+    }
+    catch {
+        // Threshold evaluation must never block the run.
+        // ponytail: surface write errors to telemetry in a future pass
+    }
+    return {
+        crossings,
+        symptomsAppended,
+        medicRequired: medicDecisionWritten,
+    };
+}

package/dist/cli/medic.js

@@ -5,6 +5,10 @@ const commander_1 = require("commander");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const chart_id_js_1 = require("../medic/chart-id.js");
+const loader_js_1 = require("../config/loader.js");
+const terminal_cli_js_1 = require("../loop/adapters/terminal-cli.js");
+const run_health_consult_js_1 = require("../medic/run-health-consult.js");
+const treatment_packets_js_1 = require("../medic/treatment-packets.js");
 function createMedicCommand(options = {}) {
     const repoRootDefault = options.repoRoot ?? (0, node_path_1.resolve)(process.cwd());
     const medic = new commander_1.Command("medic")
@@ -34,6 +38,67 @@ function createMedicCommand(options = {}) {
             process.exit(1);
         }
     }));
+    medic
+        .command("run-health-consult")
+        .description("Run a Medic run-health consult from a packet file")
+        .requiredOption("--packet-file <path>", "Path to MedicRunHealthPacket JSON")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .action(async (cmdOptions) => {
+        const repoRoot = cmdOptions.repoRoot;
+        let packet;
+        try {
+            packet = JSON.parse((0, node_fs_1.readFileSync)(cmdOptions.packetFile, "utf-8"));
+        }
+        catch (err) {
+            process.stderr.write(`medic run-health-consult error: cannot read packet: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+            return;
+        }
+        if (packet.role !== "medic-run-health") {
+            process.stderr.write(`medic run-health-consult error: packet role must be \"medic-run-health\", got \"${packet.role}\"\n`);
+            process.exit(1);
+            return;
+        }
+        const config = (0, loader_js_1.loadConfig)(repoRoot);
+        const adapter = new terminal_cli_js_1.TerminalCliAdapter(config.execution);
+        // Use shared provider resolution logic: prefer rotation, fall back to first provider
+        const providerName = (config.execution.rotation && config.execution.rotation.length > 0)
+            ? config.execution.rotation[0]
+            : Object.keys(config.execution.providers ?? {})[0] ?? "terminal-cli";
+        // Get current branch from git
+        let branch = "main";
+        try {
+            const { execFileSync } = require("node:child_process");
+            branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+                cwd: repoRoot,
+                encoding: "utf-8",
+            }).trim();
+        }
+        catch {
+            // Fall back to main if git fails
+        }
+        try {
+            const result = await (0, run_health_consult_js_1.runMedicRunHealthConsult)({
+                packet,
+                repoRoot,
+                stateFile: packet.cluster_state_path,
+                telemetryFile: packet.telemetry_path,
+                branch,
+                dryRun: false,
+                dispatchTreatmentWorkerFn: (input) => (0, treatment_packets_js_1.dispatchTreatmentWorker)({
+                    ...input,
+                    repoRoot,
+                    dispatch: (workerPacket) => adapter.dispatch(workerPacket, { provider: providerName }),
+                }),
+            });
+            (0, node_fs_1.writeFileSync)(packet.result_path, JSON.stringify(result, null, 2), "utf-8");
+            process.stdout.write(`Medic run-health consult result written to ${packet.result_path}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`medic run-health-consult error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
     return medic;
 }
 function createChart(options) {

package/dist/config/defaults.js

@@ -55,6 +55,9 @@ exports.DEFAULT_CONFIG = {
         requireMapValidation: true,
         requireSchemaValidation: true,
         archiveRunSnapshot: true,
+        medic: {
+            bypassPolicy: "none",
+        },
     },
     tracker: {
         lifecyclePolicy: {

package/dist/config/validator.js

@@ -548,6 +548,20 @@ function validateConfig(config) {
                     result.errors.push("finalize.archiveRunSnapshot must be a boolean");
                 }
             }
+            if ("medic" in config.finalize && config.finalize.medic !== undefined) {
+                if (!isPlainObject(config.finalize.medic)) {
+                    result.valid = false;
+                    result.errors.push("finalize.medic must be an object");
+                }
+                else {
+                    if ("bypassPolicy" in config.finalize.medic && config.finalize.medic.bypassPolicy !== undefined) {
+                        if (!isString(config.finalize.medic.bypassPolicy) || !["none", "cli"].includes(config.finalize.medic.bypassPolicy)) {
+                            result.valid = false;
+                            result.errors.push('finalize.medic.bypassPolicy must be one of "none" or "cli"');
+                        }
+                    }
+                }
+            }
         }
     }
     // tracker
@@ -1197,6 +1211,128 @@ function validateConfig(config) {
             }
         }
     }
+    // run_health
+    if ("run_health" in config && config.run_health !== undefined) {
+        if (!isPlainObject(config.run_health)) {
+            result.valid = false;
+            result.errors.push("run_health must be an object");
+        }
+        else {
+            if ("foreman_symptoms" in config.run_health && config.run_health.foreman_symptoms !== undefined) {
+                if (!isPlainObject(config.run_health.foreman_symptoms)) {
+                    result.valid = false;
+                    result.errors.push("run_health.foreman_symptoms must be an object");
+                }
+                else {
+                    if ("enabled" in config.run_health.foreman_symptoms && config.run_health.foreman_symptoms.enabled !== undefined) {
+                        if (!isBoolean(config.run_health.foreman_symptoms.enabled)) {
+                            result.valid = false;
+                            result.errors.push("run_health.foreman_symptoms.enabled must be a boolean");
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // sol
+    if ("sol" in config && config.sol !== undefined) {
+        if (!isPlainObject(config.sol)) {
+            result.valid = false;
+            result.errors.push("sol must be an object");
+        }
+        else {
+            if ("history" in config.sol && config.sol.history !== undefined) {
+                if (!isPlainObject(config.sol.history)) {
+                    result.valid = false;
+                    result.errors.push("sol.history must be an object");
+                }
+                else {
+                    if ("enabled" in config.sol.history && config.sol.history.enabled !== undefined) {
+                        if (!isBoolean(config.sol.history.enabled)) {
+                            result.valid = false;
+                            result.errors.push("sol.history.enabled must be a boolean");
+                        }
+                    }
+                    if ("path" in config.sol.history && config.sol.history.path !== undefined) {
+                        if (!isString(config.sol.history.path)) {
+                            result.valid = false;
+                            result.errors.push("sol.history.path must be a string");
+                        }
+                    }
+                }
+            }
+            if ("thresholds" in config.sol && config.sol.thresholds !== undefined) {
+                if (!isPlainObject(config.sol.thresholds)) {
+                    result.valid = false;
+                    result.errors.push("sol.thresholds must be an object");
+                }
+                else {
+                    if ("enabled" in config.sol.thresholds && config.sol.thresholds.enabled !== undefined) {
+                        if (!isBoolean(config.sol.thresholds.enabled)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.enabled must be a boolean");
+                        }
+                    }
+                    if ("policy" in config.sol.thresholds && config.sol.thresholds.policy !== undefined) {
+                        if (!isPlainObject(config.sol.thresholds.policy)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.policy must be an object");
+                        }
+                        else {
+                            if ("createRunHealthReport" in config.sol.thresholds.policy && config.sol.thresholds.policy.createRunHealthReport !== undefined) {
+                                if (!isBoolean(config.sol.thresholds.policy.createRunHealthReport)) {
+                                    result.valid = false;
+                                    result.errors.push("sol.thresholds.policy.createRunHealthReport must be a boolean");
+                                }
+                            }
+                            if ("requireMedic" in config.sol.thresholds.policy && config.sol.thresholds.policy.requireMedic !== undefined) {
+                                if (!isBoolean(config.sol.thresholds.policy.requireMedic)) {
+                                    result.valid = false;
+                                    result.errors.push("sol.thresholds.policy.requireMedic must be a boolean");
+                                }
+                            }
+                        }
+                    }
+                    if ("low_composite_score" in config.sol.thresholds && config.sol.thresholds.low_composite_score !== undefined) {
+                        if (!isNumber(config.sol.thresholds.low_composite_score) || !inRange(config.sol.thresholds.low_composite_score, 0, 1)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.low_composite_score must be a number between 0 and 1");
+                        }
+                    }
+                    if ("qc_repair_loop_failure_statuses" in config.sol.thresholds && config.sol.thresholds.qc_repair_loop_failure_statuses !== undefined) {
+                        if (!isStringArray(config.sol.thresholds.qc_repair_loop_failure_statuses)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.qc_repair_loop_failure_statuses must be an array of strings");
+                        }
+                    }
+                    if ("repeated_provider_failures" in config.sol.thresholds && config.sol.thresholds.repeated_provider_failures !== undefined) {
+                        if (!isPositiveInteger(config.sol.thresholds.repeated_provider_failures)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.repeated_provider_failures must be a positive integer");
+                        }
+                    }
+                    if ("foreman_intervention_count" in config.sol.thresholds && config.sol.thresholds.foreman_intervention_count !== undefined) {
+                        if (!isNonNegativeInteger(config.sol.thresholds.foreman_intervention_count)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.foreman_intervention_count must be a non-negative integer");
+                        }
+                    }
+                    if ("stale_wrong_run_telemetry" in config.sol.thresholds && config.sol.thresholds.stale_wrong_run_telemetry !== undefined) {
+                        if (!isBoolean(config.sol.thresholds.stale_wrong_run_telemetry)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.stale_wrong_run_telemetry must be a boolean");
+                        }
+                    }
+                    if ("validation_failures" in config.sol.thresholds && config.sol.thresholds.validation_failures !== undefined) {
+                        if (!isNonNegativeInteger(config.sol.thresholds.validation_failures)) {
+                            result.valid = false;
+                            result.errors.push("sol.thresholds.validation_failures must be a non-negative integer");
+                        }
+                    }
+                }
+            }
+        }
+    }
     // unknown top-level fields -> warnings
     const knownKeys = new Set([
         "version",
@@ -1213,6 +1349,11 @@ function validateConfig(config) {
         "budget",
         "compact",
         "qc",
+        "sol",
+        "run_health",
+        "orchestration",
+        "skill_packet",
+        "simplicity",
     ]);
     for (const key of Object.keys(config)) {
         if (!knownKeys.has(key)) {

package/dist/finalize/index.js

@@ -34,6 +34,7 @@ const local_graph_js_1 = require("../tracker/local-graph.js");
 const index_js_1 = require("../tracker/sync/index.js");
 const finalize_evidence_js_1 = require("../loop/finalize-evidence.js");
 const delivery_integrity_js_1 = require("./delivery-integrity.js");
+const medic_gate_js_1 = require("./medic-gate.js");
 const index_js_2 = require("../qc/index.js");
 function getBranch(repoRoot) {
     try {
@@ -368,7 +369,7 @@ async function runQcGate(options) {
     process.exit(1);
 }
 async function runFinalize(options) {
-    const { repoRoot, stateFile, dryRun, skipDelivery, skipLibrarian } = options;
+    const { repoRoot, stateFile, dryRun, skipDelivery, skipLibrarian, bypassMedicReason } = options;
     const config = (0, loader_js_1.loadConfig)(repoRoot);
     // Step 1: polaris map update --changed
     console.log("[1/14] Updating map..."); // Step count updated
@@ -580,6 +581,29 @@ async function runFinalize(options) {
         process.stderr.write(`finalize aborted: authoritative child state mismatch.\n${authChildResult.reason}\n`);
         process.exit(1);
     }
+    // Step 5.11: Run-health Medic gate
+    // After all worker/QC evidence is available and before any final commit, push,
+    // PR creation, or tracker update, require a Medic consultation decision for any
+    // run that recorded health symptoms.
+    {
+        console.log("[5.11/14] Checking run-health Medic gate...");
+        const bypassPolicy = config.finalize?.medic?.bypassPolicy ?? "none";
+        if (dryRun && bypassMedicReason && bypassPolicy === "cli") {
+            console.warn(`Dry run: would write Medic bypass to run-health report for run "${state.run_id}" (reason: ${bypassMedicReason}).`);
+        }
+        const medicBlocker = (0, medic_gate_js_1.validateMedicGate)({
+            runId: state.run_id,
+            repoRoot,
+            bypassReason: bypassMedicReason,
+            bypassPolicy,
+            dryRun,
+        });
+        if (medicBlocker) {
+            process.stderr.write(`finalize aborted: run-health Medic gate failed.\n${medicBlocker}\n`);
+            process.exit(1);
+        }
+        console.log("[5.11/14] Run-health Medic gate passed.");
+    }
     // Step 6: Tracker Reconciliation
     // LinearAdapter is sync-in only; only McpBridgeAdapter supports full reconciliation.
     const trackerType = config.tracker?.adapter;
@@ -715,11 +739,19 @@ function createFinalizeCommand(handlers = {}) {
         .option("--dry-run", "non-mutating preview: validate and generate report without committing or pushing")
         .option("--skip-delivery", "perform local finalize steps only; skip push/PR/Linear/archive")
         .option("--skip-librarian", "skip the Closeout Librarian gate (backward compatibility only)")
+        .option("--bypass-medic <reason>", "bypass the run-health Medic gate (requires finalize.medic.bypassPolicy=cli)")
         .action((options) => {
         const repoRoot = options.repoRoot;
         const stateFile = options.stateFile ??
             (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
-        finalizeHandler({ repoRoot, stateFile, dryRun: options.dryRun, skipDelivery: options.skipDelivery, skipLibrarian: options.skipLibrarian })
+        finalizeHandler({
+            repoRoot,
+            stateFile,
+            dryRun: options.dryRun,
+            skipDelivery: options.skipDelivery,
+            skipLibrarian: options.skipLibrarian,
+            bypassMedicReason: options.bypassMedic,
+        })
             .catch((err) => {
             process.stderr.write(`finalize error: ${err instanceof Error ? err.message : String(err)}\n`);
             process.exit(1);

package/dist/finalize/medic-gate.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMedicGate = validateMedicGate;
+const index_js_1 = require("../run-health/index.js");
+/**
+ * Validates that a run with a run-health report either has a Medic decision or
+ * an explicit, allowed policy bypass. Returns `null` when finalize may proceed;
+ * returns a human-readable blocker string otherwise.
+ *
+ * Fails closed: a report that exists but lacks a Medic decision/bypass blocks
+ * final commit, push, PR creation, and tracker update.
+ */
+function validateMedicGate(options) {
+    const { runId, repoRoot, bypassReason, bypassPolicy = "none", dryRun = false } = options;
+    const reportPath = (0, index_js_1.getRunHealthReportPath)(runId, repoRoot);
+    const report = (0, index_js_1.readRunHealthReport)(runId, repoRoot);
+    // No report means no symptoms were recorded — gate does not apply.
+    if (!report)
+        return null;
+    if ((0, index_js_1.isMedicGateSatisfied)(report))
+        return null;
+    if (bypassReason) {
+        if (bypassPolicy !== "cli") {
+            return (`Run-health report at ${reportPath} requires Medic consultation, but a CLI bypass is not allowed ` +
+                `by finalize.medic.bypassPolicy (current: "${bypassPolicy}").`);
+        }
+        if (!dryRun) {
+            (0, index_js_1.markBypassed)(runId, {
+                reason: bypassReason,
+                bypassed_by: process.env.USER ?? process.env.LOGNAME ?? "operator",
+                bypassed_at: new Date().toISOString(),
+            }, repoRoot);
+        }
+        return null;
+    }
+    const bypassHint = bypassPolicy === "cli"
+        ? `To bypass this gate, use --bypass-medic "<reason>".`
+        : `Bypass is not enabled by finalize.medic.bypassPolicy (current: "${bypassPolicy}").`;
+    return (`Run-health report at ${reportPath} has recorded symptoms and requires a Medic consultation decision ` +
+        `(medic_consult.status "resolved" or "bypassed", or an explicit policy_bypass) before finalize can commit, push, ` +
+        `create a PR, or update the tracker.\n${bypassHint}`);
+}