@lsctech/polaris 0.1.0

package/dist/cognition/validate.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Cognition surface validation.
+ *
+ * Validates SUMMARY.md and POLARIS.md files for:
+ * - Oversized SUMMARY.md (exceeds byte cap)
+ * - Doctrine bleed in SUMMARY.md (operational imperatives belong in POLARIS.md)
+ * - POLARIS.md churn detection (trivial/non-operational changes)
+ * - Locality assumptions (route-local only, no repo-wide surface)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.looksLikePolarisChurn = looksLikePolarisChurn;
+exports.validateCognitionSurfaces = validateCognitionSurfaces;
+exports.validateSummaryFile = validateSummaryFile;
+exports.getSummaryFileSize = getSummaryFileSize;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const route_cognition_delta_js_1 = require("./route-cognition-delta.js");
+const summary_delta_js_1 = require("./summary-delta.js");
+// ── POLARIS.md churn detection ────────────────────────────────────────────────
+/**
+ * Signals that indicate a POLARIS.md change is likely non-operational churn
+ * (formatting, comments, tiny refactors).
+ * Returns true when the diff looks like churn.
+ */
+function looksLikePolarisChurn(before, after) {
+    // Normalize whitespace and comments for comparison
+    const normalize = (s) => s
+        .split("\n")
+        .map((l) => l.trimEnd())
+        .filter((l) => !l.startsWith("<!--") && l !== "")
+        .join("\n");
+    const a = normalize(before);
+    const b = normalize(after);
+    // If normalized content is identical, it's churn
+    if (a === b)
+        return true;
+    // If only whitespace/blank-line diff
+    if (before.replace(/\s+/g, " ").trim() === after.replace(/\s+/g, " ").trim())
+        return true;
+    return false;
+}
+// ── Walker ────────────────────────────────────────────────────────────────────
+function* walkForCognitionFiles(dir, repoRoot) {
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = (0, node_path_1.join)(dir, entry.name);
+        const rel = (0, node_path_1.relative)(repoRoot, full).replace(/\\/g, "/");
+        if (entry.isDirectory()) {
+            if ((0, route_cognition_delta_js_1.isCognitionSkippedFolder)(rel + "/") || (0, route_cognition_delta_js_1.isCognitionSkippedFolder)(rel))
+                continue;
+            yield* walkForCognitionFiles(full, repoRoot);
+        }
+        else if (entry.name === "SUMMARY.md" || entry.name === "POLARIS.md") {
+            yield { rel, name: entry.name };
+        }
+    }
+}
+// ── Main validation entry point ───────────────────────────────────────────────
+/**
+ * Validate all route-local cognition surfaces under repoRoot.
+ *
+ * Checks:
+ * 1. SUMMARY.md size guard (≤ SUMMARY_MAX_BYTES)
+ * 2. SUMMARY.md doctrine bleed
+ * 3. Locality: POLARIS.md at root is not flagged (root is special)
+ */
+function validateCognitionSurfaces(repoRoot) {
+    const violations = [];
+    const warnings = [];
+    for (const { rel, name } of walkForCognitionFiles((0, node_path_1.resolve)(repoRoot), repoRoot)) {
+        // Skip root-level files — root cognition is special (AGENTS.md / CLAUDE.md)
+        if (!rel.includes("/"))
+            continue;
+        let content;
+        try {
+            content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(repoRoot, rel), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        if (name === "SUMMARY.md") {
+            if ((0, summary_delta_js_1.isSummaryOversized)(content)) {
+                const bytes = Buffer.byteLength(content, "utf-8");
+                violations.push({
+                    type: "summary-oversized",
+                    file: rel,
+                    detail: `SUMMARY.md is ${bytes} bytes, exceeds limit of ${summary_delta_js_1.SUMMARY_MAX_BYTES} bytes`,
+                    severity: "error",
+                });
+            }
+            if ((0, summary_delta_js_1.hasDoctrineBled)(content)) {
+                // Doctrine bleed is WARN-only — never a hard blocker.
+                // Summaries may contain "do not" in quoted context.
+                warnings.push({
+                    type: "summary-doctrine-bleed",
+                    file: rel,
+                    detail: "SUMMARY.md may contain operational doctrine (section headings or imperatives); consider moving to POLARIS.md",
+                    severity: "warn",
+                });
+            }
+        }
+    }
+    return {
+        valid: violations.length === 0,
+        violations,
+        warnings,
+    };
+}
+// ── Targeted file validation ──────────────────────────────────────────────────
+/**
+ * Validate a single SUMMARY.md file by path (absolute or relative to repoRoot).
+ */
+function validateSummaryFile(summaryPath, repoRoot) {
+    const abs = summaryPath.startsWith("/") ? summaryPath : (0, node_path_1.resolve)(repoRoot, summaryPath);
+    const rel = (0, node_path_1.relative)(repoRoot, abs).replace(/\\/g, "/");
+    const results = [];
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)(abs, "utf-8");
+    }
+    catch {
+        return results;
+    }
+    if ((0, summary_delta_js_1.isSummaryOversized)(content)) {
+        const bytes = Buffer.byteLength(content, "utf-8");
+        results.push({
+            type: "summary-oversized",
+            file: rel,
+            detail: `SUMMARY.md is ${bytes} bytes, exceeds limit of ${summary_delta_js_1.SUMMARY_MAX_BYTES} bytes`,
+            severity: "error",
+        });
+    }
+    if ((0, summary_delta_js_1.hasDoctrineBled)(content)) {
+        // Warn-only — see hasDoctrineBled() docstring.
+        results.push({
+            type: "summary-doctrine-bleed",
+            file: rel,
+            detail: "SUMMARY.md may contain operational doctrine; consider moving to POLARIS.md",
+            severity: "warn",
+        });
+    }
+    return results;
+}
+/**
+ * Check file size on disk for a SUMMARY.md without reading full content.
+ */
+function getSummaryFileSize(summaryPath, repoRoot) {
+    const abs = (0, node_fs_1.existsSync)(summaryPath) ? summaryPath : (0, node_path_1.resolve)(repoRoot, summaryPath);
+    try {
+        return (0, node_fs_1.statSync)(abs).size;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/config/defaults.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.DEFAULT_CONFIG = {
+    version: "1.0",
+    repo: {
+        name: "",
+        sourceRoots: ["src"],
+        docsRoots: [],
+        taskchainRoots: [],
+        generatedRoots: [],
+        sidecarOutputPath: ".polaris/map",
+    },
+    map: {
+        confidenceThreshold: 0.75,
+        autoWriteAbove: 0.85,
+        reviewRequiredBelow: 0.75,
+        inferenceRules: [],
+        onLowConfidence: "warn",
+    },
+    loop: {
+        bootstrapOutputPath: ".polaris/bootstrap",
+        analyzeImplBoundaryEnforced: true,
+        sessionTerminationMode: "emit-marker",
+        allowBranchDivergence: false,
+    },
+    graph: {
+        outputPath: ".polaris/graph",
+        invalidationTriggers: ["repo-change", "config-change"],
+    },
+    orchestration: {
+        mode: "supervised",
+        auto_finalize: false,
+        notification_format: "terse",
+    },
+    execution: {
+        adapter: "terminal-cli",
+        providers: {},
+        rotation: [],
+        allowCrossAgentFallback: false,
+        roles: {},
+    },
+    finalize: {
+        targetBranch: "main",
+        prDraft: true,
+        runChecks: [],
+        requireMapValidation: true,
+        requireSchemaValidation: true,
+        archiveRunSnapshot: true,
+    },
+    tracker: {
+        lifecyclePolicy: {
+            childOnDispatch: "in_progress",
+            childOnValidationPassed: "in_review",
+            childOnMerged: "done",
+            parentOnAllChildrenComplete: "in_review",
+            parentOnDeliveryMerged: "done",
+            childOnTriageRequired: "blocked",
+            providerFailureBeforeWork: "no_status_change",
+        },
+        linear: {
+            enabled: false,
+            teamId: "",
+            projectId: "",
+        },
+    },
+    integrations: {
+        github: {
+            owner: "",
+            repo: "",
+        },
+    },
+    canon: {
+        checkOnContinue: true,
+        checkOnFinalize: true,
+    },
+    providers: {
+        repoAnalysis: {
+            preferred: undefined,
+            fallback: ["polaris-map", "ripgrep"],
+        },
+    },
+    budget: {
+        mode: "fixed-cap",
+        max_children: 6,
+        stop_on_fail: false,
+        allow_analyze_children: false,
+    },
+    compact: {
+        orchestratorMode: "standard",
+        workerMode: "standard",
+    },
+    skill_packet: {
+        analysis_confidence_threshold: 85,
+        auto_deep_analysis: false,
+        allow_cross_provider_delegation: false,
+    },
+};

package/dist/config/doctor.js

@@ -0,0 +1,273 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctor = runDoctor;
+exports.printDoctorReport = printDoctorReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const loader_js_1 = require("./loader.js");
+function checkConfigFile(repoRoot) {
+    const configPath = (0, node_path_1.resolve)(repoRoot, "polaris.config.json");
+    if (!(0, node_fs_1.existsSync)(configPath)) {
+        return {
+            id: "config-file-exists",
+            category: "config",
+            status: "warn",
+            message: "polaris.config.json not found",
+            detail: "Using default configuration. Create polaris.config.json to customize.",
+        };
+    }
+    try {
+        const raw = (0, node_fs_1.readFileSync)(configPath, "utf-8");
+        JSON.parse(raw);
+        return {
+            id: "config-file-exists",
+            category: "config",
+            status: "pass",
+            message: "polaris.config.json exists and is valid JSON",
+        };
+    }
+    catch (err) {
+        return {
+            id: "config-file-exists",
+            category: "config",
+            status: "fail",
+            message: "polaris.config.json is invalid JSON",
+            detail: err.message,
+        };
+    }
+}
+function checkConfigValidation(repoRoot) {
+    try {
+        (0, loader_js_1.loadConfig)(repoRoot);
+        return {
+            id: "config-validation",
+            category: "config",
+            status: "pass",
+            message: "Configuration passes validation",
+        };
+    }
+    catch (err) {
+        if (err instanceof loader_js_1.PolarisConfigError) {
+            return {
+                id: "config-validation",
+                category: "config",
+                status: "fail",
+                message: "Configuration validation failed",
+                detail: err.errors.join("\n"),
+            };
+        }
+        return {
+            id: "config-validation",
+            category: "config",
+            status: "fail",
+            message: "Configuration validation error",
+            detail: err.message,
+        };
+    }
+}
+function checkProviderConfig(config) {
+    const hasProviders = config.execution?.providers && Object.keys(config.execution.providers).length > 0;
+    if (!hasProviders) {
+        return {
+            id: "provider-config",
+            category: "provider",
+            status: "warn",
+            message: "No external providers configured",
+            detail: "External agent providers are optional. Configure execution.providers to use external agents.",
+        };
+    }
+    const providers = config.execution.providers;
+    const invalidProviders = Object.entries(providers).filter(([_, provider]) => {
+        return !provider.command || typeof provider.command !== "string" || provider.command.trim() === "";
+    });
+    if (invalidProviders.length > 0) {
+        return {
+            id: "provider-config",
+            category: "provider",
+            status: "fail",
+            message: "Some providers are misconfigured",
+            detail: `Providers missing valid command: ${invalidProviders.map(([name]) => name).join(", ")}`,
+        };
+    }
+    return {
+        id: "provider-config",
+        category: "provider",
+        status: "pass",
+        message: "External providers are configured",
+        detail: `Found ${Object.keys(providers).length} provider(s)`,
+    };
+}
+function checkTrackerConfig(config) {
+    const tracker = config.tracker;
+    if (!tracker) {
+        return {
+            id: "tracker-config",
+            category: "tracker",
+            status: "pass",
+            message: "No tracker configured (local mode)",
+            detail: "Tracker is optional. Polaris will operate in local-file mode.",
+        };
+    }
+    const hasAdapter = tracker.adapter;
+    if (!hasAdapter) {
+        return {
+            id: "tracker-config",
+            category: "tracker",
+            status: "pass",
+            message: "No tracker adapter configured (local mode)",
+            detail: "Tracker adapter is optional. Polaris will operate in local-file mode.",
+        };
+    }
+    if (tracker.adapter === "linear") {
+        const linearConfig = tracker.linear;
+        if (!linearConfig?.enabled) {
+            return {
+                id: "tracker-config",
+                category: "tracker",
+                status: "warn",
+                message: "Linear tracker adapter selected but not enabled",
+                detail: "Set tracker.linear.enabled to true to use Linear integration.",
+            };
+        }
+        if (!linearConfig.teamId || !linearConfig.projectId) {
+            return {
+                id: "tracker-config",
+                category: "tracker",
+                status: "warn",
+                message: "Linear tracker enabled but missing teamId or projectId",
+                detail: "Configure tracker.linear.teamId and tracker.linear.projectId for full Linear integration.",
+            };
+        }
+        return {
+            id: "tracker-config",
+            category: "tracker",
+            status: "pass",
+            message: "Linear tracker is configured",
+        };
+    }
+    if (tracker.adapter === "mcp-bridge") {
+        const mcpConfig = tracker.mcpBridge;
+        if (!mcpConfig?.enabled) {
+            return {
+                id: "tracker-config",
+                category: "tracker",
+                status: "warn",
+                message: "MCP bridge tracker adapter selected but not enabled",
+                detail: "Set tracker.mcpBridge.enabled to true to use MCP bridge integration.",
+            };
+        }
+        return {
+            id: "tracker-config",
+            category: "tracker",
+            status: "pass",
+            message: "MCP bridge tracker is configured",
+        };
+    }
+    if (tracker.adapter === "local") {
+        return {
+            id: "tracker-config",
+            category: "tracker",
+            status: "pass",
+            message: "Local file tracker adapter is configured",
+        };
+    }
+    return {
+        id: "tracker-config",
+        category: "tracker",
+        status: "warn",
+        message: "Unknown tracker adapter configured",
+        detail: `Adapter: ${tracker.adapter}`,
+    };
+}
+function checkArtifactHygiene(repoRoot) {
+    const polarisDir = (0, node_path_1.resolve)(repoRoot, ".polaris");
+    const taskchainDir = (0, node_path_1.resolve)(repoRoot, ".taskchain_artifacts");
+    const hasPolarisDir = (0, node_fs_1.existsSync)(polarisDir);
+    const hasTaskchainDir = (0, node_fs_1.existsSync)(taskchainDir);
+    if (!hasPolarisDir && !hasTaskchainDir) {
+        return {
+            id: "artifact-hygiene",
+            category: "artifact",
+            status: "pass",
+            message: "No Polaris artifact directories found",
+            detail: "This is expected for a fresh repository. Run 'polaris init' to set up.",
+        };
+    }
+    const issues = [];
+    if (hasPolarisDir) {
+        const runsDir = (0, node_path_1.resolve)(polarisDir, "runs");
+        if ((0, node_fs_1.existsSync)(runsDir)) {
+            issues.push(".polaris/runs directory exists (contains run artifacts)");
+        }
+    }
+    if (hasTaskchainDir) {
+        const runsDir = (0, node_path_1.resolve)(taskchainDir, "polaris-run", "runs");
+        if ((0, node_fs_1.existsSync)(runsDir)) {
+            issues.push(".taskchain_artifacts/polaris-run/runs directory exists (contains run artifacts)");
+        }
+    }
+    if (issues.length === 0) {
+        return {
+            id: "artifact-hygiene",
+            category: "artifact",
+            status: "pass",
+            message: "Artifact directories are clean",
+        };
+    }
+    return {
+        id: "artifact-hygiene",
+        category: "artifact",
+        status: "warn",
+        message: "Runtime artifacts present in repository",
+        detail: issues.join("\n"),
+    };
+}
+function runDoctor(repoRoot) {
+    const checks = [];
+    // Config checks
+    checks.push(checkConfigFile(repoRoot));
+    checks.push(checkConfigValidation(repoRoot));
+    // Provider checks (only if config loaded successfully)
+    try {
+        const config = (0, loader_js_1.loadConfig)(repoRoot);
+        checks.push(checkProviderConfig(config));
+        checks.push(checkTrackerConfig(config));
+    }
+    catch {
+        // Skip provider/tracker checks if config failed to load
+    }
+    // Artifact checks
+    checks.push(checkArtifactHygiene(repoRoot));
+    const summary = {
+        pass: checks.filter((c) => c.status === "pass").length,
+        warn: checks.filter((c) => c.status === "warn").length,
+        fail: checks.filter((c) => c.status === "fail").length,
+    };
+    return { checks, summary };
+}
+function printDoctorReport(report) {
+    const { checks, summary } = report;
+    // Print summary
+    console.log("\n=== Polaris Configuration Doctor ===\n");
+    console.log(`Summary: ${summary.pass} passed, ${summary.warn} warnings, ${summary.fail} failed\n`);
+    // Group checks by category
+    const categories = ["config", "provider", "tracker", "artifact"];
+    for (const category of categories) {
+        const categoryChecks = checks.filter((c) => c.category === category);
+        if (categoryChecks.length === 0)
+            continue;
+        console.log(`[${category.toUpperCase()}]`);
+        for (const check of categoryChecks) {
+            const statusSymbol = check.status === "pass" ? "✓" : check.status === "warn" ? "⚠" : "✗";
+            console.log(`  ${statusSymbol} ${check.message}`);
+            if (check.detail) {
+                console.log(`    ${check.detail}`);
+            }
+        }
+        console.log();
+    }
+    // Exit with error code if any checks failed
+    if (summary.fail > 0) {
+        process.exit(1);
+    }
+}

package/dist/config/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printDoctorReport = exports.runDoctor = exports.runConfigDoctor = exports.runConfigShow = exports.getResolvedConfigJson = exports.createConfigCommand = exports.PolarisConfigError = exports.loadConfig = void 0;
+var loader_js_1 = require("./loader.js");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return loader_js_1.loadConfig; } });
+Object.defineProperty(exports, "PolarisConfigError", { enumerable: true, get: function () { return loader_js_1.PolarisConfigError; } });
+var show_js_1 = require("./show.js");
+Object.defineProperty(exports, "createConfigCommand", { enumerable: true, get: function () { return show_js_1.createConfigCommand; } });
+Object.defineProperty(exports, "getResolvedConfigJson", { enumerable: true, get: function () { return show_js_1.getResolvedConfigJson; } });
+Object.defineProperty(exports, "runConfigShow", { enumerable: true, get: function () { return show_js_1.runConfigShow; } });
+Object.defineProperty(exports, "runConfigDoctor", { enumerable: true, get: function () { return show_js_1.runConfigDoctor; } });
+var doctor_js_1 = require("./doctor.js");
+Object.defineProperty(exports, "runDoctor", { enumerable: true, get: function () { return doctor_js_1.runDoctor; } });
+Object.defineProperty(exports, "printDoctorReport", { enumerable: true, get: function () { return doctor_js_1.printDoctorReport; } });

