@lsctech/polaris 0.2.2 → 0.3.0

package/dist/smartdocs-engine/index.js

@@ -12,6 +12,7 @@ const seed_instructions_js_1 = require("./seed-instructions.js");
 const validate_instructions_js_1 = require("./validate-instructions.js");
 const doctrine_js_1 = require("./doctrine.js");
 const audit_js_1 = require("./audit.js");
+const triage_js_1 = require("./triage.js");
 /**
  * Build and return the top-level "docs" Commander command group for Polaris docs lifecycle workflows.
  *
@@ -151,6 +152,27 @@ function createDocsCommand(options = {}) {
             process.exit(1);
         }
     });
+    docs
+        .command("triage")
+        .description("Detect contradictions, duplicates, and stale code references among candidate docs")
+        .option("-r, --repo-root <path>", "Repository root", process.cwd())
+        .option("--batch-size <n>", "Docs per LLM call", "10")
+        .option("--resume", "Resume from last checkpoint (auto-detected by default)")
+        .option("--dry-run", "Plan batches and print cost estimate without calling the LLM")
+        .action(async (options) => {
+        try {
+            await (0, triage_js_1.runTriage)({
+                repoRoot: options.repoRoot,
+                batchSize: parseInt(options.batchSize, 10) || 10,
+                resume: options.resume,
+                dryRun: options.dryRun,
+            });
+        }
+        catch (err) {
+            console.error(`polaris docs triage: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     docs
         .command("migrate")
         .description("Find scattered markdown files, move them to smartdocs/raw/, and produce an ingest cluster list")

package/dist/smartdocs-engine/triage.js

@@ -0,0 +1,494 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clusterCandidates = clusterCandidates;
+exports.extractSymbols = extractSymbols;
+exports.loadDocMeta = loadDocMeta;
+exports.loadAllDocMeta = loadAllDocMeta;
+exports.readTriageCheckpoint = readTriageCheckpoint;
+exports.writeTriageCheckpoint = writeTriageCheckpoint;
+exports.deleteTriageCheckpoint = deleteTriageCheckpoint;
+exports.writeTriageQueue = writeTriageQueue;
+exports.resolveTriageModel = resolveTriageModel;
+exports.runBatchComparison = runBatchComparison;
+exports.runGraphCheck = runGraphCheck;
+exports.runTriage = runTriage;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// clusterCandidates
+// ---------------------------------------------------------------------------
+/**
+ * Groups candidate docs into named clusters using metadata overlap with canonicals.
+ * Candidates with no signal match go into the "general" bucket.
+ */
+function clusterCandidates(candidates, canonicals) {
+    const clusters = {};
+    // Build cluster names from canonicals
+    for (const canonical of canonicals) {
+        const names = clusterNamesFor(canonical);
+        for (const name of names) {
+            if (!clusters[name]) {
+                clusters[name] = { candidates: [], canonicals: [] };
+            }
+            if (!clusters[name].canonicals.includes(canonical)) {
+                clusters[name].canonicals.push(canonical);
+            }
+        }
+    }
+    // Assign each candidate to its best cluster
+    for (const candidate of candidates) {
+        const candidateNames = clusterNamesFor(candidate);
+        let assigned = false;
+        for (const name of candidateNames) {
+            if (clusters[name]) {
+                clusters[name].candidates.push(candidate);
+                assigned = true;
+                break; // assign to first matching cluster only — multi-cluster candidates would inflate batch sizes
+            }
+        }
+        if (!assigned) {
+            if (!clusters["general"]) {
+                clusters["general"] = { candidates: [], canonicals: [] };
+            }
+            clusters["general"].candidates.push(candidate);
+        }
+    }
+    // Ensure general bucket exists
+    if (!clusters["general"]) {
+        clusters["general"] = { candidates: [], canonicals: [] };
+    }
+    return clusters;
+}
+function clusterNamesFor(doc) {
+    const names = [];
+    // Tags take priority
+    for (const tag of doc.tags) {
+        if (tag.trim())
+            names.push(tag.toLowerCase().trim());
+    }
+    // Cluster membership
+    for (const c of doc.clusterMembership) {
+        if (c.trim())
+            names.push(c.toLowerCase().trim());
+    }
+    // Filename prefix (e.g. "ADR", "EVOlearn")
+    for (const p of doc.filenamePrefixes) {
+        if (p.trim())
+            names.push(p.toLowerCase().trim());
+    }
+    // Type as fallback
+    if (doc.type.trim())
+        names.push(doc.type.toLowerCase().trim());
+    return names;
+}
+// ---------------------------------------------------------------------------
+// extractSymbols
+// ---------------------------------------------------------------------------
+const BACKTICK_RE = /`([A-Za-z_][A-Za-z0-9_]{3,})`/g;
+const CAMEL_PASCAL_RE = /(?<![`\w])([A-Z][a-z]+(?:[A-Z][a-z]+)+|[a-z][a-z]+(?:[A-Z][a-z0-9]+)+)(?![`\w])/g;
+/**
+ * Extracts likely code symbol names from markdown text.
+ * Returns deduplicated symbol names of 4+ characters.
+ */
+function extractSymbols(text) {
+    const found = new Set();
+    let m;
+    BACKTICK_RE.lastIndex = 0;
+    while ((m = BACKTICK_RE.exec(text)) !== null) {
+        found.add(m[1]);
+    }
+    CAMEL_PASCAL_RE.lastIndex = 0;
+    while ((m = CAMEL_PASCAL_RE.exec(text)) !== null) {
+        found.add(m[1]);
+    }
+    return Array.from(found);
+}
+// ---------------------------------------------------------------------------
+// DocMeta loader
+// ---------------------------------------------------------------------------
+/**
+ * Parses YAML frontmatter from a markdown file and returns DocMeta.
+ * Does not throw — returns empty arrays on any parse failure.
+ */
+function loadDocMeta(filePath) {
+    let content = "";
+    try {
+        content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+    }
+    catch {
+        return emptyMeta(filePath);
+    }
+    const frontmatter = parseFrontmatter(content);
+    const filenamePrefixes = extractFilenamePrefixes((0, node_path_1.basename)(filePath, (0, node_path_1.extname)(filePath)));
+    return {
+        path: filePath,
+        tags: toStringArray(frontmatter["Tags"] ?? frontmatter["tags"]),
+        type: String(frontmatter["Type"] ?? frontmatter["type"] ?? "").trim(),
+        clusterMembership: toStringArray(frontmatter["Member Of Concept Cluster"]),
+        relatedNotes: toStringArray(frontmatter["Related Notes"]),
+        filenamePrefixes,
+    };
+}
+/**
+ * Reads all .md files from a directory and returns their DocMeta.
+ */
+function loadAllDocMeta(dir) {
+    let entries = [];
+    try {
+        entries = (0, node_fs_1.readdirSync)(dir).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+    return entries.map((f) => loadDocMeta((0, node_path_1.join)(dir, f)));
+}
+function emptyMeta(filePath) {
+    return {
+        path: filePath,
+        tags: [],
+        type: "",
+        clusterMembership: [],
+        relatedNotes: [],
+        filenamePrefixes: extractFilenamePrefixes((0, node_path_1.basename)(filePath, (0, node_path_1.extname)(filePath))),
+    };
+}
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const result = {};
+    const lines = match[1].split("\n");
+    let currentKey = null;
+    const listBuffer = [];
+    const flushList = () => {
+        if (currentKey && listBuffer.length > 0) {
+            result[currentKey] = [...listBuffer];
+            listBuffer.length = 0;
+        }
+    };
+    for (const line of lines) {
+        // Inline array: Tags: [a, b]
+        const inlineMatch = line.match(/^([^:]+):\s*\[(.*)\]$/);
+        if (inlineMatch) {
+            flushList();
+            currentKey = null;
+            const key = inlineMatch[1].trim();
+            result[key] = inlineMatch[2]
+                .split(",")
+                .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                .filter(Boolean);
+            continue;
+        }
+        // Key with value: Type: Decision
+        const kvMatch = line.match(/^([^:]+):\s*(.+)$/);
+        if (kvMatch && !line.startsWith("  ")) {
+            flushList();
+            currentKey = kvMatch[1].trim();
+            const val = kvMatch[2].trim();
+            if (val !== "") {
+                result[currentKey] = val.replace(/^["']|["']$/g, "");
+                currentKey = null;
+            }
+            continue;
+        }
+        // Key with no inline value (list follows)
+        const keyOnlyMatch = line.match(/^([^:]+):\s*$/);
+        if (keyOnlyMatch && !line.startsWith("  ")) {
+            flushList();
+            currentKey = keyOnlyMatch[1].trim();
+            continue;
+        }
+        // List item — wikilink style: - "[[ADR-002|ADR-002]]"
+        const listItemMatch = line.match(/^\s+-\s+"?\[\[([^\]|]+)(?:\|[^\]]+)?\]\]"?$/);
+        if (listItemMatch && currentKey) {
+            listBuffer.push(listItemMatch[1].trim());
+            continue;
+        }
+        // List item — plain
+        const simpleItemMatch = line.match(/^\s+-\s+(.+)$/);
+        if (simpleItemMatch && currentKey) {
+            listBuffer.push(simpleItemMatch[1].trim().replace(/^["']|["']$/g, ""));
+        }
+    }
+    flushList();
+    return result;
+}
+function toStringArray(value) {
+    if (!value)
+        return [];
+    if (Array.isArray(value))
+        return value.map(String).filter(Boolean);
+    if (typeof value === "string" && value.trim())
+        return [value.trim()];
+    return [];
+}
+function extractFilenamePrefixes(stem) {
+    // "ADR-001 - Some Title" → ["ADR"]
+    // "EVOlearn_Governance" → ["EVOlearn"]
+    const parts = stem.split(/[-_ ]/);
+    return parts.slice(0, 2).filter((p) => p.length >= 3 && /[A-Za-z]/.test(p));
+}
+const CHECKPOINT_FILENAME = "_triage-checkpoint.json";
+function readTriageCheckpoint(outputDir) {
+    const p = (0, node_path_1.join)(outputDir, CHECKPOINT_FILENAME);
+    if (!(0, node_fs_1.existsSync)(p))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeTriageCheckpoint(checkpoint, outputDir) {
+    (0, node_fs_1.mkdirSync)(outputDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, CHECKPOINT_FILENAME), JSON.stringify(checkpoint, null, 2), "utf-8");
+}
+function deleteTriageCheckpoint(outputDir) {
+    const p = (0, node_path_1.join)(outputDir, CHECKPOINT_FILENAME);
+    if ((0, node_fs_1.existsSync)(p))
+        (0, node_fs_1.unlinkSync)(p);
+}
+// ---------------------------------------------------------------------------
+// Triage queue writer
+// ---------------------------------------------------------------------------
+function writeTriageQueue(packets, outputDir) {
+    (0, node_fs_1.mkdirSync)(outputDir, { recursive: true });
+    const queueFile = {
+        generated_at: new Date().toISOString(),
+        run_id: `triage-${Date.now()}`,
+        packets,
+    };
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, "_triage-queue.json"), JSON.stringify(queueFile, null, 2), "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, "_triage-report.md"), renderTriageReport(packets), "utf-8");
+}
+function renderTriageReport(packets) {
+    const contradictions = packets.filter((p) => p.triageFlag === "contradiction");
+    const duplicates = packets.filter((p) => p.triageFlag === "duplicate");
+    const stale = packets.filter((p) => p.triageFlag === "stale-reference");
+    const lines = [
+        "# Polaris Docs Triage Report",
+        "",
+        `Generated: ${new Date().toISOString()}`,
+        "",
+        "## Summary",
+        "",
+        `| Flag | Count |`,
+        `|------|-------|`,
+        `| contradiction | ${contradictions.length} |`,
+        `| duplicate | ${duplicates.length} |`,
+        `| stale-reference | ${stale.length} |`,
+        `| **total** | **${packets.length}** |`,
+        "",
+        "## Flagged Documents",
+        "",
+        "This file is display-only. Edit `_triage-queue.json` to record decisions,",
+        "or run `polaris docs review` to walk through them interactively.",
+        "",
+    ];
+    for (const p of packets) {
+        lines.push(`### ${p.triageFlag.toUpperCase()} · ${p.sourcePath}`);
+        lines.push("");
+        lines.push(`**Reason:** ${p.outcomeReason}`);
+        if (p.relatedCanonical) {
+            lines.push(`**Conflicts with:** ${p.relatedCanonical}`);
+        }
+        if (p.staleSymbols && p.staleSymbols.length > 0) {
+            lines.push(`**Stale symbols:** ${p.staleSymbols.join(", ")}`);
+        }
+        lines.push(`**Review decision:** ${p.reviewDecision ?? "← pending"}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function resolveTriageModel(configured) {
+    return (process.env["POLARIS_TRIAGE_MODEL"] ??
+        configured ??
+        "claude-haiku-4-5-20251001");
+}
+async function runBatchComparison(candidates, canonicals, options) {
+    const client = options.llmClient ?? (await buildDefaultLlmClient());
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            return await client.compare(candidates, canonicals, options.model);
+        }
+        catch (err) {
+            process.stderr.write(`[triage] LLM batch failed (attempt ${attempt + 1})${attempt === 0 ? ", retrying" : ", skipping batch"}: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    return [];
+}
+async function buildDefaultLlmClient() {
+    const apiKey = process.env["ANTHROPIC_API_KEY"] ?? "";
+    // 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");
+    const Anthropic = mod.default ?? mod.Anthropic;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    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 response = await sdkClient.messages.create({
+                model,
+                max_tokens: 1024,
+                messages: [{ role: "user", content: prompt }],
+            });
+            const text = response.content
+                .filter((b) => b.type === "text")
+                .map((b) => b.text)
+                .join("");
+            const cleaned = text.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim();
+            return JSON.parse(cleaned);
+        },
+    };
+}
+const STALE_SYMBOL_THRESHOLD = 2;
+const GRAPH_SYMBOL_MINIMUM = 1000;
+function runGraphCheck(candidates, options) {
+    const stats = options.graphStats();
+    if (stats.symbolCount < GRAPH_SYMBOL_MINIMUM) {
+        process.stderr.write(`[triage] Graph coverage too low for doc-vs-code check (${stats.symbolCount} symbols indexed).\n` +
+            `         Run: polaris-cli graph build\n`);
+        return [];
+    }
+    const flags = [];
+    for (const candidate of candidates) {
+        let content = "";
+        try {
+            content = options.getContent(candidate.path);
+        }
+        catch {
+            continue;
+        }
+        const symbols = extractSymbols(content);
+        const missing = symbols.filter((s) => !options.symbolLookup(s));
+        if (missing.length >= STALE_SYMBOL_THRESHOLD) {
+            flags.push({
+                candidatePath: candidate.path,
+                flagType: "stale-reference",
+                staleSymbols: missing,
+            });
+        }
+    }
+    return flags;
+}
+async function runTriage(options) {
+    const { repoRoot, batchSize = 10, dryRun = false, output = (m) => process.stdout.write(m + "\n"), llmClient, symbolLookup, graphStats, } = options;
+    const activeDir = (0, node_path_1.join)(repoRoot, "smartdocs", "doctrine", "active");
+    const candidateDir = (0, node_path_1.join)(repoRoot, "smartdocs", "doctrine", "candidate");
+    const outputDir = (0, node_path_1.join)(repoRoot, "smartdocs", "raw");
+    output(`Loading canonical docs from ${activeDir}...`);
+    const canonicals = loadAllDocMeta(activeDir);
+    output(`Loading candidate docs from ${candidateDir}...`);
+    const candidates = loadAllDocMeta(candidateDir);
+    output(`Clustering ${candidates.length} candidates against ${canonicals.length} canonicals...`);
+    const clusterMap = clusterCandidates(candidates, canonicals);
+    const clusterNames = Object.keys(clusterMap).filter((k) => k !== "general");
+    if (clusterMap["general"])
+        clusterNames.push("general");
+    if (dryRun) {
+        const batchCount = clusterNames.reduce((sum, name) => {
+            return sum + Math.ceil((clusterMap[name].candidates.length || 0) / batchSize);
+        }, 0);
+        output(`  ${clusterNames.length} clusters identified`);
+        output(`  Estimated batches: ${batchCount}`);
+        output(`  Estimated tokens: ~${batchCount * 3000} input / ~${batchCount * 200} output`);
+        output(`  Model: ${resolveTriageModel(options.model)} (configured)`);
+        output(`\nRun without --dry-run to execute.`);
+        return { flagCount: 0, outputDir };
+    }
+    let checkpoint = readTriageCheckpoint(outputDir);
+    const completedClusters = new Set(checkpoint?.completedClusters ?? []);
+    const accumulatedFlags = [...(checkpoint?.flags ?? [])];
+    if (completedClusters.size > 0) {
+        output(`Resuming triage from checkpoint (${completedClusters.size}/${clusterNames.length} clusters complete)...`);
+    }
+    const model = resolveTriageModel(options.model);
+    // Phase 1: doc-vs-doc
+    for (const clusterName of clusterNames) {
+        if (completedClusters.has(clusterName))
+            continue;
+        const cluster = clusterMap[clusterName];
+        if (cluster.candidates.length === 0) {
+            completedClusters.add(clusterName);
+            continue;
+        }
+        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 });
+            accumulatedFlags.push(...flags);
+        }
+        completedClusters.add(clusterName);
+        writeTriageCheckpoint({ completedClusters: Array.from(completedClusters), flags: accumulatedFlags }, outputDir);
+    }
+    // Phase 2: doc-vs-code
+    output(`Running doc-vs-code graph check...`);
+    const graphCheckOptions = {
+        getContent: (p) => (0, node_fs_1.readFileSync)(p, "utf-8"),
+        symbolLookup: symbolLookup ?? ((name) => {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { lookupSymbol } = require("../graph/query/index.js");
+            return lookupSymbol(name) !== null;
+        }),
+        graphStats: graphStats ?? (() => {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { getGraphStats } = require("../graph/query/index.js");
+            return getGraphStats();
+        }),
+    };
+    const graphFlags = runGraphCheck(candidates, graphCheckOptions);
+    const allPackets = [
+        ...accumulatedFlags.map((f) => ({
+            sourcePath: f.candidatePath,
+            proposedDestination: f.candidatePath,
+            classificationConfidence: 0,
+            destinationCertainty: 0,
+            authorityRisk: "medium",
+            reasoning: [f.reason],
+            conflicts: f.canonicalPath ? [f.canonicalPath] : [],
+            recommendation: "defer",
+            outcomeReason: f.reason,
+            triageFlag: f.flagType,
+            relatedCanonical: f.canonicalPath,
+        })),
+        ...graphFlags.map((f) => ({
+            sourcePath: f.candidatePath,
+            proposedDestination: f.candidatePath,
+            classificationConfidence: 0,
+            destinationCertainty: 0,
+            authorityRisk: "low",
+            reasoning: [`Stale symbol references: ${f.staleSymbols.join(", ")}`],
+            conflicts: [],
+            recommendation: "defer",
+            outcomeReason: `${f.staleSymbols.length} code symbols not found in graph: ${f.staleSymbols.join(", ")}`,
+            triageFlag: "stale-reference",
+            staleSymbols: f.staleSymbols,
+        })),
+    ];
+    writeTriageQueue(allPackets, outputDir);
+    deleteTriageCheckpoint(outputDir);
+    output(`\nTriage complete: ${allPackets.length} flags written to ${outputDir}/_triage-queue.json`);
+    output(`Run \`polaris docs review\` to walk through decisions.`);
+    return { flagCount: allPackets.length, outputDir };
+}

package/package.json

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