@lsctech/polaris 0.3.27 → 0.3.28

package/dist/cognition/closeout-librarian-types.js

@@ -106,6 +106,9 @@ function validateCloseoutLibrarianResult(value) {
     if (r["commit_sha"] !== null && typeof r["commit_sha"] !== "string") {
         errors.push("commit_sha must be a string or null");
     }
+    if (typeof r["commit_message"] !== "string") {
+        errors.push("commit_message must be a string");
+    }
     if (!Array.isArray(r["files_committed"])) {
         errors.push("files_committed must be an array");
     }

package/dist/config/validator.js

@@ -28,6 +28,7 @@ const SUPPORTED_EXECUTION_ROLES = [
     "orchestrator",
     "startup",
     "worker",
+    "foreman",
     "analyst",
     "analysis",
     "repair",

package/dist/finalize/index.js

@@ -111,7 +111,7 @@ function checkLibrarianGate(repoRoot, clusterId) {
     })[0];
     if (!latestPacket) {
         return ("Closeout Librarian has not been dispatched for this cluster.\n" +
-            `  1. Generate packet:  npm run polaris -- librarian packet ${clusterId} --state-file <state-file>\n` +
+            `  1. Generate packet:  npx polaris librarian packet ${clusterId} --state-file <state-file>\n` +
             `  2. Dispatch the Librarian with the generated packet path as the sole session prompt.\n` +
             `  3. Wait for the Librarian to write its sealed result.\n` +
             `  4. Re-run finalize.\n` +
@@ -122,11 +122,11 @@ function checkLibrarianGate(repoRoot, clusterId) {
         packetJson = JSON.parse((0, node_fs_1.readFileSync)(latestPacket, "utf-8"));
     }
     catch {
-        return `Cannot read Librarian packet at ${latestPacket}. Regenerate with: npm run polaris -- librarian packet ${clusterId}`;
+        return `Cannot read Librarian packet at ${latestPacket}. Regenerate with: npx polaris librarian packet ${clusterId}`;
     }
     const resultPath = packetJson["result_path"];
     if (typeof resultPath !== "string") {
-        return `Librarian packet is malformed: missing result_path. Regenerate with: npm run polaris -- librarian packet ${clusterId}`;
+        return `Librarian packet is malformed: missing result_path. Regenerate with: npx polaris librarian packet ${clusterId}`;
     }
     if (!(0, node_fs_1.existsSync)(resultPath)) {
         return ("Closeout Librarian has not written its sealed result yet.\n" +
@@ -152,16 +152,20 @@ function checkLibrarianGate(repoRoot, clusterId) {
     if (packetJson["run_id"] !== result.run_id) {
         return `Librarian result run_id mismatch (packet: ${packetJson["run_id"]}, result: ${result.run_id}).`;
     }
-    // Validate files_committed against packet scope constraints
+    // Validate files_committed against packet scope constraints.
+    // allowed_write_paths and prohibited_write_paths in the packet are absolute paths.
+    // files_committed in the result are repo-relative paths (git output). Resolve each
+    // to absolute before comparing so the patterns match correctly.
     const allowedWritePaths = (packetJson["allowed_write_paths"] ?? []);
     const prohibitedWritePaths = (packetJson["prohibited_write_paths"] ?? []);
     const filesCommitted = result.files_committed ?? [];
     for (const file of filesCommitted) {
-        const prohibitedMatch = prohibitedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, file));
+        const absFile = (0, node_path_1.resolve)(repoRoot, file);
+        const prohibitedMatch = prohibitedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, absFile));
         if (prohibitedMatch) {
             return `Librarian wrote to prohibited path: ${file} (matched pattern: ${prohibitedMatch})`;
         }
-        const allowedMatch = allowedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, file));
+        const allowedMatch = allowedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, absFile));
         if (allowedMatch)
             continue; // explicitly allowed
         return `Librarian wrote to out-of-scope path: ${file} (not in allowed_write_paths)`;

