@lsctech/polaris 0.5.5 → 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

@@ -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/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.5",
+  "version": "0.5.6",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",