@lsctech/polaris 0.1.0

package/dist/smartdocs-engine/validate-instructions.js

@@ -0,0 +1,366 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLastGitModDate = getLastGitModDate;
+exports.getFilesChangedAfter = getFilesChangedAfter;
+exports.parseReadBeforeEditingLinks = parseReadBeforeEditingLinks;
+exports.validateDir = validateDir;
+exports.validateInstructions = validateInstructions;
+exports.printReport = printReport;
+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 atlas_js_1 = require("../map/atlas.js");
+const seed_instructions_js_1 = require("./seed-instructions.js");
+const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
+/**
+ * Get the last git modification date of a file.
+ * Returns null if the file is untracked or git is unavailable.
+ */
+function getLastGitModDate(filePath, repoRoot) {
+    try {
+        const rel = (0, node_path_1.relative)(repoRoot, filePath).replace(/\\/g, "/");
+        const out = (0, node_child_process_1.execFileSync)("git", ["-C", repoRoot, "log", "-1", "--format=%cI", "--", rel], {
+            stdio: ["pipe", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim();
+        if (!out)
+            return null;
+        return new Date(out);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get files in a directory that were modified after a given date (via git log).
+ * Only considers files directly in the directory (not subdirs).
+ */
+function getFilesChangedAfter(dir, since, repoRoot) {
+    try {
+        const relDir = (0, node_path_1.relative)(repoRoot, dir).replace(/\\/g, "/");
+        const pattern = relDir ? `${relDir}/*` : "*";
+        const isoDate = since.toISOString();
+        const out = (0, node_child_process_1.execFileSync)("git", ["-C", repoRoot, "log", `--after=${isoDate}`, "--name-only", "--format=", "--", pattern], { stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8" }).trim();
+        if (!out)
+            return [];
+        const files = out
+            .split("\n")
+            .map((f) => f.trim())
+            .filter(Boolean)
+            .filter((f) => {
+            // Only files directly in the target dir (not nested subdirs)
+            const fileDir = (0, node_path_1.dirname)(f);
+            const normRelDir = relDir || ".";
+            return fileDir === normRelDir || (normRelDir === "." && !f.includes("/"));
+        });
+        // Deduplicate
+        return [...new Set(files)];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Parse "Read before editing" section of a POLARIS.md and extract linked file paths.
+ * Looks for markdown links: [text](path)
+ */
+function parseReadBeforeEditingLinks(content) {
+    const links = [];
+    const sectionRe = /^##\s+Read before editing/im;
+    const nextSectionRe = /^##\s+/im;
+    const sectionMatch = sectionRe.exec(content);
+    if (!sectionMatch)
+        return links;
+    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+    const remainder = content.slice(sectionStart);
+    const nextMatch = nextSectionRe.exec(remainder);
+    const sectionText = nextMatch ? remainder.slice(0, nextMatch.index) : remainder;
+    // Match markdown links: [text](path)
+    const mdLinkRe = /\[([^\]]*)\]\(([^)]+)\)/g;
+    let m;
+    while ((m = mdLinkRe.exec(sectionText)) !== null) {
+        const href = m[2].trim();
+        // Skip external URLs
+        if (!href.startsWith("http://") && !href.startsWith("https://")) {
+            links.push(href);
+        }
+    }
+    return links;
+}
+function getRequiredDirs(repoRoot) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    // The config type may not yet have a docs key; access dynamically
+    const docsConfig = config["docs"];
+    return docsConfig?.instructionFiles?.required ?? [];
+}
+function collectDirs(dir, root, eligibilityOpts = {}, result = { eligible: [], ineligible: [] }) {
+    try {
+        for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const full = (0, node_path_1.join)(dir, entry.name);
+            const rel = (0, node_path_1.relative)(root, full).replace(/\\/g, "/");
+            // Check if directory is eligible for Smart Docs coverage
+            const eligibility = (0, smartdoc_ignore_js_1.isDirectoryEligible)(full, root, eligibilityOpts);
+            if (!eligibility.eligible) {
+                result.ineligible.push({
+                    path: rel,
+                    reason: eligibility.reason || "unknown",
+                    category: eligibility.category === "eligible" ? undefined : eligibility.category,
+                });
+                continue;
+            }
+            result.eligible.push(rel);
+            collectDirs(full, root, eligibilityOpts, result);
+        }
+    }
+    catch {
+        // ignore unreadable dirs
+    }
+    return result;
+}
+/**
+ * Validate a single directory's POLARIS.md.
+ */
+function validateDir(relDir, repoRoot, allRoutes) {
+    const absDir = (0, node_path_1.resolve)(repoRoot, relDir);
+    const polarisFile = (0, node_path_1.join)(absDir, "POLARIS.md");
+    const polarisRel = (0, node_path_1.relative)(repoRoot, polarisFile).replace(/\\/g, "/");
+    if (!(0, node_fs_1.existsSync)(polarisFile)) {
+        return {
+            dir: relDir,
+            polarisFile: null,
+            status: "MISSING",
+            findings: [{ severity: "MISSING", message: `No POLARIS.md in ${relDir || "."}` }],
+        };
+    }
+    const content = (0, node_fs_1.readFileSync)(polarisFile, "utf-8");
+    const findings = [];
+    // Signal 1: ≥3 files in directory changed since last POLARIS.md git modification
+    const lastMod = getLastGitModDate(polarisFile, repoRoot);
+    if (lastMod !== null) {
+        const changed = getFilesChangedAfter(absDir, lastMod, repoRoot);
+        const relevant = changed.filter((f) => !f.endsWith("POLARIS.md") && !f.endsWith("POLARIS.draft.md"));
+        if (relevant.length >= 3) {
+            findings.push({
+                severity: "WARN",
+                message: `${relevant.length} files changed since last POLARIS.md update`,
+            });
+        }
+    }
+    // Signal 2: broken links in "Read before editing"
+    const links = parseReadBeforeEditingLinks(content);
+    for (const link of links) {
+        const absLink = (0, node_path_1.resolve)(absDir, link);
+        if (!(0, node_fs_1.existsSync)(absLink)) {
+            findings.push({
+                severity: "ERROR",
+                message: `Broken link in "Read before editing": ${link}`,
+            });
+        }
+    }
+    // Signal 3: instructionFile pointer in atlas references a non-existent path
+    const normRelDir = relDir.replace(/\\/g, "/");
+    for (const [filePath, entry] of Object.entries(allRoutes)) {
+        const fileDir = (0, node_path_1.dirname)(filePath).replace(/\\/g, "/");
+        if (fileDir !== normRelDir && !(normRelDir === "." && !filePath.includes("/")))
+            continue;
+        if (!entry.instructionFile)
+            continue;
+        const absInstr = (0, node_path_1.resolve)(repoRoot, entry.instructionFile);
+        if (!(0, node_fs_1.existsSync)(absInstr)) {
+            findings.push({
+                severity: "ERROR",
+                message: `Atlas entry "${filePath}" has instructionFile "${entry.instructionFile}" that does not exist`,
+            });
+        }
+    }
+    // Enforce POLARIS.md role boundaries (required and forbidden sections)
+    const headingRe = /^##\s+(.+)$/gm;
+    const parsedHeadings = [];
+    let headingMatch;
+    while ((headingMatch = headingRe.exec(content)) !== null) {
+        const original = headingMatch[1].trim();
+        parsedHeadings.push({
+            normalized: original.toLowerCase(),
+            original,
+        });
+    }
+    const requiredSections = [
+        { key: "purpose", name: "Purpose" },
+        { key: "what belongs here", alternative: "files", name: "What belongs here" },
+        { key: "what does not belong here", name: "What does not belong here" },
+        { key: "editing rules", name: "Editing rules" },
+        { key: "architecture assumptions", name: "Architecture assumptions" },
+        { key: "read before editing", name: "Read before editing" },
+        { key: "related routes", name: "Related routes" },
+    ];
+    for (const section of requiredSections) {
+        const hasSection = parsedHeadings.some((h) => h.normalized === section.key || (section.alternative && h.normalized === section.alternative));
+        if (!hasSection) {
+            findings.push({
+                severity: "WARN",
+                message: `Missing required section: "${section.name}"`,
+            });
+        }
+    }
+    for (const h of parsedHeadings) {
+        if (h.normalized.includes("doctrine")) {
+            findings.push({
+                severity: "ERROR",
+                message: `POLARIS.md must not contain doctrine (found section: "## ${h.original}")`,
+            });
+        }
+        if (h.normalized.includes("spec") || h.normalized.includes("specification")) {
+            if (!h.normalized.includes("read before editing") && !h.normalized.includes("nearby doc")) {
+                findings.push({
+                    severity: "ERROR",
+                    message: `POLARIS.md must not contain architecture specs (found section: "## ${h.original}")`,
+                });
+            }
+        }
+        if (h.normalized.includes("history") ||
+            h.normalized.includes("run summary") ||
+            h.normalized.includes("run history") ||
+            h.normalized.includes("session")) {
+            findings.push({
+                severity: "ERROR",
+                message: `POLARIS.md must not contain session history or run summaries (found section: "## ${h.original}")`,
+            });
+        }
+    }
+    // Signal 5: SUMMARY.md presence
+    const summaryFile = (0, node_path_1.join)(absDir, "SUMMARY.md");
+    if (!(0, node_fs_1.existsSync)(summaryFile)) {
+        // Only warn if the directory has >= 5 files in the atlas
+        const atlasFiles = Object.keys(allRoutes).filter((filePath) => {
+            const fileDir = (0, node_path_1.dirname)(filePath).replace(/\\/g, "/");
+            return fileDir === normRelDir || (normRelDir === "." && !filePath.includes("/"));
+        });
+        if (atlasFiles.length >= 5) {
+            findings.push({
+                severity: "WARN",
+                message: `Missing SUMMARY.md in ${relDir || "."}`,
+            });
+        }
+    }
+    else {
+        // Signal 6: SUMMARY.md doctrine-bleed scan
+        const summaryContent = (0, node_fs_1.readFileSync)(summaryFile, "utf-8");
+        const modalVerbs = ["must", "never", "always"];
+        const lines = summaryContent.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].toLowerCase();
+            for (const verb of modalVerbs) {
+                if (new RegExp(`\\b${verb}\\b`, 'i').test(line)) {
+                    findings.push({
+                        severity: "ERROR",
+                        message: `SUMMARY.md doctrine bleed risk: found "${verb}" on line ${i + 1}`,
+                    });
+                }
+            }
+        }
+    }
+    if (findings.length === 0) {
+        return { dir: relDir, polarisFile: polarisRel, status: "OK", findings: [] };
+    }
+    const hasError = findings.some((f) => f.severity === "ERROR");
+    return {
+        dir: relDir,
+        polarisFile: polarisRel,
+        status: hasError ? "ERROR" : "WARN",
+        findings,
+    };
+}
+function validateInstructions(opts = {}) {
+    const repoRoot = opts.repoRoot ?? process.cwd();
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const atlasPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const allRoutes = {
+        ...(0, atlas_js_1.readFileRoutes)(atlasPath),
+        ...(0, atlas_js_1.readNeedsReview)(atlasPath),
+    };
+    const requiredDirs = getRequiredDirs(repoRoot);
+    let dirsToCheck;
+    if (opts.path) {
+        const absPath = (0, node_path_1.resolve)(repoRoot, opts.path);
+        const relPath = (0, node_path_1.relative)(repoRoot, absPath).replace(/\\/g, "/");
+        // Path traversal check
+        if (relPath.startsWith("..") || relPath.startsWith("/")) {
+            throw new Error(`Path traversal detected: path is outside repo root: ${opts.path}`);
+        }
+        dirsToCheck = [relPath];
+    }
+    else {
+        // Include root dir and all eligible subdirs
+        // Note: for validation, we include root and use default eligibility (skip agent folders, etc.)
+        const { eligible: dirs } = collectDirs(repoRoot, repoRoot, {
+            includeAgentFolders: false,
+            includeHidden: false,
+            skipRoot: true,
+        });
+        dirsToCheck = [".", ...dirs];
+    }
+    const results = [];
+    for (const relDir of dirsToCheck) {
+        const result = validateDir(relDir, repoRoot, allRoutes);
+        // Upgrade MISSING → ERROR for required dirs
+        if (result.status === "MISSING" && requiredDirs.includes(relDir)) {
+            result.status = "ERROR";
+        }
+        results.push(result);
+    }
+    if (opts.fix) {
+        for (const result of results) {
+            if (result.status !== "OK") {
+                const absDir = (0, node_path_1.resolve)(repoRoot, result.dir);
+                const draftPath = (0, node_path_1.join)(absDir, "POLARIS.draft.md");
+                // Path traversal check for draft path
+                const relDraft = (0, node_path_1.relative)(repoRoot, draftPath);
+                if (relDraft.startsWith("..") || relDraft.startsWith("/")) {
+                    result.findings.push({
+                        severity: "ERROR",
+                        message: "Cannot write draft: path traversal detected",
+                    });
+                    continue;
+                }
+                // Don't clobber existing drafts in fix mode
+                if ((0, node_fs_1.existsSync)(draftPath)) {
+                    result.findings.push({
+                        severity: "WARN",
+                        message: "Draft already exists at POLARIS.draft.md; skipping write",
+                    });
+                    continue;
+                }
+                const content = (0, seed_instructions_js_1.generateDraft)(result.dir, repoRoot, allRoutes);
+                (0, node_fs_1.writeFileSync)(draftPath, content, "utf-8");
+                result.findings.push({
+                    severity: "WARN",
+                    message: "Draft written to POLARIS.draft.md",
+                });
+            }
+        }
+    }
+    const hasErrors = results.some((r) => r.status === "ERROR");
+    return { results, hasErrors };
+}
+const DRAFT_WRITTEN_MSG = "Draft written to POLARIS.draft.md";
+function printReport(report) {
+    console.log("POLARIS.md validation report:");
+    for (const result of report.results) {
+        const label = result.polarisFile ?? `${result.dir || "."}/`;
+        const statusPad = result.status.padEnd(7);
+        console.log(`  ${label.padEnd(40)} ${statusPad}`);
+        for (const finding of result.findings) {
+            if (finding.message === DRAFT_WRITTEN_MSG)
+                continue;
+            const prefix = finding.severity === "ERROR" ? "ERROR:" : "WARN: ";
+            console.log(`    ${prefix} ${finding.message}`);
+        }
+        const draftFinding = result.findings.find((f) => f.message === DRAFT_WRITTEN_MSG);
+        if (draftFinding) {
+            console.log(`    → Draft written to POLARIS.draft.md`);
+        }
+    }
+}

package/dist/smartdocs-engine/validate-instructions.test.js

@@ -0,0 +1,283 @@
+"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 validate_instructions_js_1 = require("./validate-instructions.js");
+const TMP = (0, node_path_1.join)(process.cwd(), ".test-validate-instructions-tmp");
+function makeEntry(overrides = {}) {
+    return {
+        domain: "test-domain",
+        route: "test-route",
+        taskchain: "test-chain",
+        confidence: 0.9,
+        classification: "indexed",
+        last_updated: "2026-01-01T00:00:00Z",
+        updated_by: "test",
+        tags: [],
+        ...overrides,
+    };
+}
+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, ".polaris/map"), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "polaris.config.json"), JSON.stringify({ repo: {}, map: {} }));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/file-routes.json"), JSON.stringify({}));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, ".polaris/map/needs-review.json"), JSON.stringify({}));
+}
+function teardown() {
+    (0, node_fs_1.rmSync)(TMP, { recursive: true, force: true });
+}
+// ---------------------------------------------------------------------------
+// parseReadBeforeEditingLinks
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("parseReadBeforeEditingLinks", () => {
+    (0, vitest_1.it)("returns empty array when no section present", () => {
+        const content = "# Title\n\n## Purpose\nsome text";
+        (0, vitest_1.expect)((0, validate_instructions_js_1.parseReadBeforeEditingLinks)(content)).toEqual([]);
+    });
+    (0, vitest_1.it)("extracts local markdown links from section", () => {
+        const content = [
+            "# Title",
+            "",
+            "## Read before editing",
+            "",
+            "- [Design spec](../docs/spec.md)",
+            "- [Atlas](../map/atlas.ts)",
+            "",
+            "## Other section",
+        ].join("\n");
+        const links = (0, validate_instructions_js_1.parseReadBeforeEditingLinks)(content);
+        (0, vitest_1.expect)(links).toContain("../docs/spec.md");
+        (0, vitest_1.expect)(links).toContain("../map/atlas.ts");
+    });
+    (0, vitest_1.it)("ignores external URLs", () => {
+        const content = [
+            "## Read before editing",
+            "",
+            "- [External](https://example.com/doc)",
+            "- [Local](./local.md)",
+        ].join("\n");
+        const links = (0, validate_instructions_js_1.parseReadBeforeEditingLinks)(content);
+        (0, vitest_1.expect)(links).not.toContain("https://example.com/doc");
+        (0, vitest_1.expect)(links).toContain("./local.md");
+    });
+    (0, vitest_1.it)("does not bleed into next section", () => {
+        const content = [
+            "## Read before editing",
+            "",
+            "- [Good](./good.md)",
+            "",
+            "## Related routes",
+            "",
+            "- [Other](./other.md)",
+        ].join("\n");
+        const links = (0, validate_instructions_js_1.parseReadBeforeEditingLinks)(content);
+        (0, vitest_1.expect)(links).toContain("./good.md");
+        (0, vitest_1.expect)(links).not.toContain("./other.md");
+    });
+});
+// ---------------------------------------------------------------------------
+// validateDir — MISSING
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("validateDir - MISSING", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("returns MISSING when no POLARIS.md exists", () => {
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, {});
+        (0, vitest_1.expect)(result.status).toBe("MISSING");
+        (0, vitest_1.expect)(result.polarisFile).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// validateDir — OK
+// ---------------------------------------------------------------------------
+function validPolarisContent(extra) {
+    return [
+        "# map",
+        "",
+        "## Purpose",
+        "Some text.",
+        "",
+        "## What belongs here",
+        "- files",
+        "",
+        "## What does not belong here",
+        "none",
+        "",
+        "## Editing rules",
+        "none",
+        "",
+        "## Architecture assumptions",
+        "none",
+        "",
+        "## Read before editing",
+        extra ?? "none",
+        "",
+        "## Related routes",
+        "none",
+    ].join("\n");
+}
+(0, vitest_1.describe)("validateDir - OK", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("returns OK for a POLARIS.md with no issues (no git history, no links, no atlas)", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), validPolarisContent());
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, {});
+        (0, vitest_1.expect)(result.status).toBe("OK");
+        (0, vitest_1.expect)(result.findings).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// validateDir — SUMMARY.md (WARN/ERROR)
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("validateDir - SUMMARY.md", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("reports WARN when SUMMARY.md is missing", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), validPolarisContent());
+        // Add 5 files to atlas to trigger Signal 5
+        const routes = {
+            "src/map/f1.ts": makeEntry(),
+            "src/map/f2.ts": makeEntry(),
+            "src/map/f3.ts": makeEntry(),
+            "src/map/f4.ts": makeEntry(),
+            "src/map/f5.ts": makeEntry(),
+        };
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, routes);
+        (0, vitest_1.expect)(result.status).toBe("WARN");
+        const warnFinding = result.findings.find((f) => f.severity === "WARN");
+        (0, vitest_1.expect)(warnFinding?.message).toContain("Missing SUMMARY.md");
+    });
+    (0, vitest_1.it)("reports OK when SUMMARY.md exists and is clean", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), validPolarisContent());
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/SUMMARY.md"), "# Summary\nNo modal verbs here.");
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, {});
+        (0, vitest_1.expect)(result.status).toBe("OK");
+    });
+    (0, vitest_1.it)("reports ERROR when SUMMARY.md has doctrine bleed (must/never/always)", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), validPolarisContent());
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/SUMMARY.md"), "# Summary\nAgents must always be polite.");
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, {});
+        (0, vitest_1.expect)(result.status).toBe("ERROR");
+        const errorFindings = result.findings.filter((f) => f.severity === "ERROR");
+        (0, vitest_1.expect)(errorFindings).toHaveLength(2); // must and always
+        (0, vitest_1.expect)(errorFindings[0]?.message).toContain("doctrine bleed risk");
+    });
+});
+// ---------------------------------------------------------------------------
+// validateDir — broken links (ERROR)
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("validateDir - broken links", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("reports ERROR for a broken link in Read before editing", () => {
+        const content = validPolarisContent("- [Missing spec](../nonexistent/spec.md)");
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), content);
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, {});
+        (0, vitest_1.expect)(result.status).toBe("ERROR");
+        const errorFinding = result.findings.find((f) => f.severity === "ERROR");
+        (0, vitest_1.expect)(errorFinding?.message).toContain("Broken link");
+        (0, vitest_1.expect)(errorFinding?.message).toContain("../nonexistent/spec.md");
+    });
+    (0, vitest_1.it)("does not report error for an existing linked file", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/atlas.ts"), "// file");
+        const content = validPolarisContent("- [Atlas](./atlas.ts)");
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), content);
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, {});
+        (0, vitest_1.expect)(result.status).toBe("OK");
+    });
+});
+// ---------------------------------------------------------------------------
+// validateDir — instructionFile pointer (ERROR)
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("validateDir - instructionFile pointer", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("reports ERROR when atlas instructionFile pointer references a non-existent file", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), validPolarisContent());
+        const routes = {
+            "src/map/atlas.ts": makeEntry({ instructionFile: "src/map/POLARIS.md" }),
+            "src/map/update.ts": makeEntry({ instructionFile: "src/map/GHOST.md" }),
+        };
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, routes);
+        (0, vitest_1.expect)(result.status).toBe("ERROR");
+        const errorFinding = result.findings.find((f) => f.severity === "ERROR");
+        (0, vitest_1.expect)(errorFinding?.message).toContain("src/map/GHOST.md");
+    });
+    (0, vitest_1.it)("does not report error when instructionFile exists", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), validPolarisContent());
+        const routes = {
+            "src/map/atlas.ts": makeEntry({ instructionFile: "src/map/POLARIS.md" }),
+        };
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, routes);
+        (0, vitest_1.expect)(result.status).toBe("OK");
+    });
+    (0, vitest_1.it)("ignores atlas entries for other directories", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), validPolarisContent());
+        const routes = {
+            "src/cli/index.ts": makeEntry({ instructionFile: "src/cli/GHOST.md" }),
+        };
+        const result = (0, validate_instructions_js_1.validateDir)("src/map", TMP, routes);
+        (0, vitest_1.expect)(result.status).toBe("OK");
+    });
+});
+// ---------------------------------------------------------------------------
+// validateInstructions — overall
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("validateInstructions", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("returns hasErrors=false when all checks pass", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), validPolarisContent());
+        const report = (0, validate_instructions_js_1.validateInstructions)({ repoRoot: TMP, path: "src/map" });
+        (0, vitest_1.expect)(report.hasErrors).toBe(false);
+    });
+    (0, vitest_1.it)("returns hasErrors=true when there is an ERROR", () => {
+        const content = validPolarisContent("- [Missing](./nonexistent.md)");
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), content);
+        const report = (0, validate_instructions_js_1.validateInstructions)({ repoRoot: TMP, path: "src/map" });
+        (0, vitest_1.expect)(report.hasErrors).toBe(true);
+    });
+    (0, vitest_1.it)("reports MISSING for a dir without POLARIS.md", () => {
+        const report = (0, validate_instructions_js_1.validateInstructions)({ repoRoot: TMP, path: "src/map" });
+        (0, vitest_1.expect)(report.results[0]?.status).toBe("MISSING");
+    });
+    (0, vitest_1.it)("--fix writes POLARIS.draft.md for MISSING dir", () => {
+        const report = (0, validate_instructions_js_1.validateInstructions)({ repoRoot: TMP, path: "src/map", fix: true });
+        const result = report.results[0];
+        (0, vitest_1.expect)(result?.status).toBe("MISSING");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.draft.md"))).toBe(true);
+        const draftFinding = result?.findings.find((f) => f.message === "Draft written to POLARIS.draft.md");
+        (0, vitest_1.expect)(draftFinding).toBeDefined();
+    });
+    (0, vitest_1.it)("--fix does not overwrite existing POLARIS.md", () => {
+        const original = "# Original\n";
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), original);
+        (0, validate_instructions_js_1.validateInstructions)({ repoRoot: TMP, path: "src/map", fix: true });
+        // POLARIS.md should be untouched — only POLARIS.draft.md is written
+        (0, vitest_1.expect)((0, node_fs_1.readFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), "utf-8")).toBe(original);
+    });
+    (0, vitest_1.it)("scopes validation to --path", () => {
+        // Only src/map checked; other dirs are irrelevant
+        const report = (0, validate_instructions_js_1.validateInstructions)({ repoRoot: TMP, path: "src/map" });
+        (0, vitest_1.expect)(report.results).toHaveLength(1);
+        (0, vitest_1.expect)(report.results[0]?.dir).toBe("src/map");
+    });
+});
+// ---------------------------------------------------------------------------
+// getLastGitModDate / getFilesChangedAfter — graceful fallback
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("getLastGitModDate", () => {
+    (0, vitest_1.it)("returns null for a non-existent path in a real repo (graceful)", () => {
+        const result = (0, validate_instructions_js_1.getLastGitModDate)("/tmp/nonexistent-file.md", "/tmp");
+        (0, vitest_1.expect)(result).toBeNull();
+    });
+});
+(0, vitest_1.describe)("getFilesChangedAfter", () => {
+    (0, vitest_1.it)("returns empty array when no files changed (graceful)", () => {
+        const futureDate = new Date(Date.now() + 1_000_000_000);
+        const result = (0, validate_instructions_js_1.getFilesChangedAfter)("/tmp", futureDate, "/tmp");
+        (0, vitest_1.expect)(result).toEqual([]);
+    });
+});