@lsctech/polaris 0.3.27 → 0.3.29

package/dist/cli/index.js

@@ -27,6 +27,7 @@ const librarian_js_1 = require("./librarian.js");
 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");
 function resolveStateFile(repoRoot, explicit) {
     if (explicit)
         return (0, node_path_1.resolve)(explicit);
@@ -108,6 +109,19 @@ function createPolarisCommand(options = {}) {
         repoRoot,
     }));
     program.addCommand((0, adopt_command_js_1.createAdoptCommand)({ repoRoot }));
+    program
+        .command("simplicity")
+        .description("View or override the simplicity discipline mode for the active run")
+        .option("--bypass", "Omit the discipline ladder from worker prompts for this run")
+        .option("--restore", "Re-enable the discipline ladder (clear bypass)")
+        .option("--state-file <path>", "Override path to current-state.json")
+        .action((cmdOptions) => {
+        (0, simplicity_js_1.runSimplicityCommand)({
+            bypass: !!cmdOptions.bypass,
+            restore: !!cmdOptions.restore,
+            stateFile: resolveStateFile(repoRoot, cmdOptions.stateFile),
+        });
+    });
     const agentCmd = new commander_1.Command("agent").description("Manage Polaris agent provider configuration");
     agentCmd.addCommand(new commander_1.Command("setup")
         .description("Configure agent providers per role (librarian, foreman, worker, analyst)")

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

@@ -15,6 +15,11 @@ const body_parser_js_1 = require("./body-parser.js");
 const loader_js_1 = require("../config/loader.js");
 const store_js_1 = require("../cluster-state/store.js");
 const worker_prompt_js_1 = require("./worker-prompt.js");
+function resolveSimplicityMode(state, config) {
+    if (state.simplicity_bypass)
+        return "off";
+    return config?.simplicity?.mode ?? "full";
+}
 const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
 const run_bootstrap_js_1 = require("./run-bootstrap.js");
 const ledger_js_1 = require("./ledger.js");
@@ -659,7 +664,7 @@ function selectChild(state, requestedChild) {
  * @param resultFile - Optional path for the expected result file; non-absolute paths are resolved against `repoRoot`
  * @returns The constructed WorkerPacket ready for dispatch
  */
-function buildPacket(state, childId, stateFile, telemetryFile, repoRoot, resultFile) {
+function buildPacket(state, childId, stateFile, telemetryFile, repoRoot, resultFile, config) {
     const childMeta = state.open_children_meta?.[childId];
     // Hydrate body from cluster snapshot when runtime state lacks it.
     const cachedBody = childMeta?.body;
@@ -694,6 +699,7 @@ function buildPacket(state, childId, stateFile, telemetryFile, repoRoot, resultF
         allowedScope: resolvedScope.length > 0 ? resolvedScope : undefined,
         maxConcurrentWorkers: 1,
         promptMode: (0, worker_prompt_js_1.selectPromptMode)(childId, state),
+        simplicityMode: resolveSimplicityMode(state, config),
         resultFile: canonicalPath(absoluteResultFile(repoRoot, resultFile)),
     });
 }
@@ -912,7 +918,7 @@ function runLoopDispatch(options) {
         step_cursor: "dispatch",
         dispatch_boundary: (0, dispatch_boundary_js_1.advanceDispatchEpoch)(state.dispatch_boundary, childId),
     };
-    const packet = buildPacket(preliminaryState, childId, options.stateFile, telemetryFile, options.repoRoot, canonicalResultFile);
+    const packet = buildPacket(preliminaryState, childId, options.stateFile, telemetryFile, options.repoRoot, canonicalResultFile, loadedConfig);
     const packetFailure = detectPacketGenerationFailure(packet);
     if (packetFailure) {
         appendTelemetry(telemetryFile, {

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/dist/loop/simplicity.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSimplicityCommand = runSimplicityCommand;
+const checkpoint_js_1 = require("./checkpoint.js");
+/**
+ * Handles `polaris simplicity [--bypass | --restore]`.
+ *
+ * --bypass: sets simplicity_bypass: true for the active run (omits discipline ladder from worker prompts).
+ * --restore: clears simplicity_bypass (re-enables the ladder).
+ * bare: prints current bypass status without mutating state.
+ */
+function runSimplicityCommand(opts) {
+    if (!opts.bypass && !opts.restore) {
+        const state = (0, checkpoint_js_1.readState)(opts.stateFile);
+        if (state.simplicity_bypass) {
+            console.log("Simplicity bypass: on — discipline ladder omitted for this run.");
+        }
+        else {
+            console.log("Simplicity bypass: off — discipline mode comes from project config/default.");
+        }
+        return;
+    }
+    const state = (0, checkpoint_js_1.readState)(opts.stateFile);
+    if (opts.bypass) {
+        state.simplicity_bypass = true;
+        (0, checkpoint_js_1.writeStateAtomic)(opts.stateFile, state);
+        console.log("Simplicity bypass enabled — discipline ladder will be omitted from worker prompts for this run.");
+        return;
+    }
+    // restore
+    state.simplicity_bypass = false;
+    (0, checkpoint_js_1.writeStateAtomic)(opts.stateFile, state);
+    console.log("Simplicity bypass cleared — discipline ladder will be injected into worker prompts.");
+}

package/dist/loop/worker-packet.js

@@ -265,6 +265,7 @@ function compileImplPacket(input) {
         allowedScope: resolvedScope,
         validationCommands: resolvedValidation,
         mode: promptMode,
+        simplicityMode: input.simplicityMode,
     });
     return {
         schema_version: '2.1',

package/dist/loop/worker-prompt.js

@@ -57,6 +57,29 @@ function selectPromptMode(childId, state, override) {
         return override;
     return isNarrowChild(childId, state) ? 'compact' : 'full';
 }
+// ── Discipline section ────────────────────────────────────────────────────────
+function buildDisciplineSection(mode) {
+    if (mode === "off")
+        return [];
+    const lines = [
+        "## Implementation Discipline",
+        "Before writing code, stop at the first rung that holds:",
+        "",
+        "1. Does this need to exist?   → no: skip it (YAGNI)",
+        "2. Stdlib does it?            → use it",
+        "3. Native platform feature?   → use it",
+        "4. Installed dependency?      → use it",
+        "5. One line?                  → one line",
+        "6. Only then: the minimum that works",
+        "",
+        "Lazy, not negligent: validation, error handling, security, and accessibility are never on the chopping block.",
+    ];
+    if (mode === "full") {
+        lines.push("", "When you defer a simplification for later, mark it inline:", "  // ponytail: <what you deferred and why>");
+    }
+    lines.push("");
+    return lines;
+}
 // ── Builder ───────────────────────────────────────────────────────────────────
 /**
  * Build a compact or full worker dispatch prompt.
@@ -80,6 +103,10 @@ function buildWorkerPrompt(input) {
     lines.push('## Goal');
     lines.push(input.goal.trim());
     lines.push('');
+    // ── Implementation Discipline ─────────────────────────────────────────────
+    for (const line of buildDisciplineSection(input.simplicityMode ?? 'full')) {
+        lines.push(line);
+    }
     // ── Scope ─────────────────────────────────────────────────────────────────
     lines.push('## Scope');
     if (input.scopeTouch.length > 0) {
@@ -256,5 +283,6 @@ function buildPromptFromPacketInput(input) {
         telemetryFile: input.telemetryFile,
         issueContext: input.issueContext,
         mode: input.mode,
+        simplicityMode: input.simplicityMode,
     });
 }

package/package.json

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