@lsctech/polaris 0.5.6 → 0.5.8

package/dist/autoresearch/sol-scorer.js

@@ -207,6 +207,48 @@ function scoreForemanCompletion(ev) {
         detail: `succeeded=${succeeded}/${total}`,
     });
 }
+/**
+ * qc_repair_loop: Observe QC repair loop outcomes.
+ *
+ * Scores repair loop terminal states without treating provider findings as
+ * ground truth. Best outcome = loop passed or no repairable findings.
+ * Worst = all providers failed, operator review required, or Medic referral.
+ * Skipped when QC is not configured or no repair loop ran.
+ */
+function scoreForemanQcRepairLoop(ev) {
+    if (ev.qc.availability === "future" || ev.qc.availability === "unavailable") {
+        return skipped("qc_repair_loop", `QC evidence availability=${ev.qc.availability}`);
+    }
+    const loop = ev.qc.repair_loop;
+    if (!loop) {
+        return skipped("qc_repair_loop", "no QC repair loop data available");
+    }
+    const { status, rounds_completed, max_rounds, packets_compiled, packets_failed, rerun_outcome } = loop;
+    switch (status) {
+        case "passed":
+        case "repaired":
+        case "no-repairable":
+            return dim("qc_repair_loop", 1.0, "high", {
+                detail: `status=${status}, rounds=${rounds_completed}/${max_rounds}, packets=${packets_compiled}, rerun=${rerun_outcome ?? "n/a"}`,
+            });
+        case "max-rounds":
+            return dim("qc_repair_loop", 0.5, "high", {
+                detail: `status=${status}, rounds=${rounds_completed}/${max_rounds}, packets=${packets_compiled}`,
+            });
+        case "all-providers-failed":
+        case "operator-review":
+        case "medic-referral":
+            return dim("qc_repair_loop", 0.0, "high", {
+                detail: `status=${status}, failed_packets=${packets_failed}, rerun=${rerun_outcome ?? "n/a"}`,
+            });
+        case "not-run":
+        case "not-configured":
+        case "in-progress":
+        case "unknown":
+        default:
+            return skipped("qc_repair_loop", `QC repair loop status=${status}`);
+    }
+}
 /**
  * recovery: State repair detection.
  * Score = 1.0 when no medic/repair artifacts detected; 0.0 when repair required.
@@ -388,10 +430,11 @@ function computeForemanScore(ev) {
     const scopeDim = scoreForemanScope(ev);
     const completionDim = scoreForemanCompletion(ev);
     const recoveryDim = scoreForemanRecovery(ev);
+    const qcRepairLoopDim = scoreForemanQcRepairLoop(ev);
     const dims = [
         tokenDim, durationDim, interventionDim, preAnalysisDim,
         dependencyDim, dispatchDim, evidenceValidationDim, scopeDim,
-        completionDim, recoveryDim,
+        completionDim, recoveryDim, qcRepairLoopDim,
     ];
     const { score: composite_score, confidence: composite_confidence } = composite(dims);
     return {
@@ -407,6 +450,7 @@ function computeForemanScore(ev) {
         scope: scopeDim,
         completion: completionDim,
         recovery: recoveryDim,
+        qc_repair_loop: qcRepairLoopDim,
     };
 }
 /**

package/dist/cli/autoresearch.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAutoresearchCommand = void 0;
 exports.createSolCommand = createSolCommand;
 const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
 const commander_1 = require("commander");
 const dev_gate_js_1 = require("../autoresearch/dev-gate.js");
 const score_js_1 = require("../autoresearch/score.js");
@@ -12,6 +13,9 @@ const sol_evidence_loader_js_1 = require("../autoresearch/sol-evidence-loader.js
 const sol_scorer_js_1 = require("../autoresearch/sol-scorer.js");
 const sol_history_js_1 = require("../autoresearch/sol-history.js");
 const sol_report_js_1 = require("../autoresearch/sol-report.js");
+const sol_scorecard_calculator_js_1 = require("../autoresearch/sol-scorecard-calculator.js");
+const sol_evaluation_writer_js_1 = require("../autoresearch/sol-evaluation-writer.js");
+const sol_report_renderer_js_1 = require("../autoresearch/sol-report-renderer.js");
 const sol_recommendations_js_1 = require("../autoresearch/sol-recommendations.js");
 function createSolCommand(options) {
     const repoRoot = options.repoRoot;
@@ -74,6 +78,79 @@ function createSolCommand(options) {
             process.exit(1);
         }
     });
+    sol
+        .command("report <run-id>")
+        .description("Generate SOL evaluation artifacts and a human-readable SmartDocs report for a run")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--format <mode>", "Output format: markdown or json", "markdown")
+        .option("--json", "Output raw JSON (same as --format json)")
+        .option("--no-write", "Skip writing artifact files")
+        .action((runId, cmdOptions) => {
+        const root = (0, node_path_1.resolve)(cmdOptions.repoRoot ?? repoRoot);
+        if (cmdOptions.format !== "markdown" && cmdOptions.format !== "json") {
+            process.stderr.write(`sol report error: invalid --format "${cmdOptions.format}" (expected "markdown" or "json")\n`);
+            process.exit(1);
+        }
+        try {
+            (0, dev_gate_js_1.assertPolarisDevContext)(root);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        let artifacts;
+        let evidence;
+        try {
+            artifacts = (0, score_js_1.loadRunArtifacts)(root, runId);
+            evidence = (0, sol_evidence_loader_js_1.aggregateSolEvidence)(artifacts);
+        }
+        catch (err) {
+            process.stderr.write(`sol report error: cannot load run artifacts: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        try {
+            const report = (0, sol_scorer_js_1.computeSolScoreReport)(evidence);
+            const scorecards = (0, sol_scorecard_calculator_js_1.computeAllScorecards)(evidence);
+            const qcRecommendations = (0, sol_recommendations_js_1.generateQcRecommendations)(evidence);
+            let evaluationPath;
+            let scorecardPaths;
+            let markdownPath;
+            const evaluationRecord = (0, sol_evaluation_writer_js_1.buildEvaluationRecord)(report);
+            const rendered = (0, sol_report_renderer_js_1.renderSolMarkdown)(evaluationRecord, scorecards, qcRecommendations);
+            if (cmdOptions.write) {
+                // Persist the same evaluationRecord object that was rendered, rather than rebuilding internally
+                const evaluationDir = (0, sol_evaluation_writer_js_1.getSolEvaluationsDir)(root);
+                if (!(0, node_fs_1.existsSync)(evaluationDir))
+                    (0, node_fs_1.mkdirSync)(evaluationDir, { recursive: true });
+                evaluationPath = (0, sol_evaluation_writer_js_1.getEvaluationRecordPath)(root, report.run_id);
+                (0, node_fs_1.writeFileSync)(evaluationPath, JSON.stringify(evaluationRecord, null, 2) + "\n", "utf-8");
+                scorecardPaths = (0, sol_evaluation_writer_js_1.writeScorecardSet)(root, scorecards);
+                markdownPath = (0, sol_evaluation_writer_js_1.writeSolMarkdownReport)(root, runId, rendered.markdown);
+            }
+            const outputFormat = cmdOptions.json || cmdOptions.format === "json" ? "json" : "markdown";
+            if (outputFormat === "json") {
+                const output = JSON.stringify({
+                    run_id: runId,
+                    evaluation: evaluationRecord,
+                    scorecards,
+                    qc_recommendations: qcRecommendations,
+                    artifacts: {
+                        evaluation: evaluationPath,
+                        scorecards: scorecardPaths,
+                        markdown: markdownPath,
+                    },
+                }, null, 2);
+                process.stdout.write(`${output}\n`);
+            }
+            else {
+                process.stdout.write(rendered.markdown);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`sol report error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
     sol
         .command("propose <diagnosis-file>")
         .description("File Linear improvement proposals from a diagnosis report (dev-gated — never auto-applied)")

package/dist/cluster-state/store.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordQcRun = exports.initializeClusterState = exports.writeClusterStateSync = exports.writeClusterState = exports.readClusterStateSync = exports.readClusterState = void 0;
 exports.pruneExpiredClaims = pruneExpiredClaims;
+exports.pruneMissingQcRunPointers = pruneMissingQcRunPointers;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const local_graph_1 = require("../tracker/local-graph");
@@ -350,12 +351,25 @@ const recordQcRun = async (clusterId, result, repoRoot) => {
     if (!currentState) {
         throw new Error(`Cluster ${clusterId} state not found; cannot record QC run ${result.qcRunId}.`);
     }
+    const rawArtifactPaths = result.rawArtifactPaths ?? [];
+    const providerAttemptPath = result.providerAttempt?.rawOutputArtifactPath;
+    const auditArtifactPaths = providerAttemptPath
+        ? [...rawArtifactPaths, providerAttemptPath]
+        : rawArtifactPaths;
+    const failedRun = result.status === "failed" || result.status === "blocked" || result.allProvidersFailed === true;
+    let availability = "available";
+    if (failedRun && auditArtifactPaths.some((p) => !(0, fs_1.existsSync)(p))) {
+        availability = "unavailable";
+    }
     const pointer = {
         artifact_path: artifactPath,
         status: result.status,
         provider: result.provider,
         started_at: result.startedAt,
         completed_at: result.completedAt,
+        availability,
+        raw_artifact_paths: rawArtifactPaths.length > 0 ? rawArtifactPaths : undefined,
+        provider_attempt_artifact_path: providerAttemptPath,
     };
     const nextState = {
         ...currentState,
@@ -369,3 +383,45 @@ const recordQcRun = async (clusterId, result, repoRoot) => {
     return { artifactPath, state: nextState };
 };
 exports.recordQcRun = recordQcRun;
+/**
+ * Remove QC run pointers whose primary artifacts are missing and mark
+ * pointers with missing raw audit artifacts as unavailable. Returns a new
+ * state object; callers must persist the result if they want the cleanup to
+ * be durable.
+ */
+function pruneMissingQcRunPointers(state) {
+    const warnings = [];
+    const pruned = [];
+    if (!state.qc_runs) {
+        return { state, pruned, warnings };
+    }
+    const validation = (0, artifacts_js_1.validateQcArtifactPointers)(state.qc_runs);
+    if (validation.ok && validation.unavailable.length === 0) {
+        return { state, pruned, warnings };
+    }
+    const nextQcRuns = {};
+    for (const [runId, pointer] of Object.entries(state.qc_runs)) {
+        if (validation.missing.includes(pointer.artifact_path)) {
+            pruned.push(runId);
+            warnings.push(`QC run ${runId} pointer pruned: artifact missing ${pointer.artifact_path}`);
+            continue;
+        }
+        const updated = { ...pointer };
+        const hasMissingRaw = (pointer.raw_artifact_paths ?? []).some((p) => validation.unavailable.includes(p)) ||
+            (pointer.provider_attempt_artifact_path &&
+                validation.unavailable.includes(pointer.provider_attempt_artifact_path));
+        if (hasMissingRaw && updated.availability === "available") {
+            updated.availability = "unavailable";
+            warnings.push(`QC run ${runId} raw audit artifacts missing; marked unavailable`);
+        }
+        nextQcRuns[runId] = updated;
+    }
+    return {
+        state: {
+            ...state,
+            qc_runs: nextQcRuns,
+        },
+        pruned,
+        warnings,
+    };
+}

