@lsctech/polaris 0.1.0

package/dist/tracker/adapters/spec/index.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecAdapter = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const local_graph_js_1 = require("../../local-graph.js");
+const schema_js_1 = require("../../schema.js");
+const SECTION_HEADERS = {
+    objective: new Set(["objective"]),
+    scope: new Set(["scope", "expected code areas", "code areas", "files to change", "files"]),
+    validation: new Set(["validation", "validation commands", "test commands", "verify"]),
+    children: new Set(["children"]),
+};
+function slugifySegment(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function parseSections(markdown) {
+    const sections = new Map();
+    const parts = markdown.split(/^##\s+/m);
+    for (const part of parts) {
+        const lineBreak = part.indexOf("\n");
+        if (lineBreak === -1)
+            continue;
+        const header = part.slice(0, lineBreak).trim().toLowerCase();
+        const content = part.slice(lineBreak + 1);
+        sections.set(header, content);
+    }
+    return sections;
+}
+function parseList(content) {
+    return content
+        .split("\n")
+        .filter((line) => /^\s*[-*]\s+/.test(line))
+        .map((line) => line.replace(/^\s*[-*]\s+/, "").trim())
+        .filter(Boolean);
+}
+function readSectionText(sections, headers) {
+    for (const [header, content] of sections) {
+        if (headers.has(header)) {
+            return content.trim();
+        }
+    }
+    return "";
+}
+function readSectionList(sections, headers) {
+    for (const [header, content] of sections) {
+        if (headers.has(header)) {
+            return parseList(content);
+        }
+    }
+    return [];
+}
+function toChildId(index) {
+    return `spec-child-${String(index).padStart(2, "0")}`;
+}
+function createChildBody(title, scope, validation) {
+    const lines = [
+        "## Objective",
+        title,
+        "",
+    ];
+    if (scope.length > 0) {
+        lines.push("## Scope");
+        for (const scopeEntry of scope) {
+            lines.push(`- ${scopeEntry}`);
+        }
+        lines.push("");
+    }
+    if (validation.length > 0) {
+        lines.push("## Validation");
+        for (const command of validation) {
+            lines.push(`- ${command}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trim();
+}
+class SpecAdapter {
+    async syncIn(specPath) {
+        const raw = await (0, promises_1.readFile)(specPath, "utf-8");
+        const sections = parseSections(raw);
+        const objective = readSectionText(sections, SECTION_HEADERS.objective);
+        const scope = readSectionList(sections, SECTION_HEADERS.scope);
+        const validation = readSectionList(sections, SECTION_HEADERS.validation);
+        const childTitles = readSectionList(sections, SECTION_HEADERS.children);
+        if (!objective) {
+            throw new Error("Spec file is missing required section: ## Objective");
+        }
+        if (childTitles.length === 0) {
+            throw new Error("Spec file is missing required section content: ## Children");
+        }
+        const baseName = (0, node_path_1.basename)(specPath, (0, node_path_1.extname)(specPath));
+        const clusterSlug = slugifySegment(baseName) || "cluster";
+        const clusterId = `spec-${clusterSlug}`;
+        const rootNodeId = clusterId;
+        const nodes = {};
+        const dependencies = {};
+        const children = [];
+        nodes[rootNodeId] = {
+            id: rootNodeId,
+            title: objective,
+            status: "Todo",
+            body: raw.trim(),
+        };
+        for (const [index, childTitle] of childTitles.entries()) {
+            const childId = toChildId(index + 1);
+            children.push(childId);
+            nodes[childId] = {
+                id: childId,
+                title: childTitle,
+                status: "Todo",
+                sessionType: "implement",
+                body: createChildBody(childTitle, scope, validation),
+            };
+        }
+        const cluster = {
+            id: clusterId,
+            title: objective,
+            cluster_root: rootNodeId,
+            children,
+        };
+        const graph = schema_js_1.executionGraphV2Schema.parse({
+            schemaVersion: "v2",
+            source: {
+                id: specPath,
+                type: "spec",
+                analysis: {
+                    id: "spec-sync",
+                    doc: objective,
+                },
+            },
+            nodes,
+            dependencies,
+            clusters: {
+                [clusterId]: cluster,
+            },
+            activeCluster: clusterId,
+        });
+        return local_graph_js_1.LocalGraph.fromGraph(graph);
+    }
+}
+exports.SpecAdapter = SpecAdapter;

package/dist/tracker/capabilities.js

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

package/dist/tracker/index.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalFileAdapter = exports.LinearAdapter = exports.validateLifecyclePolicy = exports.getDefaultLifecyclePolicy = exports.resolveLifecycleTransition = void 0;
+exports.loadTrackerGraph = loadTrackerGraph;
+exports.loadTrackerAdapter = loadTrackerAdapter;
+const local_graph_js_1 = require("./local-graph.js");
+const index_js_1 = require("./adapters/linear/index.js");
+Object.defineProperty(exports, "LinearAdapter", { enumerable: true, get: function () { return index_js_1.LinearAdapter; } });
+const index_js_2 = require("./adapters/local-file/index.js");
+Object.defineProperty(exports, "LocalFileAdapter", { enumerable: true, get: function () { return index_js_2.LocalFileAdapter; } });
+var lifecycle_policy_js_1 = require("./lifecycle-policy.js");
+Object.defineProperty(exports, "resolveLifecycleTransition", { enumerable: true, get: function () { return lifecycle_policy_js_1.resolveLifecycleTransition; } });
+Object.defineProperty(exports, "getDefaultLifecyclePolicy", { enumerable: true, get: function () { return lifecycle_policy_js_1.getDefaultLifecyclePolicy; } });
+Object.defineProperty(exports, "validateLifecyclePolicy", { enumerable: true, get: function () { return lifecycle_policy_js_1.validateLifecyclePolicy; } });
+/**
+ * Loads the execution graph from the configured tracker.
+ *
+ * @param config The Polaris configuration.
+ * @param clusterId The ID of the cluster to load.
+ * @returns A promise that resolves to a graph instance, or null if no tracker is enabled.
+ */
+async function loadTrackerGraph(config, clusterId) {
+    if (config.tracker?.["local-file"]?.enabled) {
+        return local_graph_js_1.LocalGraph.load(clusterId);
+    }
+    if (config.tracker?.linear?.enabled) {
+        const linearAdapter = new index_js_1.LinearAdapter(config);
+        return linearAdapter.syncIn(clusterId);
+    }
+    return null;
+}
+/**
+ * Loads a tracker adapter instance based on the configuration.
+ *
+ * @param config The Polaris configuration.
+ * @returns A capable tracker adapter instance, or null if no tracker is configured.
+ */
+function loadTrackerAdapter(config) {
+    const adapterType = config.tracker?.adapter;
+    if (adapterType === "linear" && config.tracker?.linear?.enabled) {
+        return new index_js_1.LinearAdapter(config);
+    }
+    if (adapterType === "local" && config.tracker?.["local-file"]?.enabled) {
+        return new index_js_2.LocalFileAdapter();
+    }
+    // For "mcp-bridge" or other adapters, return null for now
+    // They can be added when their CapableTrackerAdapter implementations are ready
+    return null;
+}

package/dist/tracker/lifecycle-policy.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLifecycleTransition = resolveLifecycleTransition;
+exports.getDefaultLifecyclePolicy = getDefaultLifecyclePolicy;
+exports.validateLifecyclePolicy = validateLifecyclePolicy;
+/**
+ * Resolves lifecycle transitions based on policy configuration.
+ *
+ * This resolver provides tracker-agnostic lifecycle semantics by mapping
+ * Polaris execution events to normalized lifecycle states defined in config.
+ * Individual tracker adapters then map these normalized states to their
+ * native status names or return unsupported-transition results.
+ *
+ * @param event - The lifecycle transition event to resolve.
+ * @param policy - The tracker lifecycle policy from config.
+ * @returns A transition result with target state, skip behavior, and evidence requirements.
+ */
+function resolveLifecycleTransition(event, policy) {
+    const effectivePolicy = policy || getDefaultLifecyclePolicy();
+    switch (event) {
+        case "child-dispatch":
+            return {
+                targetState: effectivePolicy.childOnDispatch || "in_progress",
+                skip: false,
+                evidenceRequirements: [],
+            };
+        case "child-validation-passed":
+            return {
+                targetState: effectivePolicy.childOnValidationPassed || "in_review",
+                skip: false,
+                evidenceRequirements: ["validation_results", "worker_commit"],
+            };
+        case "child-merged":
+            return {
+                targetState: effectivePolicy.childOnMerged || "done",
+                skip: false,
+                evidenceRequirements: ["merge_commit_hash"],
+            };
+        case "parent-all-children-complete":
+            return {
+                targetState: effectivePolicy.parentOnAllChildrenComplete || "in_review",
+                skip: false,
+                evidenceRequirements: ["completed_children_summary"],
+            };
+        case "parent-delivery-merged":
+            return {
+                targetState: effectivePolicy.parentOnDeliveryMerged || "done",
+                skip: false,
+                evidenceRequirements: ["delivery_merge_commit_hash"],
+            };
+        case "child-triage-required":
+            return {
+                targetState: effectivePolicy.childOnTriageRequired || "blocked",
+                skip: false,
+                evidenceRequirements: ["triage_reason", "failure_details"],
+            };
+        case "provider-failure-before-work":
+            return {
+                targetState: effectivePolicy.providerFailureBeforeWork || "no_status_change",
+                skip: effectivePolicy.providerFailureBeforeWork === "no_status_change",
+                skipReason: effectivePolicy.providerFailureBeforeWork === "no_status_change"
+                    ? "Provider failure before repo work does not change implementation status"
+                    : undefined,
+                evidenceRequirements: ["failure_error", "provider_context"],
+            };
+        default:
+            // Unknown event - treat as no-op
+            return {
+                targetState: "no_status_change",
+                skip: true,
+                skipReason: `Unknown lifecycle event: ${event}`,
+                evidenceRequirements: [],
+            };
+    }
+}
+/**
+ * Returns the default lifecycle policy with review-gated behavior.
+ *
+ * Defaults preserve current behavior:
+ * - Validation-passed transitions to in_review (review-gated)
+ * - Parent completion transitions to in_review (review-gated)
+ * - Provider failures before work do not change status (avoid false failures)
+ */
+function getDefaultLifecyclePolicy() {
+    return {
+        childOnDispatch: "in_progress",
+        childOnValidationPassed: "in_review",
+        childOnMerged: "done",
+        parentOnAllChildrenComplete: "in_review",
+        parentOnDeliveryMerged: "done",
+        childOnTriageRequired: "blocked",
+        providerFailureBeforeWork: "no_status_change",
+    };
+}
+/**
+ * Validates a lifecycle policy value.
+ *
+ * @param policy - The policy to validate.
+ * @returns Validation result with errors if invalid.
+ */
+function validateLifecyclePolicy(policy) {
+    const errors = [];
+    if (!policy || typeof policy !== "object") {
+        return { valid: false, errors: ["Lifecycle policy must be an object"] };
+    }
+    if (Array.isArray(policy)) {
+        return { valid: false, errors: ["Lifecycle policy must be a plain object"] };
+    }
+    if (Object.getPrototypeOf(policy) !== Object.prototype) {
+        return { valid: false, errors: ["Lifecycle policy must be a plain object"] };
+    }
+    const validStates = [
+        "backlog",
+        "in_progress",
+        "in_review",
+        "done",
+        "blocked",
+        "cancelled",
+        "no_status_change",
+    ];
+    const policyObj = policy;
+    const validateField = (fieldName, value) => {
+        if (value !== undefined && typeof value !== "string") {
+            errors.push(`tracker.lifecyclePolicy.${fieldName} must be a string`);
+            return;
+        }
+        if (value !== undefined && !validStates.includes(value)) {
+            errors.push(`tracker.lifecyclePolicy.${fieldName} must be one of: ${validStates.join(", ")}`);
+        }
+    };
+    validateField("childOnDispatch", policyObj.childOnDispatch);
+    validateField("childOnValidationPassed", policyObj.childOnValidationPassed);
+    validateField("childOnMerged", policyObj.childOnMerged);
+    validateField("parentOnAllChildrenComplete", policyObj.parentOnAllChildrenComplete);
+    validateField("parentOnDeliveryMerged", policyObj.parentOnDeliveryMerged);
+    validateField("childOnTriageRequired", policyObj.childOnTriageRequired);
+    validateField("providerFailureBeforeWork", policyObj.providerFailureBeforeWork);
+    return { valid: errors.length === 0, errors };
+}

package/dist/tracker/lifecycle-transition.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleTransitionService = void 0;
+const lifecycle_policy_js_1 = require("./lifecycle-policy.js");
+/**
+ * Service for applying tracker lifecycle transitions with policy and capability awareness.
+ *
+ * This service integrates the lifecycle policy resolver with tracker adapter capabilities
+ * to ensure transitions are:
+ * - Policy-backed: transitions follow the configured lifecycle policy
+ * - Idempotent: skipped if the target state is already reached or unsupported
+ * - Evidence-backed: requires evidence for validation-passed and merged transitions
+ * - Safe: provider/runtime failures before work do not mark implementation failures by default
+ */
+class LifecycleTransitionService {
+    /**
+     * Applies a lifecycle transition using the provided adapter and policy.
+     *
+     * @param options - The transition options.
+     * @returns A transition attempt result.
+     */
+    async applyTransition(options) {
+        const { adapter, policy, taskId, event, evidence, timestamp } = options;
+        const effectiveTimestamp = timestamp ?? new Date().toISOString();
+        // Resolve the transition from policy
+        const policyResult = (0, lifecycle_policy_js_1.resolveLifecycleTransition)(event, policy);
+        // If policy says skip, return immediately
+        if (policyResult.skip) {
+            return {
+                event,
+                targetState: policyResult.targetState,
+                applied: false,
+                skipped: true,
+                skipReason: policyResult.skipReason,
+                evidence,
+                timestamp: effectiveTimestamp,
+            };
+        }
+        // If no adapter is configured, skip with reason
+        if (!adapter) {
+            return {
+                event,
+                targetState: policyResult.targetState,
+                applied: false,
+                skipped: true,
+                skipReason: "No tracker adapter configured",
+                evidence,
+                timestamp: effectiveTimestamp,
+            };
+        }
+        // Check if adapter supports lifecycle mapping
+        const capabilities = adapter.getCapabilities();
+        if (!capabilities.supportsLifecycleMapping) {
+            return {
+                event,
+                targetState: policyResult.targetState,
+                applied: false,
+                skipped: true,
+                skipReason: "Tracker adapter does not support lifecycle mapping",
+                evidence,
+                timestamp: effectiveTimestamp,
+            };
+        }
+        // Check if target state is no_status_change
+        if (policyResult.targetState === "no_status_change") {
+            return {
+                event,
+                targetState: policyResult.targetState,
+                applied: false,
+                skipped: true,
+                skipReason: "Policy specifies no status change for this event",
+                evidence,
+                timestamp: effectiveTimestamp,
+            };
+        }
+        // Build evidence record for the adapter
+        const adapterEvidence = {};
+        if (evidence?.commit)
+            adapterEvidence.commit = evidence.commit;
+        if (evidence?.resultFile)
+            adapterEvidence.resultFile = evidence.resultFile;
+        if (evidence?.packetFile)
+            adapterEvidence.packetFile = evidence.packetFile;
+        if (evidence?.validationResults)
+            adapterEvidence.validationResults = evidence.validationResults;
+        if (evidence?.error)
+            adapterEvidence.error = evidence.error;
+        if (evidence?.providerContext)
+            adapterEvidence.providerContext = evidence.providerContext;
+        // Attempt the transition through the adapter
+        try {
+            const adapterResult = await adapter.transitionLifecycleState(taskId, policyResult.targetState, adapterEvidence);
+            if (adapterResult.skipped) {
+                return {
+                    event,
+                    targetState: policyResult.targetState,
+                    applied: false,
+                    skipped: true,
+                    skipReason: adapterResult.skipReason ?? "Adapter skipped the transition",
+                    evidence,
+                    timestamp: effectiveTimestamp,
+                };
+            }
+            if (adapterResult.error) {
+                return {
+                    event,
+                    targetState: policyResult.targetState,
+                    applied: false,
+                    skipped: false,
+                    error: adapterResult.error,
+                    evidence,
+                    timestamp: effectiveTimestamp,
+                };
+            }
+            return {
+                event,
+                targetState: policyResult.targetState,
+                applied: adapterResult.applied,
+                skipped: false,
+                evidence,
+                timestamp: effectiveTimestamp,
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                event,
+                targetState: policyResult.targetState,
+                applied: false,
+                skipped: false,
+                error: `Adapter threw exception: ${errorMessage}`,
+                evidence,
+                timestamp: effectiveTimestamp,
+            };
+        }
+    }
+    /**
+     * Applies a lifecycle transition with a fallback to no-op if the adapter is not capable.
+     *
+     * This is a convenience method for cases where you want to attempt a transition
+     * but not fail if the adapter doesn't support it.
+     *
+     * @param options - The transition options.
+     * @returns A transition attempt result (never throws).
+     */
+    async applyTransitionSafe(options) {
+        try {
+            return await this.applyTransition(options);
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                event: options.event,
+                targetState: "no_status_change",
+                applied: false,
+                skipped: false,
+                error: `Transition service threw exception: ${errorMessage}`,
+                evidence: options.evidence,
+                timestamp: options.timestamp ?? new Date().toISOString(),
+            };
+        }
+    }
+}
+exports.LifecycleTransitionService = LifecycleTransitionService;

package/dist/tracker/local-graph.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalGraph = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const schema_js_1 = require("./schema.js");
+const types_js_1 = require("./types.js");
+const migration_js_1 = require("./migration.js");
+/**
+ * Represents the local execution graph, loaded from a `clusters.json` file.
+ * It handles both v1 and v2 formats, migrating v1 to v2 in memory.
+ */
+class LocalGraph {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    /**
+     * Loads an execution graph from the specified `clusters.json` file.
+     * It automatically detects the schema version and migrates v1 graphs to v2.
+     *
+     * @param clusterId The ID of the cluster to load (e.g., "POL-105").
+     * @param repoRoot The root directory of the repository.
+     * @returns A promise that resolves to a new `LocalGraph` instance.
+     */
+    static async load(clusterId, repoRoot = process.cwd()) {
+        const filePath = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "clusters.json");
+        const fileContent = await (0, promises_1.readFile)(filePath, "utf-8");
+        const rawGraph = JSON.parse(fileContent);
+        let v2Graph;
+        if ((0, types_js_1.isV2Graph)(rawGraph)) {
+            v2Graph = schema_js_1.executionGraphV2Schema.parse(rawGraph);
+        }
+        else {
+            const v1Graph = schema_js_1.executionGraphV1Schema.parse(rawGraph);
+            v2Graph = (0, migration_js_1.migrateV1toV2)(v1Graph);
+            // We can also validate the migrated graph to be safe
+            v2Graph = schema_js_1.executionGraphV2Schema.parse(v2Graph);
+        }
+        return new LocalGraph(v2Graph);
+    }
+    /**
+     * Creates a LocalGraph instance directly from an already-validated v2 graph.
+     * Use this when the graph has been built in memory (e.g., by a tracker adapter).
+     *
+     * @param graph A validated ExecutionGraphV2 object.
+     * @returns A new LocalGraph instance.
+     */
+    static fromGraph(graph) {
+        return new LocalGraph(graph);
+    }
+    /**
+     * Persists the graph to `.polaris/clusters/{clusterId}/clusters.json`.
+     * Creates the directory if it does not exist.
+     *
+     * @param clusterId The cluster ID to use as the directory name (e.g., "POL-198").
+     * @param repoRoot The root directory of the repository.
+     * @returns The absolute path of the written file.
+     */
+    async save(clusterId, repoRoot = process.cwd()) {
+        const dir = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId);
+        await (0, promises_1.mkdir)(dir, { recursive: true });
+        const filePath = node_path_1.default.join(dir, "clusters.json");
+        await (0, promises_1.writeFile)(filePath, JSON.stringify(this.graph, null, 2), "utf-8");
+        return filePath;
+    }
+    /**
+     * Returns the full v2 execution graph.
+     */
+    get fullGraph() {
+        return this.graph;
+    }
+    /**
+     * Returns the active cluster.
+     */
+    getActiveCluster() {
+        return this.graph.clusters[this.graph.activeCluster];
+    }
+    /**
+     * Returns a node by its ID.
+     * @param id The ID of the node to retrieve.
+     */
+    getNode(id) {
+        return this.graph.nodes[id];
+    }
+    /**
+     * Returns the dependencies for a given node.
+     * @param id The ID of the node to get dependencies for.
+     * @returns An array of node IDs that the given node is blocked by.
+     */
+    getDependencies(id) {
+        return this.graph.dependencies[id] ?? [];
+    }
+}
+exports.LocalGraph = LocalGraph;

package/dist/tracker/migration.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrateV1toV2 = migrateV1toV2;
+/**
+ * Migrates a v1 execution graph to a v2 execution graph.
+ *
+ * @param v1Graph The v1 execution graph to migrate.
+ * @returns The migrated v2 execution graph.
+ */
+function migrateV1toV2(v1Graph) {
+    if (!v1Graph.clusters || v1Graph.clusters.length === 0) {
+        throw new Error("Cannot migrate v1 execution graph: clusters array is empty or missing.");
+    }
+    const v2Graph = {
+        schemaVersion: "v2",
+        source: {
+            id: v1Graph.source_id,
+            type: v1Graph.source_type,
+        },
+        nodes: {},
+        dependencies: {},
+        clusters: {},
+        activeCluster: v1Graph.clusters[0]?.cluster_id ?? "default-cluster",
+    };
+    if (v1Graph.analyze_source_id) {
+        v2Graph.source.analysis = {
+            id: v1Graph.analyze_source_id,
+            doc: v1Graph.analysis_doc,
+        };
+    }
+    for (const v1Cluster of v1Graph.clusters) {
+        const childNodeIds = [];
+        for (const child of v1Cluster.children) {
+            childNodeIds.push(child.id);
+            // Add node to the normalized map
+            if (!v2Graph.nodes[child.id]) {
+                v2Graph.nodes[child.id] = {
+                    id: child.id,
+                    title: child.title,
+                    status: "Todo", // V1 doesn't have status, so default to Todo
+                    sessionType: child.session_type,
+                };
+            }
+            // Add dependencies
+            if (child.blockedBy.length > 0) {
+                v2Graph.dependencies[child.id] = child.blockedBy;
+            }
+        }
+        v2Graph.clusters[v1Cluster.cluster_id] = {
+            id: v1Cluster.cluster_id,
+            title: v1Cluster.description,
+            children: childNodeIds,
+        };
+    }
+    return v2Graph;
+}