@lsctech/polaris 0.5.5 → 0.5.7

package/dist/cli/autoresearch.js

@@ -1,19 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAutoresearchCommand = createAutoresearchCommand;
+exports.createAutoresearchCommand = void 0;
+exports.createSolCommand = createSolCommand;
 const node_path_1 = require("node:path");
 const commander_1 = require("commander");
 const dev_gate_js_1 = require("../autoresearch/dev-gate.js");
 const score_js_1 = require("../autoresearch/score.js");
 const proposal_js_1 = require("../autoresearch/proposal.js");
 const routing_js_1 = require("../autoresearch/routing.js");
-function createAutoresearchCommand(options) {
+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_recommendations_js_1 = require("../autoresearch/sol-recommendations.js");
+function createSolCommand(options) {
     const repoRoot = options.repoRoot;
-    const autoresearch = new commander_1.Command("autoresearch")
-        .description("Autoresearch tools (dev-gated — Polaris development context only)")
+    const sol = new commander_1.Command("sol")
+        .alias("autoresearch")
+        .description("Self-Optimization Loop (SOL) tools — autoresearch compatibility alias (dev-gated — Polaris development context only)")
         .showHelpAfterError()
         .showSuggestionAfterError();
-    autoresearch
+    sol
         .command("score <run-id>")
         .description("Score a completed Polaris run against the binary gate scorecard and output a diagnosis report")
         .option("-r, --repo-root <path>", "Repository root", repoRoot)
@@ -35,11 +42,39 @@ function createAutoresearchCommand(options) {
             process.stdout.write(`${output}\n`);
         }
         catch (err) {
-            process.stderr.write(`autoresearch score error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.stderr.write(`sol score error: ${err instanceof Error ? err.message : String(err)}\n`);
             process.exit(1);
         }
     });
-    autoresearch
+    sol
+        .command("score-report <run-id>")
+        .description("Compute a SOL score report with diagnostic sub-scores for Foreman and Workers")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--json", "Output raw JSON (default: pretty-printed)")
+        .action((runId, cmdOptions) => {
+        const root = (0, node_path_1.resolve)(cmdOptions.repoRoot ?? repoRoot);
+        try {
+            (0, dev_gate_js_1.assertPolarisDevContext)(root);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        try {
+            const artifacts = (0, score_js_1.loadRunArtifacts)(root, runId);
+            const evidence = (0, sol_evidence_loader_js_1.aggregateSolEvidence)(artifacts);
+            const report = (0, sol_scorer_js_1.computeSolScoreReport)(evidence);
+            const output = cmdOptions.json
+                ? JSON.stringify(report)
+                : JSON.stringify(report, null, 2);
+            process.stdout.write(`${output}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`sol score-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)")
         .option("-r, --repo-root <path>", "Repository root", repoRoot)
@@ -60,7 +95,7 @@ function createAutoresearchCommand(options) {
             report = (0, proposal_js_1.loadDiagnosisReport)((0, node_path_1.resolve)(diagnosisFile));
         }
         catch (err) {
-            process.stderr.write(`autoresearch propose: invalid diagnosis file: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.stderr.write(`sol propose: invalid diagnosis file: ${err instanceof Error ? err.message : String(err)}\n`);
             process.exit(1);
         }
         const proposals = (0, proposal_js_1.buildProposals)(report);
@@ -70,7 +105,7 @@ function createAutoresearchCommand(options) {
         }
         const apiKey = process.env["LINEAR_API_KEY"];
         if (!apiKey && !cmdOptions.dryRun) {
-            process.stderr.write("autoresearch propose: LINEAR_API_KEY environment variable is required.\n");
+            process.stderr.write("sol propose: LINEAR_API_KEY environment variable is required.\n");
             process.exit(1);
         }
         try {
@@ -88,9 +123,148 @@ function createAutoresearchCommand(options) {
             }
         }
         catch (err) {
-            process.stderr.write(`autoresearch propose error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.stderr.write(`sol propose error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    sol
+        .command("recommend")
+        .description("Generate SOL routing recommendations from historical snapshots (advisory by default; filing is Polaris-dev only)")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--history-path <path>", "Custom history directory (relative to repo root)")
+        .option("--group-by <dims>", "Comma-separated grouping dimensions (provider,model,role,route,task_type,repo,risk,worker_id,run_id,time_window)", "provider,model,role,route,task_type")
+        .option("--threshold <n>", "Mean composite threshold below which a recommendation is triggered", "0.7")
+        .option("--min-samples <n>", "Minimum snapshots per group before recommending", "2")
+        .option("--file", "File review-gated tracker proposals (requires Polaris dev context)")
+        .option("--team <team>", "Tracker team name or ID", "Polaris")
+        .option("--dry-run", "Show tracker mutations without writing to the tracker")
+        .option("--json", "Output raw JSON (default: human-readable)")
+        .action(async (cmdOptions) => {
+        const root = (0, node_path_1.resolve)(cmdOptions.repoRoot ?? repoRoot);
+        let snapshots;
+        try {
+            snapshots = (0, sol_history_js_1.loadSnapshots)(root, cmdOptions.historyPath);
+        }
+        catch (err) {
+            process.stderr.write(`sol recommend error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        const groupBy = cmdOptions.groupBy.split(",").filter(Boolean);
+        const threshold = parseFloat(cmdOptions.threshold) || 0.7;
+        const minSamples = parseInt(cmdOptions.minSamples, 10) || 2;
+        const report = (0, sol_recommendations_js_1.generateRecommendations)(snapshots, { groupBy, threshold, minSamples });
+        // Advisory mode: never touches the tracker or filesystem.
+        if (!cmdOptions.file) {
+            if (cmdOptions.json) {
+                process.stdout.write(JSON.stringify(report) + "\n");
+            }
+            else {
+                process.stdout.write((0, sol_recommendations_js_1.formatRecommendationsCli)(report));
+            }
+            process.exit(0);
+        }
+        // Filing mode: Polaris dev context only.
+        try {
+            (0, dev_gate_js_1.assertPolarisDevContext)(root);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        if (report.recommendations.length === 0) {
+            process.stdout.write("No underperforming groups — nothing to file.\n");
+            process.exit(0);
+        }
+        const apiKey = process.env["LINEAR_API_KEY"];
+        if (!apiKey && !cmdOptions.dryRun) {
+            process.stderr.write("sol recommend: LINEAR_API_KEY environment variable is required.\n");
+            process.exit(1);
+        }
+        const proposals = (0, sol_recommendations_js_1.recommendationsToProposals)(report.recommendations);
+        try {
+            const result = await (0, routing_js_1.routeProposals)(proposals, {
+                apiKey: apiKey ?? "",
+                teamKey: cmdOptions.team,
+                dryRun: cmdOptions.dryRun,
+            });
+            const output = cmdOptions.json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+            process.stdout.write(`${output}\n`);
+            if (result.total_errors > 0) {
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`sol recommend error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    // ── history subcommand group ──
+    const history = new commander_1.Command("history")
+        .description("SOL historical performance storage and reports");
+    history
+        .command("save <run-id>")
+        .description("Score a run and persist the SOL score snapshot to local history")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--history-path <path>", "Custom history directory (relative to repo root)")
+        .action((runId, cmdOptions) => {
+        const root = (0, node_path_1.resolve)(cmdOptions.repoRoot ?? repoRoot);
+        try {
+            (0, dev_gate_js_1.assertPolarisDevContext)(root);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        try {
+            const artifacts = (0, score_js_1.loadRunArtifacts)(root, runId);
+            const evidence = (0, sol_evidence_loader_js_1.aggregateSolEvidence)(artifacts);
+            const report = (0, sol_scorer_js_1.computeSolScoreReport)(evidence);
+            const workerIds = evidence.children.map((c) => c.worker_id);
+            const snapshot = (0, sol_history_js_1.buildSnapshot)(report, evidence.grouping_keys, workerIds);
+            const path = (0, sol_history_js_1.appendSnapshot)(root, snapshot, cmdOptions.historyPath);
+            process.stdout.write(`Snapshot saved to ${path}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`sol history save error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    history
+        .command("report")
+        .description("Generate a report from SOL historical snapshots")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .option("--history-path <path>", "Custom history directory (relative to repo root)")
+        .option("--group-by <dims>", "Comma-separated grouping dimensions (repo,route,task_type,role,risk,provider,model,worker_id,run_id,time_window)", "run_id")
+        .option("--window-days <days>", "Time window size in days for time_window grouping", "7")
+        .option("--json", "Output raw JSON (default: human-readable table)")
+        .action((cmdOptions) => {
+        const root = (0, node_path_1.resolve)(cmdOptions.repoRoot ?? repoRoot);
+        try {
+            (0, dev_gate_js_1.assertPolarisDevContext)(root);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        try {
+            const snapshots = (0, sol_history_js_1.loadSnapshots)(root, cmdOptions.historyPath);
+            const groupBy = cmdOptions.groupBy.split(",").filter(Boolean);
+            const windowDays = parseInt(cmdOptions.windowDays, 10) || 7;
+            const report = (0, sol_report_js_1.generateReport)(snapshots, { groupBy, windowDays });
+            if (cmdOptions.json) {
+                process.stdout.write(JSON.stringify(report) + "\n");
+            }
+            else {
+                process.stdout.write((0, sol_report_js_1.formatReportCli)(report));
+            }
+        }
+        catch (err) {
+            process.stderr.write(`sol history report error: ${err instanceof Error ? err.message : String(err)}\n`);
             process.exit(1);
         }
     });
-    return autoresearch;
+    sol.addCommand(history);
+    return sol;
 }
+/** @deprecated Use {@link createSolCommand}. */
+exports.createAutoresearchCommand = createSolCommand;

package/dist/cli/index.js

@@ -129,7 +129,7 @@ function createPolarisCommand(options = {}) {
     }));
     program.addCommand((0, adopt_command_js_1.createAdoptCommand)({ repoRoot }));
     program.addCommand((0, upgrade_command_js_1.createUpgradeCommand)({ repoRoot }));
-    program.addCommand((0, autoresearch_js_1.createAutoresearchCommand)({ repoRoot }));
+    program.addCommand((0, autoresearch_js_1.createSolCommand)({ repoRoot }));
     program
         .command("simplicity")
         .description("View or override the simplicity discipline mode for the active run")

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/index.js

@@ -185,7 +185,7 @@ function resolveQcTelemetryFile(state, repoRoot) {
 }
 async function runQcGate(options) {
     const { config, state, repoRoot, branch, trigger, prUrl, stepLabel } = options;
-    const registry = (0, index_js_2.createDefaultQcRegistry)();
+    const registry = (0, index_js_2.createQcRegistry)(config);
     const result = await (0, index_js_2.runQcAtTrigger)({
         config,
         registry,

package/dist/loop/parent.js

@@ -37,12 +37,15 @@ const node_child_process_1 = require("node:child_process");
 const artifact_policy_js_1 = require("../finalize/artifact-policy.js");
 const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
 const triggers_js_1 = require("../qc/triggers.js");
+const index_js_1 = require("../qc/index.js");
+const repair_loop_js_1 = require("../qc/repair-loop.js");
+const worker_packet_js_2 = require("./worker-packet.js");
 const run_bootstrap_js_1 = require("./run-bootstrap.js");
 const ledger_js_1 = require("./ledger.js");
 const dispatch_js_1 = require("./dispatch.js");
-const index_js_1 = require("./router/index.js");
+const index_js_2 = require("./router/index.js");
 const child_selector_js_1 = require("../runtime/scheduling/child-selector.js");
-const index_js_2 = require("../tracker/index.js");
+const index_js_3 = require("../tracker/index.js");
 const lifecycle_transition_js_1 = require("../tracker/lifecycle-transition.js");
 const local_graph_js_1 = require("../tracker/local-graph.js");
 const CLAIM_TTL_MS = 30 * 60 * 1000;
@@ -813,7 +816,7 @@ async function runParentLoop(options) {
         if (openChildrenNeedingScope.length > 0) {
             process.stderr.write(`[polaris] ${openChildrenNeedingScope.length} children missing scope — attempting tracker sync-in...\n`);
             try {
-                await (0, index_js_2.loadTrackerGraph)(config, state.cluster_id);
+                await (0, index_js_3.loadTrackerGraph)(config, state.cluster_id);
                 process.stderr.write(`[polaris] sync-in complete.\n`);
             }
             catch (syncErr) {
@@ -844,7 +847,7 @@ async function runParentLoop(options) {
             max_concurrent: maxConcurrentWorkers,
             claim_ttl_ms: CLAIM_TTL_MS,
             get_dependencies: (childId) => localGraph?.getDependencies(childId) ?? [],
-            decide_route: ({ activeSlotsByProvider }) => (0, index_js_1.decideWorkerRoute)({
+            decide_route: ({ activeSlotsByProvider }) => (0, index_js_2.decideWorkerRoute)({
                 role: "worker",
                 taskType: "impl",
                 adapter: adapterName,
@@ -884,6 +887,154 @@ async function runParentLoop(options) {
                 };
             }
             const autoFinalizeRequested = orchestrationMode === "auto" && config.orchestration?.auto_finalize === true;
+            // ── QC repair loop (post-completion gate) ─────────────────────────────
+            // When QC is enabled, run the completed-cluster QC trigger and, if
+            // findings are produced, run the bounded repair loop before halting.
+            // The repair loop is Foreman-owned: it dispatches repair workers via the
+            // same adapter and NEVER implements repairs inline.
+            if (!dryRun && config.qc?.enabled) {
+                const qcRegistry = (0, index_js_1.createQcRegistry)(config.qc);
+                let initialQcResult;
+                try {
+                    initialQcResult = await (0, index_js_1.runQcAtTrigger)({
+                        config: config.qc,
+                        registry: qcRegistry,
+                        trigger: "completed-cluster",
+                        repoRoot,
+                        runId: state.run_id,
+                        clusterId: state.cluster_id,
+                        branch: state.branch ?? getCurrentBranch(repoRoot),
+                        telemetryFile,
+                        state,
+                    });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    appendTelemetry(telemetryFile, {
+                        event: "qc-repair-loop-qc-run-error",
+                        run_id: state.run_id,
+                        error: msg,
+                        timestamp: new Date().toISOString(),
+                    });
+                    // Non-fatal: proceed to cluster-complete without repair loop.
+                    initialQcResult = null;
+                }
+                const hasFindings = initialQcResult !== null &&
+                    initialQcResult.results.some((r) => r.findings.length > 0 && r.status !== "passed" && r.status !== "skipped");
+                if (initialQcResult !== null && hasFindings) {
+                    const maxRepairRounds = config.qc.maxRepairRounds ?? repair_loop_js_1.DEFAULT_MAX_REPAIR_ROUNDS;
+                    const priorLoopState = state.qc_repair_loop ?? null;
+                    // Build the repair worker dispatcher using the existing adapter + provider.
+                    const repairDispatcher = async (packet, round, manifest) => {
+                        const repairPacketId = packet.packetId;
+                        const dispatchId = (0, node_crypto_1.randomUUID)();
+                        const repairWorkerId = `${state.run_id}:repair-${repairPacketId}:${Date.now()}`;
+                        const repairResultPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", state.cluster_id, "results", `repair-${repairPacketId}-${dispatchId}.json`);
+                        const workerPacket = (0, worker_packet_js_2.compileRepairWorkerPacket)({
+                            runId: state.run_id,
+                            clusterId: state.cluster_id,
+                            packetId: repairPacketId,
+                            branch: state.branch ?? getCurrentBranch(repoRoot),
+                            stateFile,
+                            telemetryFile,
+                            round,
+                            allowedScope: packet.allowedScope,
+                            prohibitedScope: packet.prohibitedScope,
+                            validationCommands: packet.validationCommands,
+                            rootCauseHint: packet.rootCauseHint,
+                            resultFile: repairResultPath,
+                            maxConcurrentWorkers,
+                        });
+                        appendTelemetry(telemetryFile, {
+                            event: "repair-worker-dispatched",
+                            run_id: state.run_id,
+                            cluster_id: state.cluster_id,
+                            packet_id: repairPacketId,
+                            worker_id: repairWorkerId,
+                            round,
+                            timestamp: new Date().toISOString(),
+                        });
+                        try {
+                            const dispatchResult = await adapter.dispatch(workerPacket, { provider: providerName, dryRun });
+                            const workerSummary = parseWorkerSummary(dispatchResult.summary);
+                            const success = workerSummary?.status === "done";
+                            appendTelemetry(telemetryFile, {
+                                event: "repair-worker-completed",
+                                run_id: state.run_id,
+                                packet_id: repairPacketId,
+                                worker_id: repairWorkerId,
+                                round,
+                                status: success ? "success" : "failure",
+                                timestamp: new Date().toISOString(),
+                            });
+                            return {
+                                packetId: repairPacketId,
+                                status: success ? "success" : "failure",
+                                commitSha: workerSummary?.commit,
+                                errorMessage: success ? undefined : String(workerSummary?.error_message ?? "repair worker failed"),
+                            };
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            appendTelemetry(telemetryFile, {
+                                event: "repair-worker-error",
+                                run_id: state.run_id,
+                                packet_id: repairPacketId,
+                                worker_id: repairWorkerId,
+                                round,
+                                error: msg,
+                                timestamp: new Date().toISOString(),
+                            });
+                            return {
+                                packetId: repairPacketId,
+                                status: "failure",
+                                errorMessage: msg,
+                            };
+                        }
+                    };
+                    try {
+                        const repairLoopResult = await (0, repair_loop_js_1.runQcRepairLoop)({
+                            clusterId: state.cluster_id,
+                            runId: state.run_id,
+                            branch: state.branch ?? getCurrentBranch(repoRoot),
+                            repoRoot,
+                            telemetryFile,
+                            config: config.qc,
+                            registry: qcRegistry,
+                            initialQcResults: initialQcResult.results,
+                            dispatchRepairWorker: repairDispatcher,
+                            maxRounds: maxRepairRounds,
+                            priorLoopState,
+                            onStateUpdate: (loopState) => {
+                                // Persist loop state to the state file on each mutation.
+                                const stateWithLoop = { ...state, qc_repair_loop: loopState };
+                                (0, checkpoint_js_1.writeStateAtomic)(stateFile, stateWithLoop);
+                            },
+                        });
+                        state = { ...state, qc_repair_loop: repairLoopResult.loop_state };
+                        (0, checkpoint_js_1.writeStateAtomic)(stateFile, state);
+                        appendTelemetry(telemetryFile, {
+                            event: "qc-repair-loop-finished",
+                            run_id: state.run_id,
+                            outcome: repairLoopResult.outcome,
+                            rounds_completed: repairLoopResult.rounds_completed,
+                            summary: repairLoopResult.summary,
+                            timestamp: new Date().toISOString(),
+                        });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        appendTelemetry(telemetryFile, {
+                            event: "qc-repair-loop-error",
+                            run_id: state.run_id,
+                            error: msg,
+                            timestamp: new Date().toISOString(),
+                        });
+                        // Non-fatal: proceed to cluster-complete.
+                    }
+                }
+            }
+            // ── End QC repair loop ─────────────────────────────────────────────────
             // All children completed — write final state and halt
             if (!dryRun) {
                 logStatus(notificationFormat, "COMPLETE");
@@ -1427,7 +1578,7 @@ async function runParentLoop(options) {
                 // Errors are logged to telemetry but do not fail the halt.
                 let adapter;
                 try {
-                    adapter = (0, index_js_2.loadTrackerAdapter)(config);
+                    adapter = (0, index_js_3.loadTrackerAdapter)(config);
                 }
                 catch (err) {
                     const errorMsg = err instanceof Error ? err.message : String(err);