@lsctech/polaris 0.1.0

package/dist/docs/ingest.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyDoc = classifyDoc;
+exports.ingestDocs = ingestDocs;
+exports.printIngestResults = printIngestResults;
+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");
+const DEFAULT_BATCH_LIMIT = 4;
+const TARGET_DIRS = {
+    "runtime-summary": "docs/runtime/summaries",
+    "run-report": "docs/runtime/run-reports",
+    "spec-raw": "docs/specs/raw",
+    "spec-active": "docs/specs/active",
+    "audit-finding": "docs/audits/findings",
+    "doctrine-candidate": "docs/doctrine/candidate",
+    architecture: "docs/architecture",
+    decision: "docs/decisions",
+    "deprecated-noise": "docs/runtime/generated",
+};
+const APPROVAL_REQUIRED = new Set(["spec-active", "architecture", "decision"]);
+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 frontMatterValue(content, key) {
+    if (!content.startsWith("---\n"))
+        return undefined;
+    const end = content.indexOf("\n---", 4);
+    if (end === -1)
+        return undefined;
+    const lines = content.slice(4, end).split(/\r?\n/);
+    const found = lines.find((line) => line.toLowerCase().startsWith(`${key.toLowerCase()}:`));
+    return found?.slice(found.indexOf(":") + 1).trim().replace(/^["']|["']$/g, "");
+}
+function classifyDoc(content, filePath = "") {
+    const lower = `${filePath}\n${content}`.toLowerCase();
+    const status = frontMatterValue(content, "status")?.toLowerCase();
+    const authority = frontMatterValue(content, "authority")?.toLowerCase();
+    if (status === "deprecated" || lower.includes("deprecated noise") || lower.includes("obsolete")) {
+        return "deprecated-noise";
+    }
+    if (lower.includes("run report") || lower.includes("run-report"))
+        return "run-report";
+    if (lower.includes("runtime summary") || lower.includes("session summary"))
+        return "runtime-summary";
+    if (lower.includes("audit finding") || lower.includes("vulnerability") || lower.includes("security audit")) {
+        return "audit-finding";
+    }
+    if (authority === "doctrine" || lower.includes("doctrine") || lower.includes("must always") || lower.includes("never silently")) {
+        return "doctrine-candidate";
+    }
+    if (lower.includes("architecture decision record") || /^#\s*adr[:\s-]/im.test(content))
+        return "decision";
+    if (authority === "architecture" || lower.includes("architecture") || lower.includes("structural design"))
+        return "architecture";
+    if (status === "active" || lower.includes("active spec"))
+        return "spec-active";
+    if (lower.includes("spec") || lower.includes("acceptance criteria") || lower.includes("implementation plan")) {
+        return "spec-raw";
+    }
+    return "spec-raw";
+}
+function ensureDocsScaffold(repoRoot) {
+    for (const dir of Object.values(TARGET_DIRS)) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.resolve)(repoRoot, dir), { recursive: true });
+    }
+    for (const dir of [
+        "docs/raw",
+        "docs/specs/implemented",
+        "docs/specs/superseded",
+        "docs/audits/raw",
+        "docs/audits/resolved",
+        "docs/doctrine/raw",
+        "docs/doctrine/active",
+        "docs/doctrine/deprecated",
+    ]) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.resolve)(repoRoot, dir), { recursive: true });
+    }
+}
+function readCurrentState(repoRoot) {
+    return readJson((0, node_path_1.resolve)(repoRoot, ".taskchain_artifacts/polaris-run/current-state.json"), {});
+}
+function telemetryPath(repoRoot, runId) {
+    if (!runId)
+        return null;
+    return (0, node_path_1.resolve)(repoRoot, ".taskchain_artifacts/polaris-run/runs", runId, "telemetry.jsonl");
+}
+function emitTelemetry(repoRoot, runId, event) {
+    const path = telemetryPath(repoRoot, runId);
+    if (!path)
+        return;
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.appendFileSync)(path, `${JSON.stringify({ ...event, run_id: runId, timestamp: new Date().toISOString() })}\n`, "utf-8");
+}
+function uniqueDestination(filePath) {
+    if (!(0, node_fs_1.existsSync)(filePath))
+        return filePath;
+    const dir = (0, node_path_1.dirname)(filePath);
+    const ext = (0, node_path_1.extname)(filePath);
+    const stem = (0, node_path_1.basename)(filePath, ext);
+    let index = 2;
+    let candidate = (0, node_path_1.join)(dir, `${stem}-${index}${ext}`);
+    while ((0, node_fs_1.existsSync)(candidate)) {
+        index += 1;
+        candidate = (0, node_path_1.join)(dir, `${stem}-${index}${ext}`);
+    }
+    return candidate;
+}
+function addCandidateFrontMatter(content, originalPath) {
+    if (content.startsWith("---\n"))
+        return content;
+    const today = new Date().toISOString().slice(0, 10);
+    return [
+        "---",
+        "status: candidate",
+        `candidate-since: ${today}`,
+        `source: ${originalPath}`,
+        "---",
+        "",
+        content,
+    ].join("\n");
+}
+function deriveLinkedArea(content, routes) {
+    const entries = Object.entries(routes);
+    const explicit = entries.find(([filePath]) => content.includes(filePath));
+    if (explicit) {
+        return { label: explicit[1].route || explicit[0], entry: explicit[1] };
+    }
+    const area = content.match(/\b(src\/[A-Za-z0-9_/-]+)/)?.[1];
+    if (area) {
+        const matched = entries.find(([filePath]) => filePath.startsWith(area));
+        if (matched)
+            return { label: matched[1].route || area, entry: matched[1] };
+        return { label: area, entry: null };
+    }
+    return { label: null, entry: null };
+}
+function updateMapEntry(repoRoot, destinationPath, linkedEntry) {
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const atlasPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const routes = (0, atlas_js_1.readFileRoutes)(atlasPath);
+    const relDestination = (0, node_path_1.relative)(repoRoot, destinationPath).replace(/\\/g, "/");
+    const now = new Date().toISOString();
+    routes[relDestination] = {
+        domain: linkedEntry?.domain ?? "docs",
+        route: linkedEntry?.route ?? (0, node_path_1.dirname)(relDestination),
+        taskchain: linkedEntry?.taskchain ?? "polaris-docs",
+        confidence: linkedEntry ? 0.85 : 0.7,
+        classification: "indexed",
+        last_updated: now,
+        updated_by: "polaris-docs-ingest",
+        tags: ["docs", "ingested"],
+        instructionFile: linkedEntry?.instructionFile,
+    };
+    (0, atlas_js_1.writeFileRoutes)(atlasPath, routes);
+    const needsReview = (0, atlas_js_1.readNeedsReview)(atlasPath);
+    const entries = { ...routes, ...needsReview };
+    const instructionCoverage = (0, atlas_js_1.computeInstructionCoverage)(entries);
+    (0, atlas_js_1.writeAtlasIndex)(atlasPath, {
+        scan_date: now,
+        file_count: Object.keys(entries).length,
+        coverage_pct: Math.round((Object.values(entries).filter((e) => e.classification === "indexed").length / Object.keys(entries).length) * 100),
+        instructionCoverage,
+        entries,
+    });
+}
+function ingestDocs(files, options) {
+    const repoRoot = (0, node_path_1.resolve)(options.repoRoot);
+    const limit = options.maxFiles ?? DEFAULT_BATCH_LIMIT;
+    if (files.length === 0)
+        throw new Error("polaris docs ingest: provide at least one file");
+    if (files.length > limit)
+        throw new Error(`polaris docs ingest: batch limit is ${limit} files`);
+    ensureDocsScaffold(repoRoot);
+    const state = readCurrentState(repoRoot);
+    const runId = state.run_id ?? null;
+    const clusterId = options.clusterId ?? state.cluster_id ?? null;
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    const atlasPath = (0, node_path_1.resolve)(repoRoot, config.repo.sidecarOutputPath ?? ".polaris/map");
+    const routes = {
+        ...(0, atlas_js_1.readFileRoutes)(atlasPath),
+        ...(0, atlas_js_1.readNeedsReview)(atlasPath),
+    };
+    emitTelemetry(repoRoot, runId, {
+        event: "docs-ingest-start",
+        file: files[0],
+        count: files.length,
+        cluster_id: clusterId,
+    });
+    const results = [];
+    for (const source of files) {
+        const absSource = (0, node_path_1.resolve)(repoRoot, source);
+        // Path traversal check: ensure absSource is within repoRoot
+        const relCheck = (0, node_path_1.relative)(repoRoot, absSource);
+        if (relCheck.startsWith("..") || relCheck.startsWith("/")) {
+            throw new Error(`polaris docs ingest: path traversal detected, file outside repo: ${source}`);
+        }
+        if (!(0, node_fs_1.existsSync)(absSource))
+            throw new Error(`polaris docs ingest: file not found: ${source}`);
+        const content = (0, node_fs_1.readFileSync)(absSource, "utf-8");
+        const relSource = (0, node_path_1.relative)(repoRoot, absSource).replace(/\\/g, "/");
+        const classification = classifyDoc(content, relSource);
+        if (APPROVAL_REQUIRED.has(classification) && !options.approveAuthority) {
+            throw new Error(`polaris docs ingest: ${classification} requires explicit approval; rerun with --approve-authority`);
+        }
+        const { label: linkedMapArea, entry: linkedEntry } = deriveLinkedArea(content, routes);
+        const targetDir = (0, node_path_1.resolve)(repoRoot, TARGET_DIRS[classification]);
+        (0, node_fs_1.mkdirSync)(targetDir, { recursive: true });
+        const destination = uniqueDestination((0, node_path_1.join)(targetDir, (0, node_path_1.basename)(absSource)));
+        const relDestination = (0, node_path_1.relative)(repoRoot, destination).replace(/\\/g, "/");
+        // Fix: only replace .md suffix if present, otherwise append .provenance.json
+        const provenancePath = /\.md$/i.test(destination)
+            ? destination.replace(/\.md$/i, ".provenance.json")
+            : `${destination}.provenance.json`;
+        emitTelemetry(repoRoot, runId, {
+            event: "docs-ingest-classified",
+            file: relSource,
+            classification,
+            destination: relDestination,
+            linked_map_area: linkedMapArea,
+            cluster_id: clusterId,
+        });
+        if (!options.dryRun) {
+            const output = classification === "doctrine-candidate" ? addCandidateFrontMatter(content, relSource) : content;
+            if (output !== content) {
+                (0, node_fs_1.writeFileSync)(absSource, output, "utf-8");
+            }
+            (0, node_fs_1.renameSync)(absSource, destination);
+            (0, node_fs_1.writeFileSync)(provenancePath, JSON.stringify({
+                currentPath: relDestination,
+                originalPath: relSource,
+                ingestedAt: new Date().toISOString(),
+                ingestRunId: runId,
+                ingestClusterId: clusterId,
+                relatedRunId: runId,
+                relatedIssue: state.cluster_id ?? null,
+                classifiedAs: classification,
+                linkedMapArea,
+                conflictsDetected: false,
+            }, null, 2) + "\n", "utf-8");
+            updateMapEntry(repoRoot, destination, linkedEntry);
+        }
+        if (classification === "doctrine-candidate") {
+            emitTelemetry(repoRoot, runId, {
+                event: "doctrine-candidate-proposed",
+                file: relDestination,
+                cluster_id: clusterId,
+            });
+        }
+        emitTelemetry(repoRoot, runId, {
+            event: "docs-ingest",
+            file: relSource,
+            classification,
+            destination: relDestination,
+            linked_map_area: linkedMapArea,
+            cluster_id: clusterId,
+        });
+        results.push({
+            sourcePath: relSource,
+            destinationPath: relDestination,
+            classification,
+            linkedMapArea,
+            runId,
+            provenancePath: options.dryRun ? null : (0, node_path_1.relative)(repoRoot, provenancePath).replace(/\\/g, "/"),
+            dryRun: Boolean(options.dryRun),
+        });
+    }
+    emitTelemetry(repoRoot, runId, {
+        event: "docs-ingest-complete",
+        file: files[files.length - 1],
+        count: files.length,
+        cluster_id: clusterId,
+    });
+    return results;
+}
+function printIngestResults(results) {
+    for (const result of results) {
+        const prefix = result.dryRun ? "[dry-run] " : "";
+        console.log(`${prefix}${result.sourcePath} -> ${result.destinationPath}`);
+        console.log(`classification: ${result.classification}`);
+        console.log(`linked_map_area: ${result.linkedMapArea ?? "none"}`);
+        console.log(`run_id: ${result.runId ?? "none"}`);
+        if (result.provenancePath)
+            console.log(`provenance: ${result.provenancePath}`);
+    }
+}

