@lsctech/polaris 0.1.0

package/dist/map/query.test.js

@@ -0,0 +1,174 @@
+"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 query_js_1 = require("./query.js");
+const TMP = (0, node_path_1.join)(process.cwd(), ".test-query-tmp");
+const POLARIS_MD_CONTENT = "# Map subsystem instructions\n\nHandle atlas data.";
+const ROUTES = {
+    "src/cli/index.ts": {
+        domain: "cli",
+        route: "src/cli",
+        taskchain: "polaris-cli",
+        confidence: 0.95,
+        classification: "indexed",
+        last_updated: "2026-05-22T20:00:00Z",
+        updated_by: "polaris-map-index",
+        tags: ["cli", "entry-point"],
+    },
+    "src/map/atlas.ts": {
+        domain: "map",
+        route: "src/map",
+        taskchain: "polaris-core",
+        confidence: 0.92,
+        classification: "indexed",
+        last_updated: "2026-05-22T20:00:00Z",
+        updated_by: "polaris-map-index",
+        tags: ["map"],
+        instructionFile: "src/map/POLARIS.md",
+    },
+};
+const NEEDS_REVIEW = {
+    "src/map/query.ts": {
+        domain: "map",
+        route: "src/map",
+        taskchain: "polaris-core",
+        confidence: 0.6,
+        classification: "needs-review",
+        last_updated: "2026-05-22T20:00:00Z",
+        updated_by: "polaris-map-index",
+        tags: ["map"],
+    },
+};
+const EXEMPTIONS = {
+    "dist/cli/index.js": { classification: "tracked-not-indexed", reason: "generatedRoots" },
+};
+const POLARIS_CONFIG = {
+    repo: { sidecarOutputPath: ".polaris/map" },
+    map: { autoWriteAbove: 0.85, confidenceThreshold: 0.75 },
+};
+function setup() {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, ".polaris/map"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, "src/cli"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, "src/map"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, "dist/cli"), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/cli/index.ts"), "");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/atlas.ts"), "");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), POLARIS_MD_CONTENT);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), JSON.stringify(ROUTES));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/needs-review.json"), JSON.stringify(NEEDS_REVIEW));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/exemptions.json"), JSON.stringify(EXEMPTIONS));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/index.json"), JSON.stringify({ scan_date: "", file_count: 0, coverage_pct: 0, entries: {} }));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "polaris.config.json"), JSON.stringify(POLARIS_CONFIG));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polarisignore"), ".env\n*.log\n");
+}
+function teardown() {
+    (0, node_fs_1.rmSync)(TMP, { recursive: true, force: true });
+}
+function captureOutput(fn) {
+    const stdoutLines = [];
+    const stderrLines = [];
+    const origStdout = process.stdout.write.bind(process.stdout);
+    const origStderr = process.stderr.write.bind(process.stderr);
+    const origLog = console.log.bind(console);
+    const origError = console.error.bind(console);
+    console.log = (...args) => { stdoutLines.push(args.map(String).join(" ")); };
+    console.error = (...args) => { stderrLines.push(args.map(String).join(" ")); };
+    process.stdout.write = (chunk) => { stdoutLines.push(String(chunk)); return true; };
+    process.stderr.write = (chunk) => { stderrLines.push(String(chunk)); return true; };
+    try {
+        fn();
+    }
+    finally {
+        console.log = origLog;
+        console.error = origError;
+        process.stdout.write = origStdout;
+        process.stderr.write = origStderr;
+    }
+    return { stdout: stdoutLines.join(""), stderr: stderrLines.join("") };
+}
+(0, vitest_1.describe)("runMapQuery", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("returns indexed metadata for an exact file lookup", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/cli/index.ts", undefined, undefined, false));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(result["src/cli/index.ts"].classification).toBe("indexed");
+        (0, vitest_1.expect)(result["src/cli/index.ts"].domain).toBe("cli");
+        (0, vitest_1.expect)(result["src/cli/index.ts"].taskchain).toBe("polaris-cli");
+    });
+    (0, vitest_1.it)("returns ignored classification for a .polarisignore-matched file", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, ".env", undefined, undefined, false));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(result[".env"].classification).toBe("ignored");
+    });
+    (0, vitest_1.it)("returns unmapped for a file not in the atlas", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/cli/unknown.ts", undefined, undefined, false));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(result["src/cli/unknown.ts"].classification).toBe("unmapped");
+    });
+    (0, vitest_1.it)("returns tracked-not-indexed for an exempted file", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "dist/cli/index.js", undefined, undefined, false));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(result["dist/cli/index.js"].classification).toBe("tracked-not-indexed");
+    });
+    (0, vitest_1.it)("matches all .ts files in src/ with a glob", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/**/*.ts", undefined, undefined, false));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(Object.keys(result)).toContain("src/cli/index.ts");
+        (0, vitest_1.expect)(Object.keys(result)).toContain("src/map/atlas.ts");
+        (0, vitest_1.expect)(Object.keys(result)).toContain("src/map/query.ts");
+    });
+    (0, vitest_1.it)("filters by domain", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, undefined, "cli", undefined, false));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(Object.keys(result)).toContain("src/cli/index.ts");
+        (0, vitest_1.expect)(Object.keys(result)).not.toContain("src/map/atlas.ts");
+    });
+    (0, vitest_1.it)("filters by taskchain", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, undefined, undefined, "polaris-core", false));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(Object.keys(result)).toContain("src/map/atlas.ts");
+        (0, vitest_1.expect)(Object.keys(result)).toContain("src/map/query.ts");
+        (0, vitest_1.expect)(Object.keys(result)).not.toContain("src/cli/index.ts");
+    });
+    (0, vitest_1.it)("returns all files in a directory with trailing slash", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/map/", undefined, undefined, false));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(Object.keys(result)).toContain("src/map/atlas.ts");
+        (0, vitest_1.expect)(Object.keys(result)).toContain("src/map/query.ts");
+        (0, vitest_1.expect)(Object.keys(result)).not.toContain("src/cli/index.ts");
+    });
+    (0, vitest_1.it)("emits --text output with classification and metadata", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/cli/index.ts", undefined, undefined, true));
+        (0, vitest_1.expect)(stdout).toContain("src/cli/index.ts");
+        (0, vitest_1.expect)(stdout).toContain("indexed");
+        (0, vitest_1.expect)(stdout).toContain("domain:cli");
+    });
+    (0, vitest_1.it)("warns when file does not exist in repo", () => {
+        const { stderr } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "does/not/exist.ts", undefined, undefined, false));
+        (0, vitest_1.expect)(stderr).toContain("warn: file does not exist in repo");
+    });
+    (0, vitest_1.it)("includes instructionFile path in output when entry has one", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/map/atlas.ts", undefined, undefined, false, true));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(result["src/map/atlas.ts"].instructionFile).toBe("src/map/POLARIS.md");
+    });
+    (0, vitest_1.it)("--include-instructions adds instructionContent to output", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/map/atlas.ts", undefined, undefined, false, true));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(result["src/map/atlas.ts"].instructionFile).toBe("src/map/POLARIS.md");
+        (0, vitest_1.expect)(result["src/map/atlas.ts"].instructionContent).toBe(POLARIS_MD_CONTENT);
+    });
+    (0, vitest_1.it)("--include-instructions includes instructionFile in --text output", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/map/atlas.ts", undefined, undefined, true, true));
+        (0, vitest_1.expect)(stdout).toContain("instructions:src/map/POLARIS.md");
+    });
+    (0, vitest_1.it)("entry without instructionFile omits field even with --include-instructions", () => {
+        const { stdout } = captureOutput(() => (0, query_js_1.runMapQuery)(TMP, "src/cli/index.ts", undefined, undefined, false, true));
+        const result = JSON.parse(stdout);
+        (0, vitest_1.expect)(result["src/cli/index.ts"].instructionFile).toBeUndefined();
+        (0, vitest_1.expect)(result["src/cli/index.ts"].instructionContent).toBeUndefined();
+    });
+});

