@lsctech/polaris 0.2.2 → 0.3.1

package/dist/skill-packet/generator.js

@@ -8,6 +8,7 @@ exports.SKILL_ROLE_MAP = {
     run: "Foreman",
     ingest: "Librarian",
     promote: "Librarian",
+    triage: "Librarian",
 };
 const ROLE_SUMMARIES = {
     Analyst: "The Analyst gathers evidence, assesses feasibility, and produces implementation-ready plans. The Analyst shapes work but never executes it.",
@@ -187,6 +188,39 @@ function buildPromotePacket() {
         ],
     };
 }
+function buildTriagePacket() {
+    return {
+        authority_boundaries: [
+            "Read smartdocs/doctrine/active/ to load canonicals for comparison",
+            "Read smartdocs/doctrine/candidate/ to load candidates for triage",
+            "Call polaris docs triage [--dry-run] [--batch-size N] [--resume] to run the triage pipeline",
+            "Read smartdocs/raw/_triage-queue.json and _triage-report.md produced by triage",
+            "Emit telemetry events",
+        ],
+        prohibited_actions: [
+            "Move, promote, or delete any document — triage flags only, never decides",
+            "Mutate source files (src/, tests, config)",
+            "Call polaris loop continue or polaris finalize",
+            "Suppress or ignore detected flags",
+            "Auto-approve or auto-reject any triage flag without user review",
+        ],
+        allowed_outputs: [
+            "smartdocs/raw/_triage-queue.json — machine-readable flag list for polaris docs review",
+            "smartdocs/raw/_triage-report.md — human-readable summary",
+            "Telemetry events",
+        ],
+        deliverables: [
+            "_triage-queue.json written with all flags from Phase 1 (doc-vs-doc) and Phase 2 (doc-vs-code)",
+            "_triage-report.md written summarising flag counts by type",
+            "Checkpoint deleted on successful completion",
+        ],
+        stop_conditions: [
+            "Triage pipeline completes and outputs written",
+            "API key not available — report and wait for instruction",
+            "Graph coverage below threshold — Phase 2 skipped with warning",
+        ],
+    };
+}
 function generateSkillPacket(skillName, config) {
     const active_role = exports.SKILL_ROLE_MAP[skillName];
     const role_summary = ROLE_SUMMARIES[active_role];
@@ -211,6 +245,9 @@ function generateSkillPacket(skillName, config) {
         case "promote":
             body = buildPromotePacket();
             break;
+        case "triage":
+            body = buildTriagePacket();
+            break;
     }
     return {
         packet_id,
@@ -222,4 +259,4 @@ function generateSkillPacket(skillName, config) {
         generated_at,
     };
 }
-exports.SUPPORTED_SKILLS = ["analyze", "run", "ingest", "promote"];
+exports.SUPPORTED_SKILLS = ["analyze", "run", "ingest", "promote", "triage"];

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/dist/workspace/workspace/.polaris/skills/ROUTING.md

@@ -33,6 +33,8 @@ message whose primary instruction is to invoke a named Polaris skill.
 | `run polaris-status` | polaris-tools | `.polaris/skills/polaris-tools/` |
 | `docs-ingest` | docs-ingest | `.polaris/skills/docs-ingest/` |
 | `run docs-ingest` | docs-ingest | `.polaris/skills/docs-ingest/` |
+| `docs-triage` | docs-triage | `.polaris/skills/docs-triage/` |
+| `run docs-triage` | docs-triage | `.polaris/skills/docs-triage/` |
 | `polaris-reconcile <CLUSTER-ID>` | polaris-reconcile | `.polaris/skills/polaris-reconcile/` |
 | `run polaris-reconcile on [issue] <CLUSTER-ID>` | polaris-reconcile | `.polaris/skills/polaris-reconcile/` |
 | `polaris-catalog <CLUSTER-ID>` | polaris-catalog | `.polaris/skills/polaris-catalog/` |

package/dist/workspace/workspace/.polaris/skills/docs-triage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: docs-triage
+description: Detect contradictions, duplicates, and stale code references among candidate docs by comparing them against canonicals via LLM batch calls and graph symbol lookup. Writes a triage queue for human review via polaris docs review.
+role: librarian
+role_file: .polaris/roles/librarian.md
+---
+
+## Polaris Skill Bootloader
+
+**Before proceeding, you must obtain a skill packet from the Polaris runtime.**
+
+Run the following command:
+
+```
+npm run polaris -- skill packet triage
+```
+
+- Do not begin work until a packet is returned.
+- Treat the packet as your authoritative instruction source.
+- The packet defines your active role, authority boundaries, prohibited actions, deliverables, and stop conditions.
+- If no packet is produced, stop and report: **Polaris could not authorize this run.**
+
+---
+
+# docs-triage
+
+Use this skill when candidate docs need to be screened for conflicts, duplicates, and stale symbol references before human review.
+
+## When to use
+
+- "Run docs triage"
+- "Triage the candidate docs"
+- "Find contradictions among the candidates"
+- "Check for stale code references in candidates"
+- "Run a dry-run triage to see the estimate"
+
+## How to execute
+
+1. Read `chain.md` — step order, traversal rules, output contract.
+2. Execute steps in the order `chain.md` defines. Do not skip steps.
+3. After triage completes, hand off to `polaris docs review` for human decisions.
+
+## Hard rules — what docs-triage may do
+
+- Read canonicals from `smartdocs/doctrine/active/`
+- Read candidates from `smartdocs/doctrine/candidate/`
+- Call `polaris docs triage [--dry-run] [--batch-size N] [--resume]`
+- Read `smartdocs/raw/_triage-queue.json` and `_triage-report.md`
+- Emit telemetry events
+
+## Hard rules — what docs-triage must NOT do
+
+- Move, promote, or delete any document — triage produces flags only
+- Mutate source files (`src/`, tests, config)
+- Call `polaris loop continue` or `polaris finalize`
+- Auto-approve or auto-reject any triage flag without human review
+
+**Docs-triage flags. It does not decide.**

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

@@ -0,0 +1,99 @@
+---
+name: docs-triage-chain
+description: Route map for docs-triage — step order, stop conditions, output contract, and CLI reference.
+---
+
+# docs-triage chain
+
+## Authority
+
+**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
+
+Query runtime state before acting. Do not infer triage scope or prior progress from conversation context.
+
+## CLI
+
+Always use the repo-local Polaris CLI:
+
+```
+npm run polaris -- docs triage [--dry-run] [--batch-size <n>] [--resume] [--repo-root <path>]
+```
+
+- `--dry-run`: prints cluster count, estimated batches, estimated tokens, and model — no LLM calls
+- `--batch-size <n>`: docs per LLM call (default: 10)
+- `--resume`: resume from last checkpoint (auto-detected if checkpoint exists)
+
+Never assume a globally linked `polaris` command exists.
+
+## Output contract
+
+All outputs written to `smartdocs/raw/`:
+
+| File | Purpose |
+|------|---------|
+| `_triage-queue.json` | Machine-readable flag list — fed directly into `polaris docs review` |
+| `_triage-report.md` | Human-readable summary — display only, never parsed |
+| `_triage-checkpoint.json` | Resume state — deleted automatically on completion |
+
+## Step traversal order
+
+```text
+01-orient-triage     ← dry-run first to confirm cluster count and cost estimate; emit telemetry
+02-run-triage        ← polaris docs triage (with --resume if checkpoint exists)
+03-verify-outputs    ← confirm _triage-queue.json and _triage-report.md written; read summary
+04-hand-off          ← report flag counts by type; instruct user to run polaris docs review
+```
+
+## Stop conditions
+
+**Any step:**
+- `ANTHROPIC_API_KEY` not available → halt, report: "Set ANTHROPIC_API_KEY and re-run"
+- `smartdocs/doctrine/active/` or `smartdocs/doctrine/candidate/` not found → halt, report
+- `_triage-queue.json` not written after pipeline completes → halt, report
+
+**Step 01 (dry-run):**
+- Estimated batches > 500 → pause and surface cost estimate to user before proceeding
+
+**Step 02 (run-triage):**
+- Checkpoint detected → pass `--resume` automatically
+- Graph symbol count < 1000 → Phase 2 skipped (this is expected — log and continue)
+
+## Run ID format
+
+Format: `docs-triage-<date>-<seq>`
+- `<date>`: `YYYY-MM-DD`
+- `<seq>`: zero-padded sequential number per day (`001`, `002`, …)
+
+Example: `docs-triage-2026-06-14-001`
+
+## Telemetry
+
+Telemetry file: `.taskchain_artifacts/docs-triage/runs/<run-id>/telemetry.jsonl` (append-only).
+
+| Event | Trigger |
+|-------|---------|
+| `run-start` | Begin step 01 |
+| `step-complete` | End of every step |
+| `triage-dry-run-complete` | Dry-run summary printed |
+| `triage-complete` | Pipeline finished, outputs written |
+
+Required fields on every event: `event`, `run_id`, `timestamp`.
+
+## Execution reporting
+
+After each completed step, emit a checkpoint:
+
+```text
+**[step-name]** done | blocked | needs-input
+Changed: <outputs written> or none
+Validated: <checks passed> or none
+Blockers: none | <explicit blocker>
+```
+
+### Never compressed
+
+Always write in full:
+- Flag count summary (contradictions / duplicates / stale-references)
+- Any batches skipped due to API errors
+- Phase 2 skip warning if graph coverage is low
+- Hand-off instructions for `polaris docs review`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris-cli": "dist/cli/index.js"
@@ -71,5 +71,8 @@
     "@types/node": "^25.9.1",
     "typescript": "^5.4.2",
     "vitest": "^3.0.5"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.104.1"
   }
 }