@lsctech/polaris 0.1.0

package/dist/skill-packet/generator.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_SKILLS = exports.SKILL_ROLE_MAP = void 0;
+exports.generateSkillPacket = generateSkillPacket;
+const node_crypto_1 = require("node:crypto");
+exports.SKILL_ROLE_MAP = {
+    analyze: "Analyst",
+    run: "Foreman",
+    ingest: "Librarian",
+    promote: "Librarian",
+};
+const ROLE_SUMMARIES = {
+    Analyst: "The Analyst gathers evidence, assesses feasibility, and produces implementation-ready plans. The Analyst shapes work but never executes it.",
+    Foreman: "The Foreman coordinates implementation by dispatching Workers. The Foreman never writes code directly — all implementation is delegated.",
+    Librarian: "The Librarian ingests, classifies, indexes, and promotes knowledge artifacts. The Librarian preserves provenance and maintains canonical structure.",
+    Worker: "The Worker implements a focused, bounded task as directed by the Foreman. The Worker owns implementation for its assigned child.",
+};
+function buildAnalyzePacket(config) {
+    const onBelowThreshold = config.auto_deep_analysis ? "auto_proceed" : "ask_user";
+    return {
+        authority_boundaries: [
+            "Inspect repository files and architecture",
+            "Query repo-analysis providers for code intelligence",
+            "Summarize findings and assess feasibility",
+            "Create implementation plans and specs in docs/",
+            "Create or update tracker child issues",
+            "Generate local cluster artifacts (.polaris/clusters/)",
+            "Update tracker comments and status",
+            "Close the analysis issue when complete",
+        ],
+        prohibited_actions: [
+            "Implement production or runtime code",
+            "Mutate source files (src/, tests, config)",
+            "Execute implementation loops",
+            "Open implementation PRs",
+            "Continue automatically into polaris-run execution",
+            "Call polaris loop continue or polaris finalize",
+        ],
+        allowed_outputs: [
+            "Linear issue descriptions and child issues",
+            "Cluster artifact files (.polaris/clusters/)",
+            "Spec documents in docs/",
+            "Tracker comments and status updates",
+        ],
+        deliverables: [
+            "Implementation-ready Linear issues, or",
+            "Explanation of why user approval is needed for deeper analysis",
+        ],
+        stop_conditions: [
+            "All cluster children created and linked",
+            "Confidence below threshold and user approval required but not yet obtained",
+            "Blocking dependency discovered that prevents planning",
+        ],
+        confidence_policy: {
+            threshold: config.analysis_confidence_threshold,
+            auto_deep_analysis: config.auto_deep_analysis,
+            on_below_threshold: onBelowThreshold,
+        },
+    };
+}
+function buildRunPacket(config) {
+    const delegationNote = config.allow_cross_provider_delegation
+        ? "Cross-provider delegation is permitted per configuration."
+        : "Cross-provider delegation is NOT permitted. Native subagent spawning is prohibited. Use terminal-cli adapter with configured providers (e.g. copilot, codex), or interactive-agent/agent-subtask adapters when running in interactive mode.";
+    return {
+        authority_boundaries: [
+            "Read cluster artifacts and current run state",
+            "Call polaris loop dispatch to assign work to a Worker",
+            "Call polaris loop continue after a Worker has returned results",
+            "Call polaris loop status to check run state",
+            "Pass worker packets to the internal child/subagent as the full prompt",
+            `Delegation policy: ${delegationNote}`,
+        ],
+        prohibited_actions: [
+            "Implement code directly (inline implementation is forbidden)",
+            "Modify source files without dispatching a Worker",
+            "Mark a child complete without Worker result evidence",
+            "Attempt cross-provider delegation unless explicitly configured",
+            "Call polaris finalize before all children are complete",
+        ],
+        allowed_outputs: [
+            "polaris loop dispatch invocations",
+            "polaris loop continue invocations (post-worker only)",
+            "polaris loop status output",
+            "Worker packet contents passed to internal child/subagent",
+        ],
+        deliverables: [
+            "All assigned children dispatched and completed via Worker",
+            "Run checkpointed after each child",
+        ],
+        stop_conditions: [
+            "All cluster children complete",
+            "A child returns status failed and stop_on_fail is enabled",
+            "Budget cap reached",
+            "Worker result evidence is absent — do not mark complete without it",
+        ],
+    };
+}
+/**
+ * Builds the ingest skill packet body that defines authority boundaries, prohibited actions, allowed outputs, required deliverables, and stop conditions for processing smartdocs.
+ *
+ * The packet enforces reading from smartdocs/raw/, classification and routing into smartdocs/, provenance recording, Polaris map updates, doctrine candidate routing, and telemetry emission while forbidding source mutation, silent promotions, writing to root docs/, loop/finalize calls, and conflict suppression.
+ *
+ * @returns An object with `authority_boundaries`, `prohibited_actions`, `allowed_outputs`, `deliverables`, and `stop_conditions` describing the ingest skill's policies and required outcomes.
+ */
+function buildIngestPacket() {
+    return {
+        authority_boundaries: [
+            "Read documents from smartdocs/raw/",
+            "Classify documents by content analysis and front-matter",
+            "Route documents to correct authority directories within smartdocs/",
+            "Write provenance records alongside placed files",
+            "Update Polaris map entries to link docs to code areas",
+            "Propose doctrine candidates (route to doctrine/candidate/ only)",
+            "Emit telemetry events",
+        ],
+        prohibited_actions: [
+            "Write new Smart Docs to root docs/ — smartdocs/ is the canonical target",
+            "Silently promote documents to doctrine/active/, specs/active/, architecture/, or decisions/",
+            "Mutate source files (src/, tests, config)",
+            "Call polaris loop continue or polaris finalize",
+            "Suppress detected conflicts",
+        ],
+        allowed_outputs: [
+            "Classified and routed documents in smartdocs/",
+            "Provenance sidecar records",
+            "Polaris map entry updates",
+            "Doctrine candidate proposals in doctrine/candidate/",
+            "Telemetry events",
+        ],
+        deliverables: [
+            "All pending raw documents classified and routed",
+            "Provenance records written",
+            "Map entries updated",
+        ],
+        stop_conditions: [
+            "All documents in raw/ processed",
+            "Conflict detected that requires user resolution",
+            "Document cannot be classified — report and wait for instruction",
+        ],
+    };
+}
+/**
+ * Construct the promotion/governance packet body that governs doctrine/spec promotion and deprecation.
+ *
+ * @returns The body of a `SkillPacket` for the `promote` skill containing:
+ * - `authority_boundaries`: allowed read/verify/promote/deprecate actions and telemetry emission;
+ * - `prohibited_actions`: actions that must not be performed (auto-approve, source mutation, suppressing conflicts, etc.);
+ * - `allowed_outputs`: permitted resulting artifacts (promoted/ deprecated docs, conflict reports, telemetry);
+ * - `deliverables`: required outcomes (reviewed promotions/deprecations and surfaced conflict reports);
+ * - `stop_conditions`: conditions that halt the promotion process (all reviewed, unresolved conflicts, missing user approval).
+ */
+function buildPromotePacket() {
+    return {
+        authority_boundaries: [
+            "Read smartdocs/raw/ and smartdocs/doctrine/candidate/ to identify promotion candidates",
+            "Read linked source files (from linkedMapArea in provenance sidecar) to verify relevance",
+            "Read smartdocs/doctrine/active/ and smartdocs/specs/active/ to check for conflicts",
+            "Call polaris doctrine spec-promote <path> to surface the conflict report (without --approve)",
+            "Call polaris doctrine spec-promote <path> --approve only after surfacing report and receiving explicit user confirmation",
+            "Call polaris doctrine promote <path> for doctrine candidates that pass governance checks",
+            "Call polaris doctrine deprecate <path> for active docs that are superseded or stale",
+            "Emit telemetry events",
+        ],
+        prohibited_actions: [
+            "Auto-promote without surfacing the conflict report first",
+            "Call --approve without explicit user confirmation in the session",
+            "Mutate source files (src/, tests, config)",
+            "Call polaris loop continue or polaris finalize",
+            "Promote to architecture/ or decisions/ — those require explicit ADR process",
+            "Suppress or ignore detected conflicts",
+        ],
+        allowed_outputs: [
+            "Promoted documents in doctrine/active/ or specs/active/",
+            "Deprecated documents with deprecation markers",
+            "Conflict reports surfaced to user",
+            "Telemetry events",
+        ],
+        deliverables: [
+            "Reviewed candidates promoted, deprecated, or deferred with explanation",
+            "All conflict reports surfaced before any promotion",
+        ],
+        stop_conditions: [
+            "All candidates reviewed",
+            "Unresolved conflict requiring user decision",
+            "User confirmation not obtained before --approve step",
+        ],
+    };
+}
+function generateSkillPacket(skillName, config) {
+    const active_role = exports.SKILL_ROLE_MAP[skillName];
+    const role_summary = ROLE_SUMMARIES[active_role];
+    const generated_at = new Date().toISOString();
+    const packet_id = (0, node_crypto_1.randomUUID)();
+    const source_config_snapshot = {
+        analysis_confidence_threshold: config.analysis_confidence_threshold,
+        auto_deep_analysis: config.auto_deep_analysis,
+        allow_cross_provider_delegation: config.allow_cross_provider_delegation,
+    };
+    let body;
+    switch (skillName) {
+        case "analyze":
+            body = buildAnalyzePacket(config);
+            break;
+        case "run":
+            body = buildRunPacket(config);
+            break;
+        case "ingest":
+            body = buildIngestPacket();
+            break;
+        case "promote":
+            body = buildPromotePacket();
+            break;
+    }
+    return {
+        packet_id,
+        skill_name: skillName,
+        active_role,
+        role_summary,
+        ...body,
+        source_config_snapshot,
+        generated_at,
+    };
+}
+exports.SUPPORTED_SKILLS = ["analyze", "run", "ingest", "promote"];