package/dist/docs/ingest.test.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_fs_2 = require("node:fs");
+const node_os_1 = require("node:os");
+const vitest_1 = require("vitest");
+const ingest_js_1 = require("./ingest.js");
+function makeRepo() {
+    const repoRoot = (0, node_fs_2.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "polaris-docs-ingest-"));
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "docs", "raw"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, ".polaris", "map"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run"), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, "polaris.config.json"), JSON.stringify({ repo: { sidecarOutputPath: ".polaris/map" } }), "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".polaris", "map", "file-routes.json"), JSON.stringify({
+        "src/docs/index.ts": {
+            domain: "docs",
+            route: "src/docs",
+            taskchain: "polaris-docs",
+            confidence: 0.95,
+            classification: "indexed",
+            last_updated: "",
+            updated_by: "",
+            tags: ["docs"],
+            instructionFile: "src/docs/POLARIS.md",
+        },
+    }), "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".polaris", "map", "needs-review.json"), "{}\n", "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json"), JSON.stringify({ run_id: "test-run-001", cluster_id: "POL-42" }), "utf-8");
+    return repoRoot;
+}
+(0, vitest_1.describe)("classifyDoc", () => {
+    (0, vitest_1.it)("classifies docs from explicit content signals", () => {
+        (0, vitest_1.expect)((0, ingest_js_1.classifyDoc)("# Runtime Summary\n\nSession summary")).toBe("runtime-summary");
+        (0, vitest_1.expect)((0, ingest_js_1.classifyDoc)("# Audit Finding\n\nSecurity audit result")).toBe("audit-finding");
+        (0, vitest_1.expect)((0, ingest_js_1.classifyDoc)("# Doctrine\n\nAgents must always preserve state")).toBe("doctrine-candidate");
+        (0, vitest_1.expect)((0, ingest_js_1.classifyDoc)("# Feature Spec\n\nAcceptance Criteria")).toBe("spec-raw");
+    });
+});
+(0, vitest_1.describe)("ingestDocs", () => {
+    (0, vitest_1.it)("moves a raw spec, writes provenance, links map area, and emits telemetry", () => {
+        const repoRoot = makeRepo();
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, "docs", "raw", "ingest-plan.md"), "# Ingest Spec\n\nAcceptance Criteria\n\nTouches src/docs/index.ts.", "utf-8");
+        const [result] = (0, ingest_js_1.ingestDocs)(["docs/raw/ingest-plan.md"], { repoRoot });
+        (0, vitest_1.expect)(result.classification).toBe("spec-raw");
+        (0, vitest_1.expect)(result.destinationPath).toBe("docs/specs/raw/ingest-plan.md");
+        (0, vitest_1.expect)(result.linkedMapArea).toBe("src/docs");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "docs", "specs", "raw", "ingest-plan.md"))).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "docs", "specs", "raw", "ingest-plan.provenance.json"))).toBe(true);
+        const telemetry = (0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "runs", "test-run-001", "telemetry.jsonl"), "utf-8");
+        (0, vitest_1.expect)(telemetry).toContain("\"event\":\"docs-ingest\"");
+    });
+    (0, vitest_1.it)("rejects batches above the bounded file limit", () => {
+        const repoRoot = makeRepo();
+        for (const name of ["a.md", "b.md", "c.md", "d.md", "e.md"]) {
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, "docs", "raw", name), "# Spec\n\nAcceptance Criteria", "utf-8");
+        }
+        (0, vitest_1.expect)(() => (0, ingest_js_1.ingestDocs)([
+            "docs/raw/a.md",
+            "docs/raw/b.md",
+            "docs/raw/c.md",
+            "docs/raw/d.md",
+            "docs/raw/e.md",
+        ], { repoRoot })).toThrow("batch limit is 4 files");
+    });
+    (0, vitest_1.it)("does not promote high-authority architecture docs without approval", () => {
+        const repoRoot = makeRepo();
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, "docs", "raw", "architecture.md"), "# Architecture\n\nStructural design", "utf-8");
+        (0, vitest_1.expect)(() => (0, ingest_js_1.ingestDocs)(["docs/raw/architecture.md"], { repoRoot })).toThrow("requires explicit approval");
+    });
+});