package/dist/config/loader.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolarisConfigError = void 0;
+exports.loadConfig = loadConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const defaults_js_1 = require("./defaults.js");
+const validator_js_1 = require("./validator.js");
+class PolarisConfigError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.name = "PolarisConfigError";
+        this.errors = errors;
+    }
+}
+exports.PolarisConfigError = PolarisConfigError;
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const srcVal = source[key];
+        const tgtVal = result[key];
+        if (typeof srcVal === "object" &&
+            srcVal !== null &&
+            !Array.isArray(srcVal) &&
+            typeof tgtVal === "object" &&
+            tgtVal !== null &&
+            !Array.isArray(tgtVal)) {
+            result[key] = deepMerge(tgtVal, srcVal);
+        }
+        else if (srcVal !== undefined) {
+            result[key] = srcVal;
+        }
+    }
+    return result;
+}
+function loadConfig(repoRoot) {
+    const configPath = (0, node_path_1.resolve)(repoRoot, "polaris.config.json");
+    let userConfig = {};
+    try {
+        const raw = (0, node_fs_1.readFileSync)(configPath, "utf-8");
+        userConfig = JSON.parse(raw);
+    }
+    catch (err) {
+        const isEnoent = typeof err === "object" &&
+            err !== null &&
+            "code" in err &&
+            err.code === "ENOENT";
+        if (!isEnoent) {
+            throw new PolarisConfigError(`Failed to read polaris.config.json: ${err.message ?? String(err)}`, []);
+        }
+    }
+    const validation = (0, validator_js_1.validateConfig)(userConfig);
+    if (!validation.valid) {
+        throw new PolarisConfigError(`Invalid polaris.config.json:\n${validation.errors.join("\n")}`, validation.errors);
+    }
+    return deepMerge(defaults_js_1.DEFAULT_CONFIG, userConfig);
+}