package/dist/loop/abort.js

@@ -31,7 +31,7 @@ function appendBlockedLedgerEvent(repoRoot, state, childId, reason) {
         timestamp: new Date().toISOString(),
         blocker: {
             summary: reason,
-            unblock_condition: `Resolve blocker then run: npm run polaris -- loop run ${state.cluster_id}`,
+            unblock_condition: `Resolve blocker then run: npx polaris loop run ${state.cluster_id}`,
         },
     });
 }
@@ -183,6 +183,6 @@ function runLoopAbort(options) {
         reason,
         timestamp,
     });
-    process.stderr.write(`Loop aborted. Reason: ${reason}. Resolve blocker then run: npm run polaris -- loop run ${updatedState.cluster_id}\n`);
+    process.stderr.write(`Loop aborted. Reason: ${reason}. Resolve blocker then run: npx polaris loop run ${updatedState.cluster_id}\n`);
     process.exit(0);
 }

package/dist/loop/dispatch-boundary.js

@@ -49,7 +49,7 @@ const node_path_1 = require("node:path");
  * Error emitted when the parent/orchestrator attempts inline child execution.
  * This is the canonical error message for dispatch boundary violations.
  */
-exports.INLINE_EXECUTION_ERROR = "Child execution requires dispatch boundary. Parent/orchestrator may not implement child inline. Use npm run polaris -- loop dispatch.";
+exports.INLINE_EXECUTION_ERROR = "Child execution requires dispatch boundary. Parent/orchestrator may not implement child inline. Use npx polaris loop dispatch.";
 /**
  * Error emitted when PR creation is attempted without a passing Librarian gate.
  */
@@ -57,7 +57,7 @@ exports.LIBRARIAN_GATE_ERROR = "PR creation requires Closeout Librarian gate. Ge
 /**
  * Error emitted when `polaris loop continue` is called without a prior dispatch.
  */
