@lsctech/polaris 0.1.0

package/dist/config/validator.test.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const validator_js_1 = require("./validator.js");
+(0, vitest_1.describe)("validateConfig — providers", () => {
+    (0, vitest_1.it)("accepts config with no providers field", () => {
+        const result = (0, validator_js_1.validateConfig)({ version: "1.0" });
+        (0, vitest_1.expect)(result.valid).toBe(true);
+        (0, vitest_1.expect)(result.errors).toHaveLength(0);
+    });
+    (0, vitest_1.it)("accepts empty providers object", () => {
+        const result = (0, validator_js_1.validateConfig)({ providers: {} });
+        (0, vitest_1.expect)(result.valid).toBe(true);
+        (0, vitest_1.expect)(result.errors).toHaveLength(0);
+    });
+    (0, vitest_1.it)("accepts valid providers.repoAnalysis with preferred and fallback", () => {
+        const result = (0, validator_js_1.validateConfig)({
+            providers: {
+                repoAnalysis: {
+                    preferred: "gitnexus",
+                    fallback: ["polaris-map", "ripgrep"],
+                },
+            },
+        });
+        (0, vitest_1.expect)(result.valid).toBe(true);
+        (0, vitest_1.expect)(result.errors).toHaveLength(0);
+    });
+    (0, vitest_1.it)("accepts providers.repoAnalysis with only preferred", () => {
+        const result = (0, validator_js_1.validateConfig)({
+            providers: { repoAnalysis: { preferred: "gitnexus" } },
+        });
+        (0, vitest_1.expect)(result.valid).toBe(true);
+    });
+    (0, vitest_1.it)("accepts providers.repoAnalysis with only fallback", () => {
+        const result = (0, validator_js_1.validateConfig)({
+            providers: { repoAnalysis: { fallback: ["polaris-map"] } },
+        });
+        (0, vitest_1.expect)(result.valid).toBe(true);
+    });
+    (0, vitest_1.it)("rejects providers that is not an object", () => {
+        const result = (0, validator_js_1.validateConfig)({ providers: "gitnexus" });
+        (0, vitest_1.expect)(result.valid).toBe(false);
+        (0, vitest_1.expect)(result.errors).toContain("providers must be an object");
+    });
+    (0, vitest_1.it)("rejects providers.repoAnalysis that is not an object", () => {
+        const result = (0, validator_js_1.validateConfig)({ providers: { repoAnalysis: 42 } });
+        (0, vitest_1.expect)(result.valid).toBe(false);
+        (0, vitest_1.expect)(result.errors).toContain("providers.repoAnalysis must be an object");
+    });
+    (0, vitest_1.it)("rejects providers.repoAnalysis.preferred that is not a string", () => {
+        const result = (0, validator_js_1.validateConfig)({
+            providers: { repoAnalysis: { preferred: 123 } },
+        });
+        (0, vitest_1.expect)(result.valid).toBe(false);
+        (0, vitest_1.expect)(result.errors).toContain("providers.repoAnalysis.preferred must be a string");
+    });
+    (0, vitest_1.it)("rejects providers.repoAnalysis.fallback that is not an array of strings", () => {
+        const result = (0, validator_js_1.validateConfig)({
+            providers: { repoAnalysis: { fallback: "polaris-map" } },
+        });
+        (0, vitest_1.expect)(result.valid).toBe(false);
+        (0, vitest_1.expect)(result.errors).toContain("providers.repoAnalysis.fallback must be an array of strings");
+    });
+    (0, vitest_1.it)("rejects providers.repoAnalysis.fallback with non-string elements", () => {
+        const result = (0, validator_js_1.validateConfig)({
+            providers: { repoAnalysis: { fallback: [1, 2] } },
+        });
+        (0, vitest_1.expect)(result.valid).toBe(false);
+        (0, vitest_1.expect)(result.errors).toContain("providers.repoAnalysis.fallback must be an array of strings");
+    });
+    (0, vitest_1.it)("does not warn on the providers key", () => {
+        const result = (0, validator_js_1.validateConfig)({
+            providers: { repoAnalysis: { preferred: "gitnexus" } },
+        });
+        (0, vitest_1.expect)(result.warnings).not.toContain('Unknown config field: "providers"');
+    });
+});

