@lsctech/polaris 0.4.7 → 0.4.8

package/dist/smartdocs-engine/doctrine.js

@@ -4,6 +4,7 @@ exports.CANDIDATE_MARKER = void 0;
 exports.parseFrontMatter = parseFrontMatter;
 exports.addCandidateGovernanceMetadata = addCandidateGovernanceMetadata;
 exports.stampIngestFrontMatter = stampIngestFrontMatter;
+exports.backfillOkfType = backfillOkfType;
 exports.doctrineDraft = doctrineDraft;
 exports.doctrinePromote = doctrinePromote;
 exports.doctrineDeprecate = doctrineDeprecate;
@@ -90,6 +91,10 @@ function parseFrontMatter(content) {
  */
 function addCandidateGovernanceMetadata(content, docType) {
     const govDefaults = {
+        // OKF-conformant type field. Mirrors doc-type's value; added alongside
+        // (not instead of) doc-type since ingest.ts and requiredFields still
+        // read doc-type for internal classification/validation.
+        "type": docType,
         "doc-type": docType,
         "confidence": "0.0",
         "recommended-action": "hold",
@@ -184,6 +189,90 @@ function stampIngestFrontMatter(content, stamp) {
     const block = Object.entries(fields).map(([k, v]) => `${k}: ${v}`).join("\n");
     return `---\n${block}\n---\n\n${normalized}`;
 }
+/**
+ * Insert a single missing frontmatter field into markdown content, preserving
+ * an existing frontmatter block if present or creating a new one if not.
+ * No-op (returns content unchanged) if the key is already present.
+ */
+function addMissingFrontMatterField(content, key, value) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    if (normalized.startsWith("---\n")) {
+        const end = normalized.indexOf("\n---", 4);
+        if (end !== -1) {
+            const frontMatter = normalized.slice(4, end);
+            const afterFrontMatter = normalized.slice(end + 4);
+            const hasKey = frontMatter
+                .split("\n")
+                .filter((l) => l.includes(":"))
+                .some((l) => l.slice(0, l.indexOf(":")).trim().toLowerCase() === key.toLowerCase());
+            if (hasKey)
+                return normalized;
+            return `---\n${frontMatter}\n${key}: ${value}\n---${afterFrontMatter}`;
+        }
+    }
+    return `---\n${key}: ${value}\n---\n\n${normalized}`;
+}
+/**
+ * Retrofit existing SmartDocs with an OKF-conformant `type` frontmatter field.
+ *
+ * Walks every `.md` file under `smartdocs/`. For each file already missing a
+ * `type` key: derives the value from `kind` if present, else `doc-type` if
+ * present, else defaults to `"raw"`. Files that already declare `type` are
+ * left untouched and reported in `skipped`.
+ *
+ * This is the retroactive counterpart to `addCandidateGovernanceMetadata`,
+ * which stamps `type` on newly-governed candidate docs going forward — this
+ * function backfills docs that predate that change (or were authored by
+ * hand without a `type` field at all).
+ *
+ * @param repoRoot - Repository root; files are read from and written to
+ *   `<repoRoot>/smartdocs/**\/*.md`.
+ * @param options.dryRun - When true, computes the result without writing
+ *   any files.
+ */
+function backfillOkfType(repoRoot, options = {}) {
+    const smartdocsDir = (0, node_path_1.join)(repoRoot, "smartdocs");
+    const result = { updated: [], skipped: [] };
+    function walk(dir) {
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = (0, node_path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                processFile(full);
+            }
+        }
+    }
+    function processFile(filePath) {
+        let content;
+        try {
+            content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+        }
+        catch {
+            return;
+        }
+        const fm = parseFrontMatter(content);
+        if (fm["type"]) {
+            result.skipped.push(filePath);
+            return;
+        }
+        const derivedType = fm.kind ?? fm["doc-type"] ?? "raw";
+        if (!options.dryRun) {
+            (0, node_fs_1.writeFileSync)(filePath, addMissingFrontMatterField(content, "type", derivedType), "utf-8");
+        }
+        result.updated.push({ path: filePath, type: derivedType });
+    }
+    walk(smartdocsDir);
+    return result;
+}
 function appendLifecycle(lifecyclePath, event) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(lifecyclePath), { recursive: true });
     (0, node_fs_1.appendFileSync)(lifecyclePath, JSON.stringify(event) + "\n", "utf-8");