package/dist/map/update.js

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectMissingCognitionSurfaces = detectMissingCognitionSurfaces;
+exports.seedCognitionDrafts = seedCognitionDrafts;
+exports.runMapUpdate = runMapUpdate;
+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 index_js_1 = require("../cognition/index.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 getChangedFiles(repoRoot, fromCommit, toCommit) {
+    const from = fromCommit ?? "HEAD~1";
+    const to = toCommit ?? "HEAD";
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["diff", "--name-only", `${from}..${to}`], {
+            cwd: repoRoot,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).toString().trim();
+        if (!output)
+            return [];
+        return output.split("\n").map((f) => f.trim()).filter(Boolean);
+    }
+    catch {
+        // Fall back to unstaged changes if no commits
+        try {
+            const output = (0, node_child_process_1.execFileSync)("git", ["diff", "--name-only"], {
+                cwd: repoRoot,
+                stdio: ["pipe", "pipe", "pipe"],
+            }).toString().trim();
+            if (!output)
+                return [];
+            return output.split("\n").map((f) => f.trim()).filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+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);
+}
+/**
+ * Draft POLARIS.md content for a newly discovered eligible folder.
+ */
+function draftPolarismd(folderRel) {
+    return [
+        `# ${folderRel}`,
+        "",
+        "<!-- DRAFT: Generated by polaris map update --seed-cognition -->",
+        "<!-- Fill in all sections before committing. Do not leave TODOs in production. -->",
+        "",
+        "## Purpose",
+        "",
+        "<!-- TODO -->",
+        "",
+        "## What belongs here",
+        "",
+        "<!-- TODO -->",
+        "",
+        "## What does not belong here",
+        "",
+        "<!-- TODO -->",
+        "",
+        "## Editing rules",
+        "",
+        "<!-- TODO -->",
+        "",
+        "## Related routes",
+        "",
+        "<!-- TODO -->",
+        "",
+    ].join("\n");
+}
+/**
+ * Draft SUMMARY.md content for a newly discovered eligible folder.
+ */
+function draftSummarymd(folderRel) {
+    return [
+        `# ${folderRel} — Summary`,
+        "",
+        "<!-- DRAFT: Generated by polaris map update --seed-cognition -->",
+        "<!-- TODO: Short informational summary of this route. Keep under 4 KB. -->",
+        "<!-- Informational only. Do not add operational doctrine here. -->",
+        "",
+    ].join("\n");
+}
+/**
+ * Detect folders touched by changed files that are missing POLARIS.md or
+ * SUMMARY.md. Only eligible non-skipped folders are reported.
+ * Root is skipped unless includeRoot=true.
+ */
+function detectMissingCognitionSurfaces(changedFiles, repoRoot, includeRoot) {
+    const missingPolaris = new Set();
+    const missingSummary = new Set();
+    const tierOneFolders = new Set([".polaris", "src", "smartdocs/specs/active"]);
+    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, "smartdocs", "doctrine", "active"))) {
+        tierOneFolders.add("smartdocs/doctrine/active");
+    }
+    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, "src"))) {
+        for (const entry of (0, node_fs_1.readdirSync)((0, node_path_1.resolve)(repoRoot, "src"), { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            tierOneFolders.add(`src/${entry.name}`);
+        }
+    }
+    const hasNonTestNonGeneratedSource = (filePath) => {
+        const normalized = filePath.replace(/\\/g, "/");
+        const fileName = normalized.split("/").pop() ?? normalized;
+        if (normalized.startsWith(".") ||
+            /(^|\/)(dist|build|out|coverage|generated|__generated__)\//.test(normalized) ||
+            /(^|\/)\.(?!well-known)/.test(normalized))
+            return false;
+        if (/\.test\./.test(fileName) ||
+            /\.spec\./.test(fileName) ||
+            /\.generated\./.test(fileName) ||
+            fileName.endsWith(".d.ts"))
+            return false;
+        return /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|rb|php|cs|c|cc|cpp|h|hpp|sh)$/.test(fileName);
+    };
+    const detectFolderForFile = (filePath) => {
+        const parts = filePath.split("/");
+        for (let i = parts.length - 1; i >= 1; i--) {
+            const dir = parts.slice(0, i).join("/");
+            if (!dir || (0, index_js_1.isCognitionSkippedFolder)(dir, repoRoot))
+                continue;
+            if ((0, index_js_1.isPolarisOwnedFolder)(dir))
+                return dir;
+            const folderTouchedFiles = changedFiles.filter((changed) => changed.startsWith(`${dir}/`));
+            const sourceTouchedFiles = folderTouchedFiles.filter(hasNonTestNonGeneratedSource);
+            if (sourceTouchedFiles.length === 0)
+                continue;
+            if ((0, index_js_1.detectOperationalReasons)(sourceTouchedFiles).length === 0)
+                continue;
+            return dir;
+        }
+        return null;
+    };
+    for (const tierOne of tierOneFolders) {
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, tierOne)))
+            continue;
+        if ((0, index_js_1.isCognitionSkippedFolder)(tierOne, repoRoot))
+            continue;
+        const hasPolarismd = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, tierOne, "POLARIS.md"));
+        const hasSummarymd = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, tierOne, "SUMMARY.md"));
+        if (!hasPolarismd)
+            missingPolaris.add(tierOne);
+        if (hasPolarismd && !hasSummarymd)
+            missingSummary.add(tierOne);
+    }
+    for (const file of changedFiles) {
+        const folder = detectFolderForFile(file);
+        const foundAncestor = Boolean(folder);
+        if (folder) {
+            const hasPolarismd = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, folder, "POLARIS.md"));
+            const hasSummarymd = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, folder, "SUMMARY.md"));
+            if (!hasPolarismd)
+                missingPolaris.add(folder);
+            if (hasPolarismd && !hasSummarymd)
+                missingSummary.add(folder);
+        }
+        // Check root only when explicitly opted in and no non-root ancestor was found
+        if (includeRoot && !foundAncestor) {
+            const hasPolarismd = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, "POLARIS.md"));
+            const hasSummarymd = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, "SUMMARY.md"));
+            if (!hasPolarismd)
+                missingPolaris.add("");
+            if (hasPolarismd && !hasSummarymd)
+                missingSummary.add("");
+        }
+    }
+    return {
+        missingPolaris: Array.from(missingPolaris),
+        missingSummary: Array.from(missingSummary),
+    };
+}
+/**
+ * Seed draft POLARIS.md and/or SUMMARY.md files for newly eligible folders.
+ * Only called when --seed-cognition flag is explicitly set.
+ * Root is skipped unless includeRoot=true. Already-existing files are never overwritten.
+ *
+ * Returns the list of folders that were actually seeded.
+ */
+function seedCognitionDrafts(folders, repoRoot, includeRoot) {
+    const seeded = [];
+    for (const dir of folders.polaris) {
+        // Root (empty string) is only seeded when explicitly opted in
+        if (!includeRoot && !dir)
+            continue;
+        if (dir && (0, index_js_1.isCognitionSkippedFolder)(dir, repoRoot))
+            continue;
+        const target = dir ? (0, node_path_1.resolve)(repoRoot, dir, "POLARIS.md") : (0, node_path_1.resolve)(repoRoot, "POLARIS.md");
+        if (!(0, node_fs_1.existsSync)(target)) {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+            (0, node_fs_1.writeFileSync)(target, draftPolarismd(dir || "."), "utf-8");
+            seeded.push(dir ? `${dir}/POLARIS.md` : "POLARIS.md");
+        }
+    }
+    for (const dir of folders.summary) {
+        if (!includeRoot && !dir)
+            continue;
+        if (dir && (0, index_js_1.isCognitionSkippedFolder)(dir, repoRoot))
+            continue;
+        const target = dir ? (0, node_path_1.resolve)(repoRoot, dir, "SUMMARY.md") : (0, node_path_1.resolve)(repoRoot, "SUMMARY.md");
+        if (!(0, node_fs_1.existsSync)(target)) {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+            (0, node_fs_1.writeFileSync)(target, draftSummarymd(dir || "."), "utf-8");
+            seeded.push(dir ? `${dir}/SUMMARY.md` : "SUMMARY.md");
+        }
+    }
+    return seeded;
+}
+function runMapUpdate(repoRoot, explicitFiles, fromCommit, toCommit, seedCognition, includeRoot) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const outputPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const ig = loadIgnoreFilter(repoRoot);
+    const changedFiles = explicitFiles.length > 0
+        ? explicitFiles
+        : getChangedFiles(repoRoot, fromCommit, toCommit);
+    const routes = (0, atlas_js_1.readFileRoutes)(outputPath);
+    const needsReview = (0, atlas_js_1.readNeedsReview)(outputPath);
+    const exemptions = (0, atlas_js_1.readExemptions)(outputPath);
+    let branchName = "";
+    try {
+        branchName = (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd: repoRoot,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).toString().trim();
+    }
+    catch { /* ignore */ }
+    const summary = { mapped: 0, validated: 0, inferred: 0, needs_review: 0, ignored: 0 };
+    const now = new Date().toISOString();
+    for (const filePath of changedFiles) {
+        // Security check
+        if (isSecretFile(filePath)) {
+            console.error(`[HIGH] Secret file pattern matched, skipping: ${filePath}`);
+            summary.ignored++;
+            continue;
+        }
+        // 1. .polarisignore
+        if (ig.ignores(filePath)) {
+            summary.ignored++;
+            continue;
+        }
+        // 2. File doesn't exist on disk (deleted) → remove from both indexes, skip
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, filePath))) {
+            delete needsReview[filePath];
+            delete routes[filePath];
+            summary.ignored++;
+            continue;
+        }
+        // 3. Existing entry in file-routes.json → validate and update timestamp
+        if (routes[filePath]) {
+            routes[filePath].last_updated = now;
+            routes[filePath].updated_by = "polaris-map-update";
+            routes[filePath].instructionFile = (0, atlas_js_1.resolveInstructionFile)(filePath, repoRoot);
+            summary.validated++;
+            continue;
+        }
+        // 4. Tracked-not-indexed → skip
+        if (exemptions[filePath]) {
+            summary.ignored++;
+            continue;
+        }
+        // 5. Run inference for new file
+        const inferred = (0, inference_js_1.inferRoute)(filePath, repoRoot, config, routes, branchName);
+        const autoWriteAbove = config.map.autoWriteAbove ?? 0.85;
+        const confidenceThreshold = config.map.confidenceThreshold ?? 0.75;
+        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-update",
+            tags: inferred.tags,
+            instructionFile: (0, atlas_js_1.resolveInstructionFile)(filePath, repoRoot),
+        };
+        if (inferred.confidence >= autoWriteAbove) {
+            routes[filePath] = entry;
+            delete needsReview[filePath];
+            summary.inferred++;
+            summary.mapped++;
+        }
+        else {
+            needsReview[filePath] = entry;
+            delete routes[filePath];
+            summary.needs_review++;
+            if (inferred.confidence >= confidenceThreshold) {
+                // Between thresholds: also track in needs-review but don't fail by default
+            }
+            else {
+                const onLow = config.map.onLowConfidence ?? "warn";
+                if (onLow === "warn") {
+                    console.error(`[WARN] Low confidence (${inferred.confidence.toFixed(2)}) for ${filePath} — added to needs-review`);
+                }
+            }
+        }
+    }
+    (0, atlas_js_1.writeFileRoutes)(outputPath, routes);
+    (0, atlas_js_1.writeNeedsReview)(outputPath, needsReview);
+    const allEntries = { ...routes, ...needsReview };
+    const totalFiles = 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: totalFiles,
+        coverage_pct: totalFiles > 0 ? Math.round((indexedCount / totalFiles) * 100) : 0,
+        instructionCoverage: (0, atlas_js_1.computeInstructionCoverage)(allEntries),
+        entries: allEntries,
+    });
+    // ── Cognition surface detection ─────────────────────────────────────────
+    // Detect newly eligible folders missing POLARIS.md or SUMMARY.md.
+    // Default: report only. With seedCognition=true: create draft files.
+    // Root is skipped by default; opt in with includeRoot=true.
+    // Agent/generated/runtime folders are always skipped.
+    const { missingPolaris, missingSummary } = detectMissingCognitionSurfaces(changedFiles, repoRoot, includeRoot);
+    summary.missing_polaris = missingPolaris;
+    summary.missing_summary = missingSummary;
+    if (missingPolaris.length > 0) {
+        console.error(`[INFO] Folders missing POLARIS.md (${missingPolaris.length}): ${missingPolaris.join(", ")}`);
+    }
+    if (missingSummary.length > 0) {
+        console.error(`[INFO] Folders eligible for SUMMARY.md (${missingSummary.length}): ${missingSummary.join(", ")}`);
+    }
+    if (seedCognition) {
+        const seeded = seedCognitionDrafts({ polaris: missingPolaris, summary: missingSummary }, repoRoot, includeRoot);
+        summary.seeded = seeded;
+        if (seeded.length > 0) {
+            console.error(`[INFO] Seeded draft cognition files (${seeded.length}): ${seeded.join(", ")}`);
+        }
+    }
+    console.log(JSON.stringify(summary));
+    return { summary, hasNeedsReview: summary.needs_review > 0 };
+}

