@lsctech/polaris 0.1.0

package/dist/loop/worker.test.js

@@ -0,0 +1,372 @@
+"use strict";
+/**
+ * Unit tests for src/loop/worker.ts
+ *
+ * Uses a mock executeChild hook and mock bootstrap packet to verify:
+ * - CompactReturn schema validity on success
+ * - current-state.json child completion fields updated
+ * - Telemetry JSONL events appended
+ * - Worker does not continue to next child
+ * - Failure path returns correct CompactReturn
+ */
+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 worker_js_1 = require("./worker.js");
+const compact_return_js_1 = require("./compact-return.js");
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function makeTmpDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-worker-test-${Date.now()}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    return dir;
+}
+function makeStateFile(dir, childId) {
+    const stateFile = (0, node_path_1.join)(dir, "current-state.json");
+    const state = {
+        schema_version: "1.0",
+        run_id: "test-run-001",
+        cluster_id: "POL-99",
+        skill: "polaris-run",
+        artifact_dir: dir,
+        branch: "feature/test",
+        step_cursor: "dispatching",
+        status: "executing",
+        session_type: "implementation",
+        active_child: childId,
+        last_commit: "abc1234",
+        next_open_child: childId,
+        completed_children: ["POL-68"],
+        open_children: [childId, "POL-70"],
+        open_children_meta: {},
+        context_budget: {
+            children_completed: 1,
+            files_touched_total: 5,
+            max_children_per_session: 3,
+        },
+        updated_at: new Date().toISOString(),
+    };
+    (0, node_fs_1.writeFileSync)(stateFile, JSON.stringify(state, null, 2), "utf-8");
+    return stateFile;
+}
+function makeTelemetryFile(dir, runId) {
+    const telemetryFile = (0, node_path_1.join)(dir, "runs", runId, "telemetry.jsonl");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, "runs", runId), { recursive: true });
+    (0, node_fs_1.writeFileSync)(telemetryFile, "", "utf-8");
+    return telemetryFile;
+}
+function makePacket(stateFile, telemetryFile, childId = "POL-69", runId = "test-run-001") {
+    return {
+        schema_version: "1.0",
+        run_id: runId,
+        cluster_id: "POL-99",
+        active_child: childId,
+        state_file: stateFile,
+        telemetry_file: telemetryFile,
+    };
+}
+// ── Tests ─────────────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("executeOneChild", () => {
+    let tmpDir;
+    (0, vitest_1.beforeEach)(() => {
+        tmpDir = makeTmpDir();
+    });
+    (0, vitest_1.afterEach)(() => {
+        try {
+            (0, node_fs_1.rmSync)(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    });
+    (0, vitest_1.it)("returns a valid CompactReturn JSON for a successful child", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        let childExecuted = false;
+        const result = await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            executeChild: (childId) => {
+                (0, vitest_1.expect)(childId).toBe("POL-69");
+                childExecuted = true;
+            },
+        });
+        (0, vitest_1.expect)(childExecuted).toBe(true);
+        // Schema validity
+        const errors = (0, compact_return_js_1.validateCompactReturn)(result);
+        (0, vitest_1.expect)(errors).toHaveLength(0);
+        // Core fields
+        (0, vitest_1.expect)(result.child_id).toBe("POL-69");
+        (0, vitest_1.expect)(result.status).toBe("done");
+        (0, vitest_1.expect)(result.validation).toBe("passed");
+        (0, vitest_1.expect)(result.telemetry_updated).toBe(true);
+        (0, vitest_1.expect)(result.state_updated).toBe(true);
+        (0, vitest_1.expect)(result.next_recommended_action).toBe("continue");
+    });
+    (0, vitest_1.it)("updates current-state.json child completion fields", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            executeChild: () => { },
+        });
+        const savedState = JSON.parse((0, node_fs_1.readFileSync)(stateFile, "utf-8"));
+        // POL-69 moved from open_children to completed_children
+        (0, vitest_1.expect)(savedState["open_children"]).not.toContain("POL-69");
+        (0, vitest_1.expect)(savedState["completed_children"]).toContain("POL-69");
+        // active_child cleared
+        (0, vitest_1.expect)(savedState["active_child"]).toBe("");
+        // children_completed incremented
+        const budget = savedState["context_budget"];
+        (0, vitest_1.expect)(budget["children_completed"]).toBe(2); // was 1, now 2
+        // status reflects remaining children
+        (0, vitest_1.expect)(savedState["status"]).toBe("running"); // POL-70 still open
+    });
+    (0, vitest_1.it)("does not emit intermediate step-complete telemetry events on success", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            executeChild: () => { },
+        });
+        // Worker writes no telemetry on the success path — the parent emits
+        // child-complete via polaris loop continue (checkpoint cadence).
+        const raw = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim();
+        const lines = raw ? raw.split("\n").filter(Boolean) : [];
+        const stepCompleteEvents = lines
+            .map((l) => JSON.parse(l))
+            .filter((e) => e["event"] === "step-complete");
+        (0, vitest_1.expect)(stepCompleteEvents).toHaveLength(0);
+    });
+    (0, vitest_1.it)("returns status=failed when executeChild throws", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        const result = await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            executeChild: () => {
+                throw new Error("mock child failure");
+            },
+        });
+        const errors = (0, compact_return_js_1.validateCompactReturn)(result);
+        (0, vitest_1.expect)(errors).toHaveLength(0);
+        (0, vitest_1.expect)(result.child_id).toBe("POL-69");
+        (0, vitest_1.expect)(result.status).toBe("failed");
+        (0, vitest_1.expect)(result.validation).toBe("failed");
+        (0, vitest_1.expect)(result.state_updated).toBe(false);
+        (0, vitest_1.expect)(result.next_recommended_action).toBe("investigate");
+    });
+    (0, vitest_1.it)("does not continue to the next child (single execution only)", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        let callCount = 0;
+        await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            executeChild: () => {
+                callCount += 1;
+            },
+        });
+        // executeChild must be called exactly once — never for POL-70 or any other child
+        (0, vitest_1.expect)(callCount).toBe(1);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// POL-221: worker-acknowledged event emission tests
+// ─────────────────────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("executeOneChild — worker-acknowledged event (POL-221)", () => {
+    let tmpDir;
+    (0, vitest_1.beforeEach)(() => {
+        tmpDir = makeTmpDir();
+    });
+    (0, vitest_1.afterEach)(() => {
+        try {
+            (0, node_fs_1.rmSync)(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    });
+    (0, vitest_1.it)("emits worker-acknowledged event with dispatch_id, worker_id, packet_sha", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        packet.dispatch_id = "dispatch-uuid-001";
+        packet.worker_id = "worker-uuid-001";
+        // Write the packet to a file so SHA can be computed
+        const packetPath = tmpDir + "/packet.json";
+        (0, node_fs_1.writeFileSync)(packetPath, JSON.stringify(packet), "utf-8");
+        await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            packetPath,
+            executeChild: () => { },
+        });
+        const raw = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim();
+        const events = raw.split("\n").filter(Boolean).map((l) => JSON.parse(l));
+        const ackEvent = events.find((e) => e["event"] === "worker-acknowledged");
+        (0, vitest_1.expect)(ackEvent).toBeDefined();
+        (0, vitest_1.expect)(ackEvent?.["dispatch_id"]).toBe("dispatch-uuid-001");
+        (0, vitest_1.expect)(ackEvent?.["worker_id"]).toBe("worker-uuid-001");
+        (0, vitest_1.expect)(typeof ackEvent?.["packet_sha"]).toBe("string");
+        (0, vitest_1.expect)((ackEvent?.["packet_sha"]).length).toBe(64); // SHA-256 hex
+    });
+    (0, vitest_1.it)("emits worker-acknowledged before any other telemetry events", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        packet.dispatch_id = "dispatch-uuid-002";
+        packet.worker_id = "worker-uuid-002";
+        await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            executeChild: () => { },
+        });
+        const raw = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim();
+        const events = raw.split("\n").filter(Boolean).map((l) => JSON.parse(l));
+        (0, vitest_1.expect)(events.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(events[0]?.["event"]).toBe("worker-acknowledged");
+    });
+    (0, vitest_1.it)("emits worker-acknowledged with empty packet_sha when no packet file or raw JSON provided", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        packet.dispatch_id = "dispatch-uuid-003";
+        packet.worker_id = "worker-uuid-003";
+        // No packetPath or packetRawJson — SHA will be empty string
+        await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            executeChild: () => { },
+        });
+        const raw = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim();
+        const events = raw.split("\n").filter(Boolean).map((l) => JSON.parse(l));
+        const ackEvent = events.find((e) => e["event"] === "worker-acknowledged");
+        (0, vitest_1.expect)(ackEvent).toBeDefined();
+        (0, vitest_1.expect)(ackEvent?.["packet_sha"]).toBe("");
+    });
+    (0, vitest_1.it)("computes packet_sha from packetRawJson when no file path provided", async () => {
+        const stateFile = makeStateFile(tmpDir, "POL-69");
+        const telemetryFile = makeTelemetryFile(tmpDir, "test-run-001");
+        const packet = makePacket(stateFile, telemetryFile);
+        packet.dispatch_id = "dispatch-uuid-004";
+        packet.worker_id = "worker-uuid-004";
+        const rawJson = JSON.stringify(packet);
+        await (0, worker_js_1.executeOneChild)(packet, {
+            repoRoot: tmpDir,
+            packetRawJson: rawJson,
+            executeChild: () => { },
+        });
+        const raw = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim();
+        const events = raw.split("\n").filter(Boolean).map((l) => JSON.parse(l));
+        const ackEvent = events.find((e) => e["event"] === "worker-acknowledged");
+        (0, vitest_1.expect)(ackEvent).toBeDefined();
+        (0, vitest_1.expect)(typeof ackEvent?.["packet_sha"]).toBe("string");
+        (0, vitest_1.expect)((ackEvent?.["packet_sha"]).length).toBe(64);
+    });
+});
+(0, vitest_1.describe)("readBootstrapPacket", () => {
+    let tmpDir;
+    (0, vitest_1.beforeEach)(() => {
+        tmpDir = makeTmpDir();
+    });
+    (0, vitest_1.afterEach)(() => {
+        try {
+            (0, node_fs_1.rmSync)(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+        // Restore env vars
+        delete process.env["POLARIS_BOOTSTRAP_PACKET"];
+        delete process.env["POLARIS_PACKET_FILE"];
+        delete process.env["POLARIS_PACKET_JSON"];
+    });
+    (0, vitest_1.it)("reads packet from --bootstrap CLI argument", () => {
+        const packetFile = (0, node_path_1.join)(tmpDir, "packet.json");
+        const packet = {
+            schema_version: "1.0",
+            run_id: "run-1",
+            cluster_id: "POL-99",
+            active_child: "POL-69",
+            state_file: "/tmp/state.json",
+            telemetry_file: "/tmp/telemetry.jsonl",
+        };
+        (0, node_fs_1.writeFileSync)(packetFile, JSON.stringify(packet), "utf-8");
+        const result = (0, worker_js_1.readBootstrapPacket)(["node", "worker.js", "--bootstrap", packetFile]);
+        (0, vitest_1.expect)(result.active_child).toBe("POL-69");
+        (0, vitest_1.expect)(result.run_id).toBe("run-1");
+    });
+    (0, vitest_1.it)("reads packet from POLARIS_BOOTSTRAP_PACKET env var", () => {
+        const packetFile = (0, node_path_1.join)(tmpDir, "packet.json");
+        const packet = {
+            schema_version: "1.0",
+            run_id: "run-2",
+            cluster_id: "POL-99",
+            active_child: "POL-70",
+            state_file: "/tmp/state.json",
+            telemetry_file: "/tmp/telemetry.jsonl",
+        };
+        (0, node_fs_1.writeFileSync)(packetFile, JSON.stringify(packet), "utf-8");
+        process.env["POLARIS_BOOTSTRAP_PACKET"] = packetFile;
+        const result = (0, worker_js_1.readBootstrapPacket)(["node", "worker.js"]);
+        (0, vitest_1.expect)(result.active_child).toBe("POL-70");
+    });
+    (0, vitest_1.it)("reads packet from POLARIS_PACKET_JSON env var", () => {
+        const packet = {
+            schema_version: "1.0",
+            run_id: "run-3",
+            cluster_id: "POL-99",
+            active_child: "POL-71",
+            state_file: "/tmp/state.json",
+            telemetry_file: "/tmp/telemetry.jsonl",
+        };
+        process.env["POLARIS_PACKET_JSON"] = JSON.stringify(packet);
+        const result = (0, worker_js_1.readBootstrapPacket)(["node", "worker.js"]);
+        (0, vitest_1.expect)(result.active_child).toBe("POL-71");
+    });
+    (0, vitest_1.it)("throws when no packet source is available", () => {
+        (0, vitest_1.expect)(() => (0, worker_js_1.readBootstrapPacket)(["node", "worker.js"])).toThrow(/No bootstrap packet found/);
+    });
+});
+(0, vitest_1.describe)("validateCompactReturn", () => {
+    (0, vitest_1.it)("accepts a valid CompactReturn", () => {
+        const valid = {
+            child_id: "POL-69",
+            status: "done",
+            commit: "abc1234",
+            validation: "passed",
+            tracker_updated: false,
+            state_updated: true,
+            telemetry_updated: true,
+            next_recommended_action: "continue",
+        };
+        (0, vitest_1.expect)((0, compact_return_js_1.validateCompactReturn)(valid)).toHaveLength(0);
+    });
+    (0, vitest_1.it)("rejects missing child_id", () => {
+        const invalid = {
+            child_id: "",
+            status: "done",
+            commit: null,
+            validation: "passed",
+            tracker_updated: false,
+            state_updated: true,
+            telemetry_updated: true,
+            next_recommended_action: "continue",
+        };
+        (0, vitest_1.expect)((0, compact_return_js_1.validateCompactReturn)(invalid).length).toBeGreaterThan(0);
+    });
+    (0, vitest_1.it)("rejects invalid status value", () => {
+        const invalid = {
+            child_id: "POL-69",
+            status: "unknown",
+            commit: null,
+            validation: "passed",
+            tracker_updated: false,
+            state_updated: true,
+            telemetry_updated: true,
+            next_recommended_action: "continue",
+        };
+        (0, vitest_1.expect)((0, compact_return_js_1.validateCompactReturn)(invalid).length).toBeGreaterThan(0);
+    });
+});

package/dist/map/atlas.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_ROLE_OWNERS = void 0;
+exports.resolveInstructionFile = resolveInstructionFile;
+exports.computeInstructionCoverage = computeInstructionCoverage;
+exports.readFileRoutes = readFileRoutes;
+exports.writeFileRoutes = writeFileRoutes;
+exports.readNeedsReview = readNeedsReview;
+exports.writeNeedsReview = writeNeedsReview;
+exports.readExemptions = readExemptions;
+exports.writeExemptions = writeExemptions;
+exports.writeAtlasIndex = writeAtlasIndex;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.VALID_ROLE_OWNERS = ["worker", "foreman", "analyst", "librarian", "any"];
+function resolveInstructionFile(filePath, repoRoot) {
+    const parts = filePath.split("/");
+    for (let i = parts.length - 1; i >= 0; i--) {
+        const dir = parts.slice(0, i).join("/");
+        const candidate = dir ? `${dir}/POLARIS.md` : "POLARIS.md";
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, candidate))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function computeInstructionCoverage(entries) {
+    const routesTotal = Object.keys(entries).length;
+    const routesCovered = Object.values(entries).filter((e) => e.instructionFile !== undefined).length;
+    return {
+        routesCovered,
+        routesTotal,
+        coveragePercent: routesTotal > 0 ? Math.round((routesCovered / routesTotal) * 100) : 0,
+    };
+}
+function ensureDir(filePath) {
+    const dir = (0, node_path_1.dirname)(filePath);
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    }
+}
+function readJson(filePath, fallback) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return fallback;
+        }
+        throw error;
+    }
+}
+function writeJson(filePath, data) {
+    ensureDir(filePath);
+    (0, node_fs_1.writeFileSync)(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function readFileRoutes(outputPath) {
+    return readJson((0, node_path_1.resolve)(outputPath, "file-routes.json"), {});
+}
+function writeFileRoutes(outputPath, routes) {
+    writeJson((0, node_path_1.resolve)(outputPath, "file-routes.json"), routes);
+}
+function readNeedsReview(outputPath) {
+    return readJson((0, node_path_1.resolve)(outputPath, "needs-review.json"), {});
+}
+function writeNeedsReview(outputPath, entries) {
+    writeJson((0, node_path_1.resolve)(outputPath, "needs-review.json"), entries);
+}
+function readExemptions(outputPath) {
+    return readJson((0, node_path_1.resolve)(outputPath, "exemptions.json"), {});
+}
+function writeExemptions(outputPath, entries) {
+    writeJson((0, node_path_1.resolve)(outputPath, "exemptions.json"), entries);
+}
+function writeAtlasIndex(outputPath, index) {
+    writeJson((0, node_path_1.resolve)(outputPath, "index.json"), index);
+}

package/dist/map/backfill.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMapBackfill = runMapBackfill;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const loader_js_1 = require("../config/loader.js");
+const parser_js_1 = require("../ignore/parser.js");
+const defaults_js_1 = require("../ignore/defaults.js");
+const inference_js_1 = require("./inference.js");
+const atlas_js_1 = require("./atlas.js");
+const SECRET_REGEXES = defaults_js_1.SECRET_PATTERNS.map((p) => new RegExp("^" + p.replace(/\./g, "\\.").replace(/\*/g, ".*") + "$"));
+function isSecretFile(filePath) {
+    const parts = filePath.split("/");
+    const base = parts[parts.length - 1];
+    return SECRET_REGEXES.some((re) => re.test(base) || re.test(filePath));
+}
+function* walkDir(dir, root, ig) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return;
+    for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+        const full = (0, node_path_1.join)(dir, entry.name);
+        const rel = (0, node_path_1.relative)(root, full).replace(/\\/g, "/");
+        if (entry.isDirectory()) {
+            if (ig?.ignores(rel + "/"))
+                continue;
+            yield* walkDir(full, root, ig);
+        }
+        else {
+            yield rel;
+        }
+    }
+}
+function loadIgnoreFilter(repoRoot) {
+    let userPatterns = [];
+    try {
+        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(repoRoot, ".polarisignore"), "utf-8");
+        userPatterns = raw.split(/\r?\n/).filter((line) => line.trim() !== "" && !line.startsWith("#"));
+    }
+    catch (err) {
+        if (typeof err === "object" && err !== null && "code" in err && err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    return (0, parser_js_1.parsePolarisIgnore)(userPatterns);
+}
+function getBranchName(repoRoot) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd: repoRoot,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).toString().trim();
+    }
+    catch {
+        return "";
+    }
+}
+function runMapBackfill(repoRoot, dryRun, domainFilter, verbose) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const outputPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(outputPath, "file-routes.json"))) {
+        console.error("atlas not initialized — run `polaris map index` first");
+        process.exit(1);
+    }
+    const routes = (0, atlas_js_1.readFileRoutes)(outputPath);
+    const needsReview = (0, atlas_js_1.readNeedsReview)(outputPath);
+    const exemptions = (0, atlas_js_1.readExemptions)(outputPath);
+    const ig = loadIgnoreFilter(repoRoot);
+    const branchName = getBranchName(repoRoot);
+    const autoWriteAbove = config.map.autoWriteAbove ?? 0.85;
+    const now = new Date().toISOString();
+    const newRoutes = { ...routes };
+    const newNeedsReview = { ...needsReview };
+    let added = 0;
+    let queued = 0;
+    let skippedSecret = 0;
+    let skippedAlreadyMapped = 0;
+    let skippedExempted = 0;
+    let skippedIgnored = 0;
+    const scanRoots = [
+        ...(config.repo.sourceRoots ?? ["src"]),
+        ...(config.repo.docsRoots ?? []),
+    ];
+    const processedFiles = new Set();
+    for (const scanRoot of scanRoots) {
+        const scanDir = (0, node_path_1.resolve)(repoRoot, scanRoot);
+        for (const filePath of walkDir(scanDir, repoRoot, ig)) {
+            // Apply --domain filter: only process files under sourceRoot/domain/
+            if (domainFilter !== undefined) {
+                const domainPrefix = `${scanRoot}/${domainFilter}/`;
+                if (!filePath.startsWith(domainPrefix))
+                    continue;
+            }
+            if (processedFiles.has(filePath))
+                continue;
+            processedFiles.add(filePath);
+            // Security check — never process secret files
+            if (isSecretFile(filePath)) {
+                console.log(`  [HIGH] secret file skipped: ${filePath}`);
+                skippedSecret++;
+                continue;
+            }
+            // Skip if already mapped (never overwrite)
+            if (routes[filePath] || needsReview[filePath]) {
+                skippedAlreadyMapped++;
+                if (verbose)
+                    console.log(`  skip (already mapped): ${filePath}`);
+                continue;
+            }
+            // Skip if exempted
+            if (exemptions[filePath]) {
+                skippedExempted++;
+                if (verbose)
+                    console.log(`  skip (exempted): ${filePath}`);
+                continue;
+            }
+            // Skip if ignored
+            if (ig.ignores(filePath)) {
+                skippedIgnored++;
+                if (verbose)
+                    console.log(`  skip (ignored): ${filePath}`);
+                continue;
+            }
+            // Run inference on unmapped file
+            const inferred = (0, inference_js_1.inferRoute)(filePath, repoRoot, config, routes, branchName);
+            const instructionFile = (0, atlas_js_1.resolveInstructionFile)(filePath, repoRoot);
+            const entry = {
+                domain: inferred.domain,
+                route: inferred.route,
+                taskchain: inferred.taskchain,
+                confidence: inferred.confidence,
+                classification: inferred.confidence >= autoWriteAbove ? "indexed" : "needs-review",
+                last_updated: now,
+                updated_by: "polaris-map-backfill",
+                tags: inferred.tags,
+                ...(instructionFile && { instructionFile }),
+            };
+            if (inferred.confidence >= autoWriteAbove) {
+                newRoutes[filePath] = entry;
+                added++;
+                if (verbose)
+                    console.log(`  add (${inferred.confidence.toFixed(2)}): ${filePath}`);
+            }
+            else {
+                newNeedsReview[filePath] = entry;
+                queued++;
+                if (verbose)
+                    console.log(`  queue (${inferred.confidence.toFixed(2)}): ${filePath}`);
+            }
+        }
+    }
+    const total = added + queued;
+    if (!dryRun && total > 0) {
+        (0, atlas_js_1.writeFileRoutes)(outputPath, newRoutes);
+        (0, atlas_js_1.writeNeedsReview)(outputPath, newNeedsReview);
+        const allEntries = { ...newRoutes, ...newNeedsReview };
+        const totalEntries = Object.keys(allEntries).length;
+        const indexedCount = Object.values(allEntries).filter((e) => e.classification === "indexed").length;
+        (0, atlas_js_1.writeAtlasIndex)(outputPath, {
+            scan_date: now,
+            file_count: totalEntries,
+            coverage_pct: totalEntries > 0 ? Math.round((indexedCount / totalEntries) * 100) : 0,
+            instructionCoverage: (0, atlas_js_1.computeInstructionCoverage)(allEntries),
+            entries: allEntries,
+        });
+    }
+    const skipped = skippedSecret + skippedAlreadyMapped + skippedExempted + skippedIgnored;
+    console.log(`Backfilled ${total} files. Added ${added}. Queued ${queued} for review. Skipped ${skipped} (secret: ${skippedSecret}, already mapped: ${skippedAlreadyMapped}, exempted: ${skippedExempted}, ignored: ${skippedIgnored}).`);
+    if (dryRun)
+        console.log("(dry-run: no files written)");
+}