package/dist/docs/canon-check.js

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCanonCheck = runCanonCheck;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// Modal verbs that indicate behavioral assertions in doctrine/spec files
+const MODAL_VERBS = /\b(must|never|always|should|required|requires|shall)\b/i;
+// Domains matched by filename keywords
+const DOMAIN_KEYWORDS = ["loop", "map", "finalize", "config", "cli", "docs"];
+/** Walk up from `startDir` to `repoRoot` looking for the nearest POLARIS.md */
+function findNearestPolarisMd(startDir, repoRoot) {
+    let dir = (0, node_path_1.resolve)(startDir);
+    const root = (0, node_path_1.resolve)(repoRoot);
+    let searching = true;
+    while (searching) {
+        const candidate = (0, node_path_1.join)(dir, "POLARIS.md");
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+        if (dir === root)
+            break;
+        const parent = (0, node_path_1.dirname)(dir);
+        if (parent === dir) {
+            searching = false;
+            break;
+        } // filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/** Collect all relevant canon files for the given changed files */
+function locateCanonFiles(changedFiles, repoRoot) {
+    const canon = new Set();
+    // POLARIS.md files — nearest ancestor for each changed file
+    for (const f of changedFiles) {
+        const absFile = (0, node_path_1.resolve)(repoRoot, f);
+        const startDir = (0, node_path_1.dirname)(absFile);
+        const polarisMd = findNearestPolarisMd(startDir, repoRoot);
+        if (polarisMd)
+            canon.add(polarisMd);
+    }
+    // Active doctrine
+    const doctrineDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "active");
+    if ((0, node_fs_1.existsSync)(doctrineDir)) {
+        for (const f of (0, node_fs_1.readdirSync)(doctrineDir)) {
+            if (f.endsWith(".md"))
+                canon.add((0, node_path_1.join)(doctrineDir, f));
+        }
+    }
+    // Active and implemented specs — filtered by domain keyword overlap
+    const changedDomains = new Set();
+    for (const f of changedFiles) {
+        for (const kw of DOMAIN_KEYWORDS) {
+            if (f.toLowerCase().includes(kw))
+                changedDomains.add(kw);
+        }
+    }
+    for (const specSubdir of ["active", "implemented"]) {
+        const specDir = (0, node_path_1.join)(repoRoot, "docs", "specs", specSubdir);
+        if (!(0, node_fs_1.existsSync)(specDir))
+            continue;
+        for (const f of (0, node_fs_1.readdirSync)(specDir)) {
+            if (!f.endsWith(".md"))
+                continue;
+            const lower = f.toLowerCase();
+            const matches = changedDomains.size === 0 || Array.from(changedDomains).some((kw) => lower.includes(kw));
+            if (matches)
+                canon.add((0, node_path_1.join)(specDir, f));
+        }
+    }
+    return canon;
+}
+/** Extract bullet-point lines from a named markdown section */
+function extractSection(content, sectionHeader) {
+    const lines = content.split("\n");
+    const result = [];
+    let inSection = false;
+    for (const line of lines) {
+        if (line.startsWith("##") && line.toLowerCase().includes(sectionHeader.toLowerCase())) {
+            inSection = true;
+            continue;
+        }
+        if (inSection) {
+            if (line.startsWith("##"))
+                break; // next section
+            const trimmed = line.trim();
+            if (trimmed.startsWith("-") || trimmed.startsWith("*")) {
+                result.push(trimmed.replace(/^[-*]\s*/, ""));
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Check if a POLARIS.md rule explicitly names a changed file as deleted/removed while it still exists.
+ * This is the primary `stale-implementation` trigger for MVP.
+ */
+function checkPolarisMd(canonFile, changedFiles, repoRoot) {
+    const conflicts = [];
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)(canonFile, "utf-8");
+    }
+    catch {
+        return conflicts;
+    }
+    const editingRules = extractSection(content, "editing rules");
+    const archAssumptions = extractSection(content, "architecture assumptions");
+    const allRules = [...editingRules, ...archAssumptions];
+    for (const rule of allRules) {
+        const lower = rule.toLowerCase();
+        // Detect rules that say something is deleted/removed but the file still exists
+        const isDeleted = /\b(deleted|removed|no longer exists|do not use)\b/.test(lower);
+        if (!isDeleted)
+            continue;
+        for (const changedFile of changedFiles) {
+            const fileBasename = (0, node_path_1.basename)(changedFile);
+            if (lower.includes(fileBasename.toLowerCase()) && (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, changedFile))) {
+                // Determine conflict type based on rule text and changed file
+                let conflictType = "stale-implementation";
+                const ext = changedFile.split(".").pop()?.toLowerCase() ?? "";
+                const isDocFile = ext === "md" || changedFile.startsWith("docs/");
+                const hasDocKeywords = /\b(doc|documentation|readme|guide|spec)\b/i.test(lower);
+                const hasCandidateKeywords = /\b(candidate|divergence|proposal)\b/i.test(lower);
+                if (isDocFile || hasDocKeywords) {
+                    conflictType = "stale-docs";
+                }
+                else if (hasCandidateKeywords) {
+                    conflictType = "candidate-divergence";
+                }
+                conflicts.push({
+                    type: conflictType,
+                    canonFile,
+                    statement: rule,
+                    changedFile,
+                    detail: `POLARIS.md states "${fileBasename}" is deleted/removed but the file still exists`,
+                });
+            }
+        }
+    }
+    return conflicts;
+}
+/**
+ * Check doctrine/spec files for modal-verb assertions that directly contradict changed files.
+ * MVP: only flag stale-implementation when a named file/command is explicitly asserted to
+ * exist/be-required but is missing, or asserted as deleted while still present.
+ */
+function checkDocFile(canonFile, changedFiles, repoRoot) {
+    const conflicts = [];
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)(canonFile, "utf-8");
+    }
+    catch {
+        return conflicts;
+    }
+    const lines = content.split("\n");
+    for (const line of lines) {
+        if (!MODAL_VERBS.test(line))
+            continue;
+        const lower = line.toLowerCase();
+        // Only flag lines that name a specific file/command that should exist but doesn't
+        const deletedAssertion = /\b(deleted|removed|no longer exists)\b/.test(lower);
+        if (!deletedAssertion)
+            continue;
+        for (const changedFile of changedFiles) {
+            const fileBasename = (0, node_path_1.basename)(changedFile);
+            if (lower.includes(fileBasename.toLowerCase()) && (0, node_fs_1.existsSync)((0, node_path_1.resolve)(repoRoot, changedFile))) {
+                conflicts.push({
+                    type: "stale-implementation",
+                    canonFile,
+                    statement: line.trim(),
+                    changedFile,
+                    detail: `Canon asserts "${fileBasename}" is deleted/removed but file still exists`,
+                });
+            }
+        }
+    }
+    return conflicts;
+}
+function appendTelemetry(telemetryFile, event) {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+        (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
+    }
+    catch {
+        // Non-fatal: telemetry write failure should not block operation
+    }
+}
+/**
+ * Run the canon reconciliation check.
+ *
+ * Emits `canon-check-start` and either `canon-check-result` or `canon-conflict-halt`
+ * to the telemetry file. Returns the result for the caller to act on.
+ *
+ * Note: This function does NOT call process.exit. Callers are responsible for
+ * halting execution based on the returned outcome.
+ */
+function runCanonCheck(options) {
+    const { repoRoot, changedFiles, childId, runId, telemetryFile } = options;
+    const canonFilesSet = locateCanonFiles(changedFiles, repoRoot);
+    const canonFilesInspected = canonFilesSet.size;
+    appendTelemetry(telemetryFile, {
+        event: "canon-check-start",
+        run_id: runId,
+        child_id: childId ?? null,
+        canon_files_inspected: canonFilesInspected,
+        changed_files_count: changedFiles.length,
+        timestamp: new Date().toISOString(),
+    });
+    if (canonFilesInspected === 0 || changedFiles.length === 0) {
+        const result = { outcome: "aligned", conflicts: [], canonFilesInspected };
+        appendTelemetry(telemetryFile, {
+            event: "canon-check-result",
+            run_id: runId,
+            child_id: childId ?? null,
+            outcome: "aligned",
+            conflicts: [],
+            timestamp: new Date().toISOString(),
+        });
+        return result;
+    }
+    const allConflicts = [];
+    for (const canonFile of canonFilesSet) {
+        const fileBasename = (0, node_path_1.basename)(canonFile);
+        const isPolarisMd = fileBasename === "POLARIS.md";
+        const fileConflicts = isPolarisMd
+            ? checkPolarisMd(canonFile, changedFiles, repoRoot)
+            : checkDocFile(canonFile, changedFiles, repoRoot);
+        allConflicts.push(...fileConflicts);
+    }
+    // Classify outcome: stale-implementation wins; then stale-docs; then candidate-divergence; else aligned
+    let outcome = "aligned";
+    if (allConflicts.some((c) => c.type === "stale-implementation")) {
+        outcome = "stale-implementation";
+    }
+    else if (allConflicts.some((c) => c.type === "stale-docs")) {
+        outcome = "stale-docs";
+    }
+    else if (allConflicts.some((c) => c.type === "candidate-divergence")) {
+        outcome = "candidate-divergence";
+    }
+    const result = { outcome, conflicts: allConflicts, canonFilesInspected };
+    if (outcome === "stale-implementation") {
+        const first = allConflicts.find((c) => c.type === "stale-implementation");
+        appendTelemetry(telemetryFile, {
+            event: "canon-conflict-halt",
+            run_id: runId,
+            child_id: childId ?? null,
+            reason: first.detail,
+            canon_file: first.canonFile,
+            conflicting_statement: first.statement,
+            missing_or_differing: first.changedFile,
+            suggested_resolution: "Update the canon file to reflect current state, or remove/fix the conflicting assertion",
+            timestamp: new Date().toISOString(),
+        });
+    }
+    else {
+        appendTelemetry(telemetryFile, {
+            event: "canon-check-result",
+            run_id: runId,
+            child_id: childId ?? null,
+            outcome,
+            conflicts: allConflicts,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // For non-blocking outcomes, write draft docs as specified
+    if (outcome === "stale-docs") {
+        writeStaleDraftDocs(allConflicts.filter((c) => c.type === "stale-docs"), repoRoot, childId);
+    }
+    else if (outcome === "candidate-divergence") {
+        writeCandidateDraftDocs(allConflicts.filter((c) => c.type === "candidate-divergence"), repoRoot, childId);
+    }
+    return result;
+}
+function writeStaleDraftDocs(conflicts, repoRoot, childId) {
+    const rawDir = (0, node_path_1.join)(repoRoot, "docs", "raw");
+    try {
+        (0, node_fs_1.mkdirSync)(rawDir, { recursive: true });
+        for (const conflict of conflicts) {
+            const slug = (0, node_path_1.basename)(conflict.canonFile).replace(/\.md$/, "");
+            const date = new Date().toISOString().slice(0, 10);
+            const filename = `stale-flag-${slug}-${date}.md`;
+            const path = (0, node_path_1.join)(rawDir, filename);
+            if (!(0, node_fs_1.existsSync)(path)) {
+                (0, node_fs_1.writeFileSync)(path, [
+                    `# Stale Doc Flag`,
+                    ``,
+                    `**Canon file:** ${conflict.canonFile}`,
+                    `**Triggering file:** ${conflict.changedFile}`,
+                    `**What appears outdated:** ${conflict.statement}`,
+                    `**Detail:** ${conflict.detail}`,
+                    `**Flagged by:** ${childId ?? "finalize"}`,
+                    `**Date:** ${new Date().toISOString()}`,
+                ].join("\n"), "utf-8");
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
+function writeCandidateDraftDocs(conflicts, repoRoot, childId) {
+    const candidateDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate");
+    try {
+        (0, node_fs_1.mkdirSync)(candidateDir, { recursive: true });
+        for (const conflict of conflicts) {
+            const slug = (0, node_path_1.basename)(conflict.canonFile).replace(/\.md$/, "");
+            const date = new Date().toISOString().slice(0, 10);
+            const filename = `${slug}-${date}.draft.md`;
+            const path = (0, node_path_1.join)(candidateDir, filename);
+            if (!(0, node_fs_1.existsSync)(path)) {
+                (0, node_fs_1.writeFileSync)(path, [
+                    `---`,
+                    `status: candidate`,
+                    `source: ${conflict.canonFile}`,
+                    `proposed-by: ${childId ?? "unknown"}`,
+                    `proposed-at: ${new Date().toISOString()}`,
+                    `---`,
+                    ``,
+                    `# Candidate Divergence Draft`,
+                    ``,
+                    `**Source canon file:** ${conflict.canonFile}`,
+                    `**Conflicting statement:** ${conflict.statement}`,
+                    `**Changed file:** ${conflict.changedFile}`,
+                    `**Detail:** ${conflict.detail}`,
+                ].join("\n"), "utf-8");
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}

package/dist/docs/canon-check.test.js

@@ -0,0 +1,207 @@
+"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 node_os_1 = require("node:os");
+const canon_check_js_1 = require("./canon-check.js");
+function makeTestDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `canon-check-test-${Date.now()}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    return dir;
+}
+function makeTelemetryFile(dir) {
+    const telDir = (0, node_path_1.join)(dir, "telemetry");
+    (0, node_fs_1.mkdirSync)(telDir, { recursive: true });
+    return (0, node_path_1.join)(telDir, "telemetry.jsonl");
+}
+(0, vitest_1.describe)("runCanonCheck", () => {
+    let testDir;
+    let telemetryFile;
+    (0, vitest_1.beforeEach)(() => {
+        testDir = makeTestDir();
+        telemetryFile = makeTelemetryFile(testDir);
+    });
+    (0, vitest_1.afterEach)(() => {
+        (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true });
+    });
+    (0, vitest_1.describe)("aligned outcome", () => {
+        (0, vitest_1.it)("returns aligned when no changed files are provided", () => {
+            const result = (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: [],
+                runId: "test-run-1",
+                telemetryFile,
+            });
+            (0, vitest_1.expect)(result.outcome).toBe("aligned");
+            (0, vitest_1.expect)(result.conflicts).toEqual([]);
+        });
+        (0, vitest_1.it)("returns aligned when no POLARIS.md or canon dirs exist", () => {
+            const result = (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: ["src/loop/continue.ts"],
+                runId: "test-run-1",
+                telemetryFile,
+            });
+            (0, vitest_1.expect)(result.outcome).toBe("aligned");
+            (0, vitest_1.expect)(result.conflicts).toEqual([]);
+        });
+        (0, vitest_1.it)("returns aligned when POLARIS.md has no rules mentioning changed files as deleted", () => {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src", "loop"), { recursive: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "src", "loop", "continue.ts"), "// placeholder");
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "POLARIS.md"), [
+                "# POLARIS.md",
+                "",
+                "## Editing rules",
+                "- State writes must use checkpoint.ts",
+                "- Keep loop files small",
+                "",
+                "## Architecture assumptions",
+                "- Bootstrap packets are immutable once written",
+            ].join("\n"));
+            const result = (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: ["src/loop/continue.ts"],
+                runId: "test-run-1",
+                telemetryFile,
+            });
+            (0, vitest_1.expect)(result.outcome).toBe("aligned");
+            (0, vitest_1.expect)(result.conflicts).toEqual([]);
+        });
+        (0, vitest_1.it)("sets canonFilesInspected based on found canon files", () => {
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "POLARIS.md"), "# POLARIS.md\n## Editing rules\n- No special rules\n");
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src"), { recursive: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "src", "foo.ts"), "// code");
+            const result = (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: ["src/foo.ts"],
+                runId: "test-run-1",
+                telemetryFile,
+            });
+            (0, vitest_1.expect)(result.canonFilesInspected).toBeGreaterThan(0);
+        });
+    });
+    (0, vitest_1.describe)("stale-implementation outcome", () => {
+        (0, vitest_1.it)("returns stale-implementation when POLARIS.md says a file is deleted but it still exists", () => {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src", "loop"), { recursive: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "src", "loop", "old-module.ts"), "// still here");
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "POLARIS.md"), [
+                "# POLARIS.md",
+                "",
+                "## Architecture assumptions",
+                "- old-module.ts has been deleted and must not be used",
+            ].join("\n"));
+            const result = (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: ["src/loop/old-module.ts"],
+                runId: "test-run-1",
+                telemetryFile,
+            });
+            (0, vitest_1.expect)(result.outcome).toBe("stale-implementation");
+            (0, vitest_1.expect)(result.conflicts.length).toBeGreaterThan(0);
+            (0, vitest_1.expect)(result.conflicts[0].type).toBe("stale-implementation");
+        });
+        (0, vitest_1.it)("emits canon-conflict-halt telemetry event on stale-implementation", () => {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src"), { recursive: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "src", "legacy.ts"), "// still exists");
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "POLARIS.md"), [
+                "# POLARIS.md",
+                "",
+                "## Architecture assumptions",
+                "- legacy.ts has been removed and should not be referenced",
+            ].join("\n"));
+            (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: ["src/legacy.ts"],
+                runId: "test-run-halt",
+                telemetryFile,
+                childId: "POL-99",
+            });
+            const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8")
+                .trim()
+                .split("\n")
+                .map((l) => JSON.parse(l));
+            const halt = lines.find((e) => e.event === "canon-conflict-halt");
+            (0, vitest_1.expect)(halt).toBeTruthy();
+            (0, vitest_1.expect)(halt.run_id).toBe("test-run-halt");
+            (0, vitest_1.expect)(halt.child_id).toBe("POL-99");
+        });
+    });
+    (0, vitest_1.describe)("telemetry events", () => {
+        (0, vitest_1.it)("emits canon-check-start event", () => {
+            (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: ["src/foo.ts"],
+                runId: "test-run-tel",
+                telemetryFile,
+                childId: "POL-51",
+            });
+            const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8")
+                .trim()
+                .split("\n")
+                .map((l) => JSON.parse(l));
+            const start = lines.find((e) => e.event === "canon-check-start");
+            (0, vitest_1.expect)(start).toBeTruthy();
+            (0, vitest_1.expect)(start.run_id).toBe("test-run-tel");
+            (0, vitest_1.expect)(start.child_id).toBe("POL-51");
+            (0, vitest_1.expect)(typeof start.changed_files_count).toBe("number");
+        });
+        (0, vitest_1.it)("emits canon-check-result event for aligned outcome", () => {
+            (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: [],
+                runId: "test-run-aligned",
+                telemetryFile,
+            });
+            const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8")
+                .trim()
+                .split("\n")
+                .map((l) => JSON.parse(l));
+            const result = lines.find((e) => e.event === "canon-check-result");
+            (0, vitest_1.expect)(result).toBeTruthy();
+            (0, vitest_1.expect)(result.outcome).toBe("aligned");
+            (0, vitest_1.expect)(result.conflicts).toEqual([]);
+        });
+        (0, vitest_1.it)("sets child_id to null when not provided", () => {
+            (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: [],
+                runId: "test-run-no-child",
+                telemetryFile,
+            });
+            const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8")
+                .trim()
+                .split("\n")
+                .map((l) => JSON.parse(l));
+            const start = lines.find((e) => e.event === "canon-check-start");
+            (0, vitest_1.expect)(start.child_id).toBeNull();
+        });
+    });
+    (0, vitest_1.describe)("config flags", () => {
+        (0, vitest_1.it)("does not alter return value — callers control skip logic", () => {
+            // canon-check itself has no checkOnContinue/checkOnFinalize logic;
+            // skipping is the caller's responsibility. Just verify function is callable.
+            const checkResult = (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: [],
+                runId: "test-flag",
+                telemetryFile,
+            });
+            (0, vitest_1.expect)(checkResult).toBeDefined();
+        });
+    });
+    (0, vitest_1.describe)("POLARIS.md nearest ancestor lookup", () => {
+        (0, vitest_1.it)("finds POLARIS.md in a parent directory", () => {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, "src", "loop", "deep"), { recursive: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "src", "loop", "deep", "file.ts"), "// code");
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(testDir, "src", "POLARIS.md"), "# POLARIS.md\n## Editing rules\n- no rules\n");
+            const result = (0, canon_check_js_1.runCanonCheck)({
+                repoRoot: testDir,
+                changedFiles: ["src/loop/deep/file.ts"],
+                runId: "test-ancestor",
+                telemetryFile,
+            });
+            (0, vitest_1.expect)(result.canonFilesInspected).toBeGreaterThan(0);
+        });
+    });
+});