@lsctech/polaris 0.5.0 → 0.5.2

package/dist/autoresearch/gates.js

@@ -23,6 +23,7 @@ exports.gateValidationFailed = gateValidationFailed;
 exports.gateWorkerWentOutOfScope = gateWorkerWentOutOfScope;
 exports.gateForemanTokenBurnOverBudget = gateForemanTokenBurnOverBudget;
 exports.gateStateRepairRequired = gateStateRepairRequired;
+exports.gateQcBlockingFindings = gateQcBlockingFindings;
 exports.readJsonLines = readJsonLines;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -362,6 +363,51 @@ function safeReaddir(dir) {
         return [];
     }
 }
+/**
+ * qc-blocking-findings: Are there unresolved critical/high QC findings
+ * attributed to this cluster with high or medium confidence?
+ *
+ * Evidence: qcResults loaded from .polaris/clusters/<cluster-id>/qc/.
+ * Skipped when no QC artifacts exist.
+ *
+ * Only high/medium attribution-confidence findings are counted — provider noise
+ * (low/unattributed confidence) is excluded so workers are not penalized for
+ * external reviewer uncertainty.
+ */
+function gateQcBlockingFindings(artifacts) {
+    if (artifacts.qcResults.length === 0) {
+        return { gate: "qc-blocking-findings", outcome: "skipped", detail: "no QC artifacts found" };
+    }
+    let blockingCount = 0;
+    let weightedOpenScore = 0;
+    const severityWeights = { critical: 10, high: 5, medium: 2, low: 1, info: 0.5 };
+    const confidenceWeights = { high: 1.0, medium: 0.7, low: 0.3, unattributed: 0 };
+    for (const result of artifacts.qcResults) {
+        for (const finding of result.findings) {
+            const conf = finding.attribution.confidence;
+            const isOpenUnresolved = finding.status === "open" || finding.status === "follow-up";
+            if (isOpenUnresolved && conf !== "low" && conf !== "unattributed") {
+                weightedOpenScore += severityWeights[finding.severity] * confidenceWeights[conf];
+            }
+            if (conf === "low" || conf === "unattributed")
+                continue;
+            if (finding.status === "autofixed" || finding.status === "repaired" || finding.status === "waived")
+                continue;
+            if ((finding.severity === "critical" || finding.severity === "high") &&
+                (finding.status === "open" || finding.status === "follow-up")) {
+                blockingCount++;
+            }
+        }
+    }
+    if (blockingCount > 0) {
+        return {
+            gate: "qc-blocking-findings",
+            outcome: "failed",
+            detail: `${blockingCount} unresolved critical/high QC finding${blockingCount === 1 ? "" : "s"} with attributed confidence (weighted open score ${weightedOpenScore.toFixed(2)})`,
+        };
+    }
+    return { gate: "qc-blocking-findings", outcome: "passed" };
+}
 exports.ALL_GATES = [
     gateUserIntervened,
     gateForemanResentPacket,
@@ -371,4 +417,5 @@ exports.ALL_GATES = [
     gateWorkerWentOutOfScope,
     gateForemanTokenBurnOverBudget,
     gateStateRepairRequired,
+    gateQcBlockingFindings,
 ];

package/dist/autoresearch/proposal.js

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FIX_ZONE_MAP = void 0;
+exports.buildQcProposals = buildQcProposals;
 exports.buildProposals = buildProposals;
 exports.loadDiagnosisReport = loadDiagnosisReport;
 exports.validateDiagnosisReport = validateDiagnosisReport;
@@ -50,6 +51,10 @@ exports.FIX_ZONE_MAP = {
         artifact_type: "medic-template",
         hint: "Medic artifacts detected — state repair was required. Review medic template heuristics and state-repair triggers.",
     },
+    "qc-blocking-findings": {
+        artifact_type: "scoring-rule",
+        hint: "Unresolved critical/high QC findings with attributed confidence. Review QC artifacts, triage open findings, and route repairs before delivery.",
+    },
 };
 const ROUTER_FAILURE_FIX_ZONE_MAP = {
     "quota-exhausted": {
@@ -88,6 +93,80 @@ const ROUTER_FAILURE_FIX_ZONE_MAP = {
  * Maps a DiagnosisReport's failed gates to AutresearchProposal objects.
  * Gates without a fix zone entry are skipped.
  */
+const QC_FIX_ZONE_MAP = {
+    "qc-recurring-provider": {
+        artifact_type: "provider-role-recommendation",
+        hint: "A QC provider is producing recurring attributed findings. Review provider capability mapping, role assignment, and confidence thresholds.",
+    },
+    "qc-recurring-child": {
+        artifact_type: "worker-template",
+        hint: "A child/worker route accumulates recurring QC findings. Tighten packet scope, validation commands, or acceptance criteria for this route.",
+    },
+    "qc-unvalidated-noise": {
+        artifact_type: "runtime-config",
+        hint: "A large share of QC findings are low/unattributed provider noise. Raise providerConfidenceThreshold or tighten QC provider selection.",
+    },
+    "qc-recurring-validation": {
+        artifact_type: "scoring-rule",
+        hint: "Unresolved QC findings indicate validation gaps. Strengthen scoring rules and repair routing before delivery.",
+    },
+    "qc-recurring-docs": {
+        artifact_type: "skill-prompt",
+        hint: "Recurring QC findings relate to documentation. Update skill prompts and worker instructions that produce docs artifacts.",
+    },
+};
+/**
+ * Builds QC-derived improvement proposals from the diagnosis report.
+ *
+ * These recommendations target config, provider, packet-scope, validation,
+ * and docs artifacts for recurring QC failure patterns.
+ */
+function buildQcProposals(report) {
+    const qc = report.qc_summary;
+    if (!qc)
+        return [];
+    const proposals = [];
+    const confidence = Math.max(0, Math.min(1, 1 - qc.qc_penalty));
+    const addProposal = (gateId, artifactType, hint) => {
+        proposals.push({
+            gate_id: gateId,
+            artifact_type: artifactType,
+            hint,
+            run_id: report.run_id,
+            evidence_run_ids: [report.run_id],
+            confidence,
+            fix_zone: `${artifactType}/${gateId}`,
+        });
+    };
+    // Recurring provider signal: multiple blocking findings from the same provider.
+    for (const [provider, summary] of Object.entries(qc.provider_breakdown)) {
+        if (summary.total >= 2 && summary.blocking > 0) {
+            addProposal(`qc-recurring-provider:${provider}`, "provider-role-recommendation", `Provider '${provider}' produced ${summary.blocking} blocking QC findings across ${summary.total} total findings. Review provider capability mapping, role assignment, and confidence thresholds.`);
+        }
+    }
+    // Recurring child/worker route signal: same child owns multiple findings.
+    for (const signal of qc.recurring_child_signals) {
+        if (signal.finding_count >= 2) {
+            addProposal(`qc-recurring-child:${signal.child_id}`, "worker-template", `Child '${signal.child_id}' accumulated ${signal.finding_count} attributed QC findings (weighted score ${signal.weighted_score.toFixed(2)}). Tighten packet scope, validation commands, or acceptance criteria for this worker route.`);
+        }
+    }
+    // High share of unvalidated/provider-noise findings.
+    const noiseRatio = qc.total_findings > 0 ? qc.unvalidated_findings / qc.total_findings : 0;
+    if (qc.unvalidated_findings >= 3 && noiseRatio > 0.3) {
+        addProposal("qc-unvalidated-noise", "runtime-config", `${qc.unvalidated_findings} of ${qc.total_findings} QC findings are low/unattributed provider noise. Raise providerConfidenceThreshold or tighten QC provider selection in runtime config.`);
+    }
+    // Unresolved blocking findings indicate a validation/routing gap.
+    if (qc.blocking_findings > 0 && qc.weighted_open_score > 0) {
+        addProposal("qc-recurring-validation", "scoring-rule", `${qc.blocking_findings} blocking QC findings remain unresolved (weighted score ${qc.weighted_open_score.toFixed(2)}). Strengthen validation gates and repair routing before delivery.`);
+    }
+    // Recurring docs-category findings.
+    for (const [category, summary] of Object.entries(qc.category_breakdown)) {
+        if (category === "docs" && summary.total >= 2) {
+            addProposal("qc-recurring-docs", "skill-prompt", `${summary.total} QC findings relate to documentation. Update skill prompts and worker instructions that produce docs artifacts.`);
+        }
+    }
+    return proposals;
+}
 function buildProposals(report) {
     const proposals = [];
     for (const gateId of report.failed_gates) {
@@ -104,6 +183,7 @@ function buildProposals(report) {
             fix_zone: `${entry.artifact_type}/${gateId}`,
         });
     }
+    proposals.push(...buildQcProposals(report));
     const recurringRouterFailures = report.router_outcomes?.recurring_failures ?? [];
     for (const failure of recurringRouterFailures) {
         if (failure.occurrences < 2)
@@ -144,6 +224,37 @@ function loadDiagnosisReport(filePath) {
     }
     return validateDiagnosisReport(raw);
 }
+function defaultRoutingBreakdown() {
+    return { original_worker: 0, repair_worker: 0, follow_up: 0, operator_review: 0, unset: 0 };
+}
+function normalizeQcScoreSummary(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const q = raw;
+    const zeroSeverity = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+    const rawOpen = q.open_by_severity && typeof q.open_by_severity === "object" && !Array.isArray(q.open_by_severity)
+        ? q.open_by_severity
+        : undefined;
+    const openBySeverity = rawOpen ? { ...zeroSeverity, ...rawOpen } : zeroSeverity;
+    return {
+        total_findings: q.total_findings ?? 0,
+        blocking_findings: q.blocking_findings ?? 0,
+        autofixed_findings: q.autofixed_findings ?? 0,
+        repaired_findings: q.repaired_findings ?? 0,
+        waived_findings: q.waived_findings ?? 0,
+        unvalidated_findings: q.unvalidated_findings ?? 0,
+        open_by_severity: openBySeverity,
+        weighted_open_score: q.weighted_open_score ?? 0,
+        qc_penalty: q.qc_penalty ?? 0,
+        blocks_delivery: q.blocks_delivery ?? false,
+        qc_run_count: q.qc_run_count ?? 0,
+        provider_breakdown: q.provider_breakdown ?? {},
+        routing_breakdown: q.routing_breakdown ?? defaultRoutingBreakdown(),
+        category_breakdown: q.category_breakdown ?? {},
+        recurring_child_signals: Array.isArray(q.recurring_child_signals) ? q.recurring_child_signals : [],
+        recurring_provider_signals: Array.isArray(q.recurring_provider_signals) ? q.recurring_provider_signals : [],
+    };
+}
 /**
  * Validates a parsed value against the DiagnosisReport schema.
  * Throws a descriptive error if required fields are missing or have wrong types.
@@ -183,8 +294,10 @@ function validateDiagnosisReport(raw) {
             successful_fallbacks: 0,
             recurring_failures: [],
         };
+    const normalizedQcSummary = normalizeQcScoreSummary(r["qc_summary"]);
     return {
         ...raw,
         router_outcomes: normalizedRouterOutcomes,
+        qc_summary: normalizedQcSummary,
     };
 }

package/dist/autoresearch/score.js

@@ -19,10 +19,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadRunArtifacts = loadRunArtifacts;
 exports.computeScore = computeScore;
 exports.buildDiagnosisHints = buildDiagnosisHints;
+exports.computeQcSummary = computeQcSummary;
 exports.summarizeRouterOutcomes = summarizeRouterOutcomes;
 exports.scoreRun = scoreRun;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const artifacts_js_1 = require("../qc/artifacts.js");
 const gates_js_1 = require("./gates.js");
 // ──────────────────────────────────────────────
 // Diagnosis hints table
@@ -60,6 +62,10 @@ const HINTS = {
         fix_zone: "medic / cluster-state",
         hint: "Medic artifacts detected — state repair was required during this run. Review the medic chart and root cause.",
     },
+    "qc-blocking-findings": {
+        fix_zone: "qc / findings",
+        hint: "QC produced unresolved critical/high findings attributed to this run. Review QC artifacts, triage findings, and route repairs before delivery.",
+    },
 };
 // ──────────────────────────────────────────────
 // Artifact loader
@@ -96,6 +102,18 @@ function safeReaddir(dir) {
     }
 }
 const NON_WORKER_PREFIXES = ["librarian-", "CHART-", "medic-result-"];
+function loadQcArtifacts(clusterId, repoRoot) {
+    if (!clusterId)
+        return [];
+    const ids = (0, artifacts_js_1.listQcArtifactIds)(clusterId, repoRoot);
+    const results = [];
+    for (const id of ids) {
+        const result = (0, artifacts_js_1.readQcArtifact)(clusterId, id, repoRoot);
+        if (result)
+            results.push(result);
+    }
+    return results;
+}
 function readResultPackets(clusterDir) {
     if (!clusterDir)
         return [];
@@ -177,6 +195,7 @@ function loadRunArtifacts(repoRoot, runId) {
         // Legacy fallback: extract from result packet files
         workerResultContracts = extractWorkerResultContracts(resultPackets);
     }
+    const qcResults = loadQcArtifacts(clusterId, repoRoot);
     return {
         runId,
         runDir,
@@ -186,6 +205,7 @@ function loadRunArtifacts(repoRoot, runId) {
         resultPackets,
         workerResultContracts,
         telemetryEvents,
+        qcResults,
     };
 }
 // ──────────────────────────────────────────────
@@ -204,6 +224,163 @@ function buildDiagnosisHints(failedGateNames) {
         return { gate, ...h };
     });
 }
+const SEVERITY_WEIGHTS = {
+    critical: 10,
+    high: 5,
+    medium: 2,
+    low: 1,
+    info: 0.5,
+};
+const CONFIDENCE_WEIGHTS = {
+    high: 1.0,
+    medium: 0.7,
+    low: 0.3,
+    unattributed: 0,
+};
+function zeroCounts() {
+    return { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+}
+function zeroRouting() {
+    return { original_worker: 0, repair_worker: 0, follow_up: 0, operator_review: 0, unset: 0 };
+}
+function computeQcPenalty(weightedOpenScore) {
+    // Soft penalty that grows with weighted severity but does not dominate the score.
+    return weightedOpenScore === 0 ? 0 : weightedOpenScore / (weightedOpenScore + 20);
+}
+/**
+ * Computes a QcScoreSummary from the QC results loaded for this run.
+ * Returns null when no QC results are present.
+ *
+ * A finding is "blocking" if:
+ *   - severity is critical or high
+ *   - status is "open" or "follow-up" (not autofixed, repaired, or waived)
+ *   - attribution confidence is "high" or "medium" (not unvalidated provider noise)
+ *
+ * Worker scoring intentionally does not penalize for "unvalidated" or
+ * "low" attribution-confidence findings — these are treated as provider noise.
+ *
+ * The weighted open score multiplies severity by attribution confidence so that
+ * a critical/high-confidence finding hurts SOL scoring more than a low-severity
+ * or uncertain finding.
+ */
+function computeQcSummary(qcResults) {
+    if (qcResults.length === 0)
+        return null;
+    let total = 0;
+    let blocking = 0;
+    let autofixed = 0;
+    let repaired = 0;
+    let waived = 0;
+    let unvalidated = 0;
+    const openBySeverity = zeroCounts();
+    let weightedOpenScore = 0;
+    let blocksDelivery = false;
+    const providerBreakdown = new Map();
+    const categoryBreakdown = new Map();
+    const routingBreakdown = zeroRouting();
+    const childScores = new Map();
+    const providerScores = new Map();
+    for (const result of qcResults) {
+        if (result.policyDecision.blocksDelivery)
+            blocksDelivery = true;
+        for (const finding of result.findings) {
+            total++;
+            const provider = result.provider;
+            const providerEntry = providerBreakdown.get(provider) ?? { total: 0, blocking: 0, unvalidated: 0 };
+            providerEntry.total += 1;
+            providerBreakdown.set(provider, providerEntry);
+            const category = (finding.category ?? "uncategorized").toLowerCase();
+            const categoryEntry = categoryBreakdown.get(category) ?? { total: 0, blocking: 0 };
+            categoryEntry.total += 1;
+            const routing = finding.routingDecision ?? "unset";
+            if (routing === "original-worker")
+                routingBreakdown.original_worker += 1;
+            else if (routing === "repair-worker")
+                routingBreakdown.repair_worker += 1;
+            else if (routing === "follow-up")
+                routingBreakdown.follow_up += 1;
+            else if (routing === "operator-review")
+                routingBreakdown.operator_review += 1;
+            else
+                routingBreakdown.unset += 1;
+            const conf = finding.attribution.confidence;
+            const isUnvalidated = conf === "low" || conf === "unattributed";
+            if (isUnvalidated) {
+                unvalidated++;
+                providerEntry.unvalidated += 1;
+                categoryBreakdown.set(category, categoryEntry);
+                continue; // do not count provider noise toward any negative bucket
+            }
+            if (finding.status === "autofixed") {
+                autofixed++;
+                categoryBreakdown.set(category, categoryEntry);
+                continue;
+            }
+            if (finding.status === "repaired") {
+                repaired++;
+                categoryBreakdown.set(category, categoryEntry);
+                continue;
+            }
+            if (finding.status === "waived") {
+                waived++;
+                categoryBreakdown.set(category, categoryEntry);
+                continue;
+            }
+            // "open" or "follow-up" — count toward open_by_severity and weighted score
+            const sev = finding.severity;
+            if (sev in openBySeverity)
+                openBySeverity[sev]++;
+            const isBlocking = (sev === "critical" || sev === "high") &&
+                (finding.status === "open" || finding.status === "follow-up");
+            if (isBlocking) {
+                blocking++;
+                categoryEntry.blocking += 1;
+                providerEntry.blocking += 1;
+            }
+            const findingWeight = SEVERITY_WEIGHTS[sev] * CONFIDENCE_WEIGHTS[conf];
+            weightedOpenScore += findingWeight;
+            const childId = finding.attribution.childId;
+            if (childId) {
+                const childEntry = childScores.get(childId) ?? { weighted_score: 0, finding_count: 0 };
+                childEntry.weighted_score += findingWeight;
+                childEntry.finding_count += 1;
+                childScores.set(childId, childEntry);
+            }
+            const providerScoreEntry = providerScores.get(provider) ?? { weighted_score: 0, finding_count: 0 };
+            providerScoreEntry.weighted_score += findingWeight;
+            providerScoreEntry.finding_count += 1;
+            providerScores.set(provider, providerScoreEntry);
+            categoryBreakdown.set(category, categoryEntry);
+            providerBreakdown.set(provider, providerEntry);
+        }
+    }
+    const recurringChildSignals = Array.from(childScores.entries())
+        .map(([child_id, value]) => ({ child_id, ...value }))
+        .filter((s) => s.weighted_score > 0)
+        .sort((a, b) => b.weighted_score - a.weighted_score || a.child_id.localeCompare(b.child_id));
+    const recurringProviderSignals = Array.from(providerScores.entries())
+        .map(([provider, value]) => ({ provider, ...value }))
+        .filter((s) => s.weighted_score > 0)
+        .sort((a, b) => b.weighted_score - a.weighted_score || a.provider.localeCompare(b.provider));
+    return {
+        total_findings: total,
+        blocking_findings: blocking,
+        autofixed_findings: autofixed,
+        repaired_findings: repaired,
+        waived_findings: waived,
+        unvalidated_findings: unvalidated,
+        open_by_severity: openBySeverity,
+        weighted_open_score: Number(weightedOpenScore.toFixed(3)),
+        qc_penalty: Number(computeQcPenalty(weightedOpenScore).toFixed(4)),
+        blocks_delivery: blocksDelivery,
+        qc_run_count: qcResults.length,
+        provider_breakdown: Object.fromEntries(providerBreakdown),
+        routing_breakdown: routingBreakdown,
+        category_breakdown: Object.fromEntries(categoryBreakdown),
+        recurring_child_signals: recurringChildSignals,
+        recurring_provider_signals: recurringProviderSignals,
+    };
+}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -308,6 +485,7 @@ function scoreRun(repoRoot, runId) {
     const score = computeScore(gateResults);
     const diagnosisHints = buildDiagnosisHints(failedGates);
     const routerOutcomes = summarizeRouterOutcomes(artifacts);
+    const qcSummary = computeQcSummary(artifacts.qcResults);
     const clusterId = artifacts.currentState &&
         typeof artifacts.currentState === "object" &&
         !Array.isArray(artifacts.currentState)
@@ -322,5 +500,6 @@ function scoreRun(repoRoot, runId) {
         score,
         diagnosis_hints: diagnosisHints,
         router_outcomes: routerOutcomes,
+        qc_summary: qcSummary,
     };
 }

package/dist/cluster-state/store.js

@@ -33,17 +33,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initializeClusterState = exports.writeClusterStateSync = exports.writeClusterState = exports.readClusterStateSync = exports.readClusterState = void 0;
+exports.recordQcRun = exports.initializeClusterState = exports.writeClusterStateSync = exports.writeClusterState = exports.readClusterStateSync = exports.readClusterState = void 0;
 exports.pruneExpiredClaims = pruneExpiredClaims;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const local_graph_1 = require("../tracker/local-graph");
+const artifacts_js_1 = require("../qc/artifacts.js");
 const getClusterStatePath = (clusterId, repoRoot) => {
     return path.join(repoRoot || process.cwd(), '.polaris', 'clusters', clusterId, 'cluster-state.json');
 };
 const normalizeClusterState = (state) => ({
     ...state,
     tracker_mutations: state.tracker_mutations ?? {},
+    qc_runs: state.qc_runs ?? {},
 });
 function pruneExpiredClaims(state, now = new Date()) {
     const nowMs = now.getTime();
@@ -330,8 +332,40 @@ const initializeClusterState = async (clusterId, repoRoot) => {
         commits: {},
         tracker_mutations: {},
         blockers: [],
+        qc_runs: {},
     };
     await (0, exports.writeClusterState)(clusterId, initialState, repoRoot);
     return initialState;
 };
 exports.initializeClusterState = initializeClusterState;
+/**
+ * Persist a QC result artifact under the active cluster's evidence surface and
+ * record a pointer in the cluster state. This is the only supported way to
+ * durably store QC runs; callers must not write QC artifacts directly outside
+ * `.polaris/clusters/<cluster-id>/qc/`.
+ */
+const recordQcRun = async (clusterId, result, repoRoot) => {
+    const artifactPath = (0, artifacts_js_1.writeQcArtifact)(clusterId, result, repoRoot);
+    const currentState = await (0, exports.readClusterState)(clusterId, repoRoot);
+    if (!currentState) {
+        throw new Error(`Cluster ${clusterId} state not found; cannot record QC run ${result.qcRunId}.`);
+    }
+    const pointer = {
+        artifact_path: artifactPath,
+        status: result.status,
+        provider: result.provider,
+        started_at: result.startedAt,
+        completed_at: result.completedAt,
+    };
+    const nextState = {
+        ...currentState,
+        state_generation: currentState.state_generation + 1,
+        qc_runs: {
+            ...currentState.qc_runs,
+            [result.qcRunId]: pointer,
+        },
+    };
+    await (0, exports.writeClusterState)(clusterId, nextState, repoRoot);
+    return { artifactPath, state: nextState };
+};
+exports.recordQcRun = recordQcRun;

package/dist/config/defaults.js

@@ -103,4 +103,21 @@ exports.DEFAULT_CONFIG = {
         auto_deep_analysis: false,
         allow_cross_provider_delegation: false,
     },
+    qc: {
+        enabled: false,
+        defaultTrigger: "completed-cluster",
+        providers: {},
+        severityThresholds: {
+            block: "high",
+            repair: "medium",
+            followUp: "low",
+        },
+        autoFix: "disabled",
+        repairRouting: "route",
+        artifactRetention: {
+            retainRawOutput: false,
+            maxRuns: 10,
+        },
+        routes: {},
+    },
 };