@lsctech/polaris 0.1.0

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

@@ -0,0 +1,238 @@
+"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
+// ---------------------------------------------------------------------------
+(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"), "# map\n\n## Purpose\nSome text.\n");
+        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 — 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 = [
+            "# map",
+            "",
+            "## Read before editing",
+            "",
+            "- [Missing spec](../nonexistent/spec.md)",
+        ].join("\n");
+        (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 = [
+            "# map",
+            "",
+            "## Read before editing",
+            "",
+            "- [Atlas](./atlas.ts)",
+        ].join("\n");
+        (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"), "# map\n\n## Purpose\nText.\n");
+        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"), "# map\n\n## Purpose\nText.\n");
+        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"), "# map\n\n## Purpose\nText.\n");
+        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"), "# map\n\n## Purpose\nText.\n");
+        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 = [
+            "# map",
+            "",
+            "## Read before editing",
+            "",
+            "- [Missing](./nonexistent.md)",
+        ].join("\n");
+        (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([]);
+    });
+});

package/dist/finalize/artifact-policy.js

@@ -0,0 +1,214 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyArtifactPath = classifyArtifactPath;
+exports.isPromotedArtifactPath = isPromotedArtifactPath;
+exports.explainArtifactPolicy = explainArtifactPolicy;
+exports.findArtifactPromotionViolations = findArtifactPromotionViolations;
+exports.getArtifactPromotionPolicy = getArtifactPromotionPolicy;
+exports.getArtifactPromotionStageTargets = getArtifactPromotionStageTargets;
+exports.getGitignorePatterns = getGitignorePatterns;
+exports.formatGitignoreBlock = formatGitignoreBlock;
+exports.isPathBlockedFromStaging = isPathBlockedFromStaging;
+exports.filterStageablePaths = filterStageablePaths;
+const node_path_1 = __importDefault(require("node:path"));
+const PROMOTED_RUN_LEDGER = ".polaris/runs/ledger.jsonl";
+const PROMOTED_COGNITION_ARCHIVE_PREFIX = ".polaris/cognition/archive/";
+const PROMOTED_MAP_PREFIX = ".polaris/map/";
+const WORKSPACE_SCRATCH_PREFIX = ".taskchain_artifacts/";
+const LEGACY_RUN_ARTIFACTS = new Set([
+    ".polaris/runs/mutation-queue.json",
+    ".polaris/runs/current-state.pre-pol-198.json",
+]);
+function normalizeArtifactPath(filePath) {
+    const normalized = node_path_1.default.posix.normalize(filePath.replace(/\\/g, "/"));
+    return normalized.startsWith("./") ? normalized.slice(2) : normalized;
+}
+function getActiveClusterPrefix(activeClusterId) {
+    return `.polaris/clusters/${activeClusterId}/`;
+}
+function isPromotedClusterArtifact(relativePath, activeClusterId) {
+    const activeClusterPrefix = getActiveClusterPrefix(activeClusterId);
+    if (!relativePath.startsWith(activeClusterPrefix)) {
+        return false;
+    }
+    const suffix = relativePath.slice(activeClusterPrefix.length);
+    return (suffix === "clusters.json"
+        || suffix === "cluster-state.json"
+        || suffix.startsWith("packets/")
+        || suffix.startsWith("results/"));
+}
+function classifyArtifactPath(filePath, activeClusterId) {
+    const relativePath = normalizeArtifactPath(filePath);
+    if (relativePath.endsWith(".bak")) {
+        return "workspace-scratch";
+    }
+    if (!relativePath.startsWith(".polaris/") && !relativePath.startsWith(WORKSPACE_SCRATCH_PREFIX)) {
+        return "non-artifact";
+    }
+    if (relativePath.startsWith(WORKSPACE_SCRATCH_PREFIX)) {
+        return "workspace-scratch";
+    }
+    if (LEGACY_RUN_ARTIFACTS.has(relativePath) || relativePath.startsWith(".polaris/runs/evo-run-archive/")) {
+        return "legacy-run-artifact";
+    }
+    if (relativePath === PROMOTED_RUN_LEDGER) {
+        return "promoted-run-ledger";
+    }
+    if (relativePath.startsWith(PROMOTED_COGNITION_ARCHIVE_PREFIX)) {
+        return "promoted-cognition-archive";
+    }
+    if (relativePath.startsWith(PROMOTED_MAP_PREFIX)) {
+        return "promoted-map-artifact";
+    }
+    if (isPromotedClusterArtifact(relativePath, activeClusterId)) {
+        return "promoted-cluster-artifact";
+    }
+    if (relativePath.startsWith(".polaris/clusters/")) {
+        return "foreign-cluster-artifact";
+    }
+    if (relativePath.startsWith(".polaris/runs/")) {
+        return "legacy-run-artifact";
+    }
+    return "non-artifact";
+}
+function isPromotedArtifactPath(filePath, activeClusterId) {
+    const classification = classifyArtifactPath(filePath, activeClusterId);
+    return (classification === "promoted-cluster-artifact"
+        || classification === "promoted-run-ledger"
+        || classification === "promoted-cognition-archive"
+        || classification === "promoted-map-artifact");
+}
+function explainArtifactPolicy(filePath, activeClusterId) {
+    const relativePath = normalizeArtifactPath(filePath);
+    const classification = classifyArtifactPath(relativePath, activeClusterId);
+    switch (classification) {
+        case "promoted-cluster-artifact":
+            return "active cluster evidence is eligible for promotion into finalize commits";
+        case "promoted-run-ledger":
+            return "the run ledger is durable audit evidence and stays commit-eligible";
+        case "promoted-cognition-archive":
+            return "archived cognition reconciliation notes are durable provenance and stay commit-eligible";
+        case "promoted-map-artifact":
+            return "atlas outputs under .polaris/map/ are durable derived artifacts";
+        case "workspace-scratch":
+            return "workspace scratch under .taskchain_artifacts/ and backup files must never be promoted into delivery commits";
+        case "foreign-cluster-artifact":
+            return "only the active cluster's durable evidence may be promoted during finalize";
+        case "legacy-run-artifact":
+            return "legacy or workspace-run artifacts under .polaris/runs/ stay out of delivery commits unless explicitly promoted by newer policy";
+        case "non-artifact":
+        default:
+            return "this path is not a Polaris-managed artifact and should be evaluated by the normal source/document review flow";
+    }
+}
+function findArtifactPromotionViolations(stagedPaths, activeClusterId) {
+    const violations = [];
+    for (const stagedPath of stagedPaths) {
+        const relativePath = normalizeArtifactPath(stagedPath);
+        const classification = classifyArtifactPath(relativePath, activeClusterId);
+        if (classification === "non-artifact"
+            || classification === "promoted-cluster-artifact"
+            || classification === "promoted-run-ledger"
+            || classification === "promoted-cognition-archive"
+            || classification === "promoted-map-artifact") {
+            continue;
+        }
+        violations.push({
+            path: relativePath,
+            classification,
+            message: explainArtifactPolicy(relativePath, activeClusterId),
+        });
+    }
+    return violations;
+}
+function getArtifactPromotionPolicy(activeClusterId) {
+    const activeClusterPrefix = getActiveClusterPrefix(activeClusterId);
+    return {
+        promoted: [
+            `${activeClusterPrefix}clusters.json`,
+            `${activeClusterPrefix}cluster-state.json`,
+            `${activeClusterPrefix}packets/**`,
+            `${activeClusterPrefix}results/**`,
+            PROMOTED_RUN_LEDGER,
+            `${PROMOTED_COGNITION_ARCHIVE_PREFIX}**`,
+            `${PROMOTED_MAP_PREFIX}**`,
+        ],
+        blocked: [
+            `${WORKSPACE_SCRATCH_PREFIX}**`,
+            "*.bak",
+            ".polaris/runs/mutation-queue.json",
+            ".polaris/runs/current-state.pre-pol-198.json",
+            ".polaris/runs/evo-run-archive/**",
+            ".polaris/clusters/<other-cluster>/**",
+        ],
+    };
+}
+function getArtifactPromotionStageTargets(activeClusterId) {
+    return getArtifactPromotionPolicy(activeClusterId).promoted.map((pattern) => (pattern.endsWith("/**") ? pattern.slice(0, -3) : pattern));
+}
+/**
+ * Returns gitignore patterns for runtime and crash-recovery artifact classes.
+ * These patterns should be added to .gitignore to prevent accidental staging.
+ */
+function getGitignorePatterns() {
+    return [
+        "# Polaris workspace scratch — never commit",
+        ".taskchain_artifacts/**",
+        "*.bak",
+        ".polaris/runs/mutation-queue.json",
+        ".polaris/runs/current-state.pre-pol-198.json",
+        ".polaris/runs/evo-run-archive/**",
+        ".polaris/bootstrap/**",
+        ".polaris/session-type",
+        "# Cognition staging — ephemeral, not committed",
+        ".polaris/cognition/pending/**",
+    ];
+}
+/**
+ * Formats gitignore patterns as a block suitable for appending to .gitignore.
+ */
+function formatGitignoreBlock() {
+    return getGitignorePatterns().join("\n");
+}
+/**
+ * Returns true if the given path should be blocked from staging by adoption.
+ * This is a stricter check than promotion violations — it blocks all runtime/crash-recovery
+ * classes, not just violations during finalize.
+ */
+function isPathBlockedFromStaging(filePath) {
+    const relativePath = normalizeArtifactPath(filePath);
+    // Block workspace scratch
+    if (relativePath.startsWith(WORKSPACE_SCRATCH_PREFIX)) {
+        return true;
+    }
+    // Block backup files
+    if (relativePath.endsWith(".bak")) {
+        return true;
+    }
+    // Block legacy run artifacts
+    if (LEGACY_RUN_ARTIFACTS.has(relativePath) || relativePath.startsWith(".polaris/runs/evo-run-archive/")) {
+        return true;
+    }
+    // Block runtime crash-recovery artifacts
+    if (relativePath === ".polaris/runs/mutation-queue.json" ||
+        relativePath === ".polaris/runs/current-state.pre-pol-198.json" ||
+        relativePath.startsWith(".polaris/bootstrap/") ||
+        relativePath === ".polaris/session-type") {
+        return true;
+    }
+    // Block cognition pending staging
+    if (relativePath.startsWith(".polaris/cognition/pending/")) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Filters a list of paths to return only those that are safe to stage.
+ * This is used by adoption to ensure runtime artifacts are not staged.
+ */
+function filterStageablePaths(paths) {
+    return paths.filter((path) => !isPathBlockedFromStaging(path));
+}

package/dist/finalize/artifact-policy.test.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const artifact_policy_js_1 = require("./artifact-policy.js");
+(0, vitest_1.describe)("artifact promotion policy", () => {
+    (0, vitest_1.it)("promotes only durable evidence for the active cluster", () => {
+        (0, vitest_1.expect)((0, artifact_policy_js_1.isPromotedArtifactPath)(".polaris/clusters/POL-242/clusters.json", "POL-242")).toBe(true);
+        (0, vitest_1.expect)((0, artifact_policy_js_1.isPromotedArtifactPath)(".polaris/clusters/POL-242/cluster-state.json", "POL-242")).toBe(true);
+        (0, vitest_1.expect)((0, artifact_policy_js_1.isPromotedArtifactPath)(".polaris/clusters/POL-242/packets/worker.json", "POL-242")).toBe(true);
+        (0, vitest_1.expect)((0, artifact_policy_js_1.isPromotedArtifactPath)(".polaris/clusters/POL-242/results/worker.json", "POL-242")).toBe(true);
+        (0, vitest_1.expect)((0, artifact_policy_js_1.isPromotedArtifactPath)(".polaris/runs/ledger.jsonl", "POL-242")).toBe(true);
+        (0, vitest_1.expect)((0, artifact_policy_js_1.isPromotedArtifactPath)(".polaris/cognition/archive/src/loop/cognition-index.json", "POL-242")).toBe(true);
+        (0, vitest_1.expect)((0, artifact_policy_js_1.isPromotedArtifactPath)(".polaris/map/file-routes.json", "POL-242")).toBe(true);
+    });
+    (0, vitest_1.it)("flags workspace scratch, legacy run files, and foreign cluster evidence", () => {
+        (0, vitest_1.expect)((0, artifact_policy_js_1.classifyArtifactPath)(".taskchain_artifacts/polaris-run/current-state.json", "POL-242")).toBe("workspace-scratch");
+        (0, vitest_1.expect)((0, artifact_policy_js_1.classifyArtifactPath)(".taskchain_artifacts/polaris-run/runs/run-1/telemetry.jsonl", "POL-242")).toBe("workspace-scratch");
+        (0, vitest_1.expect)((0, artifact_policy_js_1.classifyArtifactPath)(".polaris/runs/mutation-queue.json", "POL-242")).toBe("legacy-run-artifact");
+        (0, vitest_1.expect)((0, artifact_policy_js_1.classifyArtifactPath)(".polaris/clusters/POL-240/cluster-state.json", "POL-242")).toBe("foreign-cluster-artifact");
+        (0, vitest_1.expect)((0, artifact_policy_js_1.classifyArtifactPath)("src/finalize/steps/06-commit.ts", "POL-242")).toBe("non-artifact");
+    });
+    (0, vitest_1.it)("reports actionable commit-hygiene violations without blocking non-artifact files", () => {
+        (0, vitest_1.expect)((0, artifact_policy_js_1.findArtifactPromotionViolations)([
+            "src/finalize/index.ts",
+            ".taskchain_artifacts/polaris-run/current-state.json",
+            ".polaris/runs/mutation-queue.json",
+            ".polaris/clusters/POL-240/results/POL-240.json",
+            ".taskchain_artifacts/polaris-run/current-state.json.backup.bak",
+        ], "POL-242")).toEqual([
+            {
+                path: ".taskchain_artifacts/polaris-run/current-state.json",
+                classification: "workspace-scratch",
+                message: (0, artifact_policy_js_1.explainArtifactPolicy)(".taskchain_artifacts/polaris-run/current-state.json", "POL-242"),
+            },
+            {
+                path: ".polaris/runs/mutation-queue.json",
+                classification: "legacy-run-artifact",
+                message: (0, artifact_policy_js_1.explainArtifactPolicy)(".polaris/runs/mutation-queue.json", "POL-242"),
+            },
+            {
+                path: ".polaris/clusters/POL-240/results/POL-240.json",
+                classification: "foreign-cluster-artifact",
+                message: (0, artifact_policy_js_1.explainArtifactPolicy)(".polaris/clusters/POL-240/results/POL-240.json", "POL-242"),
+            },
+            {
+                path: ".taskchain_artifacts/polaris-run/current-state.json.backup.bak",
+                classification: "workspace-scratch",
+                message: (0, artifact_policy_js_1.explainArtifactPolicy)(".taskchain_artifacts/polaris-run/current-state.json.backup.bak", "POL-242"),
+            },
+        ]);
+    });
+    (0, vitest_1.it)("exposes promoted and blocked policy patterns for finalize consumers", () => {
+        (0, vitest_1.expect)((0, artifact_policy_js_1.getArtifactPromotionPolicy)("POL-242")).toEqual({
+            promoted: [
+                ".polaris/clusters/POL-242/clusters.json",
+                ".polaris/clusters/POL-242/cluster-state.json",
+                ".polaris/clusters/POL-242/packets/**",
+                ".polaris/clusters/POL-242/results/**",
+                ".polaris/runs/ledger.jsonl",
+                ".polaris/cognition/archive/**",
+                ".polaris/map/**",
+            ],
+            blocked: [
+                ".taskchain_artifacts/**",
+                "*.bak",
+                ".polaris/runs/mutation-queue.json",
+                ".polaris/runs/current-state.pre-pol-198.json",
+                ".polaris/runs/evo-run-archive/**",
+                ".polaris/clusters/<other-cluster>/**",
+            ],
+        });
+    });
+    (0, vitest_1.it)("derives git-add stage targets from promoted policy patterns", () => {
+        (0, vitest_1.expect)((0, artifact_policy_js_1.getArtifactPromotionStageTargets)("POL-242")).toEqual([
+            ".polaris/clusters/POL-242/clusters.json",
+            ".polaris/clusters/POL-242/cluster-state.json",
+            ".polaris/clusters/POL-242/packets",
+            ".polaris/clusters/POL-242/results",
+            ".polaris/runs/ledger.jsonl",
+            ".polaris/cognition/archive",
+            ".polaris/map",
+        ]);
+    });
+});