@lsctech/polaris 0.4.1 → 0.4.3

package/dist/agent-plugin/claude-generator.js

@@ -46,7 +46,7 @@ const commands_js_1 = require("./commands.js");
  * `.claude/commands/polaris-<verb>.md` file per verb.
  *
  * Skill-backed verbs route through the existing packet+chain path:
- *   1. Read .polaris/skills/<skill>/SKILL.md
+ *   1. Read .polaris/skills/<target-skill>/SKILL.md
  *   2. Run `polaris skill packet <skill>`
  *   3. Execute the chain
  *
@@ -96,8 +96,8 @@ See \`${command.routing}\` for the full routing protocol and skill directory res
 
 ## Execution
 
-1. Look up \`/${command.name}\` in \`${command.routing}\` to find the target skill directory.
-2. Read \`.polaris/skills/<target-skill>/SKILL.md\` — it is the authoritative instruction source.
+1. Look up \`/${command.name}\` in \`${command.routing}\` to confirm the target skill directory.
+2. Read \`.polaris/skills/${command.targetSkill}/SKILL.md\` — it is the authoritative instruction source.
 3. Run the skill bootloader:
    \`\`\`bash
    polaris skill packet ${command.skill}${command.args.length > 0 ? " $ARGUMENTS" : ""}

package/dist/agent-plugin/codex-generator.js

@@ -0,0 +1,131 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_PLUGIN_SKILL_VERSION = void 0;
+exports.generateCodexPluginSkill = generateCodexPluginSkill;
+exports.generateCodexOpenAiYaml = generateCodexOpenAiYaml;
+exports.generateAllCodexPluginSkills = generateAllCodexPluginSkills;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const commands_js_1 = require("./commands.js");
+exports.CODEX_PLUGIN_SKILL_VERSION = "1";
+function skillCommands() {
+    return commands_js_1.SLASH_COMMANDS.filter((command) => command.kind === "skill");
+}
+function renderArgs(command) {
+    if (command.args.length === 0)
+        return "None.";
+    return command.args
+        .map((arg) => `- \`${arg.name}\`${arg.required ? " (required)" : " (optional)"} - ${arg.description}`)
+        .join("\n");
+}
+function renderUsage(command) {
+    const argUsage = command.args
+        .map((arg) => (arg.required ? `<${arg.name}>` : `[${arg.name}]`))
+        .join(" ");
+    return argUsage ? `${command.name} ${argUsage}` : command.name;
+}
+function renderBootloaderArgs(command) {
+    const argUsage = command.args
+        .map((arg) => (arg.required ? `<${arg.name}>` : `[${arg.name}]`))
+        .join(" ");
+    return argUsage ? ` ${argUsage}` : "";
+}
+function generateCodexPluginSkill(command) {
+    return `---
+name: ${command.name}
+description: ${command.description}
+---
+<!-- polaris-codex-skill-version: ${exports.CODEX_PLUGIN_SKILL_VERSION} -->
+
+# ${command.name}
+
+${command.description}
+
+This Codex plugin skill is a thin wrapper around the canonical Polaris skill. It does not implement a parallel runtime.
+
+## Usage
+
+\`\`\`text
+${renderUsage(command)}
+\`\`\`
+
+## Arguments
+
+${renderArgs(command)}
+
+## Mandatory Routing
+
+1. Read \`${command.routing}\` and resolve \`${command.name}\` to its target skill.
+2. Read \`.polaris/skills/${command.targetSkill}/SKILL.md\` before any repo inspection, tracker lookup, or runtime file reads.
+3. Run the skill bootloader from that canonical \`SKILL.md\`:
+   \`\`\`bash
+   polaris skill packet ${command.skill}${renderBootloaderArgs(command)}
+   \`\`\`
+4. If no packet is returned, stop and report: \`Blocking: Polaris could not authorize this run.\`
+5. Execute \`.polaris/skills/${command.targetSkill}/chain.md\` in strict step order.
+
+If \`.polaris/skills/${command.targetSkill}/SKILL.md\` is missing, stop and report:
+\`Blocking: skill packet not found at .polaris/skills/${command.targetSkill}/SKILL.md\`
+`;
+}
+function generateCodexOpenAiYaml(command) {
+    const displayName = command.name
+        .split("-")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+    return `interface:
+  display_name: "${displayName}"
+  short_description: "${command.description.replaceAll('"', '\\"')}"
+  brand_color: "#6366F1"
+  default_prompt: "Use $${command.name} to ${command.description.charAt(0).toLowerCase()}${command.description.slice(1)}."
+`;
+}
+function generateAllCodexPluginSkills(outDir = ".codex/plugins/polaris/skills") {
+    fs.mkdirSync(outDir, { recursive: true });
+    const written = [];
+    for (const command of skillCommands()) {
+        const skillDir = path.join(outDir, command.name);
+        const agentsDir = path.join(skillDir, "agents");
+        fs.mkdirSync(agentsDir, { recursive: true });
+        const skillPath = path.join(skillDir, "SKILL.md");
+        fs.writeFileSync(skillPath, generateCodexPluginSkill(command), "utf8");
+        written.push(skillPath);
+        const yamlPath = path.join(agentsDir, "openai.yaml");
+        fs.writeFileSync(yamlPath, generateCodexOpenAiYaml(command), "utf8");
+        written.push(yamlPath);
+    }
+    return written;
+}

