@lsctech/polaris 0.5.4 → 0.5.6

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

@@ -35,8 +35,25 @@ function resolveStateFile(repoRoot, explicit) {
         return (0, node_path_1.resolve)(explicit);
     const taskchainPath = (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
     const polarisPath = (0, node_path_1.join)(repoRoot, ".polaris", "runs", "current-state.json");
-    if ((0, node_fs_1.existsSync)(taskchainPath))
+    // Prefer canonical cluster-scoped state.json when it exists — finalize
+    // rejects the compatibility/debug taskchain path as the sole state source.
+    // Read cluster_id from the taskchain path if available, then check the
+    // canonical path bootstrapped alongside it.
+    if ((0, node_fs_1.existsSync)(taskchainPath)) {
+        try {
+            const raw = JSON.parse((0, node_fs_1.readFileSync)(taskchainPath, "utf-8"));
+            const clusterId = typeof raw["cluster_id"] === "string" ? raw["cluster_id"] : undefined;
+            if (clusterId) {
+                const canonicalPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "state.json");
+                if ((0, node_fs_1.existsSync)(canonicalPath))
+                    return canonicalPath;
+            }
+        }
+        catch {
+            // Fall through to taskchain path
+        }
         return taskchainPath;
+    }
     if ((0, node_fs_1.existsSync)(polarisPath))
         return polarisPath;
     return taskchainPath;
@@ -112,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/loop/dispatch.js

@@ -305,7 +305,9 @@ function detectPacketGenerationFailure(packet) {
     if (allowedScope.length === 0) {
         return {
             missingField: "allowed_scope",
-            message: `Packet generation failed for ${childId}: missing actionable allowed_scope.`,
+            message: `Packet generation failed for ${childId}: missing actionable allowed_scope. ` +
+                `Add a '## Scope' section to the child issue body in your tracker, ` +
+                `then run 'polaris tracker sync-in <cluster-id>' to pull the update.`,
         };
     }
     const issueBody = packet.instructions.issue_context?.body?.trim() ?? "";

package/dist/loop/evidence-backfill.js

@@ -95,7 +95,12 @@ function backfillClusterStateEvidence(options) {
     const packetsDir = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "packets");
     const backfilled = [];
     const skipped = [];
-    for (const childId of state.completed_children) {
+    // Scan both completed and open children — recovery may have committed work
+    // for children that were never checkpointed into completed_children.
+    const seen = new Set();
+    const allChildren = [...state.completed_children, ...state.open_children].filter((id) => { if (seen.has(id))
+        return false; seen.add(id); return true; });
+    for (const childId of allChildren) {
         // Resolve result file — mirrors continue.ts priority:
         //   1. result_file on child meta (explicit override, e.g. --result-file flag)
         //   2. dispatch_record.expected_result_path
@@ -132,10 +137,12 @@ function backfillClusterStateEvidence(options) {
             continue;
         }
         // Guard: result must indicate completion.
-        if (result["status"] !== undefined && result["status"] !== "done") {
+        // Accept "done" (backfill artifact) and "success" (SuccessResultPacket schema).
+        const resultStatus = result["status"];
+        if (resultStatus !== undefined && resultStatus !== "done" && resultStatus !== "success") {
             skipped.push({
                 childId,
-                reason: `result status is not done: ${String(result["status"])}`,
+                reason: `result status is not done or success: ${String(resultStatus)}`,
             });
             continue;
         }

package/dist/loop/parent.js

@@ -776,6 +776,52 @@ async function runParentLoop(options) {
     // persisted to disk, so a fresh loop start always begins clean.
     const lifecycle = new lifecycle_js_1.WorkerLifecycleManager(maxConcurrentWorkers);
     lifecycle.forceReleaseAll();
+    // ── Auto-sync pre-flight: fetch missing issue bodies from tracker ────────
+    // When child issue bodies are absent or lack a ## Scope section, dispatch
+    // hard-fails with "empty allowed_scope". Attempt a silent tracker sync-in
+    // before the loop starts so operators don't need to run it manually.
+    if (!dryRun) {
+        const openChildrenNeedingScope = state.open_children.filter((childId) => {
+            // Skip analyze children — they never need scope (no impl packets)
+            if (isAnalyzeChild(childId, state)) {
+                return false;
+            }
+            // Resolve child body: prefer cached meta body, then fall back to snapshot
+            const cachedChildBody = state.open_children_meta?.[childId]?.body;
+            const childBody = (cachedChildBody && cachedChildBody.trim().length > 0)
+                ? cachedChildBody
+                : (0, checkpoint_js_1.readBodyFromClusterSnapshot)(state.cluster_id, childId, repoRoot) ?? '';
+            // If body is completely absent, treat as needing scope sync-in
+            if (childBody.trim().length === 0) {
+                return true;
+            }
+            // Parse child body for scope
+            const { scope: childScope } = (0, body_parser_js_1.parseIssueBody)(childBody);
+            if (childScope.length > 0) {
+                return false; // Child has scope, no sync needed
+            }
+            // Fallback: check parent/cluster-root body for scope
+            const cachedParentBody = state.open_children_meta?.[state.cluster_id]?.body;
+            const parentBody = (cachedParentBody && cachedParentBody.trim().length > 0)
+                ? cachedParentBody
+                : (0, checkpoint_js_1.readBodyFromClusterSnapshot)(state.cluster_id, state.cluster_id, repoRoot) ?? '';
+            const { scope: parentScope } = (0, body_parser_js_1.parseIssueBody)(parentBody);
+            // If parent has scope, child can inherit — no sync needed
+            // Otherwise, child truly needs scope sync-in
+            return parentScope.length === 0;
+        });
+        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);
+                process.stderr.write(`[polaris] sync-in complete.\n`);
+            }
+            catch (syncErr) {
+                process.stderr.write(`[polaris] sync-in failed (${syncErr instanceof Error ? syncErr.message : String(syncErr)}). ` +
+                    `Run 'polaris tracker sync-in ${state.cluster_id}' manually and retry.\n`);
+            }
+        }
+    }
     // ── Main dispatch loop ───────────────────────────────────────────────────
     // eslint-disable-next-line no-constant-condition
     while (true) {

package/dist/loop/run-bootstrap.js

@@ -216,6 +216,19 @@ function runLoopBootstrapInit(options) {
     //  avoid circular deps; validateState is called by dispatch which is downstream)
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(stateFile), { recursive: true });
     const sha = (0, checkpoint_js_1.writeStateAtomic)(stateFile, initialState);
+    // Also write to the canonical cluster-scoped path so `polaris finalize`
+    // can locate it without requiring --state-file. finalize rejects the
+    // .taskchain_artifacts compatibility path as the sole state source.
+    const canonicalStatePath = (0, node_path_1.resolve)(repoRoot, ".polaris", "clusters", clusterId, "state.json");
+    if ((0, node_path_1.resolve)(stateFile) !== canonicalStatePath) {
+        try {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(canonicalStatePath), { recursive: true });
+            (0, checkpoint_js_1.writeStateAtomic)(canonicalStatePath, initialState);
+        }
+        catch (error) {
+            process.stderr.write(`Warning: Could not write canonical state to ${canonicalStatePath}: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
     const summary = {
         run_id: runId,
         cluster_id: clusterId,

package/dist/types/sol-evidence.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * SOL evidence schema.
+ *
+ * Typed inputs for the Self-Optimization Loop (SOL) scoring pipeline.
+ * These types represent the normalized read model over existing durable
+ * run artifacts: state, telemetry, result packets, QC results, and
+ * (future) router decision evidence.
+ *
+ * Design rules:
+ *   - All top-level inputs are optional unless the field documents a
+ *     required identity key (run_id, cluster_id).
+ *   - Future fields from POL-469 (router evidence) and POL-476 (QC
+ *     metrics) are marked with an `availability` tag explaining when
+ *     they will be populated.
+ *   - Nothing in this file mutates run artifacts or triggers side effects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/sol-score.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * SOL scoring model types.
+ *
+ * Defines the typed output of the SOL score reports for Foremen and Workers.
+ * Each dimension has a score, confidence, and optional skipped reason so that
+ * callers can preserve the full diagnostic signal rather than a single opaque
+ * number.
+ *
+ * Design rules:
+ *   - score is 0.0–1.0 where 1.0 = optimal and 0.0 = worst observed behavior.
+ *   - confidence reflects how trustworthy the score is given the evidence.
+ *   - skipped_reason is set when evidence was absent or insufficient.
+ *   - All dimensions are optional at the top level; only present when the
+ *     relevant evidence was observed for this run.
+ *   - The existing binary gate diagnosis is preserved alongside SOL scores.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",