@lsctech/polaris 0.5.7 → 0.5.9

package/dist/autoresearch/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatRecommendationsCli = exports.recommendationToProposal = exports.recommendationsToProposals = exports.generateRecommendations = exports.formatReportCli = exports.generateReport = exports.getHistoryFilePath = exports.buildSnapshot = exports.loadSnapshots = exports.appendSnapshot = exports.computeSolScoreReport = exports.computeWorkerScore = exports.computeForemanScore = exports.aggregateSolEvidence = exports.routeProposals = exports.validateDiagnosisReport = exports.loadDiagnosisReport = exports.buildProposals = exports.FIX_ZONE_MAP = exports.ALL_GATES = exports.buildDiagnosisHints = exports.computeScore = exports.loadRunArtifacts = exports.scoreRun = exports.assertPolarisDevContext = exports.isPolarisDevContext = void 0;
+exports.scorecardToRecommendationSummary = exports.formatRecommendationsCli = exports.recommendationToProposal = exports.recommendationsToProposals = exports.generateRecommendations = exports.renderSolMarkdown = exports.getSolMarkdownReportPath = exports.getScorecardPath = exports.getEvaluationRecordPath = exports.getSolReportsDir = exports.getSolScorecardsDir = exports.getSolEvaluationsDir = exports.writeSolMarkdownReport = exports.writeScorecardSet = exports.writeScorecard = exports.writeEvaluationRecord = exports.buildEvaluationRecord = exports.formatReportCli = exports.generateReport = exports.getHistoryFilePath = exports.buildSnapshot = exports.loadSnapshots = exports.appendSnapshot = exports.buildRoutingRawMetrics = exports.buildModelRawMetrics = exports.buildProviderRawMetrics = exports.buildWorkerRawMetrics = exports.buildForemanRawMetrics = exports.computeAllScorecards = exports.computeRoutingScorecard = exports.computeModelScorecard = exports.computeProviderScorecard = exports.computeWorkerScorecard = exports.computeForemanScorecard = exports.computeSolScoreReport = exports.computeWorkerScore = exports.computeForemanScore = exports.aggregateSolEvidence = exports.routeProposals = exports.validateDiagnosisReport = exports.loadDiagnosisReport = exports.buildProposals = exports.FIX_ZONE_MAP = exports.ALL_GATES = exports.buildDiagnosisHints = exports.computeScore = exports.loadRunArtifacts = exports.scoreRun = exports.assertPolarisDevContext = exports.isPolarisDevContext = void 0;
+exports.scorecardsToRecommendationSummaries = void 0;
 var dev_gate_js_1 = require("./dev-gate.js");
 Object.defineProperty(exports, "isPolarisDevContext", { enumerable: true, get: function () { return dev_gate_js_1.isPolarisDevContext; } });
 Object.defineProperty(exports, "assertPolarisDevContext", { enumerable: true, get: function () { return dev_gate_js_1.assertPolarisDevContext; } });
@@ -24,6 +25,18 @@ var sol_scorer_js_1 = require("./sol-scorer.js");
 Object.defineProperty(exports, "computeForemanScore", { enumerable: true, get: function () { return sol_scorer_js_1.computeForemanScore; } });
 Object.defineProperty(exports, "computeWorkerScore", { enumerable: true, get: function () { return sol_scorer_js_1.computeWorkerScore; } });
 Object.defineProperty(exports, "computeSolScoreReport", { enumerable: true, get: function () { return sol_scorer_js_1.computeSolScoreReport; } });
