@lsctech/polaris 0.4.0 → 0.4.1

package/dist/autoresearch/score.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Autoresearch scoring engine.
+ *
+ * Reads run artifacts, evaluates binary gates, and produces a structured
+ * diagnosis report:
+ *
+ *   {
+ *     run_id, cluster_id, evaluated_at,
+ *     gate_results: GateResult[],
+ *     failed_gates: string[],
+ *     score: number (0.0–1.0),
+ *     diagnosis_hints: { gate, fix_zone, hint }[]
+ *   }
+ *
+ * Score = passed_gates / evaluable_gates (skipped gates are not counted).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRunArtifacts = loadRunArtifacts;
+exports.computeScore = computeScore;
+exports.buildDiagnosisHints = buildDiagnosisHints;
+exports.scoreRun = scoreRun;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const gates_js_1 = require("./gates.js");
+// ──────────────────────────────────────────────
+// Diagnosis hints table
+// ──────────────────────────────────────────────
+const HINTS = {
+    "user-intervened": {
+        fix_zone: "worker-prompt / packet-scope",
+        hint: "User pushed commits after polaris-finalize. Review the worker packet scope and instructions for ambiguity.",
+    },
+    "foreman-resent-packet": {
+        fix_zone: "foreman-dispatch / dispatch-boundary",
+        hint: "Foreman dispatched the same child more than once. Check for state-machine bugs in dispatch-boundary.ts or loop continue logic.",
+    },
+    "foreman-fixed-worker-output": {
+        fix_zone: "worker-prompt / scope-contract",
+        hint: "Foreman made corrective commits after child-complete. Tighten the worker packet's allowed_scope and acceptance criteria.",
+    },
+    "worker-output-required-fixing": {
+        fix_zone: "worker-prompt / validation-commands",
+        hint: "Post-finalize commits indicate worker output was insufficient. Add stricter validation commands to the worker packet.",
+    },
+    "validation-failed": {
+        fix_zone: "worker-validation / build-setup",
+        hint: "One or more children failed validation. Check the validation_commands in the worker packet and the worker's implementation.",
+    },
+    "worker-went-out-of-scope": {
+        fix_zone: "worker-packet / scope-contract",
+        hint: "Worker emitted out-of-scope blocks or returned blocked status. Narrow allowed_scope in the worker packet.",
+    },
+    "foreman-token-burn-over-budget": {
+        fix_zone: "bootstrap-context / prompt-size",
+        hint: "Foreman bootstrap context exceeds token budget. Reduce current-state.json or worker packet size before dispatch.",
+    },
+    "state-repair-required": {
+        fix_zone: "medic / cluster-state",
+        hint: "Medic artifacts detected — state repair was required during this run. Review the medic chart and root cause.",
+    },
+};
+// ──────────────────────────────────────────────
+// Artifact loader
+// ──────────────────────────────────────────────
+function findRunDir(repoRoot, runId) {
+    // Standard taskchain location
+    const taskchainPath = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "runs", runId);
+    if ((0, node_fs_1.existsSync)(taskchainPath))
+        return taskchainPath;
+    // Legacy .polaris/runs location
+    const polarisPath = (0, node_path_1.join)(repoRoot, ".polaris", "runs", runId);
+    if ((0, node_fs_1.existsSync)(polarisPath))
+        return polarisPath;
+    return null;
+}
+function findClusterDir(repoRoot, clusterId) {
+    const path = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId);
+    return (0, node_fs_1.existsSync)(path) ? path : null;
+}
+function readJson(filePath) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function readResultPackets(clusterDir) {
+    if (!clusterDir)
+        return [];
+    const resultsDir = (0, node_path_1.join)(clusterDir, "results");
+    if (!(0, node_fs_1.existsSync)(resultsDir))
+        return [];
+    return safeReaddir(resultsDir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => readJson((0, node_path_1.join)(resultsDir, f)))
+        .filter((v) => v !== undefined);
+}
+function extractWorkerResultContracts(resultPackets) {
+    const contracts = [];
+    for (const packet of resultPackets) {
+        const rec = packet;
+        // WorkerResultContract has packet_hash, worker_id, role as distinguishing fields
+        if (rec && typeof rec["packet_hash"] === "string" && typeof rec["worker_id"] === "string") {
+            contracts.push(rec);
+        }
+    }
+    return contracts;
+}
+function loadRunArtifacts(repoRoot, runId) {
+    const runDir = findRunDir(repoRoot, runId);
+    // Derive cluster from current-state.json in the run dir, or fallback to the default
+    let clusterId = null;
+    let currentState = null;
+    // Try run dir's current-state.json first
+    if (runDir) {
+        const runStatePath = (0, node_path_1.join)(runDir, "current-state.json");
+        if ((0, node_fs_1.existsSync)(runStatePath)) {
+            currentState = readJson(runStatePath);
+        }
+    }
+    // Fall back to the active current-state.json
+    if (!currentState) {
+        const taskchainState = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
+        const polarisState = (0, node_path_1.join)(repoRoot, ".polaris", "runs", "current-state.json");
+        const statePath = (0, node_fs_1.existsSync)(taskchainState) ? taskchainState : polarisState;
+        if ((0, node_fs_1.existsSync)(statePath)) {
+            currentState = readJson(statePath);
+        }
+    }
+    if (currentState && typeof currentState === "object" && currentState !== null) {
+        const rec = currentState;
+        if (typeof rec["cluster_id"] === "string")
+            clusterId = rec["cluster_id"];
+        if (typeof rec["run_id"] === "string" && rec["run_id"] !== runId) {
+            // State belongs to a different run — don't use it for cluster_id derivation
+            clusterId = null;
+        }
+    }
+    const clusterDir = clusterId ? findClusterDir(repoRoot, clusterId) : null;
+    // Ledger
+    const ledgerPath = (0, node_path_1.join)(repoRoot, ".polaris", "runs", "ledger.jsonl");
+    const ledgerEvents = (0, gates_js_1.readJsonLines)(ledgerPath).filter((e) => {
+        const rec = e;
+        return rec?.["run_id"] === runId;
+    });
+    // Telemetry — prefer the run dir; some older runs have it in .polaris/runs/<runId>/
+    const telemetryPath = runDir ? (0, node_path_1.join)(runDir, "telemetry.jsonl") : null;
+    const telemetryEvents = telemetryPath ? (0, gates_js_1.readJsonLines)(telemetryPath) : [];
+    // Result packets from cluster results dir
+    const resultPackets = readResultPackets(clusterDir);
+    // Also check for WorkerResultContracts inside result packets
+    const workerResultContracts = extractWorkerResultContracts(resultPackets);
+    return {
+        runId,
+        runDir,
+        clusterDir,
+        currentState,
+        ledgerEvents,
+        resultPackets,
+        workerResultContracts,
+        telemetryEvents,
+    };
+}
+// ──────────────────────────────────────────────
+// Scoring
+// ──────────────────────────────────────────────
+function computeScore(gateResults) {
+    const evaluable = gateResults.filter((g) => g.outcome !== "skipped");
+    if (evaluable.length === 0)
+        return 1.0; // nothing to evaluate — no known problems
+    const passed = evaluable.filter((g) => g.outcome === "passed").length;
+    return passed / evaluable.length;
+}
+function buildDiagnosisHints(failedGateNames) {
+    return failedGateNames.map((gate) => {
+        const h = HINTS[gate] ?? { fix_zone: "unknown", hint: `Gate ${gate} failed — no hint available.` };
+        return { gate, ...h };
+    });
+}
+// ──────────────────────────────────────────────
+// Main entry point
+// ──────────────────────────────────────────────
+function scoreRun(repoRoot, runId) {
+    const artifacts = loadRunArtifacts(repoRoot, runId);
+    const gateResults = gates_js_1.ALL_GATES.map((evaluator) => evaluator(artifacts));
+    const failedGates = gateResults.filter((g) => g.outcome === "failed").map((g) => g.gate);
+    const score = computeScore(gateResults);
+    const diagnosisHints = buildDiagnosisHints(failedGates);
+    const clusterId = artifacts.currentState &&
+        typeof artifacts.currentState === "object" &&
+        !Array.isArray(artifacts.currentState)
+        ? artifacts.currentState["cluster_id"] ?? null
+        : null;
+    return {
+        run_id: runId,
+        cluster_id: clusterId,
+        evaluated_at: new Date().toISOString(),
+        gate_results: gateResults,
+        failed_gates: failedGates,
+        score,
+        diagnosis_hints: diagnosisHints,
+    };
+}