package/dist/agent-plugin/commands.js

@@ -7,6 +7,7 @@ exports.SLASH_COMMANDS = [
         name: "polaris-run",
         kind: "skill",
         skill: "run",
+        targetSkill: "polaris-run",
         routing: ".polaris/skills/ROUTING.md",
         args: [
             {
@@ -21,6 +22,7 @@ exports.SLASH_COMMANDS = [
         name: "polaris-analyze",
         kind: "skill",
         skill: "analyze",
+        targetSkill: "polaris-analyze",
         routing: ".polaris/skills/ROUTING.md",
         args: [
             {
@@ -31,6 +33,15 @@ exports.SLASH_COMMANDS = [
         ],
         description: "Analyze a cluster and produce an implementation plan via the Analyst skill packet",
     },
+    {
+        name: "polaris-finalize",
+        kind: "skill",
+        skill: "run",
+        targetSkill: "polaris-run",
+        routing: ".polaris/skills/ROUTING.md",
+        args: [],
+        description: "Finalize the active Polaris run through the Foreman skill packet",
+    },
     {
         name: "polaris-init",
         kind: "cli",
@@ -48,7 +59,8 @@ exports.SLASH_COMMANDS = [
     {
         name: "polaris-reconcile",
         kind: "skill",
-        skill: "triage",
+        skill: "reconcile",
+        targetSkill: "polaris-reconcile",
         routing: ".polaris/skills/ROUTING.md",
         args: [
             {
@@ -59,6 +71,21 @@ exports.SLASH_COMMANDS = [
         ],
         description: "Reconcile project cognition via the triage skill packet",
     },
+    {
+        name: "polaris-catalog",
+        kind: "skill",
+        skill: "catalog",
+        targetSkill: "polaris-catalog",
+        routing: ".polaris/skills/ROUTING.md",
+        args: [
+            {
+                name: "cluster_id",
+                required: true,
+                description: "Cluster ID to catalog (e.g., POL-257)",
+            },
+        ],
+        description: "Catalog project cognition and SmartDocs via the catalog skill packet",
+    },
     {
         name: "polaris-status",
         kind: "cli",
@@ -66,6 +93,24 @@ exports.SLASH_COMMANDS = [
         args: [],
         description: "Print the current Polaris loop run state summary",
     },
+    {
+        name: "docs-ingest",
+        kind: "skill",
+        skill: "ingest",
+        targetSkill: "docs-ingest",
+        routing: ".polaris/skills/ROUTING.md",
+        args: [],
+        description: "Ingest raw documentation files through the Polaris SmartDocs skill packet",
+    },
+    {
+        name: "docs-promote",
+        kind: "skill",
+        skill: "promote",
+        targetSkill: "docs-promote",
+        routing: ".polaris/skills/ROUTING.md",
+        args: [],
+        description: "Review and promote candidate SmartDocs through the Polaris governance skill packet",
+    },
 ];
 exports.SLASH_COMMAND_BY_NAME = Object.fromEntries(exports.SLASH_COMMANDS.map((command) => [command.name, command]));
 function resolveSlashCommand(name) {

package/dist/agent-plugin/sync.js

@@ -35,10 +35,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectShimDrift = detectShimDrift;
 exports.syncShims = syncShims;
+exports.syncCodexPluginSkills = syncCodexPluginSkills;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const commands_js_1 = require("./commands.js");
 const claude_generator_js_1 = require("./claude-generator.js");
+const codex_generator_js_1 = require("./codex-generator.js");
 /**
  * Workspace sync and versioning for generated agent-plugin shims.
  *
@@ -106,3 +108,6 @@ function syncShims(outDir = ".claude/commands") {
     }
     return { written, drift };
 }
+function syncCodexPluginSkills(outDir = ".codex/plugins/polaris/skills") {
+    return { written: (0, codex_generator_js_1.generateAllCodexPluginSkills)(outDir) };
+}

package/dist/autoresearch/gates.js

@@ -86,9 +86,18 @@ function gateUserIntervened(artifacts) {
     };
 }
 /**
- * foreman-resent-packet: Was the packet dispatched more than once (dispatch_epoch > 1)?
+ * foreman-resent-packet: Was the same child dispatched more than once?
  *
- * Evidence: dispatch_boundary.dispatch_epoch in current-state.json.
+ * Evidence:
+ *   - open_children_meta.<child>.dispatch_record.dispatch_count (if runtime tracks it)
+ *   - ledger child-dispatched events (issue_id)
+ *   - telemetry child-dispatched events (child_id)
+ *
+ * A normal multi-session run has dispatch_epoch > 1 because distinct children are
+ * dispatched across sessions. That is expected. The problematic pattern is the
+ * foreman re-sending a worker packet to the same child after that child already
+ * returned a result. When per-child dispatch count data is unavailable, the gate
+ * is skipped rather than failing on dispatch_epoch alone.
  */
 function gateForemanResentPacket(artifacts) {
     const state = artifacts.currentState;
@@ -98,13 +107,57 @@ function gateForemanResentPacket(artifacts) {
     if (typeof dispatchEpoch !== "number") {
         return { gate: "foreman-resent-packet", outcome: "skipped", detail: "dispatch_epoch not present in state" };
     }
-    const failed = dispatchEpoch > 1;
+    const perChildCounts = countChildDispatches(artifacts);
+    if (perChildCounts) {
+        const reDispatched = Array.from(perChildCounts.entries())
+            .filter(([, count]) => count > 1)
+            .map(([childId]) => childId);
+        const failed = reDispatched.length > 0;
+        return {
+            gate: "foreman-resent-packet",
+            outcome: failed ? "failed" : "passed",
+            detail: failed ? `child re-dispatched: ${reDispatched.join(", ")}` : undefined,
+        };
+    }
+    // No per-child dispatch data available. A single epoch cannot contain a re-dispatch.
+    if (dispatchEpoch === 1) {
+        return { gate: "foreman-resent-packet", outcome: "passed" };
+    }
     return {
         gate: "foreman-resent-packet",
-        outcome: failed ? "failed" : "passed",
-        detail: failed ? `dispatch_epoch=${dispatchEpoch}` : undefined,
+        outcome: "skipped",
+        detail: "per-child dispatch count data unavailable",
     };
 }
+/** Counts per-child dispatches from all available artifact sources, or null if none are present. */
+function countChildDispatches(artifacts) {
+    const counts = new Map();
+    const state = asRecord(artifacts.currentState);
+    const openChildrenMeta = asRecord(state?.["open_children_meta"]);
+    for (const [childId, meta] of Object.entries(openChildrenMeta ?? {})) {
+        const metaRec = asRecord(meta);
+        const dispatchRecord = asRecord(metaRec?.["dispatch_record"]);
+        const dispatchCount = dispatchRecord?.["dispatch_count"];
+        if (typeof dispatchCount === "number") {
+            counts.set(childId, Math.max(counts.get(childId) ?? 0, dispatchCount));
+        }
+    }
+    for (const event of artifacts.ledgerEvents) {
+        const rec = asRecord(event);
+        if (rec?.["event"] === "child-dispatched" && typeof rec["issue_id"] === "string") {
+            const childId = rec["issue_id"];
+            counts.set(childId, (counts.get(childId) ?? 0) + 1);
+        }
+    }
+    for (const event of artifacts.telemetryEvents) {
+        const rec = asRecord(event);
+        if (rec?.["event"] === "child-dispatched" && typeof rec["child_id"] === "string") {
+            const childId = rec["child_id"];
+            counts.set(childId, (counts.get(childId) ?? 0) + 1);
+        }
+    }
+    return counts.size > 0 ? counts : null;
+}
 /**
  * foreman-fixed-worker-output: Did foreman make commits between child-complete
  * and the next dispatch?

package/dist/autoresearch/score.js

@@ -94,6 +94,7 @@ function safeReaddir(dir) {
         return [];
     }
 }
+const NON_WORKER_PREFIXES = ["librarian-", "CHART-", "medic-result-"];
 function readResultPackets(clusterDir) {
     if (!clusterDir)
         return [];
@@ -101,7 +102,7 @@ function readResultPackets(clusterDir) {
     if (!(0, node_fs_1.existsSync)(resultsDir))
         return [];
     return safeReaddir(resultsDir)
-        .filter((f) => f.endsWith(".json"))
+        .filter((f) => f.endsWith(".json") && !NON_WORKER_PREFIXES.some((p) => f.startsWith(p)))
         .map((f) => readJson((0, node_path_1.join)(resultsDir, f)))
         .filter((v) => v !== undefined);
 }
@@ -158,8 +159,19 @@ function loadRunArtifacts(repoRoot, runId) {
     const telemetryEvents = telemetryPath ? (0, gates_js_1.readJsonLines)(telemetryPath) : [];
     // Result packets from cluster results dir
     const resultPackets = readResultPackets(clusterDir);
-    // Also check for WorkerResultContracts inside result packets
-    const workerResultContracts = extractWorkerResultContracts(resultPackets);
+    // WorkerResultContracts: prefer completed_children_results from current-state.json (Bug A fix)
+    let workerResultContracts;
+    const stateRec = currentState && typeof currentState === "object" && currentState !== null
+        ? currentState
+        : null;
+    const completedChildrenResults = stateRec?.["completed_children_results"];
+    if (completedChildrenResults && typeof completedChildrenResults === "object" && !Array.isArray(completedChildrenResults)) {
+        workerResultContracts = Object.values(completedChildrenResults).filter((v) => v !== null && typeof v === "object" && typeof v["worker_id"] === "string");
+    }
+    else {
+        // Legacy fallback: extract from result packet files
+        workerResultContracts = extractWorkerResultContracts(resultPackets);
+    }
     return {
         runId,
         runDir,

package/dist/cli/adopt-rules.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRepoOverview = extractRepoOverview;
+exports.refreshPolarisRules = refreshPolarisRules;
 exports.generatePolarisRules = generatePolarisRules;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -186,6 +188,32 @@ function buildContentInline(overview) {
         "",
     ].join("\n");
 }
+function extractRepoOverview(content) {
+    const match = content.match(/(?:^|\n)## Repository Overview\r?\n([\s\S]*?)(?:\r?\n## |$)/);
+    if (!match)
+        return "Repository managed by Polaris.";
+    const overview = match[1].trim().replace(/(^|\n)---\s*$/, "").trim();
+    return overview || "Repository managed by Polaris.";
+}
+function refreshPolarisRules(repoRoot, currentVersion) {
+    const outputPath = (0, node_path_1.join)(repoRoot, "POLARIS_RULES.md");
+    let content = "";
+    if ((0, node_fs_1.existsSync)(outputPath)) {
+        content = (0, node_fs_1.readFileSync)(outputPath, "utf-8");
+    }
+    const firstLine = content.split(/\r?\n/)[0] ?? "";
+    const versionMatch = firstLine.match(/^<!-- polaris-version: ([\d.]+-?[\w.]*) -->$/);
+    const existingVersion = versionMatch?.[1];
+    if (existingVersion === currentVersion) {
+        return { status: "skipped", path: outputPath };
+    }
+    const overview = extractRepoOverview(content);
+    const newContent = `<!-- polaris-version: ${currentVersion} -->\n${buildContentInline(overview)}`;
+    const dir = (0, node_path_1.dirname)(outputPath);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(outputPath, newContent, "utf-8");
+    return { status: "updated", path: outputPath };
+}
 async function generatePolarisRules(repoRoot, inventory, options = {}) {
     const { overwrite = false, workspaceDir } = options;
     const outputPath = (0, node_path_1.join)(repoRoot, "POLARIS_RULES.md");

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 upgrade_command_js_1 = require("./upgrade-command.js");
 const simplicity_js_1 = require("../loop/simplicity.js");
 const autoresearch_js_1 = require("./autoresearch.js");
 function resolveStateFile(repoRoot, explicit) {
@@ -110,6 +111,7 @@ function createPolarisCommand(options = {}) {
         repoRoot,
     }));
     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
         .command("simplicity")

package/dist/cli/upgrade-command.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUpgradeCommand = createUpgradeCommand;
+const commander_1 = require("commander");
+const version_js_1 = require("./version.js");
+const adopt_rules_js_1 = require("./adopt-rules.js");
+function createUpgradeCommand(options = {}) {
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const doRefresh = options.refresh ?? adopt_rules_js_1.refreshPolarisRules;
+    const getCurrentVersion = options.getVersion ?? version_js_1.getVersion;
+    const cmd = new commander_1.Command("upgrade")
+        .description("Refresh POLARIS_RULES.md to the current Polaris CLI version")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .action(async (cmdOptions) => {
+        const targetRoot = cmdOptions.repoRoot ?? repoRoot;
+        const version = getCurrentVersion();
+        const result = doRefresh(targetRoot, version);
+        if (result.status === "updated") {
+            process.stdout.write(`POLARIS_RULES.md updated to version ${version}\n`);
+        }
+        else {
+            process.stdout.write(`Already up to date (${version})\n`);
+        }
+    });
+    return cmd;
+}

package/dist/workspace/.polaris/skills/closeout-librarian/steps/08-librarian-commit.md

@@ -101,6 +101,8 @@ Capture the resulting commit SHA.
 
 Record the commit SHA and list of committed files for step 09.
 
+Use `git diff --cached --name-only` output as the source for `files_committed` — git outputs repo-relative paths (e.g., "src/cli/POLARIS.md"), which is the required format for the result JSON.
+
 ## Failure Handling
 
 If `git commit` fails:

package/dist/workspace/.polaris/skills/closeout-librarian/steps/09-sealed-result.md

@@ -24,7 +24,7 @@ interface CloseoutLibrarianResult {
   status: "success" | "partial" | "blocked" | "failure";
   commit_sha: string | null;
   commit_message: string;
-  files_committed: string[];
+  files_committed: string[];  // repo-relative paths (e.g., "src/cli/POLARIS.md")
   drift_reconciliation: DriftReconciliationResult;
   polaris_md_updates: FileUpdate[];
   summary_md_updates: FileUpdate[];

package/package.json

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