+var sol_scorecard_calculator_js_1 = require("./sol-scorecard-calculator.js");
+Object.defineProperty(exports, "computeForemanScorecard", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.computeForemanScorecard; } });
+Object.defineProperty(exports, "computeWorkerScorecard", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.computeWorkerScorecard; } });
+Object.defineProperty(exports, "computeProviderScorecard", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.computeProviderScorecard; } });
+Object.defineProperty(exports, "computeModelScorecard", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.computeModelScorecard; } });
+Object.defineProperty(exports, "computeRoutingScorecard", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.computeRoutingScorecard; } });
+Object.defineProperty(exports, "computeAllScorecards", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.computeAllScorecards; } });
+Object.defineProperty(exports, "buildForemanRawMetrics", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.buildForemanRawMetrics; } });
+Object.defineProperty(exports, "buildWorkerRawMetrics", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.buildWorkerRawMetrics; } });
+Object.defineProperty(exports, "buildProviderRawMetrics", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.buildProviderRawMetrics; } });
+Object.defineProperty(exports, "buildModelRawMetrics", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.buildModelRawMetrics; } });
+Object.defineProperty(exports, "buildRoutingRawMetrics", { enumerable: true, get: function () { return sol_scorecard_calculator_js_1.buildRoutingRawMetrics; } });
 var sol_history_js_1 = require("./sol-history.js");
 Object.defineProperty(exports, "appendSnapshot", { enumerable: true, get: function () { return sol_history_js_1.appendSnapshot; } });
 Object.defineProperty(exports, "loadSnapshots", { enumerable: true, get: function () { return sol_history_js_1.loadSnapshots; } });
@@ -32,8 +45,24 @@ Object.defineProperty(exports, "getHistoryFilePath", { enumerable: true, get: fu
 var sol_report_js_1 = require("./sol-report.js");
 Object.defineProperty(exports, "generateReport", { enumerable: true, get: function () { return sol_report_js_1.generateReport; } });
 Object.defineProperty(exports, "formatReportCli", { enumerable: true, get: function () { return sol_report_js_1.formatReportCli; } });
+var sol_evaluation_writer_js_1 = require("./sol-evaluation-writer.js");
+Object.defineProperty(exports, "buildEvaluationRecord", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.buildEvaluationRecord; } });
+Object.defineProperty(exports, "writeEvaluationRecord", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.writeEvaluationRecord; } });
+Object.defineProperty(exports, "writeScorecard", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.writeScorecard; } });
+Object.defineProperty(exports, "writeScorecardSet", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.writeScorecardSet; } });
+Object.defineProperty(exports, "writeSolMarkdownReport", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.writeSolMarkdownReport; } });
+Object.defineProperty(exports, "getSolEvaluationsDir", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.getSolEvaluationsDir; } });
+Object.defineProperty(exports, "getSolScorecardsDir", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.getSolScorecardsDir; } });
+Object.defineProperty(exports, "getSolReportsDir", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.getSolReportsDir; } });
+Object.defineProperty(exports, "getEvaluationRecordPath", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.getEvaluationRecordPath; } });
+Object.defineProperty(exports, "getScorecardPath", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.getScorecardPath; } });
+Object.defineProperty(exports, "getSolMarkdownReportPath", { enumerable: true, get: function () { return sol_evaluation_writer_js_1.getSolMarkdownReportPath; } });
+var sol_report_renderer_js_1 = require("./sol-report-renderer.js");
+Object.defineProperty(exports, "renderSolMarkdown", { enumerable: true, get: function () { return sol_report_renderer_js_1.renderSolMarkdown; } });
 var sol_recommendations_js_1 = require("./sol-recommendations.js");
 Object.defineProperty(exports, "generateRecommendations", { enumerable: true, get: function () { return sol_recommendations_js_1.generateRecommendations; } });
 Object.defineProperty(exports, "recommendationsToProposals", { enumerable: true, get: function () { return sol_recommendations_js_1.recommendationsToProposals; } });
 Object.defineProperty(exports, "recommendationToProposal", { enumerable: true, get: function () { return sol_recommendations_js_1.recommendationToProposal; } });
 Object.defineProperty(exports, "formatRecommendationsCli", { enumerable: true, get: function () { return sol_recommendations_js_1.formatRecommendationsCli; } });
+Object.defineProperty(exports, "scorecardToRecommendationSummary", { enumerable: true, get: function () { return sol_recommendations_js_1.scorecardToRecommendationSummary; } });
+Object.defineProperty(exports, "scorecardsToRecommendationSummaries", { enumerable: true, get: function () { return sol_recommendations_js_1.scorecardsToRecommendationSummaries; } });

