@lsctech/polaris 0.1.0

package/dist/cognition/librarian-dispatch.test.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const librarian_dispatch_js_1 = require("./librarian-dispatch.js");
+const summary_delta_js_1 = require("./summary-delta.js");
+function makeTmp() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-librarian-test-${Date.now()}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    return dir;
+}
+function cleanup(dir) {
+    try {
+        (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+    }
+    catch {
+        // ignore
+    }
+}
+function makePacket(overrides) {
+    return {
+        run_id: "test-run-001",
+        dispatch_id: "dispatch-001",
+        role: "cognition-librarian",
+        folder: "src/loop/",
+        folder_slug: "src-loop",
+        note_paths: [".polaris/cognition/pending/src-loop/note.md"],
+        polaris_md_path: "src/loop/POLARIS.md",
+        summary_md_path: "src/loop/SUMMARY.md",
+        cognition_index_path: ".polaris/cognition/archive/src-loop/cognition-index.json",
+        result_path: "/tmp/result.json",
+        constraints: {
+            max_polaris_addition_lines: 20,
+            max_summary_addition_lines: 30,
+            require_confidence_threshold: 0.80,
+            allowed_files: ["src/loop/POLARIS.md", "src/loop/SUMMARY.md"],
+        },
+        ...overrides,
+    };
+}
+function makeResult(overrides) {
+    return {
+        run_id: "test-run-001",
+        dispatch_id: "dispatch-001",
+        role: "cognition-librarian",
+        folder: "src/loop/",
+        folder_slug: "src-loop",
+        notes_reconciled: [".polaris/cognition/pending/src-loop/note.md"],
+        confidence: 0.90,
+        proposed_patches: [],
+        archive_actions: [],
+        status: "success",
+        ...overrides,
+    };
+}
+function makePatch(overrides) {
+    return {
+        file: "src/loop/POLARIS.md",
+        action: "update",
+        proposed_content: "# POLARIS\n\nShort update.",
+        change_summary: "minor update",
+        ...overrides,
+    };
+}
+(0, vitest_1.describe)("validateAndApplyLibrarianResult", () => {
+    let tmp;
+    (0, vitest_1.beforeEach)(() => {
+        tmp = makeTmp();
+    });
+    (0, vitest_1.afterEach)(() => {
+        cleanup(tmp);
+    });
+    // ── No-patch / success cases ─────────────────────────────────────────────
+    (0, vitest_1.it)("approves a valid result with no patches (no-change)", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({ status: "no-change" }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(true);
+        (0, vitest_1.expect)(outcome.files_written).toEqual([]);
+        (0, vitest_1.expect)(outcome.patches_applied).toEqual([]);
+        (0, vitest_1.expect)(outcome.patches_rejected).toEqual([]);
+    });
+    (0, vitest_1.it)("writes valid POLARIS.md patch to disk", () => {
+        const content = "# POLARIS\n\nNew content.";
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            confidence: 0.95,
+            proposed_patches: [makePatch({ proposed_content: content })],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(true);
+        (0, vitest_1.expect)(outcome.patches_applied).toHaveLength(1);
+        (0, vitest_1.expect)(outcome.files_written).toEqual(["src/loop/POLARIS.md"]);
+        (0, vitest_1.expect)((0, node_fs_1.readFileSync)((0, node_path_1.join)(tmp, "src/loop/POLARIS.md"), "utf-8")).toBe(content);
+    });
+    (0, vitest_1.it)("approves at exactly the confidence threshold boundary", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({ confidence: 0.80 }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(true);
+    });
+    // ── Schema validation (rejects entire result) ───────────────────────────
+    (0, vitest_1.it)("rejects result with invalid schema: missing run_id", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({ run_id: "" }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(false);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/SCHEMA_INVALID/);
+        (0, vitest_1.expect)(outcome.files_written).toEqual([]);
+    });
+    (0, vitest_1.it)("rejects result with invalid schema: wrong role", () => {
+        const result = makeResult();
+        const bad = { ...result, role: "worker" };
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(bad, tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(false);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/SCHEMA_INVALID/);
+    });
+    (0, vitest_1.it)("rejects result with invalid schema: confidence out of range", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({ confidence: 1.5 }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(false);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/SCHEMA_INVALID/);
+    });
+    // ── Confidence threshold §6.4 (rejects entire result) ──────────────────
+    (0, vitest_1.it)("rejects result below confidence threshold", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({ confidence: 0.50 }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(false);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/COGNITION_LOW_CONFIDENCE/);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/0\.5/);
+        (0, vitest_1.expect)(outcome.files_written).toEqual([]);
+    });
+    (0, vitest_1.it)("rejects result just below confidence threshold (0.799)", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({ confidence: 0.799 }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(false);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/COGNITION_LOW_CONFIDENCE/);
+    });
+    // ── File scope check §6.1 (rejects entire result) ───────────────────────
+    (0, vitest_1.it)("rejects entire result when any patch targets an out-of-scope file", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [
+                makePatch({ file: "src/other/POLARIS.md" }),
+            ],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(false);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/COGNITION_SCOPE_VIOLATION/);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/src\/other\/POLARIS\.md/);
+        (0, vitest_1.expect)(outcome.files_written).toEqual([]);
+    });
+    (0, vitest_1.it)("rejects entire result when second patch is out-of-scope, even if first is valid", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [
+                makePatch({ file: "src/loop/POLARIS.md" }),
+                makePatch({ file: "src/other/POLARIS.md" }),
+            ],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(false);
+        (0, vitest_1.expect)(outcome.rejection_reason).toMatch(/COGNITION_SCOPE_VIOLATION/);
+        // No files written — entire result rejected
+        (0, vitest_1.expect)(outcome.files_written).toEqual([]);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(tmp, "src/loop/POLARIS.md"))).toBe(false);
+    });
+    // ── Doctrine bleed §6.2 (rejects specific patch, not entire result) ────
+    (0, vitest_1.it)("rejects SUMMARY.md patch containing doctrine bleed patterns", () => {
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [
+                makePatch({
+                    file: "src/loop/SUMMARY.md",
+                    proposed_content: "## Editing Rules\nDo not do X.",
+                }),
+            ],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.patches_rejected).toHaveLength(1);
+        (0, vitest_1.expect)(outcome.patches_rejected[0].reason).toMatch(/COGNITION_DOCTRINE_BLEED/);
+        (0, vitest_1.expect)(outcome.files_written).toEqual([]);
+    });
+    (0, vitest_1.it)("rejects doctrine-bleeding SUMMARY.md patch but applies valid POLARIS.md patch", () => {
+        const polarisContent = "# Loop\n\nUpdated.";
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [
+                makePatch({ file: "src/loop/POLARIS.md", proposed_content: polarisContent }),
+                makePatch({
+                    file: "src/loop/SUMMARY.md",
+                    proposed_content: "## Constraints\nMust always use X.",
+                }),
+            ],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(true);
+        (0, vitest_1.expect)(outcome.patches_applied).toHaveLength(1);
+        (0, vitest_1.expect)(outcome.patches_rejected).toHaveLength(1);
+        (0, vitest_1.expect)(outcome.patches_rejected[0].reason).toMatch(/COGNITION_DOCTRINE_BLEED/);
+        (0, vitest_1.expect)(outcome.files_written).toEqual(["src/loop/POLARIS.md"]);
+        (0, vitest_1.expect)((0, node_fs_1.readFileSync)((0, node_path_1.join)(tmp, "src/loop/POLARIS.md"), "utf-8")).toBe(polarisContent);
+    });
+    (0, vitest_1.it)("does not apply doctrine-bleed check to POLARIS.md patches", () => {
+        // POLARIS.md can contain constraint-like language — only SUMMARY.md is checked
+        const content = "## Constraints\nMust always do X.";
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [makePatch({ proposed_content: content })],
+        }), tmp, makePacket());
+        // POLARIS.md lines check: "## Constraints\nMust always do X." = 2 lines ≤ 20
+        (0, vitest_1.expect)(outcome.patches_rejected).toHaveLength(0);
+        (0, vitest_1.expect)(outcome.patches_applied).toHaveLength(1);
+    });
+    // ── Size guard §6.3 (rejects specific patch, not entire result) ─────────
+    (0, vitest_1.it)("rejects POLARIS.md patch exceeding max_polaris_addition_lines", () => {
+        const lines = Array.from({ length: 21 }, (_, i) => `line ${i + 1}`).join("\n");
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [makePatch({ proposed_content: lines })],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.patches_rejected).toHaveLength(1);
+        (0, vitest_1.expect)(outcome.patches_rejected[0].reason).toMatch(/COGNITION_SIZE_GUARD/);
+        (0, vitest_1.expect)(outcome.patches_rejected[0].reason).toMatch(/21 lines/);
+    });
+    (0, vitest_1.it)("accepts POLARIS.md patch at exactly the line limit", () => {
+        const lines = Array.from({ length: 20 }, (_, i) => `line ${i + 1}`).join("\n");
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [makePatch({ proposed_content: lines })],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.patches_rejected).toHaveLength(0);
+        (0, vitest_1.expect)(outcome.patches_applied).toHaveLength(1);
+    });
+    (0, vitest_1.it)("rejects SUMMARY.md patch exceeding SUMMARY_MAX_BYTES", () => {
+        const content = "x".repeat(summary_delta_js_1.SUMMARY_MAX_BYTES + 1);
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [
+                makePatch({ file: "src/loop/SUMMARY.md", proposed_content: content }),
+            ],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.patches_rejected).toHaveLength(1);
+        (0, vitest_1.expect)(outcome.patches_rejected[0].reason).toMatch(/COGNITION_SIZE_GUARD/);
+        (0, vitest_1.expect)(outcome.files_written).toEqual([]);
+    });
+    (0, vitest_1.it)("accepts SUMMARY.md patch just under SUMMARY_MAX_BYTES", () => {
+        const content = "x".repeat(summary_delta_js_1.SUMMARY_MAX_BYTES - 1);
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [
+                makePatch({ file: "src/loop/SUMMARY.md", proposed_content: content }),
+            ],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.patches_rejected).toHaveLength(0);
+        (0, vitest_1.expect)(outcome.patches_applied).toHaveLength(1);
+    });
+    // ── All-rejected edge case ───────────────────────────────────────────────
+    (0, vitest_1.it)("returns approved: false when all patches are rejected at patch level", () => {
+        const oversized = Array.from({ length: 21 }, (_, i) => `line ${i + 1}`).join("\n");
+        const outcome = (0, librarian_dispatch_js_1.validateAndApplyLibrarianResult)(makeResult({
+            proposed_patches: [makePatch({ proposed_content: oversized })],
+        }), tmp, makePacket());
+        (0, vitest_1.expect)(outcome.approved).toBe(false);
+        (0, vitest_1.expect)(outcome.rejection_reason).toBe("all patches rejected");
+        (0, vitest_1.expect)(outcome.files_written).toEqual([]);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(tmp, "src/loop/POLARIS.md"))).toBe(false);
+    });
+});