package/dist/skill-packet/generator.test.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const generator_js_1 = require("./generator.js");
+const DEFAULT_CONFIG = {
+    analysis_confidence_threshold: 85,
+    auto_deep_analysis: false,
+    allow_cross_provider_delegation: false,
+};
+(0, vitest_1.describe)("SKILL_ROLE_MAP", () => {
+    (0, vitest_1.it)("maps analyze to Analyst", () => {
+        (0, vitest_1.expect)(generator_js_1.SKILL_ROLE_MAP.analyze).toBe("Analyst");
+    });
+    (0, vitest_1.it)("maps run to Foreman", () => {
+        (0, vitest_1.expect)(generator_js_1.SKILL_ROLE_MAP.run).toBe("Foreman");
+    });
+    (0, vitest_1.it)("maps ingest to Librarian", () => {
+        (0, vitest_1.expect)(generator_js_1.SKILL_ROLE_MAP.ingest).toBe("Librarian");
+    });
+    (0, vitest_1.it)("maps promote to Librarian", () => {
+        (0, vitest_1.expect)(generator_js_1.SKILL_ROLE_MAP.promote).toBe("Librarian");
+    });
+});
+(0, vitest_1.describe)("SUPPORTED_SKILLS", () => {
+    (0, vitest_1.it)("includes all four supported skills", () => {
+        (0, vitest_1.expect)(generator_js_1.SUPPORTED_SKILLS).toEqual(["analyze", "run", "ingest", "promote"]);
+    });
+});
+(0, vitest_1.describe)("generateSkillPacket", () => {
+    vitest_1.it.each(generator_js_1.SUPPORTED_SKILLS)("generates a packet for %s with required fields", (skill) => {
+        const packet = (0, generator_js_1.generateSkillPacket)(skill, DEFAULT_CONFIG);
+        (0, vitest_1.expect)(packet.packet_id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+        (0, vitest_1.expect)(packet.skill_name).toBe(skill);
+        (0, vitest_1.expect)(packet.active_role).toBe(generator_js_1.SKILL_ROLE_MAP[skill]);
+        (0, vitest_1.expect)(typeof packet.role_summary).toBe("string");
+        (0, vitest_1.expect)(packet.role_summary.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(Array.isArray(packet.authority_boundaries)).toBe(true);
+        (0, vitest_1.expect)(packet.authority_boundaries.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(Array.isArray(packet.prohibited_actions)).toBe(true);
+        (0, vitest_1.expect)(packet.prohibited_actions.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(Array.isArray(packet.allowed_outputs)).toBe(true);
+        (0, vitest_1.expect)(packet.allowed_outputs.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(Array.isArray(packet.deliverables)).toBe(true);
+        (0, vitest_1.expect)(packet.deliverables.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(Array.isArray(packet.stop_conditions)).toBe(true);
+        (0, vitest_1.expect)(packet.stop_conditions.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(typeof packet.generated_at).toBe("string");
+        (0, vitest_1.expect)(new Date(packet.generated_at).toISOString()).toBe(packet.generated_at);
+        (0, vitest_1.expect)(packet.source_config_snapshot).toEqual(DEFAULT_CONFIG);
+    });
+    (0, vitest_1.describe)("analyze packet", () => {
+        (0, vitest_1.it)("assigns Analyst role", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("analyze", DEFAULT_CONFIG);
+            (0, vitest_1.expect)(packet.active_role).toBe("Analyst");
+        });
+        (0, vitest_1.it)("includes a confidence_policy", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("analyze", DEFAULT_CONFIG);
+            (0, vitest_1.expect)(packet.confidence_policy).toBeDefined();
+            (0, vitest_1.expect)(packet.confidence_policy?.threshold).toBe(85);
+            (0, vitest_1.expect)(packet.confidence_policy?.auto_deep_analysis).toBe(false);
+            (0, vitest_1.expect)(packet.confidence_policy?.on_below_threshold).toBe("ask_user");
+        });
+        (0, vitest_1.it)("sets on_below_threshold to auto_proceed when auto_deep_analysis is true", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("analyze", {
+                ...DEFAULT_CONFIG,
+                auto_deep_analysis: true,
+            });
+            (0, vitest_1.expect)(packet.confidence_policy?.on_below_threshold).toBe("auto_proceed");
+            (0, vitest_1.expect)(packet.confidence_policy?.auto_deep_analysis).toBe(true);
+        });
+        (0, vitest_1.it)("reflects custom confidence threshold in policy and snapshot", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("analyze", {
+                ...DEFAULT_CONFIG,
+                analysis_confidence_threshold: 70,
+            });
+            (0, vitest_1.expect)(packet.confidence_policy?.threshold).toBe(70);
+            (0, vitest_1.expect)(packet.source_config_snapshot.analysis_confidence_threshold).toBe(70);
+        });
+        (0, vitest_1.it)("prohibits implementation actions", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("analyze", DEFAULT_CONFIG);
+            const prohibited = packet.prohibited_actions.join(" ");
+            (0, vitest_1.expect)(prohibited).toContain("production or runtime code");
+            (0, vitest_1.expect)(prohibited).toContain("polaris loop continue");
+        });
+    });
+    (0, vitest_1.describe)("run packet", () => {
+        (0, vitest_1.it)("assigns Foreman role", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("run", DEFAULT_CONFIG);
+            (0, vitest_1.expect)(packet.active_role).toBe("Foreman");
+        });
+        (0, vitest_1.it)("does not include a confidence_policy", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("run", DEFAULT_CONFIG);
+            (0, vitest_1.expect)(packet.confidence_policy).toBeUndefined();
+        });
+        (0, vitest_1.it)("prohibits inline implementation", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("run", DEFAULT_CONFIG);
+            const prohibited = packet.prohibited_actions.join(" ");
+            (0, vitest_1.expect)(prohibited).toContain("inline implementation");
+        });
+        (0, vitest_1.it)("notes cross-provider delegation is NOT permitted by default", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("run", DEFAULT_CONFIG);
+            const boundaries = packet.authority_boundaries.join(" ");
+            (0, vitest_1.expect)(boundaries).toContain("NOT permitted");
+        });
+        (0, vitest_1.it)("notes cross-provider delegation is permitted when configured", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("run", {
+                ...DEFAULT_CONFIG,
+                allow_cross_provider_delegation: true,
+            });
+            const boundaries = packet.authority_boundaries.join(" ");
+            (0, vitest_1.expect)(boundaries).toContain("permitted per configuration");
+        });
+        (0, vitest_1.it)("requires Worker result evidence before marking complete", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("run", DEFAULT_CONFIG);
+            const stops = packet.stop_conditions.join(" ");
+            (0, vitest_1.expect)(stops).toContain("Worker result evidence");
+        });
+    });
+    (0, vitest_1.describe)("ingest packet", () => {
+        (0, vitest_1.it)("assigns Librarian role", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("ingest", DEFAULT_CONFIG);
+            (0, vitest_1.expect)(packet.active_role).toBe("Librarian");
+        });
+        (0, vitest_1.it)("does not include a confidence_policy", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("ingest", DEFAULT_CONFIG);
+            (0, vitest_1.expect)(packet.confidence_policy).toBeUndefined();
+        });
+        (0, vitest_1.it)("prohibits promoting to active without approval", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("ingest", DEFAULT_CONFIG);
+            const prohibited = packet.prohibited_actions.join(" ");
+            (0, vitest_1.expect)(prohibited).toContain("doctrine/active/");
+        });
+    });
+    (0, vitest_1.describe)("promote packet", () => {
+        (0, vitest_1.it)("assigns Librarian role", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("promote", DEFAULT_CONFIG);
+            (0, vitest_1.expect)(packet.active_role).toBe("Librarian");
+        });
+        (0, vitest_1.it)("does not include a confidence_policy", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("promote", DEFAULT_CONFIG);
+            (0, vitest_1.expect)(packet.confidence_policy).toBeUndefined();
+        });
+        (0, vitest_1.it)("prohibits auto-promote without surfacing conflict report", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("promote", DEFAULT_CONFIG);
+            const prohibited = packet.prohibited_actions.join(" ");
+            (0, vitest_1.expect)(prohibited).toContain("Auto-promote");
+        });
+        (0, vitest_1.it)("prohibits calling --approve without user confirmation", () => {
+            const packet = (0, generator_js_1.generateSkillPacket)("promote", DEFAULT_CONFIG);
+            const prohibited = packet.prohibited_actions.join(" ");
+            (0, vitest_1.expect)(prohibited).toContain("--approve");
+        });
+    });
+    (0, vitest_1.it)("each packet has a unique packet_id", () => {
+        const p1 = (0, generator_js_1.generateSkillPacket)("analyze", DEFAULT_CONFIG);
+        const p2 = (0, generator_js_1.generateSkillPacket)("analyze", DEFAULT_CONFIG);
+        (0, vitest_1.expect)(p1.packet_id).not.toBe(p2.packet_id);
+    });
+});

