@lsctech/polaris 0.3.29 → 0.4.0

package/dist/cli/setup-interview/store.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadInterview = loadInterview;
+exports.saveInterview = saveInterview;
+exports.loadOrCreate = loadOrCreate;
+exports.applyAnswers = applyAnswers;
+exports.markApproved = markApproved;
+exports.nextUnansweredQuestion = nextUnansweredQuestion;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const schema_js_1 = require("./schema.js");
+function interviewPath(repoRoot) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "setup", "interview.json");
+}
+/**
+ * Load an existing interview record from disk.
+ * Returns null if the file does not exist or cannot be parsed.
+ */
+function loadInterview(repoRoot) {
+    const path = interviewPath(repoRoot);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist an interview record to .polaris/setup/interview.json. */
+function saveInterview(repoRoot, record) {
+    const path = interviewPath(repoRoot);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+}
+/**
+ * Load an existing record or create a fresh one.
+ * Supports --resume: caller passes the return value to continueInterview.
+ */
+function loadOrCreate(repoRoot, now = new Date()) {
+    return loadInterview(repoRoot) ?? (0, schema_js_1.createInterviewRecord)(now);
+}
+/** Merge new answers into the record and transition status to "answered" if appropriate. */
+function applyAnswers(record, answers) {
+    return {
+        ...record,
+        answers: { ...record.answers, ...answers },
+        status: record.status === "approved" ? "approved" : "answered",
+    };
+}
+/** Transition record to "approved" status, recording the approval timestamp. */
+function markApproved(record, now = new Date()) {
+    return {
+        ...record,
+        status: "approved",
+        approved_at: now.toISOString(),
+    };
+}
+/**
+ * Return the next unanswered required question key, or null if all are answered.
+ * Used to resume at the right question after a partial run.
+ */
+function nextUnansweredQuestion(record) {
+    const required = [
+        "project_purpose",
+        "source_roots",
+        "languages",
+        "canonical_doc_folders",
+        "never_touch",
+        "providers_by_role",
+    ];
+    return required.find((key) => record.answers[key] === undefined) ?? null;
+}

package/dist/finalize/index.js

@@ -42,7 +42,7 @@ function getBranch(repoRoot) {
     }
 }
 function normalizeBranchName(branch) {
-    return branch.toLowerCase().replace(/_/g, "-");
+    return branch.toLowerCase().replace(/[_/]/g, "-");
 }
 function extractClusterSlug(clusterId) {
     const match = clusterId.match(/([A-Z]+-\d+)/);
@@ -161,13 +161,14 @@ function checkLibrarianGate(repoRoot, clusterId) {
     const filesCommitted = result.files_committed ?? [];
     for (const file of filesCommitted) {
         const absFile = (0, node_path_1.resolve)(repoRoot, file);
+        // Allowed takes precedence over prohibited — a specific allowed path wins over a broad prohibition.
+        const allowedMatch = allowedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, absFile));
+        if (allowedMatch)
+            continue;
         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, absFile));