package/dist/docs/migrate.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAllowedException = isAllowedException;
+exports.migrateDocs = migrateDocs;
+exports.printMigrateResults = printMigrateResults;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Basenames that are always allowed regardless of location. */
+const ALLOWED_BASENAMES = new Set(["README.md", "POLARIS.md", "CHANGELOG.md", "LICENSE.md"]);
+/**
+ * Directory prefixes (relative to repo root, forward-slash notation) where
+ * markdown files may live without being migrated.
+ */
+const ALLOWED_DIR_PREFIXES = [
+    "docs/",
+    ".agents/",
+    ".codex/",
+    ".claude/",
+    ".taskchain_artifacts/",
+];
+function isAllowedException(relPath) {
+    const name = (0, node_path_1.basename)(relPath);
+    if (ALLOWED_BASENAMES.has(name)) {
+        return { allowed: true, reason: `allowed basename: ${name}` };
+    }
+    for (const prefix of ALLOWED_DIR_PREFIXES) {
+        if (relPath.startsWith(prefix)) {
+            return { allowed: true, reason: `in allowed directory: ${prefix}` };
+        }
+    }
+    return { allowed: false };
+}
+function findMarkdownFiles(repoRoot) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["ls-files", "--cached", "--others", "--exclude-standard", "*.md"], { cwd: repoRoot, encoding: "utf-8" });
+        return output
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0 && l.endsWith(".md"));
+    }
+    catch {
+        // Fallback if not a git repo: use find
+        const output = (0, node_child_process_1.execFileSync)("find", [".", "-name", "*.md", "-not", "-path", "./.git/*"], { cwd: repoRoot, encoding: "utf-8" });
+        return output
+            .split("\n")
+            .map((l) => l.trim().replace(/^\.\//, ""))
+            .filter((l) => l.length > 0 && l.endsWith(".md"));
+    }
+}
+function uniqueDestination(filePath) {
+    if (!(0, node_fs_1.existsSync)(filePath))
+        return filePath;
+    const dir = (0, node_path_1.dirname)(filePath);
+    const name = (0, node_path_1.basename)(filePath, ".md");
+    let index = 2;
+    let candidate = (0, node_path_1.join)(dir, `${name}-${index}.md`);
+    while ((0, node_fs_1.existsSync)(candidate)) {
+        index += 1;
+        candidate = (0, node_path_1.join)(dir, `${name}-${index}.md`);
+    }
+    return candidate;
+}
+function makeMigrationRunId() {
+    const date = new Date().toISOString().slice(0, 10);
+    const seq = String(Date.now()).slice(-4);
+    return `polaris-docs-migrate-${date}-${seq}`;
+}
+function batchFiles(files, batchSize = 4) {
+    const batches = [];
+    for (let i = 0; i < files.length; i += batchSize) {
+        batches.push(files.slice(i, i + batchSize));
+    }
+    return batches;
+}
+function migrateDocs(options) {
+    const repoRoot = (0, node_path_1.resolve)(options.repoRoot);
+    const migrationRunId = options.migrationRunId ?? makeMigrationRunId();
+    const rawDir = (0, node_path_1.resolve)(repoRoot, "docs/raw");
+    const allMd = findMarkdownFiles(repoRoot);
+    const results = [];
+    const toMigrate = [];
+    for (const relPath of allMd) {
+        const check = isAllowedException(relPath);
+        if (check.allowed) {
+            results.push({
+                originalPath: relPath,
+                currentPath: relPath,
+                classification: "allowed-exception",
+                exceptionReason: check.reason,
+            });
+        }
+        else {
+            toMigrate.push(relPath);
+        }
+    }
+    if (!options.dryRun && toMigrate.length > 0) {
+        (0, node_fs_1.mkdirSync)(rawDir, { recursive: true });
+    }
+    const provenanceRecords = [];
+    for (const relPath of toMigrate) {
+        const absSource = (0, node_path_1.resolve)(repoRoot, relPath);
+        const destFile = uniqueDestination((0, node_path_1.join)(rawDir, (0, node_path_1.basename)(relPath)));
+        const relDest = (0, node_path_1.relative)(repoRoot, destFile).replace(/\\/g, "/");
+        if (!options.dryRun) {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(destFile), { recursive: true });
+            (0, node_fs_1.renameSync)(absSource, destFile);
+            provenanceRecords.push({
+                originalPath: relPath,
+                currentPath: relDest,
+                migratedAt: new Date().toISOString(),
+                migrationRunId,
+            });
+        }
+        results.push({
+            originalPath: relPath,
+            currentPath: options.dryRun ? relPath : relDest,
+            classification: "migrated",
+            destination: relDest,
+        });
+    }
+    let provenancePath = null;
+    if (!options.dryRun && provenanceRecords.length > 0) {
+        const provDir = (0, node_path_1.resolve)(repoRoot, ".taskchain_artifacts", "polaris-docs-migrate", migrationRunId);
+        (0, node_fs_1.mkdirSync)(provDir, { recursive: true });
+        const absProvPath = (0, node_path_1.join)(provDir, "provenance.json");
+        (0, node_fs_1.writeFileSync)(absProvPath, JSON.stringify(provenanceRecords, null, 2) + "\n", "utf-8");
+        provenancePath = (0, node_path_1.relative)(repoRoot, absProvPath).replace(/\\/g, "/");
+    }
+    // Build ingest batch paths: where files will land in docs/raw/
+    const migratedDestPaths = results
+        .filter((r) => r.classification === "migrated")
+        .map((r) => r.destination ?? `docs/raw/${(0, node_path_1.basename)(r.originalPath)}`);
+    const ingestBatches = batchFiles(migratedDestPaths, 4);
+    return { results, migrationRunId, provenancePath, ingestBatches, dryRun: Boolean(options.dryRun) };
+}
+function printMigrateResults(result) {
+    const prefix = result.dryRun ? "[dry-run] " : "";
+    const migrated = result.results.filter((r) => r.classification === "migrated");
+    const exceptions = result.results.filter((r) => r.classification === "allowed-exception");
+    console.log(`\n${prefix}Migration run: ${result.migrationRunId}`);
+    console.log(`${prefix}Files to migrate: ${migrated.length}`);
+    for (const r of migrated) {
+        const dest = r.destination ?? `docs/raw/${(0, node_path_1.basename)(r.originalPath)}`;
+        console.log(`  ${r.originalPath} -> ${dest}`);
+    }
+    if (exceptions.length > 0) {
+        console.log(`\n${prefix}Allowed exceptions (not moved): ${exceptions.length}`);
+        for (const r of exceptions) {
+            console.log(`  ${r.originalPath}  [${r.exceptionReason}]`);
+        }
+    }
+    if (result.ingestBatches.length > 0) {
+        console.log(`\n${prefix}Ingest cluster batches (${result.ingestBatches.length} batch${result.ingestBatches.length === 1 ? "" : "es"}):`);
+        result.ingestBatches.forEach((batch, i) => {
+            console.log(`  Batch ${i + 1}:`);
+            for (const f of batch) {
+                console.log(`    polaris docs ingest --file ${f}`);
+            }
+        });
+    }
+    if (result.provenancePath) {
+        console.log(`\nProvenance written to: ${result.provenancePath}`);
+    }
+}