package/dist/cognition/librarian-packet.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * Generates a CloseoutLibrarianPacket for a completed cluster.
+ *
+ * Called by `polaris librarian packet <cluster-id>`.
+ * Writes the packet to .polaris/clusters/<cluster-id>/packets/librarian-packet-<dispatch-id>.json
+ * and prints the absolute path to stdout.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLibrarianPacket = generateLibrarianPacket;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const checkpoint_js_1 = require("../loop/checkpoint.js");
+function generateLibrarianPacket(options) {
+    const repoRoot = node_path_1.default.resolve(options.repoRoot);
+    const { clusterId } = options;
+    let stateFile;
+    if (!options.stateFile) {
+        stateFile = resolveStateFile(repoRoot, clusterId);
+    }
+    else if (node_path_1.default.isAbsolute(options.stateFile)) {
+        stateFile = options.stateFile;
+    }
+    else {
+        stateFile = node_path_1.default.resolve(repoRoot, options.stateFile);
+    }
+    const state = (0, checkpoint_js_1.readState)(stateFile);
+    if (state.cluster_id !== clusterId) {
+        throw new Error(`State file cluster_id "${state.cluster_id}" does not match requested cluster "${clusterId}".`);
+    }
+    if (state.status !== "cluster-complete") {
+        throw new Error(`Cluster "${clusterId}" is not complete (status: "${state.status}"). ` +
+            `All children must be done before dispatching the Closeout Librarian.`);
+    }
+    if (state.completed_children.length === 0) {
+        throw new Error(`Cluster "${clusterId}" has no completed children.`);
+    }
+    const dispatchId = (0, node_crypto_1.randomUUID)();
+    const resultsDir = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "results");
+    const artifactDir = state.artifact_dir ?? node_path_1.default.join(repoRoot, ".taskchain_artifacts", "polaris-run");
+    const telemetryFile = node_path_1.default.join(artifactDir, "runs", state.run_id, "telemetry.jsonl");
+    // Build per-child summaries
+    const childSummaries = state.completed_children.map((childId) => {
+        const resultFile = findResultFile(resultsDir, childId);
+        const result = resultFile ? readJsonFile(resultFile) : null;
+        const commitSha = typeof result?.["commit"] === "string" ? result["commit"] : null;
+        const changedFiles = commitSha ? getCommitFiles(repoRoot, commitSha) : [];
+        const cognitionNotePath = findCognitionNote(repoRoot, childId);
+        return {
+            child_id: childId,
+            title: state.open_children_meta?.[childId]?.title ?? childId,
+            commit_sha: commitSha,
+            changed_files: changedFiles,
+            compact_return_path: resultFile ? node_path_1.default.relative(repoRoot, resultFile) : null,
+            cognition_note_path: cognitionNotePath,
+        };
+    });
+    // Derive affected folders from all changed files across all children
+    const allChangedFiles = childSummaries.flatMap((s) => s.changed_files);
+    const affectedFolders = computeAffectedFolders(repoRoot, allChangedFiles);
+    // Build per-folder cognition paths
+    const polarisMdPaths = affectedFolders.map((folder) => {
+        const slug = folder.replace(/\/+$/, "").replace(/[^a-zA-Z0-9]+/g, "-");
+        const summaryAbs = node_path_1.default.join(repoRoot, folder, "SUMMARY.md");
+        const cognitionIndexAbs = node_path_1.default.join(repoRoot, ".polaris", "cognition", "index", `${slug}.json`);
+        return {
+            folder,
+            folder_slug: slug,
+            polaris_md: node_path_1.default.join(folder, "POLARIS.md"),
+            summary_md: node_fs_1.default.existsSync(summaryAbs) ? node_path_1.default.join(folder, "SUMMARY.md") : null,
+            cognition_index: node_fs_1.default.existsSync(cognitionIndexAbs)
+                ? node_path_1.default.relative(repoRoot, cognitionIndexAbs)
+                : null,
+        };
+    });
+    const cognitionNotes = findPendingCognitionNotes(repoRoot, state.completed_children);
+    const cognitionArchivePaths = findCognitionArchivePaths(repoRoot, affectedFolders);
+    const smartdocsRawPaths = findSmartdocsRaw(repoRoot);
+    const existingSpecs = findActiveSpecs(repoRoot);
+    const existingDoctrine = findActiveDoctrine(repoRoot);
+    const runReportPath = findRunReport(repoRoot, state.run_id);
+    const packetDir = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "packets");
+    const resultDir = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "results");
+    const resultPath = node_path_1.default.join(resultDir, `librarian-${dispatchId}.json`);
+    // Prohibited: anything that is not documentation or cognition
+    const prohibitedWritePaths = [
+        stateFile,
+        node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "state.json"),
+        node_path_1.default.join(repoRoot, ".taskchain_artifacts"),
+        node_path_1.default.join(repoRoot, ".polaris", "runs"),
+        node_path_1.default.join(repoRoot, ".polaris", "map"),
+        packetDir,
+        resultDir,
+        telemetryFile,
+        node_path_1.default.join(repoRoot, "src"),
+        node_path_1.default.join(repoRoot, "test"),
+        node_path_1.default.join(repoRoot, "scripts"),
+    ];
+    // Allowed: documentation and cognition paths only
+    const allowedWritePaths = [
+        ...polarisMdPaths.map((p) => node_path_1.default.join(repoRoot, p.polaris_md)),
+        ...polarisMdPaths.filter((p) => p.summary_md).map((p) => node_path_1.default.join(repoRoot, p.summary_md)),
+        node_path_1.default.join(repoRoot, "smartdocs"),
+        node_path_1.default.join(repoRoot, ".polaris", "cognition", "archive"),
+        resultPath,
+    ];
+    const packet = {
+        schema_version: "1.0",
+        role: "closeout-librarian",
+        run_id: state.run_id,
+        dispatch_id: dispatchId,
+        cluster_id: clusterId,
+        completed_children: state.completed_children,
+        child_summaries: childSummaries,
+        run_report_path: runReportPath,
+        current_state_path: node_path_1.default.relative(repoRoot, stateFile),
+        affected_folders: affectedFolders,
+        polaris_md_paths: polarisMdPaths,
+        cognition_notes: cognitionNotes,
+        cognition_archive_paths: cognitionArchivePaths,
+        smartdocs_raw_paths: smartdocsRawPaths,
+        existing_specs: existingSpecs,
+        existing_doctrine: existingDoctrine,
+        result_path: resultPath,
+        prohibited_write_paths: prohibitedWritePaths,
+        allowed_write_paths: allowedWritePaths,
+        constraints: {
+            max_summary_addition_lines: 50,
+            require_polaris_confidence_threshold: 0.8,
+            librarian_timeout_seconds: 600,
+        },
+    };
+    node_fs_1.default.mkdirSync(packetDir, { recursive: true });
+    const packetPath = node_path_1.default.join(packetDir, `librarian-packet-${dispatchId}.json`);
+    node_fs_1.default.writeFileSync(packetPath, JSON.stringify(packet, null, 2), "utf-8");
+    process.stdout.write(`${packetPath}\n`);
+    return packetPath;
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function resolveStateFile(repoRoot, clusterId) {
+    const canonical = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "state.json");
+    if (node_fs_1.default.existsSync(canonical))
+        return canonical;
+    const taskchain = node_path_1.default.join(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
+    if (node_fs_1.default.existsSync(taskchain))
+        return taskchain;
+    const legacy = node_path_1.default.join(repoRoot, ".polaris", "runs", "current-state.json");
+    if (node_fs_1.default.existsSync(legacy))
+        return legacy;
+    return canonical;
+}
+function findResultFile(resultsDir, childId) {
+    try {
+        const files = node_fs_1.default
+            .readdirSync(resultsDir)
+            .filter((f) => f.startsWith(`${childId}-`) && f.endsWith(".json"))
+            .sort();
+        if (files.length === 0)
+            return null;
+        return node_path_1.default.join(resultsDir, files[files.length - 1]);
+    }
+    catch {
+        return null;
+    }
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function getCommitFiles(repoRoot, commitSha) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["show", "--name-only", "--format=", commitSha], { cwd: repoRoot, encoding: "utf-8" });
+        return output.trim().split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+function findCognitionNote(repoRoot, childId) {
+    const pendingDir = node_path_1.default.join(repoRoot, ".polaris", "cognition", "pending");
+    const candidates = [
+        node_path_1.default.join(pendingDir, `${childId}.md`),
+        node_path_1.default.join(pendingDir, `${childId}.json`),
+    ];
+    for (const candidate of candidates) {
+        if (node_fs_1.default.existsSync(candidate))
+            return node_path_1.default.relative(repoRoot, candidate);
+    }
+    // Also try scanning for files that start with the child ID
+    try {
+        const found = node_fs_1.default
+            .readdirSync(pendingDir)
+            .find((f) => f.startsWith(childId + "-") || f.startsWith(childId + "."));
+        if (found)
+            return node_path_1.default.relative(repoRoot, node_path_1.default.join(pendingDir, found));
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+function computeAffectedFolders(repoRoot, changedFiles) {
+    const skip = new Set([".polaris", "node_modules", ".taskchain_artifacts", ".github"]);
+    const folders = new Set();
+    for (const file of changedFiles) {
+        const parts = file.split("/");
+        if (skip.has(parts[0] ?? ""))
+            continue;
+        // Walk up from the file's directory toward root, collecting folders with POLARIS.md
+        for (let depth = 1; depth <= parts.length - 1; depth++) {
+            const folder = parts.slice(0, depth).join("/");
+            if (node_fs_1.default.existsSync(node_path_1.default.join(repoRoot, folder, "POLARIS.md"))) {
+                folders.add(folder + "/");
+            }
+        }
+    }
+    return [...folders].sort();
+}
+function findPendingCognitionNotes(repoRoot, childIds) {
+    const pendingDir = node_path_1.default.join(repoRoot, ".polaris", "cognition", "pending");
+    const results = [];
+    try {
+        const files = node_fs_1.default.readdirSync(pendingDir);
+        for (const file of files) {
+            const base = node_path_1.default.basename(file, node_path_1.default.extname(file));
+            if (childIds.some((id) => base === id || base.startsWith(id + "-"))) {
+                results.push(node_path_1.default.relative(repoRoot, node_path_1.default.join(pendingDir, file)));
+            }
+        }
+    }
+    catch {
+        // no pending dir — normal
+    }
+    return results;
+}
+function findCognitionArchivePaths(repoRoot, affectedFolders) {
+    const archiveDir = node_path_1.default.join(repoRoot, ".polaris", "cognition", "archive");
+    const results = [];
+    try {
+        const slugs = new Set(affectedFolders.map((f) => f.replace(/\/+$/, "").replace(/[^a-zA-Z0-9]+/g, "-")));
+        const files = node_fs_1.default.readdirSync(archiveDir);
+        for (const file of files) {
+            const slug = node_path_1.default.basename(file, node_path_1.default.extname(file)).replace(/-\d{4}-\d{2}-.*$/, "");
+            if (slugs.has(slug)) {
+                results.push(node_path_1.default.relative(repoRoot, node_path_1.default.join(archiveDir, file)));
+            }
+        }
+    }
+    catch {
+        // no archive dir — normal
+    }
+    return results;
+}
+function findSmartdocsRaw(repoRoot) {
+    const candidates = [
+        node_path_1.default.join(repoRoot, "smartdocs", "raw"),
+        node_path_1.default.join(repoRoot, "smartdocs", "docs", "raw"),
+    ];
+    const results = [];
+    for (const dir of candidates) {
+        try {
+            const files = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+            for (const entry of files) {
+                if (entry.isFile()) {
+                    results.push(node_path_1.default.relative(repoRoot, node_path_1.default.join(dir, entry.name)));
+                }
+            }
+        }
+        catch {
+            // directory may not exist
+        }
+    }
+    return results;
+}
+function findActiveSpecs(repoRoot) {
+    const specsDir = node_path_1.default.join(repoRoot, "smartdocs", "specs", "active");
+    return listMarkdownFiles(repoRoot, specsDir);
+}
+function findActiveDoctrine(repoRoot) {
+    const doctrineDir = node_path_1.default.join(repoRoot, "smartdocs", "doctrine", "active");
+    return listMarkdownFiles(repoRoot, doctrineDir);
+}
+function listMarkdownFiles(repoRoot, dir) {
+    try {
+        return node_fs_1.default
+            .readdirSync(dir)
+            .filter((f) => f.endsWith(".md"))
+            .map((f) => node_path_1.default.relative(repoRoot, node_path_1.default.join(dir, f)));
+    }
+    catch {
+        return [];
+    }
+}
+function findRunReport(repoRoot, runId) {
+    const candidates = [
+        node_path_1.default.join(repoRoot, ".taskchain_artifacts", "polaris-run", "runs", runId, "run-report.md"),
+        node_path_1.default.join(repoRoot, ".polaris", "runs", runId, "run-report.md"),
+    ];
+    for (const candidate of candidates) {
+        if (node_fs_1.default.existsSync(candidate))
+            return node_path_1.default.relative(repoRoot, candidate);
+    }
+    return null;
+}

package/dist/cognition/librarian-types.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Types and schema validator for the cognition-librarian role.
+ *
+ * The librarian is dispatched by the foreman after a worker completes. It
+ * reconciles staged work notes into durable folder cognition (POLARIS.md /
+ * SUMMARY.md) and returns a sealed proposed patch — it never writes directly.
+ *
+ * Spec: smartdocs/specs/active/folder-cognition-staging-librarian.md §3
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCognitionLibrarianResult = validateCognitionLibrarianResult;
+/**
+ * Validate an unknown value against the CognitionLibrarianResult schema.
+ * Returns an array of error strings; empty means valid.
+ */
+function validateCognitionLibrarianResult(value) {
+    const errors = [];
+    if (typeof value !== "object" || value === null) {
+        return ["CognitionLibrarianResult must be a JSON object"];
+    }
+    const r = value;
+    if (r["role"] !== "cognition-librarian") {
+        errors.push('role must be "cognition-librarian"');
+    }
+    if (typeof r["run_id"] !== "string" || !r["run_id"]) {
+        errors.push("missing or empty run_id");
+    }
+    if (typeof r["dispatch_id"] !== "string" || !r["dispatch_id"]) {
+        errors.push("missing or empty dispatch_id");
+    }
+    if (typeof r["folder"] !== "string") {
+        errors.push("folder must be a string");
+    }
+    if (typeof r["folder_slug"] !== "string") {
+        errors.push("folder_slug must be a string");
+    }
+    if (!Array.isArray(r["notes_reconciled"])) {
+        errors.push("notes_reconciled must be an array");
+    }
+    if (typeof r["confidence"] !== "number" ||
+        r["confidence"] < 0 ||
+        r["confidence"] > 1) {
+        errors.push("confidence must be a number between 0.0 and 1.0");
+    }
+    if (!Array.isArray(r["proposed_patches"])) {
+        errors.push("proposed_patches must be an array");
+    }
+    if (!Array.isArray(r["archive_actions"])) {
+        errors.push("archive_actions must be an array");
+    }
+    const validStatuses = ["success", "no-change", "low-confidence", "failure"];
+    if (!validStatuses.includes(r["status"])) {
+        errors.push(`status must be one of: ${validStatuses.join(", ")}`);
+    }
+    return errors;
+}