package/dist/cli/autoresearch.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAutoresearchCommand = createAutoresearchCommand;
+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 repoRoot = options.repoRoot;
+    const autoresearch = new commander_1.Command("autoresearch")
+        .description("Autoresearch tools (dev-gated — Polaris development context only)")
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    autoresearch
+        .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)
+        .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 report = (0, score_js_1.scoreRun)(root, runId);
+            const output = cmdOptions.json
+                ? JSON.stringify(report)
+                : JSON.stringify(report, null, 2);
+            process.stdout.write(`${output}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`autoresearch score error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    autoresearch
+        .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)
+        .option("--team <team>", "Linear team name or ID to file issues in", "Polaris")
+        .option("--dry-run", "Log what would be created without calling Linear")
+        .option("--json", "Output raw JSON (default: pretty-printed)")
+        .action(async (diagnosisFile, 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);
+        }
+        let report;
+        try {
+            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.exit(1);
+        }
+        const proposals = (0, proposal_js_1.buildProposals)(report);
+        if (proposals.length === 0) {
+            process.stdout.write("No failed gates with fix zone mappings — nothing to propose.\n");
+            process.exit(0);
+        }
+        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.exit(1);
+        }
+        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(`autoresearch propose error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    return autoresearch;
+}

package/dist/cli/index.js

@@ -28,6 +28,7 @@ const medic_js_1 = require("./medic.js");
 const welfare_js_1 = require("../map/welfare.js");
 const adopt_command_js_1 = require("./adopt-command.js");
 const simplicity_js_1 = require("../loop/simplicity.js");
+const autoresearch_js_1 = require("./autoresearch.js");
 function resolveStateFile(repoRoot, explicit) {
     if (explicit)
         return (0, node_path_1.resolve)(explicit);
@@ -109,6 +110,7 @@ function createPolarisCommand(options = {}) {
         repoRoot,
     }));
     program.addCommand((0, adopt_command_js_1.createAdoptCommand)({ repoRoot }));
+    program.addCommand((0, autoresearch_js_1.createAutoresearchCommand)({ repoRoot }));
     program
         .command("simplicity")
         .description("View or override the simplicity discipline mode for the active run")

package/dist/cli/worker.js

@@ -102,17 +102,27 @@ function validateWorkerCompletionResult(repoRoot, packet, resultFile) {
         },
     };
 }
-function updateCompletionState(state, childId, commit) {
+function updateCompletionState(state, childId, commit, packet, repoRoot) {
     const completedChildren = Array.from(new Set([...state.completed_children, childId]));
     const remainingOpenChildren = state.open_children.filter((child) => child !== childId);
+    const dispatchRecord = state.open_children_meta?.[childId]?.dispatch_record;
+    const resultFile = packet.result_file_contract.result_file;
+    const telemetryFile = resolveRepoPath(repoRoot, packet.telemetry_file);
+    const packetPath = dispatchRecord?.packet_path ?? "";
+    const workerResult = (0, checkpoint_js_1.buildWorkerResultContract)({
+        state,
+        childId,
+        resultFile,
+        telemetryFile,
+        lastCommit: commit,
+        validation: "passed",
+        packetHash: packetPath ? (0, checkpoint_js_1.computePacketHashFromPath)(packetPath) : "",
+        status: "done",
+        nextRecommendedAction: "continue",
+    });
     const completedChildrenResults = {
         ...(state.completed_children_results ?? {}),
-        [childId]: {
-            status: "done",
-            validation: "passed",
-            commit,
-            next_recommended_action: "continue",
-        },
+        [childId]: workerResult,
     };
     return {
         ...state,
@@ -236,7 +246,7 @@ function createWorkerCommand(options) {
                 return;
             }
             const state = (0, checkpoint_js_1.readState)(stateFile);
-            const updatedState = updateCompletionState(state, packet.active_child, validation.result.commit);
+            const updatedState = updateCompletionState(state, packet.active_child, validation.result.commit, packet, options.repoRoot);
             (0, checkpoint_js_1.writeStateAtomic)(stateFile, updatedState);
             // Sync cluster-state.json so finalize and the parent loop see a consistent view.
             try {

package/dist/loop/bootstrap-packet.js

@@ -71,7 +71,7 @@ function buildBootstrapPacket(state, stateFile, currentStateSha, repoRoot, compl
         last_completed_step: state.step_cursor,
         last_completed_child: completedChild,
         next_step: nextChild ? "03-execute-child" : "CLUSTER-COMPLETE",
-        open_children: state.open_children,
+        open_children: { next_child: state.open_children[0] ?? null, remaining_count: state.open_children.length },
         artifact_pointers: {
             current_state: relStateFile,
             telemetry: relTelemetryFile,

package/dist/loop/checkpoint.js

@@ -9,6 +9,10 @@ exports.appendWorkerScopeFidelityEvent = appendWorkerScopeFidelityEvent;
 exports.appendBoundaryEvent = appendBoundaryEvent;
 exports.appendAbortEvent = appendAbortEvent;
 exports.appendStaleDispatchAbortedEvent = appendStaleDispatchAbortedEvent;
+exports.toValidationStatus = toValidationStatus;
+exports.countTelemetryEvents = countTelemetryEvents;
+exports.computePacketHashFromPath = computePacketHashFromPath;
+exports.buildWorkerResultContract = buildWorkerResultContract;
 exports.readBodyFromClusterSnapshot = readBodyFromClusterSnapshot;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
@@ -268,7 +272,16 @@ function validateState(state) {
     return errors;
 }
 function writeStateAtomic(stateFile, state) {
-    const content = JSON.stringify(state, null, 2);
+    const nextChild = state.open_children[0];
+    const slimmedState = state.open_children_meta
+        ? {
+            ...state,
+            open_children_meta: Object.fromEntries(Object.entries(state.open_children_meta).map(([id, meta]) => id === nextChild
+                ? [id, meta]
+                : [id, (({ body: _b, ...rest }) => rest)(meta)])),
+        }
+        : state;
+    const content = JSON.stringify(slimmedState, null, 2);
     const tmp = `${stateFile}.tmp`;
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(stateFile), { recursive: true });
     (0, node_fs_1.writeFileSync)(tmp, content, "utf-8");
@@ -305,6 +318,112 @@ function appendStaleDispatchAbortedEvent(telemetryFile, event) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
     (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(timestampedEvent) + "\n", "utf-8");
 }
+/**
+ * Normalize a raw validation value to one of the canonical result states.
+ */
+function toValidationStatus(validation) {
+    if (typeof validation === "string") {
+        const v = validation.trim().toLowerCase();
+        if (v === "passed" || v === "failed" || v === "skipped")
+            return v;
+        if (["pass", "success", "ok"].includes(v))
+            return "passed";
+    }
+    if (validation === true)
+        return "passed";
+    if (validation === false)
+        return "failed";
+    if (typeof validation === "object" && validation !== null && !Array.isArray(validation)) {
+        const r = validation;
+        if (Array.isArray(r["passed"]) && r["passed"].length > 0)
+            return "passed";
+        if (Array.isArray(r["failed"]) && r["failed"].length > 0)
+            return "failed";
+    }
+    return "skipped";
+}
+/**
+ * Count telemetry events of a specific name for a given child.
+ * Returns 0 when the telemetry file is missing or unreadable.
+ */
+function countTelemetryEvents(telemetryFile, eventName, childId) {
+    if (!(0, node_fs_1.existsSync)(telemetryFile))
+        return 0;
+    try {
+        const content = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim();
+        if (!content)
+            return 0;
+        let count = 0;
+        for (const line of content.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (event["event"] === eventName && event["child_id"] === childId) {
+                    count += 1;
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Compute the SHA-256 hash of a packet file. Returns an empty string when
+ * the file is missing or unreadable so evidence never blocks completion.
+ */
+function computePacketHashFromPath(packetPath) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)(packetPath, "utf-8");
+        return (0, node_crypto_1.createHash)("sha256").update(raw, "utf-8").digest("hex");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Build a WorkerResultContract from the durable dispatch state and telemetry.
+ * Missing optional values are filled with safe defaults so the record is always
+ * complete enough for retroactive scoring.
+ */
+function buildWorkerResultContract(args) {
+    const dispatchRecord = args.state.open_children_meta?.[args.childId]?.dispatch_record;
+    const role = dispatchRecord?.role ?? "worker";
+    const provider = dispatchRecord?.provider ?? "unknown";
+    const workerId = dispatchRecord?.worker_id ?? dispatchRecord?.dispatch_id ?? "unknown";
+    const packetPath = dispatchRecord?.packet_path ?? "";
+    const heartbeatCount = countTelemetryEvents(args.telemetryFile, "worker-heartbeat", args.childId);
+    const escalationCount = countTelemetryEvents(args.telemetryFile, "worker-blocked", args.childId);
+    return {
+        child_id: args.childId,
+        status: args.status ?? "done",
+        validation: toValidationStatus(args.validation),
+        commit: args.lastCommit,
+        next_recommended_action: args.nextRecommendedAction ?? "continue",
+        run_id: args.state.run_id,
+        cluster_id: args.state.cluster_id,
+        skill_name: args.state.skill ?? null,
+        role,
+        provider,
+        packet_hash: args.packetHash,
+        worker_id: workerId,
+        escalation_count: escalationCount,
+        heartbeat_count: heartbeatCount,
+        result_artifact_path: args.resultFile,
+        packet_path: packetPath,
+        telemetry_path: args.telemetryFile,
+        user_intervened: null,
+        foreman_intervened: null,
+        dispatch_epoch: args.state.dispatch_boundary?.dispatch_epoch,
+        session_pointer: null,
+        result_data: args.resultData,
+    };
+}
 /**
  * Reads the issue body for a node from the durable cluster snapshot at
  * `.polaris/clusters/<clusterId>/clusters.json`. Returns undefined when the

package/dist/loop/continue.js

@@ -482,12 +482,20 @@ function runLoopContinue(options) {
         ...(state.completed_children_results ?? {}),
     };
     if (completedChild && completionResultFile) {
-        updatedCompletedChildrenResults[completedChild] = {
+        const telemetryFile = resolveTelemetryFilePath(state, repoRoot);
+        const dispatchRecord = state.open_children_meta?.[completedChild]?.dispatch_record;
+        const packetPath = dispatchRecord?.packet_path ?? "";
+        updatedCompletedChildrenResults[completedChild] = (0, checkpoint_js_1.buildWorkerResultContract)({
+            state,
+            childId: completedChild,
+            resultFile: completionResultFile,
+            telemetryFile,
+            lastCommit: completionCommit || null,
+            validation: completionValidation,
+            packetHash: packetPath ? (0, checkpoint_js_1.computePacketHashFromPath)(packetPath) : "",
             status: "done",
-            validation: hasValidationEvidence(completionValidation) ? "passed" : "skipped",
-            commit: completionCommit || null,
-            next_recommended_action: "continue",
-        };
+            nextRecommendedAction: "continue",
+        });
     }
     const updatedState = {
         ...state,