package/dist/autoresearch/sol-evaluation-writer.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * SOL evaluation artifact writer.
+ *
+ * Persists machine-readable SOL evaluation records and scorecard snapshots
+ * to deterministic local paths. All writes are append-only / generation-safe:
+ * existing source run evidence is never read or rewritten.
+ *
+ * Output locations:
+ *   - Evaluations:   .polaris/sol/evaluations/<run-id>.json
+ *   - Scorecards:    .polaris/sol/scorecards/<subject>/<scorecard-id>.json
+ *   - Reports:       smartdocs/reports/sol/<run-id>-evaluation-report.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSolEvaluationsDir = getSolEvaluationsDir;
+exports.getSolScorecardsDir = getSolScorecardsDir;
+exports.getSolReportsDir = getSolReportsDir;
+exports.buildEvaluationRecord = buildEvaluationRecord;
+exports.getEvaluationRecordPath = getEvaluationRecordPath;
+exports.writeEvaluationRecord = writeEvaluationRecord;
+exports.getScorecardPath = getScorecardPath;
+exports.writeScorecard = writeScorecard;
+exports.writeScorecardSet = writeScorecardSet;
+exports.getSolMarkdownReportPath = getSolMarkdownReportPath;
+exports.writeSolMarkdownReport = writeSolMarkdownReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ──────────────────────────────────────────────
+// Paths
+// ──────────────────────────────────────────────
+const EVALUATIONS_DIR = ".polaris/sol/evaluations";
+const SCORECARDS_DIR = ".polaris/sol/scorecards";
+const REPORTS_DIR = "smartdocs/reports/sol";
+function getSolEvaluationsDir(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, EVALUATIONS_DIR);
+}
+function getSolScorecardsDir(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, SCORECARDS_DIR);
+}
+function getSolReportsDir(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, REPORTS_DIR);
+}
+// ──────────────────────────────────────────────
+// Filename safety
+// ──────────────────────────────────────────────
+function safeFilename(value) {
+    // Prevent path traversal and reserved characters while keeping readability.
+    const sanitized = value
+        .replace(/[\\/]+/g, "-")
+        .replace(/[:\?*"<>|]+/g, "-")
+        .replace(/\.{2,}/g, "-")
+        .replace(/^[.]+/, "")
+        .trim();
+    return sanitized.length > 0 ? sanitized : "unnamed";
+}
+function buildEvaluationRecord(report) {
+    return {
+        schema_version: "1.0",
+        record_type: "sol-evaluation",
+        run_id: report.run_id,
+        cluster_id: report.cluster_id,
+        scored_at: report.scored_at,
+        report,
+        generated_at: new Date().toISOString(),
+    };
+}
+function getEvaluationRecordPath(repoRoot, runId) {
+    return (0, node_path_1.join)(getSolEvaluationsDir(repoRoot), `${safeFilename(runId)}.json`);
+}
+/**
+ * Write a SOL evaluation record under .polaris/sol/evaluations/.
+ * Creates directories as needed. Overwrites only the derived record file.
+ */
+function writeEvaluationRecord(repoRoot, report) {
+    const record = buildEvaluationRecord(report);
+    const dir = getSolEvaluationsDir(repoRoot);
+    if (!(0, node_fs_1.existsSync)(dir))
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const filePath = getEvaluationRecordPath(repoRoot, report.run_id);
+    (0, node_fs_1.writeFileSync)(filePath, JSON.stringify(record, null, 2) + "\n", "utf-8");
+    return { record, path: filePath };
+}
+// ──────────────────────────────────────────────
+// Scorecard snapshots
+// ──────────────────────────────────────────────
+function scorecardSubjectDir(subject) {
+    return subject;
+}
+function getScorecardPath(repoRoot, scorecard) {
+    return (0, node_path_1.join)(getSolScorecardsDir(repoRoot), scorecardSubjectDir(scorecard.subject), `${safeFilename(scorecard.scorecard_id)}.json`);
+}
+/**
+ * Write a single scorecard snapshot under .polaris/sol/scorecards/<subject>/.
+ */
+function writeScorecard(repoRoot, scorecard) {
+    const dir = (0, node_path_1.join)(getSolScorecardsDir(repoRoot), scorecardSubjectDir(scorecard.subject));
+    if (!(0, node_fs_1.existsSync)(dir))
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const filePath = getScorecardPath(repoRoot, scorecard);
+    (0, node_fs_1.writeFileSync)(filePath, JSON.stringify(scorecard, null, 2) + "\n", "utf-8");
+    return filePath;
+}
+/**
+ * Write all scorecards in a SolScorecardSet. Returns the paths written.
+ */
+function writeScorecardSet(repoRoot, scorecardSet) {
+    const paths = [];
+    paths.push(writeScorecard(repoRoot, scorecardSet.foreman));
+    for (const s of scorecardSet.workers)
+        paths.push(writeScorecard(repoRoot, s));
+    for (const s of scorecardSet.providers)
+        paths.push(writeScorecard(repoRoot, s));
+    for (const s of scorecardSet.models)
+        paths.push(writeScorecard(repoRoot, s));
+    for (const s of scorecardSet.routing)
+        paths.push(writeScorecard(repoRoot, s));
+    return paths;
+}
+// ──────────────────────────────────────────────
+// Human-readable SmartDocs report
+// ──────────────────────────────────────────────
+function getSolMarkdownReportPath(repoRoot, runId) {
+    return (0, node_path_1.join)(getSolReportsDir(repoRoot), `${safeFilename(runId)}-evaluation-report.md`);
+}
+/**
+ * Write a rendered Markdown SOL report to smartdocs/reports/sol/.
+ */
+function writeSolMarkdownReport(repoRoot, runId, markdown) {
+    const dir = getSolReportsDir(repoRoot);
+    if (!(0, node_fs_1.existsSync)(dir))
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const filePath = getSolMarkdownReportPath(repoRoot, runId);
+    (0, node_fs_1.writeFileSync)(filePath, markdown, "utf-8");
+    return filePath;
+}

package/dist/autoresearch/sol-evidence-normalizer.js

@@ -0,0 +1,337 @@
+"use strict";
+/**
+ * SOL evidence normalizer.
+ *
+ * Materializes raw metric events (SolMetricEvent[]) and source references
+ * (SolSourceRef[]) from a loaded SolEvidence record. This is the bridge
+ * between the evidence loader and scorecard generation.
+ *
+ * Design rules:
+ *   - Never throws on missing data — absent optional fields reduce confidence.
+ *   - Source refs track every artifact that contributed evidence (present or not).
+ *   - Provider startup failures are distinguished from worker execution failures:
+ *       startup failure = provider-exhausted or selected_provider=null in router evidence
+ *       worker execution failure = worker ran but status="failed"|"error"
+ *   - Router fallback + candidate/rejection context are preserved when present.
+ *   - Missing router or QC evidence sets availability flags; no metric events
+ *     are emitted for those categories.
+ *   - Confidence: "high" when all expected source refs are available,
+ *     "medium" when some are absent, "low" when most are absent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSolEvidence = normalizeSolEvidence;
+function makeSourceRef(kind, path, available, unavailableReason) {
+    return available
+        ? { kind, path, available: true }
+        : { kind, path, available: false, unavailable_reason: unavailableReason };
+}
+function computeConfidence(refs) {
+    if (refs.length === 0)
+        return "none";
+    const available = refs.filter((r) => r.available).length;
+    const ratio = available / refs.length;
+    if (ratio >= 0.8)
+        return "high";
+    if (ratio >= 0.4)
+        return "medium";
+    if (ratio > 0)
+        return "low";
+    return "none";
+}
+// ──────────────────────────────────────────────
+// Source ref builders
+// ──────────────────────────────────────────────
+function buildSourceRefs(evidence, paths) {
+    const refs = [];
+    // Run state
+    if (paths.runStatePath) {
+        refs.push(makeSourceRef("run-state", paths.runStatePath, evidence.run.status !== null));
+    }
+    else {
+        refs.push(makeSourceRef("run-state", ".taskchain_artifacts/polaris-run/current-state.json", false, "path not resolved"));
+    }
+    // Telemetry
+    if (paths.telemetryPath) {
+        const hasTelemetry = evidence.tokens.total_worker_heartbeats > 0 || evidence.foreman.escalation_events > 0;
+        refs.push(makeSourceRef("telemetry", paths.telemetryPath, hasTelemetry));
+    }
+    else {
+        refs.push(makeSourceRef("telemetry", ".taskchain_artifacts/polaris-run/runs/<run-id>/telemetry.jsonl", false, "path not resolved"));
+    }
+    // Cluster state — available when the path was resolved (regardless of QC status)
+    if (paths.clusterStatePath) {
+        refs.push(makeSourceRef("cluster-state", paths.clusterStatePath, true));
+    }
+    else {
+        refs.push(makeSourceRef("cluster-state", `.polaris/clusters/${evidence.cluster_id ?? "unknown"}/cluster-state.json`, false, evidence.cluster_id ? "not found" : "cluster id not resolved"));
+    }
+    // Result packets (one per child with a known path)
+    for (const child of evidence.children) {
+        // Match filenames that are exactly "{child_id}.json" or start with "{child_id}-"
+        // to handle commit-suffixed names (e.g. "POL-001-abc.json") while avoiding
+        // false positives when IDs share a prefix (e.g. "1" vs "10").
+        const packetPath = paths.resultPacketPaths.find((p) => {
+            const filename = p.split('/').pop() ?? '';
+            return filename === `${child.child_id}.json` || filename.startsWith(`${child.child_id}-`);
+        });
+        const path = packetPath ?? `.polaris/clusters/${evidence.cluster_id ?? "unknown"}/results/${child.child_id}.json`;
+        refs.push(makeSourceRef("result-packet", path, packetPath !== undefined));
+    }
+    // QC artifacts
+    if (evidence.qc.availability === "available") {
+        refs.push(makeSourceRef("qc-finding", paths.qcDir ?? `.polaris/clusters/${evidence.cluster_id ?? "unknown"}/qc`, true));
+    }
+    else if (evidence.qc.availability === "future") {
+        refs.push(makeSourceRef("qc-finding", `.polaris/clusters/${evidence.cluster_id ?? "unknown"}/qc`, false, "QC not yet run for this cluster"));
+    }
+    // "unavailable" (qc-disabled): no ref emitted
+    // Run report
+    if (paths.runReportPath) {
+        refs.push(makeSourceRef("run-report", paths.runReportPath, true));
+    }
+    else {
+        refs.push(makeSourceRef("run-report", `smartdocs/reports/sol/${evidence.run_id}-evaluation-report.md`, false, "path not resolved"));
+    }
+    return refs;
+}
+// ──────────────────────────────────────────────
+// Metric event materializers
+// ──────────────────────────────────────────────
+function materializeProviderStartupFailures(evidence) {
+    if (evidence.router.availability !== "available")
+        return [];
+    return evidence.router.decisions
+        .filter((d) => d.exhausted)
+        .map((d) => ({
+        category: "provider-startup-failure",
+        run_id: evidence.run_id,
+        child_id: d.child_id || undefined,
+        provider: d.selected_provider ?? d.providers_tried[d.providers_tried.length - 1] ?? "unknown",
+        failure_reason: d.exhausted_reason,
+        providers_tried: d.providers_tried,
+        all_providers_exhausted: d.exhausted,
+    }));
+}
+function materializeRouterFallbacks(evidence) {
+    if (evidence.router.availability !== "available")
+        return [];
+    return evidence.router.decisions
+        .filter((d) => d.fallback_used && !d.exhausted)
+        .map((d) => {
+        const originalProvider = d.providers_tried[0] ?? null;
+        const fallbackProvider = d.selected_provider;
+        // Child succeeded if it has a "done" completion (check worker evidence)
+        const childResult = evidence.children.find((c) => c.child_id === d.child_id);
+        const fallbackSucceeded = childResult?.status === "done";
+        return {
+            category: "router-fallback",
+            run_id: evidence.run_id,
+            child_id: d.child_id || undefined,
+            original_provider: originalProvider,
+            fallback_provider: fallbackProvider,
+            providers_tried: d.providers_tried,
+            fallback_succeeded: fallbackSucceeded ?? false,
+            rejection_reasons: d.rejection_reasons,
+        };
+    });
+}
+function materializeWorkerExecutionFailures(evidence) {
+    // Worker execution failures: worker ran (not a startup failure) but status failed/error
+    const exhaustedChildIds = new Set(evidence.router.availability === "available"
+        ? evidence.router.decisions.filter((d) => d.exhausted).map((d) => d.child_id)
+        : []);
+    return evidence.children
+        .filter((c) => {
+        // Must be a failed/error status (not "done" or "blocked")
+        if (c.status !== "failed" && c.status !== "error")
+            return false;
+        // Exclude children where the provider never started (startup failure)
+        if (exhaustedChildIds.has(c.child_id))
+            return false;
+        return true;
+    })
+        .map((c) => {
+        const validationRecord = evidence.validation.find((v) => v.child_id === c.child_id);
+        return {
+            category: "worker-execution-failure",
+            run_id: evidence.run_id,
+            child_id: c.child_id,
+            worker_status: c.status,
+            validation: validationRecord?.outcome ?? "unknown",
+            provider: c.provider,
+            error_message: validationRecord?.error_message ?? null,
+            out_of_scope_escalation: evidence.intervention.out_of_scope_count > 0,
+            escalation_count: c.escalation_count,
+        };
+    });
+}
+function materializeValidationFailures(evidence) {
+    return evidence.validation
+        .filter((v) => v.outcome === "failed")
+        .map((v) => {
+        const childResult = evidence.children.find((c) => c.child_id === v.child_id);
+        return {
+            category: "validation-failure",
+            run_id: evidence.run_id,
+            child_id: v.child_id,
+            worker_status: childResult?.status ?? "unknown",
+            failed_commands: [], // Commands not individually tracked in SolValidationEvidence
+            passed_commands: v.passed_commands,
+            error_message: v.error_message,
+        };
+    });
+}
+function materializeQcFindings(evidence) {
+    if (evidence.qc.availability !== "available")
+        return [];
+    const events = [];
+    // Blocking open findings by severity
+    const severities = ["critical", "high", "medium", "low", "info"];
+    for (const sev of severities) {
+        const count = evidence.qc.open_by_severity[sev];
+        for (let i = 0; i < count; i++) {
+            const isHighSeverity = sev === "critical" || sev === "high";
+            events.push({
+                category: "qc-finding",
+                run_id: evidence.run_id,
+                qc_provider: Object.keys(evidence.qc.provider_breakdown)[0] ?? "unknown",
+                severity: sev,
+                blocking: isHighSeverity && evidence.qc.blocks_delivery,
+                autofixed: false,
+                repaired: false,
+                waived: false,
+                unvalidated: false,
+                summary: `Open ${sev} QC finding`,
+                attribution_confidence: isHighSeverity ? "high" : "medium",
+            });
+        }
+    }
+    // Emit a single unvalidated aggregate event when unvalidated_findings > 0
+    if (evidence.qc.unvalidated_findings > 0) {
+        const noisyProvider = evidence.qc.noisy_providers[0] ?? "unknown";
+        events.push({
+            category: "qc-finding",
+            run_id: evidence.run_id,
+            qc_provider: noisyProvider,
+            severity: "info",
+            blocking: false,
+            autofixed: false,
+            repaired: false,
+            waived: false,
+            unvalidated: true,
+            summary: `${evidence.qc.unvalidated_findings} unvalidated finding(s) from provider ${noisyProvider}`,
+            attribution_confidence: "none",
+        });
+    }
+    return events;
+}
+function materializeInterventions(evidence) {
+    const events = [];
+    if (evidence.intervention.user_intervened) {
+        // Find the children that had user interventions for child_id attribution
+        const intervened = evidence.children.filter((c) => c.user_intervened === true);
+        if (intervened.length > 0) {
+            for (const child of intervened) {
+                events.push({
+                    category: "user-intervention",
+                    run_id: evidence.run_id,
+                    child_id: child.child_id,
+                    actor: "user",
+                    intervention_type: "commit",
+                    resolved: true,
+                });
+            }
+        }
+        else {
+            events.push({
+                category: "user-intervention",
+                run_id: evidence.run_id,
+                actor: "user",
+                intervention_type: "unspecified",
+                resolved: true,
+            });
+        }
+    }
+    if (evidence.intervention.foreman_intervened) {
+        const intervened = evidence.children.filter((c) => c.foreman_intervened === true);
+        if (intervened.length > 0) {
+            for (const child of intervened) {
+                events.push({
+                    category: "foreman-intervention",
+                    run_id: evidence.run_id,
+                    child_id: child.child_id,
+                    actor: "foreman",
+                    intervention_type: "commit",
+                    resolved: true,
+                });
+            }
+        }
+        else {
+            events.push({
+                category: "foreman-intervention",
+                run_id: evidence.run_id,
+                actor: "foreman",
+                intervention_type: "unspecified",
+                resolved: true,
+            });
+        }
+    }
+    if (evidence.intervention.state_repair_required) {
+        events.push({
+            category: "foreman-intervention",
+            run_id: evidence.run_id,
+            actor: "foreman",
+            intervention_type: "state-repair",
+            resolved: false,
+        });
+    }
+    if (evidence.intervention.out_of_scope_count > 0) {
+        events.push({
+            category: "user-intervention",
+            run_id: evidence.run_id,
+            actor: "user",
+            intervention_type: "out-of-scope",
+            resolved: evidence.intervention.blocked_event_count > 0,
+        });
+    }
+    return events;
+}
+// ──────────────────────────────────────────────
+// Main entry point
+// ──────────────────────────────────────────────
+/**
+ * Normalize a loaded SolEvidence record into raw metric events and source refs.
+ *
+ * Does not throw on missing data — absent optional fields mark source refs
+ * as unavailable and reduce confidence. Missing router or QC inputs emit no
+ * events for those categories.
+ *
+ * @param evidence — already-loaded SolEvidence (from aggregateSolEvidence)
+ * @param paths    — artifact path context for source ref generation
+ * @returns SolEvidenceNormalizationResult
+ */
+function normalizeSolEvidence(evidence, paths = {
+    runStatePath: null,
+    telemetryPath: null,
+    clusterStatePath: null,
+    resultPacketPaths: [],
+    qcDir: null,
+    runReportPath: null,
+}) {
+    const source_refs = buildSourceRefs(evidence, paths);
+    const events = [
+        ...materializeProviderStartupFailures(evidence),
+        ...materializeRouterFallbacks(evidence),
+        ...materializeWorkerExecutionFailures(evidence),
+        ...materializeValidationFailures(evidence),
+        ...materializeQcFindings(evidence),
+        ...materializeInterventions(evidence),
+    ];
+    return {
+        run_id: evidence.run_id,
+        normalized_at: new Date().toISOString(),
+        events,
+        source_refs,
+        evidence_confidence: computeConfidence(source_refs),
+    };
+}

package/dist/autoresearch/sol-recommendations.js

@@ -21,6 +21,8 @@ exports.recommendationsToProposals = recommendationsToProposals;
 exports.formatRecommendationsCli = formatRecommendationsCli;
 exports.generateQcRecommendations = generateQcRecommendations;
 exports.formatQcRecommendations = formatQcRecommendations;
+exports.scorecardToRecommendationSummary = scorecardToRecommendationSummary;
+exports.scorecardsToRecommendationSummaries = scorecardsToRecommendationSummaries;
 const sol_report_js_1 = require("./sol-report.js");
 // ──────────────────────────────────────────────
 // Constants and helpers
@@ -380,3 +382,131 @@ function formatQcRecommendations(report) {
     }
     return lines.join("\n");
 }
+// ── Internal helpers ──
+function extractQptEvidence(subscores) {
+    const s = subscores.find((ss) => ss.dimension === "quality_per_token");
+    return { score: s?.score ?? null, detail: s?.detail ?? null };
+}
+function extractQcEvidence(subscores, rawMetrics) {
+    const qcSub = subscores.find((ss) => ss.dimension === "qc" || ss.dimension === "qc_repair_loop" || ss.dimension === "qc_result");
+    return {
+        qc_findings: rawMetrics.qc_total_findings,
+        blocking_findings: rawMetrics.qc_blocking_findings,
+        qc_repair_status: rawMetrics.qc_repair_loop_status,
+        qc_score: qcSub?.score ?? null,
+    };
+}
+function extractValidationEvidence(subscores, rawMetrics) {
+    const valSub = subscores.find((ss) => ss.dimension === "validation" ||
+        ss.dimension === "evidence_validation" ||
+        ss.dimension === "validation_result");
+    return {
+        validation_outcome: rawMetrics.validation_outcome,
+        passed_commands: [...(rawMetrics.passed_commands ?? [])],
+        validation_score: valSub?.score ?? null,
+    };
+}
+function deriveVerdict(scorecard, qcEvidence) {
+    const { subscores, aggregate_score, recommendation_inputs } = scorecard;
+    // Blocking QC findings always contradict.
+    if ((qcEvidence.blocking_findings ?? 0) > 0)
+        return "contradicted";
+    // confirmed_signal subscore is the strongest direct verdict signal.
+    const confirmed = subscores.find((s) => s.dimension === "confirmed_signal");
+    if (confirmed !== undefined && confirmed.score !== null) {
+        if (confirmed.score >= 0.9)
+            return "supported";
+        if (confirmed.score <= 0.1)
+            return "contradicted";
+    }
+    // Aggregate score determines verdict; intervention/router issues limit to inconclusive.
+    if (aggregate_score !== null) {
+        if (aggregate_score < 0.5)
+            return "contradicted";
+        if (aggregate_score >= 0.75 &&
+            !recommendation_inputs.intervention_detected &&
+            !recommendation_inputs.router_issue_detected) {
+            return "supported";
+        }
+    }
+    if (recommendation_inputs.intervention_detected || recommendation_inputs.router_issue_detected) {
+        return "inconclusive";
+    }
+    if (aggregate_score === null)
+        return "inconclusive";
+    if (aggregate_score >= 0.75)
+        return "supported";
+    if (aggregate_score < 0.6)
+        return "contradicted";
+    return "inconclusive";
+}
+function confidenceFromScorecard(scorecard) {
+    const { subscores, aggregate_score, recommendation_inputs } = scorecard;
+    const scoredCount = subscores.filter((s) => s.score !== null).length;
+    if (scoredCount === 0)
+        return 0.1; // minimal confidence without evidence
+    // Base: proportion of subscores with data.
+    const coverage = scoredCount / Math.max(subscores.length, 1);
+    // Small penalty when below threshold (more uncertainty in the recommendation).
+    const scorePenalty = aggregate_score !== null && recommendation_inputs.below_threshold ? 0.1 : 0;
+    return clamp01(coverage - scorePenalty);
+}
+function affectedFromScorecard(scorecard) {
+    const keys = scorecard.grouping_keys ?? {};
+    const affected = {};
+    if (keys.route)
+        affected.route = keys.route;
+    if (keys.task_type)
+        affected.task_type = keys.task_type;
+    if (keys.role)
+        affected.role = keys.role;
+    if (keys.provider)
+        affected.provider = keys.provider;
+    if (keys.model)
+        affected.model = keys.model;
+    // Subject-level key as fallback for provider/model scorecards.
+    if (!affected.provider && scorecard.subject === "provider")
+        affected.provider = scorecard.subject_key;
+    if (!affected.model && scorecard.subject === "model")
+        affected.model = scorecard.subject_key;
+    return affected;
+}
+/**
+ * Derive a `ScorecardRecommendationSummary` from a `SolScorecard`.
+ *
+ * This is a pure function: it does not read files, call APIs, or mutate
+ * the scorecard or any runtime state. Its output is advisory by default.
+ */
+function scorecardToRecommendationSummary(scorecard) {
+    const { subscores, raw_metrics, source_refs, recommendation_inputs } = scorecard;
+    const qc = extractQcEvidence(subscores, raw_metrics);
+    const validation = extractValidationEvidence(subscores, raw_metrics);
+    const quality_per_token = extractQptEvidence(subscores);
+    const verdict = deriveVerdict(scorecard, qc);
+    const confidence = confidenceFromScorecard(scorecard);
+    const affected = affectedFromScorecard(scorecard);
+    const clonedSourceRefs = source_refs.map((ref) => ({ ...ref }));
+    return {
+        scorecard_id: scorecard.scorecard_id,
+        subject: scorecard.subject,
+        subject_key: scorecard.subject_key,
+        affected,
+        verdict,
+        aggregate_score: scorecard.aggregate_score,
+        confidence,
+        low_scoring_dimensions: [...recommendation_inputs.low_scoring_dimensions],
+        quality_per_token,
+        qc,
+        validation,
+        source_refs: clonedSourceRefs,
+        intervention_detected: recommendation_inputs.intervention_detected,
+        router_issue_detected: recommendation_inputs.router_issue_detected,
+    };
+}
+/**
+ * Derive recommendation summaries from a set of scorecards.
+ * Returns all summaries; callers filter by verdict as needed.
+ */
+function scorecardsToRecommendationSummaries(scorecards) {
+    return scorecards.map(scorecardToRecommendationSummary);
+}