@lsctech/polaris 0.1.0

package/dist/docs/seed-instructions.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRAFT_MARKER = void 0;
+exports.hasDraftMarker = hasDraftMarker;
+exports.generateDraft = generateDraft;
+exports.seedInstructions = seedInstructions;
+exports.seedInstructionsAll = seedInstructionsAll;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const loader_js_1 = require("../config/loader.js");
+const atlas_js_1 = require("../map/atlas.js");
+exports.DRAFT_MARKER = "<!-- polaris:draft -->";
+function hasDraftMarker(filePath) {
+    try {
+        const content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+        return content.includes(exports.DRAFT_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+function collectDirs(dir, root) {
+    const dirs = [];
+    try {
+        for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules" && entry.name !== "dist") {
+                const full = (0, node_path_1.join)(dir, entry.name);
+                const rel = (0, node_path_1.relative)(root, full).replace(/\\/g, "/");
+                dirs.push(rel);
+                dirs.push(...collectDirs(full, root));
+            }
+        }
+    }
+    catch {
+        // ignore unreadable dirs
+    }
+    return dirs;
+}
+function generateDraft(targetDir, repoRoot, allRoutes) {
+    const filesInDir = Object.entries(allRoutes).filter(([filePath]) => {
+        const fileDir = (0, node_path_1.dirname)(filePath);
+        const normDir = targetDir.replace(/\\/g, "/");
+        return fileDir === normDir || (normDir === "." && !filePath.includes("/"));
+    });
+    const domains = [...new Set(filesInDir.map(([, e]) => e.domain))].filter(Boolean);
+    const routes = [...new Set(filesInDir.map(([, e]) => e.route))].filter(Boolean);
+    const taskchains = [...new Set(filesInDir.map(([, e]) => e.taskchain))].filter(Boolean);
+    // Nearby doc references: .md files in atlas whose route overlaps with this dir's routes
+    const nearbyDocs = Object.entries(allRoutes)
+        .filter(([p]) => p.endsWith(".md") || p.startsWith("docs/"))
+        .filter(([, e]) => routes.some((r) => e.route === r || e.domain === domains[0]))
+        .map(([p]) => p)
+        .slice(0, 5);
+    const dirLabel = (0, node_path_1.basename)(targetDir) || (0, node_path_1.basename)(repoRoot);
+    const lines = [
+        exports.DRAFT_MARKER,
+        `# ${dirLabel}`,
+        "",
+        "> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.",
+        "",
+        "## Purpose",
+        "",
+        "<!-- Replace with a description of what this directory does and its key responsibilities. -->",
+        "",
+    ];
+    if (domains.length > 0)
+        lines.push(`**Domain:** ${domains.join(", ")}`);
+    if (routes.length > 0)
+        lines.push(`**Route:** ${routes.join(", ")}`);
+    if (taskchains.length > 0)
+        lines.push(`**Taskchain:** ${taskchains.join(", ")}`);
+    if (domains.length + routes.length + taskchains.length > 0)
+        lines.push("");
+    if (filesInDir.length > 0) {
+        lines.push("## Files", "");
+        for (const [filePath, entry] of filesInDir) {
+            lines.push(`- \`${(0, node_path_1.basename)(filePath)}\` — ${entry.route} (${entry.domain})`);
+        }
+        lines.push("");
+    }
+    if (nearbyDocs.length > 0) {
+        lines.push("## Nearby docs", "");
+        for (const docPath of nearbyDocs) {
+            lines.push(`- \`${docPath}\``);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function seedInstructions(targetPath, repoRoot, opts = {}) {
+    const absTarget = (0, node_path_1.resolve)(repoRoot, targetPath);
+    // Path traversal check: ensure absTarget is within repoRoot
+    const relCheck = (0, node_path_1.relative)(repoRoot, absTarget);
+    if (relCheck.startsWith("..") || relCheck.startsWith("/")) {
+        throw new Error(`Path traversal detected: target path is outside repo root`);
+    }
+    const outFile = (0, node_path_1.join)(absTarget, "POLARIS.md");
+    if ((0, node_fs_1.existsSync)(outFile)) {
+        if (hasDraftMarker(outFile)) {
+            return "skipped-draft";
+        }
+        return "skipped-exists";
+    }
+    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 relTarget = (0, node_path_1.relative)(repoRoot, absTarget).replace(/\\/g, "/");
+    const content = generateDraft(relTarget, repoRoot, allRoutes);
+    if (!opts.dryRun) {
+        (0, node_fs_1.writeFileSync)(outFile, content, "utf-8");
+    }
+    return "written";
+}
+function seedInstructionsAll(repoRoot, opts = {}) {
+    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 dirs = collectDirs(repoRoot, repoRoot);
+    const written = [];
+    const skippedExists = [];
+    const skippedDraft = [];
+    for (const relDir of dirs) {
+        const absDir = (0, node_path_1.resolve)(repoRoot, relDir);
+        const outFile = (0, node_path_1.join)(absDir, "POLARIS.md");
+        if ((0, node_fs_1.existsSync)(outFile)) {
+            if (hasDraftMarker(outFile)) {
+                skippedDraft.push(relDir);
+            }
+            else {
+                skippedExists.push(relDir);
+            }
+            continue;
+        }
+        const content = generateDraft(relDir, repoRoot, allRoutes);
+        if (!opts.dryRun) {
+            (0, node_fs_1.writeFileSync)(outFile, content, "utf-8");
+        }
+        written.push(relDir);
+    }
+    return { written, skippedExists, skippedDraft };
+}

package/dist/docs/seed-instructions.test.js

@@ -0,0 +1,137 @@
+"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 seed_instructions_js_1 = require("./seed-instructions.js");
+const TMP = (0, node_path_1.join)(process.cwd(), ".test-docs-seed-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, "src/cli"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(TMP, ".polaris/map"), { recursive: true });
+    // Minimal polaris.config.json so loadConfig doesn't fail
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "polaris.config.json"), JSON.stringify({ repo: {}, map: {} }));
+    // Empty atlas files
+    (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 });
+}
+(0, vitest_1.describe)("hasDraftMarker", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("returns true when file starts with draft marker", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "POLARIS.md"), `${seed_instructions_js_1.DRAFT_MARKER}\n# title`);
+        (0, vitest_1.expect)((0, seed_instructions_js_1.hasDraftMarker)((0, node_path_1.join)(TMP, "POLARIS.md"))).toBe(true);
+    });
+    (0, vitest_1.it)("returns false when file has no draft marker", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "POLARIS.md"), "# Human-written doc");
+        (0, vitest_1.expect)((0, seed_instructions_js_1.hasDraftMarker)((0, node_path_1.join)(TMP, "POLARIS.md"))).toBe(false);
+    });
+    (0, vitest_1.it)("returns false for nonexistent file", () => {
+        (0, vitest_1.expect)((0, seed_instructions_js_1.hasDraftMarker)((0, node_path_1.join)(TMP, "nonexistent.md"))).toBe(false);
+    });
+});
+(0, vitest_1.describe)("generateDraft", () => {
+    (0, vitest_1.it)("includes draft marker at top", () => {
+        const content = (0, seed_instructions_js_1.generateDraft)("src/map", TMP, {});
+        (0, vitest_1.expect)(content.startsWith(seed_instructions_js_1.DRAFT_MARKER)).toBe(true);
+    });
+    (0, vitest_1.it)("uses directory basename as heading", () => {
+        const content = (0, seed_instructions_js_1.generateDraft)("src/map", TMP, {});
+        (0, vitest_1.expect)(content).toContain("# map");
+    });
+    (0, vitest_1.it)("includes domain and route from atlas entries in that directory", () => {
+        const routes = {
+            "src/map/atlas.ts": makeEntry({ domain: "atlas", route: "polaris-map" }),
+        };
+        const content = (0, seed_instructions_js_1.generateDraft)("src/map", TMP, routes);
+        (0, vitest_1.expect)(content).toContain("atlas");
+        (0, vitest_1.expect)(content).toContain("polaris-map");
+    });
+    (0, vitest_1.it)("lists files in the directory", () => {
+        const routes = {
+            "src/map/atlas.ts": makeEntry({ domain: "atlas", route: "polaris-map" }),
+            "src/map/update.ts": makeEntry({ domain: "atlas", route: "polaris-map" }),
+        };
+        const content = (0, seed_instructions_js_1.generateDraft)("src/map", TMP, routes);
+        (0, vitest_1.expect)(content).toContain("`atlas.ts`");
+        (0, vitest_1.expect)(content).toContain("`update.ts`");
+    });
+    (0, vitest_1.it)("does not include files from other directories", () => {
+        const routes = {
+            "src/cli/index.ts": makeEntry({ domain: "cli", route: "polaris-cli" }),
+            "src/map/atlas.ts": makeEntry({ domain: "atlas", route: "polaris-map" }),
+        };
+        const content = (0, seed_instructions_js_1.generateDraft)("src/map", TMP, routes);
+        (0, vitest_1.expect)(content).not.toContain("`index.ts`");
+    });
+});
+(0, vitest_1.describe)("seedInstructions", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("writes a POLARIS.md draft and returns written", () => {
+        const result = (0, seed_instructions_js_1.seedInstructions)("src/map", TMP);
+        (0, vitest_1.expect)(result).toBe("written");
+        const outPath = (0, node_path_1.join)(TMP, "src/map/POLARIS.md");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(outPath)).toBe(true);
+        const content = (0, node_fs_1.readFileSync)(outPath, "utf-8");
+        (0, vitest_1.expect)(content).toContain(seed_instructions_js_1.DRAFT_MARKER);
+    });
+    (0, vitest_1.it)("returns skipped-exists when human-edited POLARIS.md present", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), "# Human-edited");
+        const result = (0, seed_instructions_js_1.seedInstructions)("src/map", TMP);
+        (0, vitest_1.expect)(result).toBe("skipped-exists");
+    });
+    (0, vitest_1.it)("returns skipped-draft when draft POLARIS.md already present", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), `${seed_instructions_js_1.DRAFT_MARKER}\n# Draft`);
+        const result = (0, seed_instructions_js_1.seedInstructions)("src/map", TMP);
+        (0, vitest_1.expect)(result).toBe("skipped-draft");
+    });
+    (0, vitest_1.it)("does not write file in dry-run mode", () => {
+        const result = (0, seed_instructions_js_1.seedInstructions)("src/map", TMP, { dryRun: true });
+        (0, vitest_1.expect)(result).toBe("written");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"))).toBe(false);
+    });
+});
+(0, vitest_1.describe)("seedInstructionsAll", () => {
+    (0, vitest_1.beforeEach)(setup);
+    (0, vitest_1.afterEach)(teardown);
+    (0, vitest_1.it)("generates drafts for directories without POLARIS.md", () => {
+        const { written } = (0, seed_instructions_js_1.seedInstructionsAll)(TMP);
+        (0, vitest_1.expect)(written).toContain("src/map");
+        (0, vitest_1.expect)(written).toContain("src/cli");
+    });
+    (0, vitest_1.it)("skips directories with human-edited POLARIS.md", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), "# Human-edited");
+        const { written, skippedExists } = (0, seed_instructions_js_1.seedInstructionsAll)(TMP);
+        (0, vitest_1.expect)(skippedExists).toContain("src/map");
+        (0, vitest_1.expect)(written).not.toContain("src/map");
+    });
+    (0, vitest_1.it)("skips directories with draft POLARIS.md", () => {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(TMP, "src/map/POLARIS.md"), `${seed_instructions_js_1.DRAFT_MARKER}\n# Draft`);
+        const { skippedDraft } = (0, seed_instructions_js_1.seedInstructionsAll)(TMP);
+        (0, vitest_1.expect)(skippedDraft).toContain("src/map");
+    });
+    (0, vitest_1.it)("does not write files in dry-run mode", () => {
+        const { written } = (0, seed_instructions_js_1.seedInstructionsAll)(TMP, { dryRun: true });
+        (0, vitest_1.expect)(written.length).toBeGreaterThan(0);
+        for (const dir of written) {
+            (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(TMP, dir, "POLARIS.md"))).toBe(false);
+        }
+    });
+});

package/dist/docs/validate-instructions.js

@@ -0,0 +1,267 @@
+"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");
+/**
+ * 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) {
+    const dirs = [];
+    try {
+        for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            if (entry.isDirectory() &&
+                !entry.name.startsWith(".") &&
+                entry.name !== "node_modules" &&
+                entry.name !== "dist") {
+                const full = (0, node_path_1.join)(dir, entry.name);
+                const rel = (0, node_path_1.relative)(root, full).replace(/\\/g, "/");
+                dirs.push(rel);
+                dirs.push(...collectDirs(full, root));
+            }
+        }
+    }
+    catch {
+        // ignore unreadable dirs
+    }
+    return dirs;
+}
+/**
+ * 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`,
+            });
+        }
+    }
+    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 subdirs
+        dirsToCheck = [".", ...collectDirs(repoRoot, repoRoot)];
+    }
+    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`);
+        }
+    }
+}