@lsctech/polaris 0.3.4 → 0.3.6

package/dist/cli/agent-setup.js

@@ -0,0 +1,126 @@
+"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.runAgentSetup = runAgentSetup;
+const node_child_process_1 = require("node:child_process");
+const readline = __importStar(require("node:readline"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SUPPORTED_PROVIDERS = [
+    { name: "claude", detectCmd: "claude", displayName: "Claude (Anthropic)" },
+    { name: "codex", detectCmd: "codex", displayName: "Codex (OpenAI)" },
+    { name: "copilot", detectCmd: "copilot", displayName: "Copilot (GitHub)" },
+    { name: "devin", detectCmd: "devin", displayName: "Devin (Cognition)" },
+    { name: "gemini", detectCmd: "gemini", displayName: "Gemini (Google)" },
+];
+const ROLES = ["librarian", "foreman", "worker", "analyst"];
+function isInstalled(cmd) {
+    const { status } = (0, node_child_process_1.spawnSync)("which", [cmd], { stdio: "ignore" });
+    return status === 0;
+}
+function detectProviders() {
+    return SUPPORTED_PROVIDERS.map((p) => ({
+        name: p.name,
+        displayName: p.displayName,
+        installed: isInstalled(p.detectCmd),
+    }));
+}
+async function selectProvider(role, detected, currentProviders) {
+    const installed = detected.filter((p) => p.installed);
+    if (installed.length === 0)
+        return null;
+    console.log(`\nRole: ${role}`);
+    detected.forEach((p, i) => {
+        const marker = p.installed ? "✓" : "✗";
+        const current = currentProviders.includes(p.name) ? " (current)" : "";
+        const selectable = p.installed ? `[${i + 1}]` : "   ";
+        console.log(`  ${selectable} ${marker} ${p.displayName}${current}`);
+    });
+    const defaultChoice = installed.find((p) => currentProviders.includes(p.name)) ?? installed[0];
+    const defaultIdx = detected.indexOf(defaultChoice) + 1;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(`\nSelect provider for ${role} [${defaultIdx}]: `, (answer) => {
+            rl.close();
+            const idx = parseInt(answer.trim() || String(defaultIdx), 10) - 1;
+            const chosen = detected[idx];
+            if (!chosen?.installed) {
+                console.log("  That provider is not installed. Using default.");
+                res(defaultChoice.name);
+            }
+            else {
+                res(chosen.name);
+            }
+        });
+    });
+}
+async function runAgentSetup(repoRoot) {
+    console.log("\nPolaris Agent Setup — configure one provider per role\n");
+    const detected = detectProviders();
+    const installed = detected.filter((p) => p.installed);
+    if (installed.length === 0) {
+        console.error("No supported agents detected. Install one of: " +
+            SUPPORTED_PROVIDERS.map((p) => p.name).join(", "));
+        process.exit(1);
+    }
+    console.log("Detected agents:");
+    installed.forEach((p) => console.log(`  ✓ ${p.displayName}`));
+    const configPath = (0, node_path_1.resolve)(repoRoot, "polaris.config.json");
+    let config;
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    }
+    catch {
+        console.error(`polaris agent setup: could not read ${configPath}`);
+        process.exit(1);
+    }
+    const execution = config.execution ?? {};
+    const providerPolicy = execution.providerPolicy ?? {};
+    for (const role of ROLES) {
+        const currentProviders = providerPolicy[role]?.providers ?? [];
+        const chosen = await selectProvider(role, detected, currentProviders);
+        if (chosen) {
+            providerPolicy[role] = {
+                ...(providerPolicy[role] ?? {}),
+                providers: [chosen, ...currentProviders.filter((p) => p !== chosen)],
+            };
+            console.log(`  → ${role}: ${chosen}`);
+        }
+    }
+    execution.providerPolicy = providerPolicy;
+    config.execution = execution;
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2) + "\n");
+    console.log(`\nAgent configuration saved to ${configPath}`);
+}

package/dist/cli/index.js

@@ -5,6 +5,7 @@ exports.createPolarisCommand = createPolarisCommand;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const commander_1 = require("commander");
+const agent_setup_js_1 = require("./agent-setup.js");
 const version_js_1 = require("./version.js");
 const branding_js_1 = require("./branding.js");
 const index_js_1 = require("../loop/index.js");
@@ -105,6 +106,14 @@ function createPolarisCommand(options = {}) {
     program.addCommand((0, medic_js_1.createMedicCommand)({
         repoRoot,
     }));
+    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)")
+        .option("-r, --repo-root <path>", "Repository root", repoRoot)
+        .action(async (opts) => {
+        await (0, agent_setup_js_1.runAgentSetup)(opts.repoRoot);
+    }));
+    program.addCommand(agentCmd);
     program
         .command("welfare-check")
         .description("safe/read-only: run route welfare checks and report per-route health")

package/dist/skill-packet/generator.js