package/dist/config/provider-detect.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectCaveman = detectCaveman;
+exports.detectGitNexus = detectGitNexus;
+exports.detectCompactionProviders = detectCompactionProviders;
+exports.detectRepoAnalysisProviders = detectRepoAnalysisProviders;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+/**
+ * Detects whether the Caveman compaction provider is available.
+ *
+ * Caveman is considered present when `.polaris/skills/caveman/SKILL.md`
+ * exists in the repository root (canonical location). Falls back to
+ * `.codex/skills/caveman/SKILL.md` for backwards compatibility.
+ */
+function detectCaveman(repoRoot) {
+    return ((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, ".polaris", "skills", "caveman", "SKILL.md")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, ".codex", "skills", "caveman", "SKILL.md")));
+}
+/**
+ * Detects whether the GitNexus compaction provider is available.
+ *
+ * GitNexus is considered present when the `gitnexus` executable is
+ * found on PATH (cross-platform: uses `where` on Windows, `which` on Unix).
+ */
+function detectGitNexus() {
+    try {
+        const command = process.platform === "win32" ? "where" : "which";
+        (0, node_child_process_1.execFileSync)(command, ["gitnexus"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Runs all provider detections and returns the list of detected providers
+ * as an array of strings.  Returns an empty array when none are detected.
+ *
+ * Recognised provider names: "caveman", "gitnexus".
+ */
+function detectCompactionProviders(repoRoot) {
+    const detected = [];
+    if (detectCaveman(repoRoot)) {
+        detected.push("caveman");
+    }
+    if (detectGitNexus()) {
+        detected.push("gitnexus");
+    }
+    return detected;
+}
+/**
+ * Runs repo-analysis provider detection and returns detected provider IDs.
+ *
+ * Recognised repo-analysis provider names: "gitnexus".
+ */
+function detectRepoAnalysisProviders() {
+    return detectGitNexus() ? ["gitnexus"] : [];
+}