package/dist/skill-packet/index.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSkillCommand = createSkillCommand;
+const commander_1 = require("commander");
+const loader_js_1 = require("../config/loader.js");
+const generator_js_1 = require("./generator.js");
+/**
+ * Create a top-level "skill" CLI command configured for safe, read-only skill packet operations.
+ *
+ * The returned command includes a "packet" subcommand that validates the requested skill, loads
+ * repository configuration (falling back to sensible defaults for `skill_packet`), generates a
+ * skill packet, and prints the resulting JSON to stdout. If an unknown skill is requested, the
+ * subcommand writes an error to stderr and exits with code 1.
+ *
+ * @param options - Options containing `repoRoot`, the repository root used to locate and load configuration
+ * @returns A configured Commander `Command` instance with the `packet` subcommand registered
+ */
+function createSkillCommand(options) {
+    const command = new commander_1.Command("skill")
+        .description("safe/read-only: skill packet operations")
+        .showHelpAfterError()
+        .action(() => {
+        command.outputHelp();
+    });
+    const packetCommand = new commander_1.Command("packet")
+        .description("safe/read-only: generate a Polaris skill packet for the given skill. " +
+        "Any documents produced during the session must be placed in smartdocs/raw/ first — never written directly to active tiers.")
+        .argument("<skill-name>", `skill to generate a packet for (${generator_js_1.SUPPORTED_SKILLS.join(", ")})`)
+        .action((skillName) => {
+        if (!generator_js_1.SUPPORTED_SKILLS.includes(skillName)) {
+            process.stderr.write(`Unknown skill: ${skillName}\nSupported skills: ${generator_js_1.SUPPORTED_SKILLS.join(", ")}\n`);
+            process.exit(1);
+        }
+        const config = (0, loader_js_1.loadConfig)(options.repoRoot);
+        const skillPacketConfig = config.skill_packet ?? {
+            analysis_confidence_threshold: 85,
+            auto_deep_analysis: false,
+            allow_cross_provider_delegation: false,
+        };
+        const packet = (0, generator_js_1.generateSkillPacket)(skillName, {
+            analysis_confidence_threshold: skillPacketConfig.analysis_confidence_threshold ?? 85,
+            auto_deep_analysis: skillPacketConfig.auto_deep_analysis ?? false,
+            allow_cross_provider_delegation: skillPacketConfig.allow_cross_provider_delegation ?? false,
+        });
+        process.stdout.write(`${JSON.stringify(packet, null, 2)}\n`);
+    });
+    command.addCommand(packetCommand);
+    return command;
+}