@@ -229,7 +229,8 @@ function buildReviewPacket() {
             "Read candidate documents from smartdocs/doctrine/candidate/ to inform decisions",
             "Evaluate each flagged packet: read the doc, consider the flag type and stale symbols, decide approve/reject/defer",
             "Write decisions back to the triage queue by calling polaris docs review --write-decision <sourcePath> <decision>",
-            "Call polaris docs ingest to apply approved/rejected decisions after review is complete",
+            "Call polaris docs promote <path> for each approved packet (candidate → active)",
+            "Call polaris doctrine deprecate <path> for each rejected packet",
             "Emit telemetry events",
         ],
         prohibited_actions: [

package/dist/smartdocs-engine/agentic-review.js

@@ -1,49 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.agenticDecideKey = agenticDecideKey;
-const node_fs_1 = require("node:fs");
+const librarian_dispatch_js_1 = require("./librarian-dispatch.js");
+const loader_js_1 = require("../config/loader.js");
 async function agenticDecideKey(packet) {
-    let docContent = "";
+    let config = null;
     try {
-        if ((0, node_fs_1.existsSync)(packet.sourcePath)) {
-            docContent = (0, node_fs_1.readFileSync)(packet.sourcePath, "utf-8").slice(0, 3000);
-        }
+        config = (0, loader_js_1.loadConfig)(process.cwd());
     }
-    catch { /* ignore */ }
-    // @ts-ignore: @anthropic-ai/sdk may not be installed as a dependency
-    const mod = await import("@anthropic-ai/sdk");
-    const Anthropic = mod.default ?? mod.Anthropic;
-    const client = new Anthropic();
-    const staleSymbols = packet.staleSymbols;
-    const triageFlag = packet.triageFlag;
-    const prompt = `You are reviewing a candidate documentation file flagged during Polaris docs triage.
-
-Flag type: ${String(triageFlag ?? "unknown")}
-Authority risk: ${packet.authorityRisk}
-Recommendation from triage: ${packet.recommendation}
-Reasoning: ${packet.reasoning.join("; ")}
-${Array.isArray(staleSymbols) ? `Stale symbols (not found in codebase graph): ${staleSymbols.join(", ")}` : ""}
-
-Document content:
----
-${docContent}
----
-
-Decide whether this document should be:
-- approved: doc is valid doctrine and should be promoted to active
-- rejected: doc is outdated, incorrect, or superseded and should be deprecated
-- deferred: uncertain — needs human review
-
-Respond with exactly one word: approve, reject, or defer.`;
-    const response = await client.messages.create({
-        model: "claude-haiku-4-5-20251001",
-        max_tokens: 10,
-        messages: [{ role: "user", content: prompt }],
-    });
-    const text = (response.content[0].text ?? "defer").trim().toLowerCase();
-    if (text.startsWith("approve"))
+    catch {
+        throw new Error("polaris agent setup required: could not load polaris.config.json.\n" +
+            "Run `polaris agent setup` to configure a librarian or foreman agent.");
+    }
+    const providers = (config.execution?.providers ?? {});
+    const librarianOrder = config.execution?.providerPolicy?.librarian?.providers ?? [];
+    const foremanOrder = config.execution?.providerPolicy?.foreman?.providers ?? [];
+    // Try librarian first, then foreman as fallback
+    const resolvedRole = (0, librarian_dispatch_js_1.resolveLibrarianProvider)(providers, librarianOrder) != null ? "librarian"
+        : (0, librarian_dispatch_js_1.resolveLibrarianProvider)(providers, foremanOrder) != null ? "foreman"
+            : null;
+    if (!resolvedRole) {
+        const configured = [...new Set([...librarianOrder, ...foremanOrder])];
+        const msg = configured.length > 0
+            ? `Configured agents (${configured.join(", ")}) are not installed on this machine.`
+            : "No librarian or foreman agents are configured.";
+        throw new Error(`polaris agent setup required: ${msg}\n` +
+            "Run `polaris agent setup` to configure an available agent.");
+    }
+    const providerOrder = resolvedRole === "librarian" ? librarianOrder : foremanOrder;
+    const result = await (0, librarian_dispatch_js_1.dispatchLibrarianReview)({ packet, repoRoot: process.cwd(), providers, providerOrder });
+    if (result.decision === "approve")
         return "a";
-    if (text.startsWith("reject"))
+    if (result.decision === "reject")
         return "r";
     return "d";
 }

package/dist/smartdocs-engine/librarian-dispatch.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLibrarianProvider = resolveLibrarianProvider;
+exports.dispatchLibrarianReview = dispatchLibrarianReview;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+// Returns the first provider name from providerOrder whose command is installed (via `which`)
+function resolveLibrarianProvider(providers, providerOrder) {
+    for (const name of providerOrder) {
+        const cfg = providers[name];
+        if (!cfg)
+            continue;
+        const cmd = cfg.command === "env"
+            ? (cfg.args ?? []).find((a) => !a.includes("=") && !a.startsWith("-")) ?? cfg.command
+            : cfg.command;
+        try {
+            const { status } = (0, node_child_process_1.spawnSync)("which", [cmd], { stdio: "ignore" });
+            if (status === 0)
+                return name;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function grepEvidence(repoRoot, symbols) {
+    const evidence = {};
+    for (const sym of symbols.slice(0, 8)) {
+        try {
+            const result = (0, node_child_process_1.spawnSync)("grep", [
+                "-r",
+                "--include=*.ts",
+                "--include=*.tsx",
+                "--include=*.swift",
+                "--include=*.dart",
+                "-l",
+                sym,
+                ".",
+            ], { cwd: repoRoot, encoding: "utf-8", timeout: 5000 });
+            const files = (result.stdout ?? "")
+                .trim()
+                .split("\n")
+                .filter(Boolean)
+                .slice(0, 3);
+            evidence[sym] = files.length > 0 ? `found in: ${files.join(", ")}` : "not found in codebase";
+        }
+        catch {
+            evidence[sym] = "search error";
+        }
+    }
+    return evidence;
+}
+async function dispatchLibrarianReview(options) {
+    const { packet, repoRoot, providers, providerOrder } = options;
+    const providerName = resolveLibrarianProvider(providers, providerOrder);
+    if (!providerName) {
+        throw new Error("No librarian provider available. Run `polaris agent setup` to configure one.");
+    }
+    const cfg = providers[providerName];
+    const staleSymbols = packet.staleSymbols ?? [];
+    const evidence = grepEvidence(repoRoot, staleSymbols);
+    let docContent = "";
+    try {
+        if ((0, node_fs_1.existsSync)(packet.sourcePath)) {
+            docContent = (0, node_fs_1.readFileSync)(packet.sourcePath, "utf-8").slice(0, 2000);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    const evidenceLines = Object.entries(evidence)
+        .map(([sym, result]) => `  ${sym}: ${result}`)
+        .join("\n");
+    const prompt = `You are an agentic librarian reviewing a candidate documentation file for the Polaris docs review pipeline.
+
+Doc path: ${packet.sourcePath}
+Flag type: stale-reference
+Stale symbols (flagged as not in the codebase graph):
+${staleSymbols.join(", ")}
+
+Live codebase evidence (grep results):
+${evidenceLines}
+
+Document content (first 2000 chars):
+---
+${docContent}
+---
+
+Decision rules:
+- approve: symbols found in live codebase OR doc describes concepts still clearly relevant to current architecture
+- reject: doc describes systems/components that are clearly gone with no trace in codebase
+- defer: ambiguous — cannot determine from evidence alone
+
+Respond with ONLY valid JSON on a single line:
+{"decision":"approve"|"reject"|"defer","reasoning":"one sentence"}`;
+    const args = (cfg.args ?? []).map((a) => (a === "{{worker_prompt}}" ? prompt : a));
+    const result = (0, node_child_process_1.spawnSync)(cfg.command, args, {
+        encoding: "utf-8",
+        timeout: 60000,
+        cwd: repoRoot,
+    });
+    const stdout = (result.stdout ?? "").trim();
+    const jsonLine = stdout
+        .split("\n")
+        .reverse()
+        .find((l) => l.trim().startsWith("{") && l.includes("decision"));
+    if (!jsonLine) {
+        return {
+            decision: "defer",
+            reasoning: "Provider response did not contain a valid JSON decision",
+            provider: providerName,
+        };
+    }
+    try {
+        const parsed = JSON.parse(jsonLine);
+        const decision = (["approve", "reject", "defer"].includes(parsed.decision) ? parsed.decision : "defer");
+        return { decision, reasoning: parsed.reasoning ?? "", provider: providerName };
+    }
+    catch {
+        return { decision: "defer", reasoning: "Could not parse provider response", provider: providerName };
+    }
+}

package/dist/workspace/workspace/.polaris/skills/docs-review/chain.md

@@ -37,7 +37,7 @@ All decision output written to `smartdocs/raw/`:
 ```text
 01-load-queue        ← read _triage-queue.json; count pending items; emit run-start telemetry
 02-review-packets    ← for each pending packet: read doc → evaluate → record decision
-03-apply-decisions   ← run polaris docs ingest to apply approved/rejected packets
+03-apply-decisions   ← run polaris docs promote for approved packets; run polaris doctrine deprecate for rejected packets
 04-hand-off          ← report decision summary (approved / rejected / deferred); emit triage-review-complete telemetry
 ```
 
@@ -52,8 +52,10 @@ All decision output written to `smartdocs/raw/`:
 - Process all packets before moving to step 03 — do not apply decisions mid-loop
 
 **Step 03:**
-- If no packets were approved or rejected → skip ingest, report counts only
-- Ingest error → report the error; do not retry automatically
+- If no packets were approved or rejected → skip, report counts only
+- For approved packets: call `polaris docs promote <path>` for each (requires `docs-promote` skill authority if conflicts found)
+- For rejected packets: call `polaris doctrine deprecate <path>` for each
+- Error on apply → report the error; do not retry automatically
 
 ## Run ID format
 

package/package.json

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