package/dist/docs/migrate.test.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_fs_2 = require("node:fs");
+const node_os_1 = require("node:os");
+const vitest_1 = require("vitest");
+const migrate_js_1 = require("./migrate.js");
+// ---------------------------------------------------------------------------
+// isAllowedException
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("isAllowedException", () => {
+    (0, vitest_1.it)("allows README.md in any directory", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("README.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/README.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("some/deep/path/README.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("allows POLARIS.md in any directory", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("POLARIS.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/cli/POLARIS.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("allows CHANGELOG.md and LICENSE.md", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("CHANGELOG.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("LICENSE.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("allows anything under docs/", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("docs/spec/foo.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("docs/raw/bar.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("allows anything under .agents/, .codex/, .claude/, .taskchain_artifacts/", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".agents/instructions.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".codex/skills/foo/SKILL.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".claude/CLAUDE.md").allowed).toBe(true);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)(".taskchain_artifacts/run/notes.md").allowed).toBe(true);
+    });
+    (0, vitest_1.it)("does NOT allow arbitrary markdown files", () => {
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("src/some-feature/NOTES.md").allowed).toBe(false);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("planning/ideas.md").allowed).toBe(false);
+        (0, vitest_1.expect)((0, migrate_js_1.isAllowedException)("scratch.md").allowed).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// migrateDocs — dry-run
+// ---------------------------------------------------------------------------
+function makeGitRepo() {
+    const repoRoot = (0, node_fs_2.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "polaris-migrate-"));
+    (0, node_child_process_1.execFileSync)("git", ["init"], { cwd: repoRoot });
+    (0, node_child_process_1.execFileSync)("git", ["config", "user.email", "test@test.com"], { cwd: repoRoot });
+    (0, node_child_process_1.execFileSync)("git", ["config", "user.name", "Test"], { cwd: repoRoot });
+    return repoRoot;
+}
+function addTrackedFile(repoRoot, relPath, content = "# Doc\n\nContent") {
+    const absPath = (0, node_path_1.join)(repoRoot, relPath);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, relPath.split("/").slice(0, -1).join("/")), { recursive: true });
+    (0, node_fs_1.writeFileSync)(absPath, content, "utf-8");
+    (0, node_child_process_1.execFileSync)("git", ["add", relPath], { cwd: repoRoot });
+}
+(0, vitest_1.describe)("migrateDocs --dry-run", () => {
+    let repoRoot;
+    (0, vitest_1.beforeEach)(() => {
+        repoRoot = makeGitRepo();
+    });
+    (0, vitest_1.it)("reports files to migrate and allowed exceptions, does not move files", () => {
+        addTrackedFile(repoRoot, "README.md");
+        addTrackedFile(repoRoot, "planning/ideas.md");
+        addTrackedFile(repoRoot, "docs/spec/existing.md");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: true, migrationRunId: "test-migrate-001" });
+        (0, vitest_1.expect)(result.dryRun).toBe(true);
+        (0, vitest_1.expect)(result.migrationRunId).toBe("test-migrate-001");
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        const exceptions = result.results.filter((r) => r.classification === "allowed-exception");
+        (0, vitest_1.expect)(migrated).toHaveLength(1);
+        (0, vitest_1.expect)(migrated[0].originalPath).toBe("planning/ideas.md");
+        (0, vitest_1.expect)(migrated[0].destination).toBe("docs/raw/ideas.md");
+        (0, vitest_1.expect)(exceptions.length).toBeGreaterThanOrEqual(2);
+        // File must NOT have been moved
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "planning/ideas.md"))).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "docs/raw/ideas.md"))).toBe(false);
+        // No provenance written in dry-run
+        (0, vitest_1.expect)(result.provenancePath).toBeNull();
+    });
+    (0, vitest_1.it)("produces ingest batches of at most 4 files", () => {
+        for (let i = 0; i < 9; i++) {
+            addTrackedFile(repoRoot, `planning/doc${i}.md`);
+        }
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: true, migrationRunId: "test-migrate-002" });
+        const allBatched = result.ingestBatches.flat();
+        (0, vitest_1.expect)(allBatched).toHaveLength(9);
+        for (const batch of result.ingestBatches) {
+            (0, vitest_1.expect)(batch.length).toBeLessThanOrEqual(4);
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// migrateDocs — actual migration
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)("migrateDocs (live)", () => {
+    let repoRoot;
+    (0, vitest_1.beforeEach)(() => {
+        repoRoot = makeGitRepo();
+    });
+    (0, vitest_1.it)("moves files to docs/raw/, writes provenance JSON", () => {
+        addTrackedFile(repoRoot, "README.md");
+        addTrackedFile(repoRoot, "scratch/notes.md", "# Notes");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: false, migrationRunId: "test-migrate-live-001" });
+        (0, vitest_1.expect)(result.dryRun).toBe(false);
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        (0, vitest_1.expect)(migrated).toHaveLength(1);
+        (0, vitest_1.expect)(migrated[0].originalPath).toBe("scratch/notes.md");
+        (0, vitest_1.expect)(migrated[0].currentPath).toBe("docs/raw/notes.md");
+        // File should now exist in docs/raw/
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "docs/raw/notes.md"))).toBe(true);
+        // File should no longer exist at original location
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "scratch/notes.md"))).toBe(false);
+        // Provenance written
+        (0, vitest_1.expect)(result.provenancePath).not.toBeNull();
+        const provContent = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, result.provenancePath), "utf-8"));
+        (0, vitest_1.expect)(provContent).toHaveLength(1);
+        (0, vitest_1.expect)(provContent[0].originalPath).toBe("scratch/notes.md");
+        (0, vitest_1.expect)(provContent[0].currentPath).toBe("docs/raw/notes.md");
+        (0, vitest_1.expect)(provContent[0].migrationRunId).toBe("test-migrate-live-001");
+        (0, vitest_1.expect)(provContent[0].migratedAt).toBeTruthy();
+    });
+    (0, vitest_1.it)("handles filename collisions by uniquifying destination", () => {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "docs/raw"), { recursive: true });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, "docs/raw/notes.md"), "# Existing", "utf-8");
+        (0, node_child_process_1.execFileSync)("git", ["add", "docs/raw/notes.md"], { cwd: repoRoot });
+        addTrackedFile(repoRoot, "scratch/notes.md", "# Incoming");
+        const result = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun: false, migrationRunId: "test-migrate-live-002" });
+        const migrated = result.results.filter((r) => r.classification === "migrated");
+        (0, vitest_1.expect)(migrated).toHaveLength(1);
+        (0, vitest_1.expect)(migrated[0].currentPath).toBe("docs/raw/notes-2.md");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "docs/raw/notes-2.md"))).toBe(true);
+    });
+});