@lsctech/polaris 0.1.0

package/dist/finalize/linear.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNotDoneState = assertNotDoneState;
+exports.findReviewState = findReviewState;
+exports.postLinearComment = postLinearComment;
+exports.updateLinearIssueAfterFinalize = updateLinearIssueAfterFinalize;
+const node_https_1 = require("node:https");
+const lifecycle_policy_js_1 = require("../tracker/lifecycle-policy.js");
+// ──────────────────────────────────────────────────────────────────────────────
+// Review-gate policy
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * State types that finalize is PROHIBITED from transitioning to.
+ * Human review is the ONLY authority for Done/Closed transitions.
+ */
+const DONE_STATE_TYPES = new Set(["completed", "canceled", "cancelled"]);
+/**
+ * Guard: throws if the given state type corresponds to Done or Closed.
+ * Called before every issueUpdate — prevents any future code from silently
+ * adding a Done-transition path.
+ */
+function assertNotDoneState(stateType, stateName) {
+    if (DONE_STATE_TYPES.has(stateType.toLowerCase())) {
+        throw new Error(`[Linear review-gate] Finalize is prohibited from transitioning issues to Done or Closed states. ` +
+            `Attempted: "${stateName}" (type: "${stateType}"). ` +
+            `Only human review may mark issues as Done/Closed.`);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Internal HTTP helper
+// ──────────────────────────────────────────────────────────────────────────────
+async function linearGraphQL(query, variables, apiKey) {
+    const payload = JSON.stringify({ query, variables });
+    return new Promise((resolve, reject) => {
+        const req = (0, node_https_1.request)({
+            hostname: "api.linear.app",
+            path: "/graphql",
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: apiKey,
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                if ((res.statusCode ?? 0) >= 400) {
+                    reject(new Error(`Linear API returned ${res.statusCode}`));
+                    return;
+                }
+                try {
+                    const text = Buffer.concat(chunks).toString("utf-8");
+                    const parsed = JSON.parse(text);
+                    if (parsed.errors && Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+                        reject(new Error(`Linear API GraphQL errors: ${JSON.stringify(parsed.errors)}`));
+                    }
+                    else {
+                        resolve(parsed.data);
+                    }
+                }
+                catch (err) {
+                    reject(new Error(`Failed to parse Linear API response: ${err instanceof Error ? err.message : String(err)}`));
+                }
+            });
+        });
+        req.on("error", reject);
+        req.write(payload);
+        req.end();
+    });
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Review-state discovery
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Finds an "In Review" workflow state for the issue's team.
+ * Matches by state type === "review" first, then by name ("In Review" / "Review").
+ * Returns null if the issue has no team or no review-type state exists.
+ */
+async function findReviewState(issueId, apiKey) {
+    const issueData = await linearGraphQL(`query GetIssueTeam($id: String!) { issue(id: $id) { team { id } } }`, { id: issueId }, apiKey);
+    const teamId = issueData.issue?.team?.id;
+    if (!teamId)
+        return null;
+    const statesData = await linearGraphQL(`query GetWorkflowStates($teamId: String!) {
+      workflowStates(filter: { team: { id: { eq: $teamId } } }) {
+        nodes { id name type }
+      }
+    }`, { teamId }, apiKey);
+    const states = statesData.workflowStates?.nodes ?? [];
+    return (states.find((s) => s.type.toLowerCase() === "review") ??
+        states.find((s) => /^in\s+review$/i.test(s.name) || /^review$/i.test(s.name)) ??
+        null);
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Comment body builder
+// ──────────────────────────────────────────────────────────────────────────────
+function buildCommentBody(opts) {
+    const lines = [
+        `**polaris finalize complete** — run \`${opts.state.run_id}\``,
+        ``,
+        `| Field | Value |`,
+        `|---|---|`,
+        `| Branch | \`${opts.branch}\` |`,
+        `| PR | ${opts.prUrl} |`,
+        `| Children completed | ${opts.state.completed_children.length} |`,
+        `| Map validation | ${opts.validationPassed ? "✓ passed" : "✗ failed"} |`,
+    ];
+    if (opts.reviewStateMissing) {
+        lines.push(``, `> ⚠️ No "In Review" workflow state found for this issue's team — issue state was not updated automatically. Transition manually if needed.`);
+    }
+    return lines.join("\n");
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────────────────────────────────────
+/** Posts a finalize-complete comment without attempting a state transition. */
+async function postLinearComment(options) {
+    const { issueId, state, branch, prUrl, validationPassed, apiKey } = options;
+    const body = buildCommentBody({ state, branch, prUrl, validationPassed, reviewStateMissing: false });
+    const data = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
+      commentCreate(input: { issueId: $issueId, body: $body }) { success }
+    }`, { issueId, body }, apiKey);
+    if (data.commentCreate?.success !== true) {
+        throw new Error(`Linear commentCreate failed: ${JSON.stringify(data.commentCreate)}`);
+    }
+}
+/**
+ * Full post-finalize Linear update (review-gate policy):
+ *
+ * 1. Resolves the lifecycle policy for parent-all-children-complete event.
+ * 2. If policy says skip (e.g., no_status_change), skips state transition.
+ * 3. Otherwise, queries the issue's team for an "In Review" workflow state.
+ * 4. If found — calls issueUpdate to transition (NEVER to Done/Closed).
+ * 5. If not found — skips state transition; comment body notes the missing state.
+ * 6. Always posts a finalize-complete comment.
+ *
+ * POLICY: This function must NEVER call issueUpdate with a Done or Closed
+ * state ID. The assertNotDoneState guard enforces this at runtime.
+ */
+async function updateLinearIssueAfterFinalize(options) {
+    const { issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy } = options;
+    // Resolve lifecycle transition from policy
+    const lifecycleTransition = (0, lifecycle_policy_js_1.resolveLifecycleTransition)("parent-all-children-complete", lifecyclePolicy);
+    // If policy says skip, skip the state transition entirely
+    if (lifecycleTransition.skip) {
+        console.log(`[Linear] Skipping lifecycle transition for ${issueId}: ${lifecycleTransition.skipReason}`);
+        const body = buildCommentBody({
+            state,
+            branch,
+            prUrl,
+            validationPassed,
+            reviewStateMissing: false,
+        });
+        const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
+        commentCreate(input: { issueId: $issueId, body: $body }) { success }
+      }`, { issueId, body }, apiKey);
+        if (commentData.commentCreate?.success !== true) {
+            throw new Error(`Linear commentCreate failed: ${JSON.stringify(commentData.commentCreate)}`);
+        }
+        return;
+    }
+    // Only attempt state transition when the policy maps to the "in_review" normalized state.
+    // Other normalized states (e.g. "done", "no_status_change") are not handled by this function.
+    const targetState = lifecycleTransition.targetState;
+    if (targetState !== "in_review") {
+        console.log(`[Linear] Skipping lifecycle transition for ${issueId}: target state "${targetState}" is not handled by Linear finalize`);
+        const body = buildCommentBody({
+            state,
+            branch,
+            prUrl,
+            validationPassed,
+            reviewStateMissing: false,
+        });
+        const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
+        commentCreate(input: { issueId: $issueId, body: $body }) { success }
+      }`, { issueId, body }, apiKey);
+        if (commentData.commentCreate?.success !== true) {
+            throw new Error(`Linear commentCreate failed: ${JSON.stringify(commentData.commentCreate)}`);
+        }
+        return;
+    }
+    let reviewState = null;
+    try {
+        reviewState = await findReviewState(issueId, apiKey);
+    }
+    catch (err) {
+        // Log the error so auth/network/GraphQL failures are visible, then fall back to comment-only
+        console.error(`[Linear] findReviewState failed for issue ${issueId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (reviewState !== null) {
+        // Enforce review-gate: must never transition to Done or Closed.
+        assertNotDoneState(reviewState.type, reviewState.name);
+        const updateData = await linearGraphQL(`mutation UpdateIssueState($id: String!, $stateId: String!) {
+        issueUpdate(id: $id, input: { stateId: $stateId }) { success }
+      }`, { id: issueId, stateId: reviewState.id }, apiKey);
+        if (updateData.issueUpdate?.success !== true) {
+            throw new Error(`Linear issueUpdate failed: ${JSON.stringify(updateData.issueUpdate)}`);
+        }
+    }
+    const body = buildCommentBody({
+        state,
+        branch,
+        prUrl,
+        validationPassed,
+        reviewStateMissing: reviewState === null,
+    });
+    const commentData = await linearGraphQL(`mutation CreateComment($issueId: String!, $body: String!) {
+      commentCreate(input: { issueId: $issueId, body: $body }) { success }
+    }`, { issueId, body }, apiKey);
+    if (commentData.commentCreate?.success !== true) {
+        throw new Error(`Linear commentCreate failed: ${JSON.stringify(commentData.commentCreate)}`);
+    }
+}

package/dist/finalize/run-report.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRunReport = generateRunReport;
+function generateRunReport(data) {
+    const { state, branch, validationPassed, prUrl, artifacts, notes } = data;
+    const total = state.completed_children.length + state.open_children.length;
+    const completedCount = state.completed_children.length;
+    const childRows = state.completed_children
+        .map((id) => `| ${id} | — | — | Done |`)
+        .concat(state.open_children.map((id) => `| ${id} | — | — | Open |`))
+        .join("\n");
+    const artifactList = artifacts && artifacts.length > 0
+        ? artifacts.map((a) => `- ${a}`).join("\n")
+        : "- current-state.json\n- run-report.md";
+    const notesList = notes && notes.length > 0
+        ? notes.map((n) => `- ${n}`).join("\n")
+        : "_None_";
+    const blockerNote = state.blocker
+        ? `\n**Blocker:** ${state.blocker.reason} (child: ${state.blocker.child_id})\n`
+        : "";
+    return `# Run Report: ${state.run_id}
+
+**Status:** ${state.status}
+**Branch:** ${branch}
+**PR:** ${prUrl ?? "TBD — set at delivery step 9"}
+**Children completed:** ${completedCount} of ${total}
+**Validation:** ${validationPassed ? "passed" : "failed"}
+${blockerNote}
+## Children
+
+| ID | Title | Commit | Status |
+|---|---|---|---|
+${childRows || "_No children recorded_"}
+
+## Artifacts produced
+
+${artifactList}
+
+## Validation summary
+
+${validationPassed ? "Map validate passed. Schema validate passed." : "One or more validations failed — see step output above."}
+
+## Notes
+
+${notesList}
+`;
+}

package/dist/finalize/steps/01-map-update.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepMapUpdate = stepMapUpdate;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+function stepMapUpdate(repoRoot) {
+    const result = (0, node_child_process_1.spawnSync)(process.execPath, [(0, node_path_1.resolve)(repoRoot, "dist/cli/index.js"), "map", "update", "--changed"], { cwd: repoRoot, encoding: "utf-8", stdio: "inherit" });
+    if (result.status !== 0) {
+        process.stderr.write("Warning: map update --changed failed; proceeding to validate.\n");
+    }
+}

package/dist/finalize/steps/02-map-validate.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepMapValidate = stepMapValidate;
+const validate_js_1 = require("../../map/validate.js");
+function stepMapValidate(repoRoot) {
+    const result = (0, validate_js_1.runMapValidate)(repoRoot, 30);
+    if (result.hasError) {
+        process.stderr.write("finalize aborted: map validation failed — run polaris map validate for details\n");
+        process.exit(1);
+    }
+}

package/dist/finalize/steps/03-schema-validate.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepSchemaValidate = stepSchemaValidate;
+const checkpoint_js_1 = require("../../loop/checkpoint.js");
+function stepSchemaValidate(state) {
+    const errors = (0, checkpoint_js_1.validateState)(state);
+    if (errors.length > 0) {
+        process.stderr.write(`finalize aborted: current-state.json schema invalid:\n${errors.join("\n")}\n`);
+        process.exit(1);
+    }
+}

package/dist/finalize/steps/04-run-checks.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepRunChecks = stepRunChecks;
+const node_child_process_1 = require("node:child_process");
+function parseShellArgs(cmdLine) {
+    const args = [];
+    let current = "";
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    let escaped = false;
+    for (let i = 0; i < cmdLine.length; i++) {
+        const char = cmdLine[i];
+        if (escaped) {
+            current += char;
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (char === "'" && !inDoubleQuote) {
+            inSingleQuote = !inSingleQuote;
+            continue;
+        }
+        if (char === '"' && !inSingleQuote) {
+            inDoubleQuote = !inDoubleQuote;
+            continue;
+        }
+        if (char === " " && !inSingleQuote && !inDoubleQuote) {
+            if (current.length > 0) {
+                args.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (current.length > 0) {
+        args.push(current);
+    }
+    return args;
+}
+function normalizeGitPath(filePath) {
+    return filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function getStagedPaths(repoRoot) {
+    const output = (0, node_child_process_1.execFileSync)("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR"], {
+        cwd: repoRoot,
+        encoding: "utf-8",
+    });
+    return output
+        .split("\n")
+        .map((line) => normalizeGitPath(line.trim()))
+        .filter(Boolean);
+}
+function isBlockedDeliveryPath(filePath) {
+    return (filePath.startsWith(".taskchain_artifacts/")
+        || filePath.endsWith(".bak")
+        || filePath.startsWith(".polaris/runs/"));
+}
+function isForeignClusterArtifact(filePath, activeClusterId) {
+    if (!activeClusterId) {
+        return false;
+    }
+    const match = /^\.polaris\/clusters\/([^/]+)\//.exec(filePath);
+    return Boolean(match && match[1] !== activeClusterId);
+}
+function formatPathList(paths) {
+    return paths.map((filePath) => ` - ${filePath}`).join("\n");
+}
+function runStagedArtifactPreflight(repoRoot, options) {
+    if (options.skipDelivery) {
+        console.log("[4/13] Skipping staged delivery artifact check (--skip-delivery).");
+        return;
+    }
+    const stagedPaths = getStagedPaths(repoRoot);
+    if (stagedPaths.length === 0) {
+        return;
+    }
+    const blockedPaths = stagedPaths.filter(isBlockedDeliveryPath);
+    const foreignClusterPaths = stagedPaths.filter((filePath) => isForeignClusterArtifact(filePath, options.activeClusterId));
+    if (foreignClusterPaths.length > 0) {
+        console.warn([
+            "finalize warning: staged artifacts from other clusters detected:",
+            formatPathList(foreignClusterPaths),
+            `Corrective action: keep only active cluster ${options.activeClusterId ?? "<unknown>"} artifacts staged for delivery, or unstage these paths with 'git restore --staged <path>'.`,
+        ].join("\n"));
+    }
+    if (blockedPaths.length > 0) {
+        process.stderr.write([
+            "finalize aborted: staged delivery-blocked paths detected:",
+            formatPathList(blockedPaths),
+            "Corrective action: unstage these paths with 'git restore --staged <path>' (or remove them) before rerunning finalize delivery.",
+        ].join("\n") + "\n");
+        process.exit(1);
+    }
+}
+function stepRunChecks(repoRoot, checks, options = {}) {
+    for (const check of checks) {
+        const argv = parseShellArgs(check);
+        const cmd = argv[0];
+        if (!cmd)
+            continue;
+        const args = argv.slice(1);
+        const result = (0, node_child_process_1.spawnSync)(cmd, args, {
+            cwd: repoRoot,
+            encoding: "utf-8",
+            stdio: "inherit",
+            shell: false,
+        });
+        if (result.status !== 0) {
+            process.stderr.write(`finalize aborted: check failed: ${check}\n`);
+            process.exit(1);
+        }
+    }
+    runStagedArtifactPreflight(repoRoot, options);
+}

package/dist/finalize/steps/05-generate-report.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepGenerateReport = stepGenerateReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const run_report_js_1 = require("../run-report.js");
+function stepGenerateReport(repoRoot, state, branch, validationPassed) {
+    const reportPath = (0, node_path_1.resolve)(repoRoot, ".polaris", "runs", "run-report.md");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(reportPath), { recursive: true });
+    const content = (0, run_report_js_1.generateRunReport)({ state, branch, validationPassed });
+    (0, node_fs_1.writeFileSync)(reportPath, content, "utf-8");
+    console.log(`Run report written: ${reportPath}`);
+    return reportPath;
+}

package/dist/finalize/steps/06-commit.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepCommit = stepCommit;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const artifact_policy_js_1 = require("../artifact-policy.js");
+function stepCommit(repoRoot, state, _stateFile, _reportPath) {
+    const msg = `polaris finalize: ${state.run_id}\n\nChildren: ${state.completed_children.length} completed\nBranch: ${getBranch(repoRoot)}`;
+    const promotedTargets = (0, artifact_policy_js_1.getArtifactPromotionStageTargets)(state.cluster_id)
+        .filter((target) => (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, target)));
+    if (promotedTargets.length > 0) {
+        (0, node_child_process_1.execFileSync)("git", ["add", "--", ...promotedTargets], { cwd: repoRoot, stdio: "inherit" });
+    }
+    const stagedPaths = (0, node_child_process_1.execFileSync)("git", ["diff", "--cached", "--name-only"], {
+        cwd: repoRoot,
+        encoding: "utf-8",
+    }).trim().split("\n").filter(Boolean);
+    const blockedArtifacts = (0, artifact_policy_js_1.findArtifactPromotionViolations)(stagedPaths, state.cluster_id)
+        .map((violation) => violation.path);
+    if (blockedArtifacts.length > 0) {
+        (0, node_child_process_1.execFileSync)("git", ["restore", "--staged", "--", ...blockedArtifacts], { cwd: repoRoot, stdio: "inherit" });
+    }
+    (0, node_child_process_1.execFileSync)("git", ["commit", "--allow-empty", "-m", msg], { cwd: repoRoot, stdio: "inherit" });
+    const sha = (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf-8" }).trim();
+    console.log(`Finalize commit: ${sha}`);
+    return sha;
+}
+function getBranch(repoRoot) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/finalize/steps/07-push.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepPush = stepPush;
+const node_child_process_1 = require("node:child_process");
+function stepPush(repoRoot, branch) {
+    (0, node_child_process_1.execFileSync)("git", ["push", "-u", "origin", branch], {
+        cwd: repoRoot,
+        stdio: "inherit",
+    });
+}

package/dist/finalize/steps/08-create-pr.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepCreatePr = stepCreatePr;
+const github_js_1 = require("../github.js");
+function stepCreatePr(repoRoot, branch, state, draft) {
+    const prUrl = (0, github_js_1.createDraftPr)({ repoRoot, branch, state, draft });
+    console.log(`PR created: ${prUrl}`);
+    return prUrl;
+}

package/dist/finalize/steps/09-update-state.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepUpdateState = stepUpdateState;
+const checkpoint_js_1 = require("../../loop/checkpoint.js");
+function stepUpdateState(stateFile, state, prUrl) {
+    const updated = { ...state, pr_url: prUrl, status: "complete" };
+    (0, checkpoint_js_1.writeStateAtomic)(stateFile, updated);
+    return updated;
+}

package/dist/finalize/steps/10-append-jsonl.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepAppendJsonl = stepAppendJsonl;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function stepAppendJsonl(telemetryFile, state, prUrl) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    const ts = new Date().toISOString();
+    const prOpened = {
+        event: "pr-opened",
+        run_id: state.run_id,
+        pr_url: prUrl,
+        timestamp: ts,
+    };
+    const runComplete = {
+        event: "run-complete",
+        run_id: state.run_id,
+        children_completed: state.completed_children.length,
+        timestamp: ts,
+    };
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(prOpened) + "\n", "utf-8");
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(runComplete) + "\n", "utf-8");
+}

package/dist/finalize/steps/11-update-linear.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepUpdateLinear = stepUpdateLinear;
+const linear_js_1 = require("../linear.js");
+async function stepUpdateLinear(state, branch, prUrl, validationPassed, linearEnabled, parentIssueId, lifecyclePolicy) {
+    if (!linearEnabled) {
+        console.log("[11/12] Linear integration disabled — skipping.");
+        return;
+    }
+    const apiKey = process.env["LINEAR_API_KEY"];
+    if (!apiKey) {
+        process.stderr.write("Warning: LINEAR_API_KEY not set — skipping Linear update.\n");
+        return;
+    }
+    const issueId = parentIssueId ?? state.cluster_id;
+    if (!issueId) {
+        process.stderr.write("Warning: no Linear parent issue ID — skipping Linear update.\n");
+        return;
+    }
+    await (0, linear_js_1.updateLinearIssueAfterFinalize)({ issueId, state, branch, prUrl, validationPassed, apiKey, lifecyclePolicy });
+    console.log(`Linear parent ${issueId} updated.`);
+}

package/dist/finalize/steps/12-archive.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepArchive = stepArchive;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function stepArchive(repoRoot, state, stateFile, reportPath) {
+    const archiveDir = (0, node_path_1.resolve)(repoRoot, ".polaris", "runs", state.run_id);
+    (0, node_fs_1.mkdirSync)(archiveDir, { recursive: true });
+    (0, node_fs_1.copyFileSync)(stateFile, (0, node_path_1.join)(archiveDir, "current-state.json"));
+    if ((0, node_fs_1.existsSync)(reportPath)) {
+        (0, node_fs_1.copyFileSync)(reportPath, (0, node_path_1.join)(archiveDir, "run-report.md"));
+    }
+    const mapDir = (0, node_path_1.resolve)(repoRoot, ".polaris", "map");
+    for (const file of ["file-routes.json", "needs-review.json", "exemptions.json", "atlas-index.json"]) {
+        const src = (0, node_path_1.join)(mapDir, file);
+        if ((0, node_fs_1.existsSync)(src)) {
+            (0, node_fs_1.copyFileSync)(src, (0, node_path_1.join)(archiveDir, file));
+        }
+    }
+    console.log(`Run archived to .polaris/runs/${state.run_id}/`);
+}

package/dist/graph/adapter/c/adapter.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAdapter = void 0;
+exports.createCAdapter = createCAdapter;
+const node_path_1 = require("node:path");
+const extract_js_1 = require("./extract.js");
+const runtime_js_1 = require("./runtime.js");
+const DEFAULT_EXTENSIONS = [".c", ".h"];
+class CAdapter {
+    loadRuntime;
+    languageId = "c";
+    fileExtensions = DEFAULT_EXTENSIONS;
+    confidence = "high";
+    limitations = [
+        "Extracts declaration-level symbols only (functions, structs, includes).",
+        "Does not perform macro expansion or preprocessor execution.",
+    ];
+    constructor(loadRuntime) {
+        this.loadRuntime = loadRuntime;
+    }
+    async extractSymbols(filePath, source) {
+        const language = detectLanguage(filePath);
+        if (!language) {
+            throw new Error(`Unsupported C file extension: ${(0, node_path_1.extname)(filePath)}`);
+        }
+        const runtime = await this.loadRuntime();
+        const tree = runtime.parse(source, language);
+        return (0, extract_js_1.extractCSymbolsFromTree)(tree);
+    }
+    resolveImportSpecifier(specifier, _context) {
+        const trimmed = specifier.trim();
+        if (trimmed.length === 0) {
+            return null;
+        }
+        return trimmed;
+    }
+}
+exports.CAdapter = CAdapter;
+function createCAdapter(options = {}) {
+    return new CAdapter(options.loadRuntime ?? runtime_js_1.loadTreeSitterRuntime);
+}
+function detectLanguage(filePath) {
+    const extension = (0, node_path_1.extname)(filePath).toLowerCase();
+    return extension === ".c" || extension === ".h" ? "c" : null;
+}