package/dist/skill-packet/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/smartdocs-engine/audit.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditIngestRiskSurface = auditIngestRiskSurface;
+exports.formatAuditMarkdown = formatAuditMarkdown;
+exports.formatAuditSummaryTable = formatAuditSummaryTable;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const smartdoc_ignore_js_1 = require("./smartdoc-ignore.js");
+const ingest_js_1 = require("./ingest.js");
+const GENERATED_BASENAME_RE = /(?:summary|index|moc|overview)(?:[._-]|$)/i;
+const GENERATED_SUFFIX_RE = /(?:-summary|-index)\.md$/i;
+function isGeneratedBasename(filePath) {
+    const base = (0, node_path_1.basename)(filePath);
+    return GENERATED_BASENAME_RE.test(base) || GENERATED_SUFFIX_RE.test(base);
+}
+function auditIngestRiskSurface(repoRoot) {
+    const absRoot = (0, node_path_1.resolve)(repoRoot);
+    let rawOutput;
+    try {
+        rawOutput = (0, node_child_process_1.execFileSync)("git", ["ls-files", "--", "*.md"], {
+            cwd: absRoot,
+            encoding: "utf-8",
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to list tracked markdown files via git: ${message}`);
+    }
+    const trackedFiles = rawOutput
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    const findings = [];
+    for (const relPath of trackedFiles) {
+        const absPath = (0, node_path_1.resolve)(absRoot, relPath);
+        const eligibility = (0, smartdoc_ignore_js_1.isIngestIneligible)(relPath, absRoot);
+        // MEDIUM: file is in smartdocs/ canonical output dirs
+        // Check this BEFORE the ineligible branch so these findings are always emitted
+        if (relPath.startsWith("smartdocs/")) {
+            const protection = eligibility.ineligible
+                ? "isIngestIneligible"
+                : null;
+            findings.push({
+                filePath: relPath,
+                risk: "MEDIUM",
+                reason: "File in smartdocs/ canonical output — migrateDocs() would attempt to move it back",
+                pipelineStage: "migrate",
+                currentProtection: protection,
+                proposedEnforcementPoint: "endpoint artifact protection in migrateDocs()",
+            });
+            // Don't continue yet - still need to check ineligible for HIGH findings
+        }
+        if (eligibility.ineligible) {
+            // HIGH: endpoint artifact that could be ingested
+            findings.push({
+                filePath: relPath,
+                risk: "HIGH",
+                reason: "Endpoint artifact matched by .smartdocignore default patterns — ingest would be blocked but file is tracked",
+                pipelineStage: "ingest",
+                currentProtection: "isIngestIneligible",
+                proposedEnforcementPoint: "smartdoc-ignore check in ingestDocs()",
+            });
+            // HIGH (second case): endpoint artifact that would classify as doctrine-candidate
+            if ((0, node_fs_1.existsSync)(absPath)) {
+                let content;
+                try {
+                    content = (0, node_fs_1.readFileSync)(absPath, "utf-8");
+                }
+                catch {
+                    content = "";
+                }
+                const classification = (0, ingest_js_1.classifyDoc)(content, relPath);
+                if (classification === "doctrine-candidate") {
+                    findings.push({
+                        filePath: relPath,
+                        risk: "HIGH",
+                        reason: "Endpoint artifact would be classified as doctrine-candidate — if bypass were used, it would enter doctrine pipeline",
+                        pipelineStage: "classify",
+                        currentProtection: "isIngestIneligible",
+                        proposedEnforcementPoint: "endpoint artifact check before classifyDoc()",
+                    });
+                }
+            }
+            continue;
+        }
+        // MEDIUM: generated summary/index/MOC/overview basename
+        if (isGeneratedBasename(relPath)) {
+            const protection = (0, smartdoc_ignore_js_1.isIngestIneligible)(relPath, absRoot).ineligible
+                ? "isIngestIneligible"
+                : null;
+            findings.push({
+                filePath: relPath,
+                risk: "MEDIUM",
+                reason: "Generated summary or index file — ingest risk if not protected",
+                pipelineStage: "ingest",
+                currentProtection: protection,
+                proposedEnforcementPoint: "smartdoc-ignore pattern or explicit check",
+            });
+        }
+    }
+    const high = findings.filter((f) => f.risk === "HIGH").length;
+    const medium = findings.filter((f) => f.risk === "MEDIUM").length;
+    const low = findings.filter((f) => f.risk === "LOW").length;
+    const protectedBySmartdocIgnore = findings.filter((f) => f.currentProtection === "isIngestIneligible").length;
+    return {
+        scanDate: new Date().toISOString(),
+        repoRoot: absRoot,
+        findings,
+        summary: {
+            high,
+            medium,
+            low,
+            protectedBySmartdocIgnore,
+            alreadyProtected: protectedBySmartdocIgnore,
+        },
+    };
+}
+function formatAuditMarkdown(result) {
+    const lines = [
+        "# Polaris Smart Docs — Ingest Risk Audit",
+        "",
+        `**Scanned:** ${result.repoRoot}`,
+        `**Date:** ${result.scanDate}`,
+        "",
+        `## Summary`,
+        "",
+        `| Risk | Count |`,
+        `|------|-------|`,
+        `| HIGH | ${result.summary.high} |`,
+        `| MEDIUM | ${result.summary.medium} |`,
+        `| LOW | ${result.summary.low} |`,
+        `| Protected by .smartdocignore | ${result.summary.protectedBySmartdocIgnore} |`,
+        "",
+    ];
+    const highFindings = result.findings.filter((f) => f.risk === "HIGH");
+    const mediumFindings = result.findings.filter((f) => f.risk === "MEDIUM");
+    const lowFindings = result.findings.filter((f) => f.risk === "LOW");
+    if (highFindings.length > 0) {
+        lines.push("## HIGH Risk Findings", "");
+        for (const f of highFindings) {
+            lines.push(`### \`${f.filePath}\``, "", `- **Reason:** ${f.reason}`, `- **Pipeline stage:** ${f.pipelineStage}`, `- **Current protection:** ${f.currentProtection ?? "none"}`, `- **Proposed enforcement:** ${f.proposedEnforcementPoint}`, "");
+        }
+    }
+    if (mediumFindings.length > 0) {
+        lines.push("## MEDIUM Risk Findings", "");
+        for (const f of mediumFindings) {
+            lines.push(`### \`${f.filePath}\``, "", `- **Reason:** ${f.reason}`, `- **Pipeline stage:** ${f.pipelineStage}`, `- **Current protection:** ${f.currentProtection ?? "none"}`, `- **Proposed enforcement:** ${f.proposedEnforcementPoint}`, "");
+        }
+    }
+    if (lowFindings.length > 0) {
+        lines.push("## LOW Risk Findings", "");
+        for (const f of lowFindings) {
+            lines.push(`### \`${f.filePath}\``, "", `- **Reason:** ${f.reason}`, `- **Pipeline stage:** ${f.pipelineStage}`, `- **Current protection:** ${f.currentProtection ?? "none"}`, `- **Proposed enforcement:** ${f.proposedEnforcementPoint}`, "");
+        }
+    }
+    if (result.findings.length === 0) {
+        lines.push("_No findings — no files at risk of recursive ingestion detected._", "");
+    }
+    return lines.join("\n");
+}
+function formatAuditSummaryTable(result) {
+    const lines = [
+        "Polaris Smart Docs — Ingest Risk Audit",
+        `Scanned: ${result.repoRoot}  Date: ${result.scanDate}`,
+        "",
+    ];
+    const highFindings = result.findings.filter((f) => f.risk === "HIGH");
+    const mediumFindings = result.findings.filter((f) => f.risk === "MEDIUM");
+    const lowFindings = result.findings.filter((f) => f.risk === "LOW");
+    if (highFindings.length > 0) {
+        lines.push(`HIGH (${highFindings.length}):`);
+        for (const f of highFindings) {
+            lines.push(`  ${f.filePath} — ${f.reason} [stage: ${f.pipelineStage}]`);
+        }
+        lines.push("");
+    }
+    if (mediumFindings.length > 0) {
+        lines.push(`MEDIUM (${mediumFindings.length}):`);
+        for (const f of mediumFindings) {
+            lines.push(`  ${f.filePath} — ${f.reason} [stage: ${f.pipelineStage}]`);
+        }
+        lines.push("");
+    }
+    if (lowFindings.length > 0) {
+        lines.push(`LOW (${lowFindings.length}):`);
+        for (const f of lowFindings) {
+            lines.push(`  ${f.filePath} — ${f.reason} [stage: ${f.pipelineStage}]`);
+        }
+        lines.push("");
+    }
+    lines.push("Summary:", `  High: ${result.summary.high}  Medium: ${result.summary.medium}  Low: ${result.summary.low}`, `  Protected by .smartdocignore: ${result.summary.protectedBySmartdocIgnore}`);
+    return lines.join("\n");
+}