package/dist/map/update.test.js

@@ -0,0 +1,67 @@
+"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 atlas_js_1 = require("./atlas.js");
+const TMP = (0, node_path_1.join)(process.cwd(), ".test-update-tmp");
+function setup() {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, "src/map"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, "src/cli"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, "src/deep/nested/dir"), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), "# Map instructions");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "POLARIS.md"), "# Root instructions");
+}
+function teardown() {
+    (0, node_fs_1.rmSync)(TMP, { recursive: true, force: true });
+}
+(0, vitest_1.describe)("resolveInstructionFile", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("finds POLARIS.md in the same directory as the file", () => {
+        const result = (0, atlas_js_1.resolveInstructionFile)("src/map/atlas.ts", TMP);
+        (0, vitest_1.expect)(result).toBe("src/map/POLARIS.md");
+    });
+    (0, vitest_1.it)("finds root POLARIS.md for a file in a directory without one", () => {
+        const result = (0, atlas_js_1.resolveInstructionFile)("src/cli/index.ts", TMP);
+        (0, vitest_1.expect)(result).toBe("POLARIS.md");
+    });
+    (0, vitest_1.it)("finds nearest ancestor POLARIS.md for deeply nested file", () => {
+        const result = (0, atlas_js_1.resolveInstructionFile)("src/deep/nested/dir/file.ts", TMP);
+        (0, vitest_1.expect)(result).toBe("POLARIS.md");
+    });
+    (0, vitest_1.it)("returns undefined when no POLARIS.md exists anywhere", () => {
+        (0, node_fs_1.rmSync)((0, node_path_1.join)(TMP, "POLARIS.md"));
+        const result = (0, atlas_js_1.resolveInstructionFile)("src/cli/index.ts", TMP);
+        (0, vitest_1.expect)(result).toBeUndefined();
+    });
+    (0, vitest_1.it)("prefers the closest ancestor over a more distant one", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/deep/POLARIS.md"), "# Deep src instructions");
+        const result = (0, atlas_js_1.resolveInstructionFile)("src/deep/nested/dir/file.ts", TMP);
+        (0, vitest_1.expect)(result).toBe("src/deep/POLARIS.md");
+    });
+});
+(0, vitest_1.describe)("computeInstructionCoverage", () => {
+    (0, vitest_1.it)("returns zero coverage for empty entries", () => {
+        const result = (0, atlas_js_1.computeInstructionCoverage)({});
+        (0, vitest_1.expect)(result).toEqual({ routesCovered: 0, routesTotal: 0, coveragePercent: 0 });
+    });
+    (0, vitest_1.it)("counts covered and total correctly", () => {
+        const entries = {
+            "src/a.ts": { domain: "x", route: "x", taskchain: "x", confidence: 1, classification: "indexed", last_updated: "", updated_by: "", tags: [], instructionFile: "POLARIS.md" },
+            "src/b.ts": { domain: "x", route: "x", taskchain: "x", confidence: 1, classification: "indexed", last_updated: "", updated_by: "", tags: [] },
+        };
+        const result = (0, atlas_js_1.computeInstructionCoverage)(entries);
+        (0, vitest_1.expect)(result.routesCovered).toBe(1);
+        (0, vitest_1.expect)(result.routesTotal).toBe(2);
+        (0, vitest_1.expect)(result.coveragePercent).toBe(50);
+    });
+    (0, vitest_1.it)("returns 100% when all entries have instructionFile", () => {
+        const entries = {
+            "src/a.ts": { domain: "x", route: "x", taskchain: "x", confidence: 1, classification: "indexed", last_updated: "", updated_by: "", tags: [], instructionFile: "POLARIS.md" },
+            "src/b.ts": { domain: "x", route: "x", taskchain: "x", confidence: 1, classification: "indexed", last_updated: "", updated_by: "", tags: [], instructionFile: "src/POLARIS.md" },
+        };
+        const result = (0, atlas_js_1.computeInstructionCoverage)(entries);
+        (0, vitest_1.expect)(result.coveragePercent).toBe(100);
+    });
+});