package/dist/config/defaults.js

@@ -119,5 +119,6 @@ exports.DEFAULT_CONFIG = {
             maxRuns: 10,
         },
         routes: {},
+        maxRepairRounds: 2,
     },
 };

package/dist/config/validator.js

@@ -10,6 +10,9 @@ function isNumber(value) {
 function isPositiveInteger(value) {
     return Number.isInteger(value) && Number(value) > 0;
 }
+function isNonNegativeInteger(value) {
+    return Number.isInteger(value) && Number(value) >= 0;
+}
 function isString(value) {
     return typeof value === "string";
 }
@@ -91,6 +94,8 @@ const SUPPORTED_QC_PROVIDER_CAPABILITIES = [
     "auto-fix",
     "metrics-import",
 ];
+const SUPPORTED_QC_OUTPUT_FORMATS = ["json", "jsonl", "sarif", "generic"];
+const SUPPORTED_QC_FAILURE_ACTIONS = ["fail", "fallback", "ignore", "block"];
 const SEVERITY_ORDER = ["info", "low", "medium", "high", "critical"];
 function severityIndex(severity) {
     return SEVERITY_ORDER.indexOf(severity);
@@ -908,6 +913,158 @@ function validateConfig(config) {
                                 }
                             }
                         }
+                        if ("enabled" in providerConfig && providerConfig.enabled !== undefined && !isBoolean(providerConfig.enabled)) {
+                            result.valid = false;
+                            result.errors.push(`qc.providers.${providerName}.enabled must be a boolean`);
+                        }
+                        if ("execution" in providerConfig && providerConfig.execution !== undefined) {
+                            if (!isPlainObject(providerConfig.execution)) {
+                                result.valid = false;
+                                result.errors.push(`qc.providers.${providerName}.execution must be a plain object`);
+                            }
+                            else {
+                                const execution = providerConfig.execution;
+                                if ("command" in execution && execution.command !== undefined && !isString(execution.command)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.execution.command must be a string`);
+                                }
+                                if ("args" in execution && execution.args !== undefined && !isStringArray(execution.args)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.execution.args must be an array of strings`);
+                                }
+                                if ("output" in execution && execution.output !== undefined) {
+                                    if (!isPlainObject(execution.output)) {
+                                        result.valid = false;
+                                        result.errors.push(`qc.providers.${providerName}.execution.output must be a plain object`);
+                                    }
+                                    else {
+                                        if ("format" in execution.output &&
+                                            execution.output.format !== undefined &&
+                                            (!isString(execution.output.format) ||
+                                                !SUPPORTED_QC_OUTPUT_FORMATS.includes(execution.output.format))) {
+                                            result.valid = false;
+                                            result.errors.push(`qc.providers.${providerName}.execution.output.format must be one of json, jsonl, sarif, generic`);
+                                        }
+                                        if ("parser" in execution.output &&
+                                            execution.output.parser !== undefined &&
+                                            !isString(execution.output.parser)) {
+                                            result.valid = false;
+                                            result.errors.push(`qc.providers.${providerName}.execution.output.parser must be a string`);
+                                        }
+                                    }
+                                }
+                                if ("configPath" in execution &&
+                                    execution.configPath !== undefined &&
+                                    !isString(execution.configPath)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.execution.configPath must be a string`);
+                                }
+                            }
+                        }
+                        if ("timeoutMs" in providerConfig && providerConfig.timeoutMs !== undefined && !isPositiveInteger(providerConfig.timeoutMs)) {
+                            result.valid = false;
+                            result.errors.push(`qc.providers.${providerName}.timeoutMs must be a positive integer`);
+                        }
+                        if ("primary" in providerConfig && providerConfig.primary !== undefined && !isBoolean(providerConfig.primary)) {
+                            result.valid = false;
+                            result.errors.push(`qc.providers.${providerName}.primary must be a boolean`);
+                        }
+                        if ("fallback" in providerConfig && providerConfig.fallback !== undefined && !isStringArray(providerConfig.fallback)) {
+                            result.valid = false;
+                            result.errors.push(`qc.providers.${providerName}.fallback must be an array of strings`);
+                        }
+                        if ("failurePolicy" in providerConfig && providerConfig.failurePolicy !== undefined) {
+                            if (!isPlainObject(providerConfig.failurePolicy)) {
+                                result.valid = false;
+                                result.errors.push(`qc.providers.${providerName}.failurePolicy must be a plain object`);
+                            }
+                            else {
+                                for (const key of ["timeout", "parseFailure", "allProvidersFailed"]) {
+                                    const value = providerConfig.failurePolicy[key];
+                                    if (value !== undefined && (!isString(value) || !SUPPORTED_QC_FAILURE_ACTIONS.includes(value))) {
+                                        result.valid = false;
+                                        result.errors.push(`qc.providers.${providerName}.failurePolicy.${key} must be one of fail, fallback, ignore, block`);
+                                    }
+                                }
+                            }
+                        }
+                        if ("rateLimit" in providerConfig && providerConfig.rateLimit !== undefined) {
+                            if (!isPlainObject(providerConfig.rateLimit)) {
+                                result.valid = false;
+                                result.errors.push(`qc.providers.${providerName}.rateLimit must be a plain object`);
+                            }
+                            else {
+                                if ("requestsPerMinute" in providerConfig.rateLimit &&
+                                    providerConfig.rateLimit.requestsPerMinute !== undefined &&
+                                    !isPositiveInteger(providerConfig.rateLimit.requestsPerMinute)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.rateLimit.requestsPerMinute must be a positive integer`);
+                                }
+                                if ("maxConcurrent" in providerConfig.rateLimit &&
+                                    providerConfig.rateLimit.maxConcurrent !== undefined &&
+                                    !isPositiveInteger(providerConfig.rateLimit.maxConcurrent)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.rateLimit.maxConcurrent must be a positive integer`);
+                                }
+                            }
+                        }
+                        if ("retry" in providerConfig && providerConfig.retry !== undefined) {
+                            if (!isPlainObject(providerConfig.retry)) {
+                                result.valid = false;
+                                result.errors.push(`qc.providers.${providerName}.retry must be a plain object`);
+                            }
+                            else {
+                                if ("maxRetries" in providerConfig.retry &&
+                                    providerConfig.retry.maxRetries !== undefined &&
+                                    !isNonNegativeInteger(providerConfig.retry.maxRetries)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.retry.maxRetries must be a non-negative integer`);
+                                }
+                                if ("backoffMs" in providerConfig.retry &&
+                                    providerConfig.retry.backoffMs !== undefined &&
+                                    !isNonNegativeInteger(providerConfig.retry.backoffMs)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.retry.backoffMs must be a non-negative integer`);
+                                }
+                            }
+                        }
+                        if ("artifactPolicy" in providerConfig && providerConfig.artifactPolicy !== undefined) {
+                            if (!isPlainObject(providerConfig.artifactPolicy)) {
+                                result.valid = false;
+                                result.errors.push(`qc.providers.${providerName}.artifactPolicy must be a plain object`);
+                            }
+                            else {
+                                if ("retainRawOutput" in providerConfig.artifactPolicy &&
+                                    providerConfig.artifactPolicy.retainRawOutput !== undefined &&
+                                    !isBoolean(providerConfig.artifactPolicy.retainRawOutput)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.artifactPolicy.retainRawOutput must be a boolean`);
+                                }
+                                if ("outputDir" in providerConfig.artifactPolicy &&
+                                    providerConfig.artifactPolicy.outputDir !== undefined &&
+                                    !isString(providerConfig.artifactPolicy.outputDir)) {
+                                    result.valid = false;
+                                    result.errors.push(`qc.providers.${providerName}.artifactPolicy.outputDir must be a string`);
+                                }
+                            }
+                        }
+                    }
+                    // Validate fallback references after all provider keys are known.
+                    if (providers) {
+                        const providerKeys = new Set(Object.keys(config.qc.providers));
+                        for (const [providerName, providerConfig] of Object.entries(config.qc.providers)) {
+                            if (!isPlainObject(providerConfig))
+                                continue;
+                            const fallback = providerConfig.fallback;
+                            if (Array.isArray(fallback)) {
+                                for (const fallbackName of fallback) {
+                                    if (isString(fallbackName) && !providerKeys.has(fallbackName)) {
+                                        result.valid = false;
+                                        result.errors.push(`qc.providers.${providerName}.fallback contains unknown provider: ${fallbackName}`);
+                                    }
+                                }
+                            }
+                        }
                     }
                 }
             }