-        if (allowedMatch)
-            continue; // explicitly allowed
         return `Librarian wrote to out-of-scope path: ${file} (not in allowed_write_paths)`;
     }
     try {

package/dist/loop/adapters/foreman-dispatch.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Foreman dispatch — launches the assigned Foreman with a setup-bootstrap
+ * packet through the configured execution adapter.
+ *
+ * Provider selection comes from config (`execution.providerPolicy.foreman`);
+ * no provider-specific logic lives here — the adapter handles that.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchForeman = dispatchForeman;
+const terminal_cli_js_1 = require("./terminal-cli.js");
+/**
+ * Validate that the setup-bootstrap packet has checkpoint gate enforcement.
+ *
+ * This is the "by construction" guard: a packet without a valid checkpoint_gate
+ * (or with self_approval_prohibited !== true) cannot be dispatched. Because
+ * `generateSetupBootstrapPacket` always sets self_approval_prohibited to true,
+ * any packet that fails this check was manually constructed — and is rejected.
+ *
+ * @throws {Error} if checkpoint_gate is absent or self_approval_prohibited is not true.
+ */
+function assertCheckpointGateEnforced(packet) {
+    if (!packet.checkpoint_gate || packet.checkpoint_gate.self_approval_prohibited !== true) {
+        throw new Error(`Cannot dispatch setup-bootstrap packet "${packet.packet_id}": ` +
+            `checkpoint_gate.self_approval_prohibited must be true. ` +
+            `Use generateSetupBootstrapPacket() to produce a valid packet.`);
+    }
+}
+/**
+ * Wraps a SetupBootstrapPacket into a BootstrapPacket-compatible shape
+ * that existing adapters can dispatch. The setup-bootstrap fields are
+ * carried as context so the foreman receives the full packet.
+ */
+function toBootstrapPacket(packet) {
+    return {
+        schema_version: "1.0",
+        run_id: `setup-${packet.mode}-${packet.packet_id}`,
+        cluster_id: `setup-${packet.mode}`,
+        active_child: "",
+        state_file: "",
+        telemetry_file: "",
+        context: {
+            setup_bootstrap: packet,
+        },
+    };
+}
+/**
+ * Dispatch the Foreman with the setup-bootstrap packet.
+ *
+ * Enforces checkpoint gate presence before dispatch — a packet without
+ * self_approval_prohibited: true is rejected, making self-approval
+ * impossible by construction.
+ *
+ * Uses the existing TerminalCliAdapter so provider-specific logic stays
+ * in provider configs — this function is provider-neutral.
+ */
+async function dispatchForeman(input) {
+    assertCheckpointGateEnforced(input.packet);
+    const adapter = new terminal_cli_js_1.TerminalCliAdapter(input.executionConfig);
+    const bootstrapPacket = toBootstrapPacket(input.packet);
+    return adapter.dispatch(bootstrapPacket, {
+        provider: input.provider,
+        dryRun: input.dryRun,
+    });
+}

package/dist/loop/adapters/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAdapter = exports.AgentSubtaskAdapter = exports.TerminalCliAdapter = void 0;
+exports.dispatchForeman = exports.createAdapter = exports.AgentSubtaskAdapter = exports.TerminalCliAdapter = void 0;
 var terminal_cli_js_1 = require("./terminal-cli.js");
 Object.defineProperty(exports, "TerminalCliAdapter", { enumerable: true, get: function () { return terminal_cli_js_1.TerminalCliAdapter; } });
 var agent_subtask_js_1 = require("./agent-subtask.js");
 Object.defineProperty(exports, "AgentSubtaskAdapter", { enumerable: true, get: function () { return agent_subtask_js_1.AgentSubtaskAdapter; } });
 var registry_js_1 = require("./registry.js");
 Object.defineProperty(exports, "createAdapter", { enumerable: true, get: function () { return registry_js_1.createAdapter; } });
+var foreman_dispatch_js_1 = require("./foreman-dispatch.js");
+Object.defineProperty(exports, "dispatchForeman", { enumerable: true, get: function () { return foreman_dispatch_js_1.dispatchForeman; } });

package/dist/loop/worker-packet.js

@@ -250,7 +250,7 @@ function compileImplPacket(input) {
         `Create exactly ONE git commit: [${input.childId}] ${childTitle}.`,
         `Do NOT modify open_children or completed_children in ${input.stateFile}. The parent runtime (loop continue) owns that state transition.`,
         `Append a telemetry event to ${input.telemetryFile}.`,
-        `Write compact return JSON to stdout (fields: ${exports.IMPL_RETURN_CONTRACT.join(', ')}).`,
+        `Write compact return JSON to stdout (fields: ${exports.IMPL_RETURN_CONTRACT.join(', ')}). next_recommended_action MUST be exactly "continue" on success, "stop" on unresolvable blocker, or "investigate" if manual review is needed.`,
         `TERMINATE SESSION IMMEDIATELY. Do not select or execute the next child.`,
     ];
     // Build compact or full prompt; primary_goal uses the structured template.

package/dist/skill-packet/generator.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_SKILLS = exports.SKILL_ROLE_MAP = void 0;
+exports.generateSetupBootstrapPacket = generateSetupBootstrapPacket;
 exports.generateSkillPacket = generateSkillPacket;
 const node_crypto_1 = require("node:crypto");
 exports.SKILL_ROLE_MAP = {
@@ -10,6 +11,8 @@ exports.SKILL_ROLE_MAP = {
     promote: "Librarian",
     triage: "Librarian",
     review: "Librarian",
+    catalog: "Librarian",
+    reconcile: "Librarian",
 };
 const ROLE_SUMMARIES = {
     Analyst: "The Analyst gathers evidence, assesses feasibility, and produces implementation-ready plans. The Analyst shapes work but never executes it.",
@@ -258,6 +261,136 @@ function buildReviewPacket() {
         ],
     };
 }
+const SETUP_BOOTSTRAP_CHECKPOINTS = [
+    "canon",
+    "doc-movement",
+    "instruction-files",
+    "graph-root",
+    "route-scaffold",
+    "source-mutation",
+];
+/**
+ * Builds the checkpoint gate that is embedded in every setup-bootstrap packet.
+ *
+ * Each checkpoint gate entry is a halt instruction — the Foreman MUST stop
+ * and surface the gate to the operator before proceeding. Self-approval is
+ * structurally impossible: `self_approval_prohibited` is typed as `true` and
+ * this function never sets it to anything else.
+ */
+function buildCheckpointGate() {
+    const gateInstruction = (name) => `HALT at checkpoint "${name}": stop, surface this gate to the operator, and wait for explicit approval before proceeding. You may not self-approve.`;
+    return {
+        gates: {
+            canon: gateInstruction("canon"),
+            "doc-movement": gateInstruction("doc-movement"),
+            "instruction-files": gateInstruction("instruction-files"),
+            "graph-root": gateInstruction("graph-root"),
+            "route-scaffold": gateInstruction("route-scaffold"),
+            "source-mutation": gateInstruction("source-mutation"),
+        },
+        self_approval_prohibited: true,
+        enforcement_note: "Checkpoint gates are non-optional. The Foreman must halt and surface each gate to the operator. " +
+            "Proceeding without explicit operator approval is a protocol violation.",
+    };
+}
+function generateSetupBootstrapPacket(mode) {
+    return {
+        packet_id: (0, node_crypto_1.randomUUID)(),
+        packet_kind: "setup-bootstrap",
+        active_role: "Foreman",
+        role_file: ".polaris/skills/polaris-run/SKILL.md",
+        mode,
+        authority_boundaries: [
+            "Read repository structure and existing configuration files",
+            "Create or update Polaris configuration and scaffold files",
+            "Dispatch Workers for bounded setup sub-tasks",
+            "Coordinate approval checkpoints before advancing to the next setup phase",
+            "Write to .polaris/ directories as part of init or adopt setup",
+            "Update POLARIS.md and SUMMARY.md within the project root",
+        ],
+        prohibited_actions: [
+            "Mutate source files without an approved checkpoint (unapproved mutation is forbidden)",
+            "Implement features directly — all implementation must be delegated to a Worker",
+            "Advance past an approval checkpoint without explicit user confirmation",
+            "Self-approve any checkpoint — operator approval is mandatory and cannot be delegated to the Foreman",
+            "Modify tracker state or issue descriptions during setup",
+        ],
+        approval_checkpoints: SETUP_BOOTSTRAP_CHECKPOINTS,
+        checkpoint_gate: buildCheckpointGate(),
+        stop_conditions: [
+            "All setup phases complete and scaffold is valid",
+            "An approval checkpoint is reached — pause and await user confirmation",
+            "A required configuration value is missing and cannot be inferred",
+            "A Worker returns a failure result during setup",
+        ],
+        generated_at: new Date().toISOString(),
+    };
+}
+function buildCatalogPacket() {
+    return {
+        authority_boundaries: [
+            "Read packet-scoped POLARIS.md and SUMMARY.md files",
+            "Update cognition files only within packet-allowed write paths",
+            "Read smartdocs/raw/ and classify documents through supported Polaris CLI commands",
+            "Auto-place only high-confidence documents",
+            "Leave low-confidence documents in raw when unattended or request operator direction",
+        ],
+        prohibited_actions: [
+            "Modify implementation source code, tests, or configuration",
+            "Write outside packet-allowed paths",
+            "Auto-place low-confidence documents",
+            "Move or copy SmartDocs directly instead of using supported CLI commands",
+            "Call polaris loop continue or polaris finalize",
+            "Git push or create a pull request",
+        ],
+        allowed_outputs: [
+            "Updated POLARIS.md and SUMMARY.md files in packet-allowed paths",
+            "Classified documents placed through supported Polaris CLI commands",
+            "A sealed local cognition and document commit",
+            "A report of deferred low-confidence documents",
+        ],
+        deliverables: [
+            "Packet-scoped cognition reconciled",
+            "Raw documents classified or explicitly deferred",
+            "All changes recorded in one sealed local commit",
+        ],
+        stop_conditions: [
+            "All packet-scoped cognition and raw documents processed",
+            "A required command is unsupported by the installed CLI",
+            "A requested write falls outside packet-allowed paths",
+            "An unresolved conflict requires operator direction",
+        ],
+    };
+}
+function buildReconcilePacket() {
+    return {
+        authority_boundaries: [
+            "Read packet-scoped folders and their POLARIS.md and SUMMARY.md files",
+            "Update cognition files only within packet-allowed write paths",
+            "Create one sealed local cognition commit",
+        ],
+        prohibited_actions: [
+            "Modify implementation source code, tests, or configuration",
+            "Move, ingest, classify, or promote documents",
+            "Write outside packet-allowed paths",
+            "Call polaris loop continue or polaris finalize",
+            "Git push or create a pull request",
+        ],
+        allowed_outputs: [
+            "Updated POLARIS.md and SUMMARY.md files in packet-allowed paths",
+            "A sealed local cognition commit",
+        ],
+        deliverables: [
+            "Packet-scoped cognition reconciled with completed work",
+            "All cognition changes recorded in one sealed local commit",
+        ],
+        stop_conditions: [
+            "All packet-scoped cognition reconciled",
+            "A requested write falls outside packet-allowed paths",
+            "Work evidence is missing or contradictory",
+        ],
+    };
+}
 function generateSkillPacket(skillName, config) {
     const active_role = exports.SKILL_ROLE_MAP[skillName];
     const role_summary = ROLE_SUMMARIES[active_role];
@@ -288,6 +421,12 @@ function generateSkillPacket(skillName, config) {
         case "review":
             body = buildReviewPacket();
             break;
+        case "catalog":
+            body = buildCatalogPacket();
+            break;
+        case "reconcile":
+            body = buildReconcilePacket();
+            break;
     }
     return {
         packet_id,
@@ -299,4 +438,13 @@ function generateSkillPacket(skillName, config) {
         generated_at,
     };
 }
-exports.SUPPORTED_SKILLS = ["analyze", "run", "ingest", "promote", "triage", "review"];
+exports.SUPPORTED_SKILLS = [
+    "analyze",
+    "run",
+    "ingest",
+    "promote",
+    "triage",
+    "review",
+    "catalog",
+    "reconcile",
+];

package/dist/workspace/.polaris/skills/polaris-tools/tools.js

@@ -10,11 +10,9 @@
  *   node tools.js polaris_loop_status
  */
 
-'use strict';
-
-const { spawnSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
+let spawnSync;
+let fs;
+let path;
 
 // ── binary resolution ──────────────────────────────────────────────────────
 
@@ -171,21 +169,32 @@ function unknownTool(tool) {
 
 // ── dispatch ───────────────────────────────────────────────────────────────
 
-const [, , tool, ...rest] = process.argv;
-
-switch (tool) {
-  case 'polaris_run':
-    operatorOnly('polaris_run', 'polaris run <issue_id>');
-    break;
-  case 'polaris_loop_continue':
-    operatorOnly('polaris_loop_continue', 'polaris loop continue');
-    break;
-  case 'polaris_status':
-    polarisStatus('polaris_status', ['status', '--json']);
-    break;
-  case 'polaris_loop_status':
-    polarisStatus('polaris_loop_status', ['loop', 'status', '--json']);
-    break;
-  default:
-    unknownTool(tool);
+async function main() {
+  ({ spawnSync } = await import('node:child_process'));
+  fs = await import('node:fs');
+  path = await import('node:path');
+
+  const [, , tool] = process.argv;
+
+  switch (tool) {
+    case 'polaris_run':
+      operatorOnly('polaris_run', 'polaris run <issue_id>');
+      break;
+    case 'polaris_loop_continue':
+      operatorOnly('polaris_loop_continue', 'polaris loop continue');
+      break;
+    case 'polaris_status':
+      polarisStatus('polaris_status', ['status', '--json']);
+      break;
+    case 'polaris_loop_status':
+      polarisStatus('polaris_loop_status', ['loop', 'status', '--json']);
+      break;
+    default:
+      unknownTool(tool);
+  }
 }
+
+main().catch((error) => {
+  console.log(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.3.29",
+  "version": "0.4.0",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",
@@ -22,7 +22,7 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsc && rm -rf dist/workspace && cp -r src/workspace dist/workspace",
+    "build": "tsc && rm -rf dist/workspace && cp -r src/workspace dist/workspace && cp .codex/plugins/polaris/skills/polaris-tools/tools.js dist/workspace/.polaris/skills/polaris-tools/tools.js",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit --project tsconfig.typecheck.json",
     "test": "vitest run",