package/dist/smartdocs-engine/index.js

@@ -434,9 +434,29 @@ function createDocsCommand(options = {}) {
             console.log(`skipped (draft exists): ${targetPath}/index.md`);
         }
     });
+    docs
+        .command("backfill-type")
+        .description("Add OKF-conformant `type` frontmatter to existing smartdocs/ files that are missing it, " +
+        "deriving the value from `kind` or `doc-type` when present, else defaulting to \"raw\".")
+        .option("-r, --repo-root <path>", "Repository root", defaultRepoRoot)
+        .option("--dry-run", "Print what would be written without writing files")
+        .action((options) => {
+        try {
+            const { updated, skipped } = (0, doctrine_js_1.backfillOkfType)(options.repoRoot, { dryRun: options.dryRun });
+            for (const { path, type } of updated) {
+                console.log(`${options.dryRun ? "[dry-run] would add" : "added"} type: ${type} — ${path}`);
+            }
+            console.log(`Done. ${updated.length} updated, ${skipped.length} already had type.`);
+        }
+        catch (err) {
+            console.error(`polaris docs backfill-type: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     docs
         .command("reformat-okf")
-        .description("Migrate existing smartdocs to OKF structure in one step: runs migrate → seed-index --all → seed-instructions --all. " +
+        .description("Migrate existing smartdocs to OKF structure in one step: runs migrate → seed-index --all → " +
+        "seed-instructions --all → backfill-type. " +
         "Agent instruction files (CLAUDE.md, AGENTS.md, etc.) are never touched. " +
         "Use --dry-run to preview changes before writing.")
         .option("--dry-run", "Preview what would change without writing any files")
@@ -446,7 +466,7 @@ function createDocsCommand(options = {}) {
         const repoRoot = options.repoRoot;
         const label = dryRun ? "[dry-run]" : "";
         // Step 1: migrate (moves scattered markdown to smartdocs/raw/)
-        console.log(`${label ? label + " " : ""}Step 1/3: migrate`);
+        console.log(`${label ? label + " " : ""}Step 1/4: migrate`);
         try {
             const migrateResult = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun });
             (0, migrate_js_1.printMigrateResults)(migrateResult);
@@ -455,8 +475,8 @@ function createDocsCommand(options = {}) {
             console.error(`reformat-okf: migrate failed — ${err instanceof Error ? err.message : String(err)}`);
             process.exit(1);
         }
-        // Step 2: seed-index --all (ensures index.md with okf_version frontmatter in every smartdocs dir)
-        console.log(`\n${label ? label + " " : ""}Step 2/3: seed-index --all`);
+        // Step 2: seed-index --all (ensures index.md with okf_version + type frontmatter in every smartdocs dir)
+        console.log(`\n${label ? label + " " : ""}Step 2/4: seed-index --all`);
         try {
             const { written, skippedExists, skippedDraft } = (0, seed_instructions_js_1.seedIndexAll)(repoRoot, { dryRun });
             printSeedAllResult("index.md", dryRun, { written, skippedExists, skippedDraft }, { leadingBlankLine: false });
@@ -466,7 +486,7 @@ function createDocsCommand(options = {}) {
             process.exit(1);
         }
         // Step 3: seed-instructions --all (ensures POLARIS.md drafts; never touches CLAUDE.md/AGENTS.md)
-        console.log(`\n${label ? label + " " : ""}Step 3/3: seed-instructions --all`);
+        console.log(`\n${label ? label + " " : ""}Step 3/4: seed-instructions --all`);
         try {
             const { written, skippedExists, skippedDraft, skippedIneligible, skippedRoot } = (0, seed_instructions_js_1.seedInstructionsAll)(repoRoot, { dryRun });
             const rootCount = skippedRoot ? 1 : 0;
@@ -476,6 +496,19 @@ function createDocsCommand(options = {}) {
             console.error(`reformat-okf: seed-instructions failed — ${err instanceof Error ? err.message : String(err)}`);
             process.exit(1);
         }
+        // Step 4: backfill-type (existing docs missing `type` get it derived from kind/doc-type, or "raw")
+        console.log(`\n${label ? label + " " : ""}Step 4/4: backfill-type`);
+        try {
+            const { updated, skipped } = (0, doctrine_js_1.backfillOkfType)(repoRoot, { dryRun });
+            for (const { path, type } of updated) {
+                console.log(`${dryRun ? "[dry-run] would add" : "added"} type: ${type} — ${path}`);
+            }
+            console.log(`Done. ${updated.length} updated, ${skipped.length} already had type.`);
+        }
+        catch (err) {
+            console.error(`reformat-okf: backfill-type failed — ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
         console.log(`\nreformat-okf complete.${dryRun ? " (dry-run — no files written)" : ""}`);
     });
     docs

package/dist/smartdocs-engine/migrate.js

@@ -11,6 +11,7 @@ const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
 const ALLOWED_BASENAMES = new Set([
     "README.md",
     "POLARIS.md",
+    "SUMMARY.md",
     "CHANGELOG.md",
     "LICENSE.md",
     "AGENTS.md",

package/dist/smartdocs-engine/seed-instructions.js

@@ -196,6 +196,18 @@ function listConceptFiles(dir) {
         return [];
     }
 }
+/** Immediate child subdirectories eligible for their own index.md (excludes hidden dirs and raw/). */
+function listChildDirs(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "raw")
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
 function conceptLabel(filePath) {
     try {
         const content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
@@ -232,6 +244,7 @@ function generateBundleRootIndex(repoRoot, allRoutes) {
     const lines = [
         "---",
         "okf_version: \"0.1\"",
+        "type: index",
         "---",
         "",
         exports.DRAFT_MARKER,
@@ -289,6 +302,7 @@ function generateDirectoryIndex(targetDir, repoRoot) {
     const lines = [
         "---",
         "okf_version: \"0.1\"",
+        "type: index",
         "---",
         "",
         exports.DRAFT_MARKER,
@@ -309,6 +323,18 @@ function generateDirectoryIndex(targetDir, repoRoot) {
         lines.push("<!-- No concept files in this directory yet. -->");
     }
     lines.push("");
+    const childDirs = listChildDirs(absDir);
+    if (childDirs.length > 0) {
+        lines.push("## Subdirectories", "");
+        for (const child of childDirs) {
+            // Always link to the child's index.md rather than checking existsSync: generateDirectoryIndex
+            // only ever runs under smartdocs/ (enforced by seedIndex's own path guard), where every
+            // eligible subdirectory gets its own index.md — and seedIndexAll writes parents before
+            // children in the same pass, so existsSync would be write-order-dependent here.
+            lines.push(`- [${child}/](${child}/index.md)`);
+        }
+        lines.push("");
+    }
     return lines.join("\n");
 }
 function seedInstructions(targetPath, repoRoot, opts = {}) {

package/dist/smartdocs-engine/triage.js

@@ -10,10 +10,13 @@ exports.deleteTriageCheckpoint = deleteTriageCheckpoint;
 exports.writeTriageQueue = writeTriageQueue;
 exports.resolveTriageModel = resolveTriageModel;
 exports.runBatchComparison = runBatchComparison;
+exports.resolveLibrarianProviderConfig = resolveLibrarianProviderConfig;
 exports.runGraphCheck = runGraphCheck;
 exports.runTriage = runTriage;
 const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
 const node_path_1 = require("node:path");
+const index_js_1 = require("../config/index.js");
 // ---------------------------------------------------------------------------
 // clusterCandidates
 // ---------------------------------------------------------------------------
@@ -307,7 +310,7 @@ function resolveTriageModel(configured) {
         "claude-haiku-4-5-20251001");
 }
 async function runBatchComparison(candidates, canonicals, options) {
-    const client = options.llmClient ?? (await buildDefaultLlmClient());
+    const client = options.llmClient ?? (await buildDefaultLlmClient(options.repoRoot ?? process.cwd()));
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
             return await client.compare(candidates, canonicals, options.model);
@@ -318,8 +321,103 @@ async function runBatchComparison(candidates, canonicals, options) {
     }
     return [];
 }
-async function buildDefaultLlmClient() {
+function buildComparisonPrompt(candidates, canonicals) {
+    const candidateSummaries = candidates
+        .map((c, i) => `[${i}] ${(0, node_path_1.basename)(c.path)} (${c.type || "unknown type"}) tags: ${c.tags.join(", ") || "none"}`)
+        .join("\n");
+    const canonicalSummaries = canonicals
+        .map((c) => `- ${(0, node_path_1.basename)(c.path)} (${c.type || "unknown type"}) tags: ${c.tags.join(", ") || "none"}`)
+        .join("\n");
+    return [
+        "You are comparing candidate documentation files against canonical documentation.",
+        "Identify any candidates that CONTRADICT or DUPLICATE a canonical.",
+        'Return ONLY a JSON array. If no issues found, return [].',
+        'Each item must be: { "candidatePath": string, "flagType": "contradiction" | "duplicate", "canonicalPath"?: string, "reason": string }',
+        "",
+        "CANDIDATES:",
+        candidateSummaries,
+        "",
+        "CANONICALS:",
+        canonicalSummaries,
+        "",
+        "Respond with JSON only. No prose.",
+    ].join("\n");
+}
+function parseFlagsFromText(text) {
+    const cleaned = text.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim();
+    return JSON.parse(cleaned);
+}
+/** Expand $VAR and ${VAR} references from process.env. */
+function expandEnvVars(str) {
+    return str
+        .replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (_, name) => process.env[name] ?? "")
+        .replace(/\$([A-Z_][A-Z0-9_]*)/g, (_, name) => process.env[name] ?? "");
+}
+/** Substitute {{key}} template variables. Unknown keys are left as-is. */
+function substituteTemplates(str, vars) {
+    return str.replace(/\{\{([^}]+)\}\}/g, (original, key) => vars[key.trim()] ?? original);
+}
+/**
+ * Resolve the configured CLI provider for triage's librarian-role LLM calls, per
+ * polaris.config.json's execution.providerPolicy.librarian / execution.providers —
+ * the same config the terminal-cli dispatch adapter reads for Foreman/Worker
+ * sessions. Returns undefined if no usable provider is configured, in which case
+ * callers fall back to a raw API-key-based client.
+ */
+function resolveLibrarianProviderConfig(repoRoot) {
+    try {
+        const config = (0, index_js_1.loadConfig)(repoRoot);
+        const providers = config.execution?.providers ?? {};
+        const policyNames = config.execution?.providerPolicy?.librarian?.providers ?? [];
+        for (const name of policyNames) {
+            const cfg = providers[name];
+            if (cfg)
+                return cfg;
+        }
+        // Fall back to a directly-named "claude" provider if no policy entry resolved.
+        return providers["claude"];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build an LlmClient that shells out to the configured CLI provider (e.g. `claude
+ * --print`), the same mechanism the terminal-cli execution adapter uses for
+ * Foreman/Worker dispatch. This authenticates via the CLI's own session (OAuth),
+ * not a raw ANTHROPIC_API_KEY.
+ */
+function buildCliLlmClient(providerCfg) {
+    return {
+        async compare(candidates, canonicals) {
+            const prompt = buildComparisonPrompt(candidates, canonicals);
+            const templateVars = { worker_prompt: prompt };
+            const command = substituteTemplates(expandEnvVars(providerCfg.command), templateVars);
+            if (!command.trim()) {
+                throw new Error(`Provider command "${providerCfg.command}" expanded to an empty string — likely an unset environment variable.`);
+            }
+            const args = (providerCfg.args ?? []).map((arg) => substituteTemplates(expandEnvVars(arg), templateVars));
+            const stdout = (0, node_child_process_1.execFileSync)(command, args, {
+                encoding: "utf-8",
+                maxBuffer: 10 * 1024 * 1024,
+                timeout: 300000,
+            });
+            return parseFlagsFromText(stdout);
+        },
+    };
+}
+async function buildDefaultLlmClient(repoRoot) {
+    const cliProviderCfg = resolveLibrarianProviderConfig(repoRoot);
+    if (cliProviderCfg) {
+        return buildCliLlmClient(cliProviderCfg);
+    }
     const apiKey = process.env["ANTHROPIC_API_KEY"] ?? "";
+    if (!apiKey) {
+        throw new Error("No CLI provider configured for the librarian role (execution.providerPolicy.librarian / " +
+            "execution.providers in polaris.config.json) and ANTHROPIC_API_KEY is not set. " +
+            "Configure a librarian provider (preferred — uses the CLI's own session auth) or set " +
+            "ANTHROPIC_API_KEY as a fallback.");
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     // @ts-ignore: @anthropic-ai/sdk may not be installed as a dependency
     const mod = await import("@anthropic-ai/sdk");
@@ -328,26 +426,7 @@ async function buildDefaultLlmClient() {
     const sdkClient = new Anthropic({ apiKey });
     return {
         async compare(candidates, canonicals, model) {
-            const candidateSummaries = candidates
-                .map((c, i) => `[${i}] ${(0, node_path_1.basename)(c.path)} (${c.type || "unknown type"}) tags: ${c.tags.join(", ") || "none"}`)
-                .join("\n");
-            const canonicalSummaries = canonicals
-                .map((c) => `- ${(0, node_path_1.basename)(c.path)} (${c.type || "unknown type"}) tags: ${c.tags.join(", ") || "none"}`)
-                .join("\n");
-            const prompt = [
-                "You are comparing candidate documentation files against canonical documentation.",
-                "Identify any candidates that CONTRADICT or DUPLICATE a canonical.",
-                'Return ONLY a JSON array. If no issues found, return [].',
-                'Each item must be: { "candidatePath": string, "flagType": "contradiction" | "duplicate", "canonicalPath"?: string, "reason": string }',
-                "",
-                "CANDIDATES:",
-                candidateSummaries,
-                "",
-                "CANONICALS:",
-                canonicalSummaries,
-                "",
-                "Respond with JSON only. No prose.",
-            ].join("\n");
+            const prompt = buildComparisonPrompt(candidates, canonicals);
             const response = await sdkClient.messages.create({
                 model,
                 max_tokens: 1024,
@@ -357,8 +436,7 @@ async function buildDefaultLlmClient() {
                 .filter((b) => b.type === "text")
                 .map((b) => b.text)
                 .join("");
-            const cleaned = text.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim();
-            return JSON.parse(cleaned);
+            return parseFlagsFromText(text);
         },
     };
 }
@@ -436,7 +514,7 @@ async function runTriage(options) {
         output(`  Comparing cluster "${clusterName}" (${cluster.candidates.length} candidates, ${cluster.canonicals.length} canonicals)...`);
         for (let i = 0; i < cluster.candidates.length; i += batchSize) {
             const batch = cluster.candidates.slice(i, i + batchSize);
-            const flags = await runBatchComparison(batch, cluster.canonicals, { model, llmClient });
+            const flags = await runBatchComparison(batch, cluster.canonicals, { model, llmClient, repoRoot });
             accumulatedFlags.push(...flags);
         }
         completedClusters.add(clusterName);

package/package.json

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