package/dist/finalize/artifact-policy.js

@@ -37,6 +37,7 @@ function isPromotedClusterArtifact(relativePath, activeClusterId) {
     const suffix = relativePath.slice(activeClusterPrefix.length);
     return (suffix === "clusters.json"
         || suffix === "cluster-state.json"
+        || suffix === "state.json"
         || suffix.startsWith("packets/")
         || suffix.startsWith("results/")
         || suffix.startsWith("qc/"));
@@ -131,6 +132,7 @@ function getArtifactPromotionPolicy(activeClusterId) {
         promoted: [
             `${activeClusterPrefix}clusters.json`,
             `${activeClusterPrefix}cluster-state.json`,
+            `${activeClusterPrefix}state.json`,
             `${activeClusterPrefix}packets/**`,
             `${activeClusterPrefix}results/**`,
             `${activeClusterPrefix}qc/**`,

package/dist/finalize/github.js

@@ -1,9 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPrBody = buildPrBody;
 exports.createDraftPr = createDraftPr;
 const node_child_process_1 = require("node:child_process");
+function buildPrBody(state, branch, authoritativeChildCount) {
+    return [
+        `**Cluster ID:** ${state.cluster_id}`,
+        `**Run ID:** ${state.run_id}`,
+        `**Branch:** ${branch}`,
+        `**Children completed:** ${authoritativeChildCount ?? state.completed_children.length}`,
+        ``,
+        `_Generated by polaris finalize_`,
+    ].join("\n");
+}
 function createDraftPr(options) {
-    const { repoRoot, branch, state, draft } = options;
+    const { repoRoot, branch, state, draft, authoritativeChildCount } = options;
     if (!state.cluster_id) {
         throw new Error(`createDraftPr: state.cluster_id is empty — cannot create PR without a cluster identifier`);
     }
@@ -16,14 +27,7 @@ function createDraftPr(options) {
             `branch/cluster mismatch, aborting PR creation`);
     }
     const title = `polaris finalize: ${state.cluster_id} (${state.run_id})`;
-    const body = [
-        `**Cluster ID:** ${state.cluster_id}`,
-        `**Run ID:** ${state.run_id}`,
-        `**Branch:** ${branch}`,
-        `**Children completed:** ${state.completed_children.length}`,
-        ``,
-        `_Generated by polaris finalize_`,
-    ].join("\n");
+    const body = buildPrBody(state, branch, authoritativeChildCount);
     const args = [
         "pr", "create",
         "--title", title,