-exports.DISPATCH_REQUIRED_ERROR = "Dispatch required before continuation. Call `npm run polaris -- loop dispatch` first, then run the worker before calling continue.";
+exports.DISPATCH_REQUIRED_ERROR = "Dispatch required before continuation. Call `npx polaris loop dispatch` first, then run the worker before calling continue.";
 /**
  * Allowed transitions in the dispatch state machine.
  * Format: [from, to, command-that-drives-transition]
@@ -186,7 +186,7 @@ function assertNoActiveChildBeforeDispatch(state, telemetryFile) {
         });
         throw new Error(`active_child is already set to "${state.active_child}". Previous dispatch was not completed. ` +
             exports.INLINE_EXECUTION_ERROR +
-            " Use `npm run polaris -- loop abort` to reset blocked state.");
+            " Use `npx polaris loop abort` to reset blocked state.");
     }
 }
 /**

package/dist/loop/run-bootstrap.js

@@ -41,7 +41,7 @@ const git_custody_js_1 = require("./git-custody.js");
 // ──────────────────────────────────────────────────────────────────────────────
 exports.BOOTSTRAP_REQUIRED_ERROR = "Run state must be initialized through 'polaris loop bootstrap' before dispatch. " +
     "Parent sessions may not hand-create run state. " +
-    "Use: npm run polaris -- loop bootstrap --cluster-id <ID> --children <CSV>";
+    "Use: npx polaris loop bootstrap --cluster-id <ID> --children <CSV>";
 // ──────────────────────────────────────────────────────────────────────────────
 // Seal helpers
 // ──────────────────────────────────────────────────────────────────────────────
@@ -229,6 +229,6 @@ function runLoopBootstrapInit(options) {
     process.stderr.write(`Bootstrap complete. State initialized at: ${stateFile}\n` +
         `Run ID: ${runId}\n` +
         `Children: ${openChildren.join(", ")}\n` +
-        `Next: npm run polaris -- loop dispatch\n`);
+        `Next: npx polaris loop dispatch\n`);
     return clusterStateInitPromise;
 }

package/dist/loop/run-preflight.js

@@ -24,7 +24,7 @@ async function loadOrSyncGraph(clusterId, repoRoot) {
         }
         const config = (0, loader_js_1.loadConfig)(repoRoot);
         if (!config.tracker?.linear?.enabled) {
-            throw new Error(`No local cluster graph found for ${clusterId}. Run 'npm run polaris -- tracker sync-in ${clusterId}' or bootstrap with --children.`);
+            throw new Error(`No local cluster graph found for ${clusterId}. Run 'npx polaris tracker sync-in ${clusterId}' or bootstrap with --children.`);
         }
         const graph = await new index_js_1.LinearAdapter(config).syncIn(clusterId);
         await graph.save(clusterId, repoRoot);
@@ -74,7 +74,7 @@ function topoSort(children, getDeps) {
     }
     return sorted;
 }
-function buildBootstrapPlan(clusterId, graph) {
+function buildBootstrapPlan(clusterId, graph, repoRoot) {
     const activeCluster = graph.getActiveCluster();
     // Exclude the cluster root from runnable children when it has implementation
     // children. The root is a context/coordination node. If after filtering nothing
@@ -85,7 +85,13 @@ function buildBootstrapPlan(clusterId, graph) {
         ? activeCluster.children.filter((id) => id !== clusterRoot)
         : activeCluster.children;
     const unsortedChildren = runnableChildren.length > 0 ? runnableChildren : [clusterId];
-    const openChildren = topoSort(unsortedChildren, (id) => graph.getDependencies(id));
+    // If a cluster-plan.json exists, use its children order as the preferred
+    // tiebreaker within each ready wave of the topological sort. The plan order
+    // reflects the analyst's intended sequencing; clusters.json order is whatever
+    // the tracker returned, which may be arbitrary.
+    const planOrder = readClusterPlanOrder(clusterId, repoRoot);
+    const preferredOrder = applyPlanOrder(unsortedChildren, planOrder);
+    const openChildren = topoSort(preferredOrder, (id) => graph.getDependencies(id));
     const openChildrenMeta = {};
     const clusterNode = graph.getNode(clusterId);
     openChildrenMeta[clusterId] = {
@@ -102,6 +108,29 @@ function buildBootstrapPlan(clusterId, graph) {
     }
     return { openChildren, openChildrenMeta };
 }
+function readClusterPlanOrder(clusterId, repoRoot) {
+    const planPath = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "cluster-plan.json");
+    if (!(0, node_fs_1.existsSync)(planPath))
+        return [];
+    try {
+        const plan = JSON.parse((0, node_fs_1.readFileSync)(planPath, "utf-8"));
+        if (Array.isArray(plan.children)) {
+            return plan.children.map((c) => c.id).filter(Boolean);
+        }
+    }
+    catch {
+        // malformed plan — fall back to no preferred order
+    }
+    return [];
+}
+function applyPlanOrder(children, planOrder) {
+    if (planOrder.length === 0)
+        return children;
+    const childSet = new Set(children);
+    const ordered = planOrder.filter((id) => childSet.has(id));
+    const remaining = children.filter((id) => !ordered.includes(id));
+    return [...ordered, ...remaining];
+}
 function preserveMismatchedState(stateFile) {
     const suffix = (() => {
         try {
@@ -191,7 +220,7 @@ async function ensureClusterRunState(options) {
             }
         }
     }
-    const { openChildren, openChildrenMeta } = buildBootstrapPlan(clusterId, await loadOrSyncGraph(clusterId, repoRoot));
+    const { openChildren, openChildrenMeta } = buildBootstrapPlan(clusterId, await loadOrSyncGraph(clusterId, repoRoot), repoRoot);
     await bootstrapHandler({
         clusterId,
         openChildren,

package/package.json

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