@lsctech/polaris 0.1.0

package/dist/finalize/index.js

@@ -0,0 +1,474 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFinalize = runFinalize;
+exports.createFinalizeCommand = createFinalizeCommand;
+const commander_1 = require("commander");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const closeout_librarian_types_js_1 = require("../cognition/closeout-librarian-types.js");
+const loader_js_1 = require("../config/loader.js");
+const checkpoint_js_1 = require("../loop/checkpoint.js");
+const artifact_policy_js_1 = require("./artifact-policy.js");
+const git_custody_js_1 = require("../loop/git-custody.js");
+const store_js_1 = require("../cluster-state/store.js");
+const canon_check_js_1 = require("../smartdocs-engine/canon-check.js");
+const _01_map_update_js_1 = require("./steps/01-map-update.js");
+const _02_map_validate_js_1 = require("./steps/02-map-validate.js");
+const _03_schema_validate_js_1 = require("./steps/03-schema-validate.js");
+const _04_run_checks_js_1 = require("./steps/04-run-checks.js");
+const _05_generate_report_js_1 = require("./steps/05-generate-report.js");
+const _06_commit_js_1 = require("./steps/06-commit.js");
+const _07_push_js_1 = require("./steps/07-push.js");
+const _08_create_pr_js_1 = require("./steps/08-create-pr.js");
+const _09_update_state_js_1 = require("./steps/09-update-state.js");
+const _10_append_jsonl_js_1 = require("./steps/10-append-jsonl.js");
+const _11_update_linear_js_1 = require("./steps/11-update-linear.js");
+const _12_archive_js_1 = require("./steps/12-archive.js");
+const local_graph_js_1 = require("../tracker/local-graph.js");
+const index_js_1 = require("../tracker/sync/index.js");
+const finalize_evidence_js_1 = require("../loop/finalize-evidence.js");
+const delivery_integrity_js_1 = require("./delivery-integrity.js");
+function getBranch(repoRoot) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to get current branch in ${repoRoot}: ${msg}`);
+    }
+}
+function normalizeBranchName(branch) {
+    return branch.toLowerCase().replace(/_/g, "-");
+}
+function extractClusterSlug(clusterId) {
+    const match = clusterId.match(/([A-Z]+-\d+)/);
+    return match ? normalizeBranchName(match[1]) : normalizeBranchName(clusterId);
+}
+function validateStateFilePath(stateFile) {
+    const normalizedPath = stateFile.replace(/\\/g, "/");
+    const debugPath = ".taskchain_artifacts/polaris-run/current-state.json";
+    const legacyPath = ".polaris/runs/current-state.json";
+    if (normalizedPath.endsWith(debugPath)) {
+        process.stderr.write(`finalize aborted: state file at compatibility/debug path — ${stateFile}\n` +
+            `Canonical state files must be at .polaris/clusters/<cluster-id>/state.json or custom path.\n`);
+        process.exit(1);
+    }
+    if (normalizedPath.endsWith(legacyPath)) {
+        process.stderr.write(`finalize aborted: state file at legacy path — ${stateFile}\n` +
+            `Canonical state files must be at .polaris/clusters/<cluster-id>/state.json or custom path.\n`);
+        process.exit(1);
+    }
+}
+function validateClusterIdMatchesBranch(clusterId, branch) {
+    const clusterSlug = extractClusterSlug(clusterId);
+    const normalizedBranch = normalizeBranchName(branch);
+    const slugPattern = new RegExp(`(^|-)${clusterSlug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(-|$)`);
+    if (!slugPattern.test(normalizedBranch)) {
+        process.stderr.write(`finalize aborted: cluster_id mismatch — state.cluster_id "${clusterId}" ` +
+            `does not match current branch "${branch}".\n` +
+            `Expected branch to contain slug "${clusterSlug}" (normalized from "${clusterId}").\n`);
+        process.exit(1);
+    }
+}
+function validateStateBranchMatchesGitBranch(stateBranch, branch) {
+    if (!stateBranch || stateBranch.trim() === "") {
+        return;
+    }
+    if (stateBranch !== branch) {
+        process.stderr.write(`finalize aborted: state.branch mismatch — state.branch "${stateBranch}" ` +
+            `does not match current git branch "${branch}".\n`);
+        process.exit(1);
+    }
+}
+/**
+ * Check that the Closeout Librarian has run and its result passes the gate.
+ * Returns null if finalize may proceed; returns a human-readable blocker string if not.
+ */
+function checkLibrarianGate(repoRoot, clusterId) {
+    const packetsDir = (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "packets");
+    let packetFiles = [];
+    try {
+        packetFiles = (0, node_fs_1.readdirSync)(packetsDir)
+            .filter((f) => f.startsWith("librarian-packet-") && f.endsWith(".json"))
+            .sort();
+    }
+    catch {
+        // directory absent — no packet has been generated
+    }
+    const latestPacket = packetFiles
+        .map((file) => (0, node_path_1.join)(packetsDir, file))
+        .sort((a, b) => {
+        try {
+            return (0, node_fs_1.statSync)(b).mtimeMs - (0, node_fs_1.statSync)(a).mtimeMs;
+        }
+        catch {
+            return b.localeCompare(a);
+        }
+    })[0];
+    if (!latestPacket) {
+        return ("Closeout Librarian has not been dispatched for this cluster.\n" +
+            `  1. Generate packet:  npm run polaris -- librarian packet ${clusterId} --state-file <state-file>\n` +
+            `  2. Dispatch the Librarian with the generated packet path as the sole session prompt.\n` +
+            `  3. Wait for the Librarian to write its sealed result.\n` +
+            `  4. Re-run finalize.\n` +
+            `Use --skip-librarian to bypass this gate for backward compatibility.`);
+    }
+    let packetJson;
+    try {
+        packetJson = JSON.parse((0, node_fs_1.readFileSync)(latestPacket, "utf-8"));
+    }
+    catch {
+        return `Cannot read Librarian packet at ${latestPacket}. Regenerate with: npm run polaris -- librarian packet ${clusterId}`;
+    }
+    const resultPath = packetJson["result_path"];
+    if (typeof resultPath !== "string") {
+        return `Librarian packet is malformed: missing result_path. Regenerate with: npm run polaris -- librarian packet ${clusterId}`;
+    }
+    if (!(0, node_fs_1.existsSync)(resultPath)) {
+        return ("Closeout Librarian has not written its sealed result yet.\n" +
+            `  Expected result at: ${resultPath}\n` +
+            `  Dispatch the Librarian session and wait for it to write its sealed result, then re-run finalize.`);
+    }
+    let resultJson;
+    try {
+        resultJson = JSON.parse((0, node_fs_1.readFileSync)(resultPath, "utf-8"));
+    }
+    catch {
+        return `Cannot read Librarian result at ${resultPath}. The file may be corrupt.`;
+    }
+    const validationErrors = (0, closeout_librarian_types_js_1.validateCloseoutLibrarianResult)(resultJson);
+    if (validationErrors.length > 0) {
+        return `Librarian result is invalid: ${validationErrors.join("; ")}`;
+    }
+    // Cross-validate dispatch_id and run_id
+    const result = resultJson;
+    if (packetJson["dispatch_id"] !== result.dispatch_id) {
+        return `Librarian result dispatch_id mismatch (packet: ${packetJson["dispatch_id"]}, result: ${result.dispatch_id}). Regenerate and re-dispatch.`;
+    }
+    if (packetJson["run_id"] !== result.run_id) {
+        return `Librarian result run_id mismatch (packet: ${packetJson["run_id"]}, result: ${result.run_id}).`;
+    }
+    // Validate files_committed against packet scope constraints
+    const allowedWritePaths = (packetJson["allowed_write_paths"] ?? []);
+    const prohibitedWritePaths = (packetJson["prohibited_write_paths"] ?? []);
+    const filesCommitted = result.files_committed ?? [];
+    for (const file of filesCommitted) {
+        const prohibitedMatch = prohibitedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, file));
+        if (prohibitedMatch) {
+            return `Librarian wrote to prohibited path: ${file} (matched pattern: ${prohibitedMatch})`;
+        }
+        const allowedMatch = allowedWritePaths.find((pattern) => (0, git_custody_js_1.patternMatchesPath)(pattern, file));
+        if (allowedMatch)
+            continue; // explicitly allowed
+        return `Librarian wrote to out-of-scope path: ${file} (not in allowed_write_paths)`;
+    }
+    try {
+        return (0, closeout_librarian_types_js_1.checkLibrarianResultGate)(result);
+    }
+    catch (err) {
+        return `Librarian result gate error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+async function runFinalize(options) {
+    const { repoRoot, stateFile, dryRun, skipDelivery, skipLibrarian } = options;
+    const config = (0, loader_js_1.loadConfig)(repoRoot);
+    // Step 1: polaris map update --changed
+    console.log("[1/14] Updating map..."); // Step count updated
+    (0, _01_map_update_js_1.stepMapUpdate)(repoRoot);
+    // Step 2: polaris map validate — fail fast
+    console.log("[2/14] Validating map..."); // Step count updated
+    (0, _02_map_validate_js_1.stepMapValidate)(repoRoot);
+    // Step 3: Validate current-state.json schema
+    console.log("[3/14] Validating current-state.json schema..."); // Step count updated
+    let rawState;
+    try {
+        rawState = (0, checkpoint_js_1.readState)(stateFile);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`finalize aborted: cannot read state file ${stateFile}: ${msg}\n`);
+        process.exit(1);
+    }
+    (0, _03_schema_validate_js_1.stepSchemaValidate)(rawState);
+    let state = rawState;
+    // Preflight: state file authority gate (must run before Step 4)
+    const branch = getBranch(repoRoot);
+    validateStateFilePath(stateFile);
+    validateClusterIdMatchesBranch(state.cluster_id, branch);
+    validateStateBranchMatchesGitBranch(state.branch, branch);
+    // Step 4: Run configured checks
+    const checks = config.finalize?.runChecks ?? [];
+    if (checks.length > 0) {
+        console.log(`[4/14] Running ${checks.length} configured check(s) and staging preflight...`); // Step count updated
+    }
+    else {
+        console.log("[4/14] Running staging preflight..."); // Step count updated
+    }
+    (0, _04_run_checks_js_1.stepRunChecks)(repoRoot, checks, { activeClusterId: state.cluster_id, skipDelivery });
+    // Step 4.5: Canon reconciliation check
+    const canonCheckEnabled = config.canon?.checkOnFinalize !== false;
+    if (canonCheckEnabled) {
+        console.log("[4.5/14] Running canon reconciliation check..."); // Step count updated
+        let changedFiles = [];
+        try {
+            const baseBranch = config.finalize?.targetBranch ?? "main";
+            const diffOutput = (0, node_child_process_1.execFileSync)("git", ["diff", "--name-only", `${baseBranch}...HEAD`], { cwd: repoRoot, encoding: "utf-8" });
+            changedFiles = diffOutput.trim().split("\n").filter(Boolean);
+        }
+        catch (err) {
+            // Fail closed: if git diff fails, we cannot determine changed files for canon check
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Error: git diff failed during canon check: ${msg}`);
+            throw new Error(`Canon check cannot proceed: git diff failed: ${msg}`);
+        }
+        const artifactDirForCheck = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
+        const telemetryFileForCheck = (0, node_path_1.join)(artifactDirForCheck, "runs", state.run_id, "telemetry.jsonl");
+        const canonResult = (0, canon_check_js_1.runCanonCheck)({
+            repoRoot,
+            changedFiles,
+            childId: undefined,
+            runId: state.run_id,
+            telemetryFile: telemetryFileForCheck,
+        });
+        if (canonResult.outcome === "stale-implementation") {
+            const conflict = canonResult.conflicts.find((c) => c.type === "stale-implementation");
+            process.stderr.write([
+                `Canon conflict halt — finalize blocked. PR will not be created.`,
+                `Canon file: ${conflict?.canonFile ?? "unknown"}`,
+                `Statement: ${conflict?.statement ?? ""}`,
+                `Affected file: ${conflict?.changedFile ?? ""}`,
+                `Detail: ${conflict?.detail ?? ""}`,
+                `Resolution: Update the canon file or implement the missing piece before finalizing.`,
+            ].join("\n") + "\n");
+            process.exit(1);
+        }
+    }
+    // Step 5: Generate run-report.md (written once, never updated)
+    console.log("[5/14] Generating run-report.md..."); // Step count updated
+    const reportPath = (0, _05_generate_report_js_1.stepGenerateReport)(repoRoot, state, branch, true);
+    if (dryRun) {
+        console.log("[6–14/14] Dry run — skipping reconciliation, commit and delivery.");
+        console.log("Finalize dry run complete.");
+        return;
+    }
+    // Step 5.5: Implementation evidence gate
+    // Require at least one non-artifact staged file before committing. A finalize
+    // commit with only Polaris artifact files means no real implementation work
+    // was recorded — abort to prevent a phantom delivery.
+    {
+        const stagedOutput = (0, node_child_process_1.execFileSync)("git", ["diff", "--cached", "--name-only"], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+        const stagedFiles = stagedOutput ? stagedOutput.split("\n").filter(Boolean) : [];
+        const implFiles = stagedFiles.filter((f) => (0, artifact_policy_js_1.classifyArtifactPath)(f, state.cluster_id) === "non-artifact");
+        if (implFiles.length === 0) {
+            const evidenceReport = (0, finalize_evidence_js_1.verifyCompletedChildFinalizeEvidence)(repoRoot, stateFile);
+            if (!evidenceReport.ok) {
+                process.stderr.write("finalize aborted: No implementation evidence found. " +
+                    "No non-artifact source files are staged and canonical completed-child evidence failed.\n" +
+                    `${(0, finalize_evidence_js_1.formatFinalizeEvidenceFailures)(evidenceReport.failures)}\n`);
+                process.exit(1);
+            }
+        }
+    }
+    // Step 5.6: Branch custody verification
+    // When the cluster state records a delivery_branch and base_branch (set by dispatch),
+    // verify that base..delivery_branch contains at least one non-artifact source change
+    // and that no completed child's commit is already reachable from the base branch.
+    //
+    // Skipped when no custody record is present (backward compatibility with runs
+    // that did not go through the custody-aware dispatch path) or when
+    // loop.allowBranchDivergence is true (direct-main mode).
+    {
+        const clusterState = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+        const baseBranch = clusterState?.base_branch;
+        const deliveryBranch = clusterState?.delivery_branch;
+        const directMainMode = config.loop?.allowBranchDivergence === true;
+        if (!directMainMode && baseBranch && deliveryBranch) {
+            // Assert finalize is running on the recorded delivery branch.
+            if (branch !== deliveryBranch) {
+                process.stderr.write(`finalize aborted: branch custody violation — not on delivery branch. ` +
+                    `Expected "${deliveryBranch}", got "${branch}".\n`);
+                process.exit(1);
+            }
+            const hasImplChanges = (0, git_custody_js_1.hasNonArtifactSourceChanges)(repoRoot, baseBranch, state.cluster_id, deliveryBranch);
+            if (!hasImplChanges) {
+                process.stderr.write(`finalize aborted: branch custody violation — no non-artifact source changes found in ` +
+                    `${baseBranch}...${deliveryBranch}. Child commits may already be on the base branch, ` +
+                    `or no implementation work was recorded on this delivery branch.\n`);
+                process.exit(1);
+            }
+            // Check each completed child's commit to verify it is not already on the base branch.
+            for (const childId of state.completed_children) {
+                const commitHash = clusterState.commits?.[childId] ??
+                    state.completed_children_results?.[childId]?.commit ??
+                    null;
+                if (!commitHash)
+                    continue;
+                const custodyError = (0, git_custody_js_1.verifyChildCommitCustody)(repoRoot, commitHash, deliveryBranch, baseBranch);
+                if (custodyError) {
+                    process.stderr.write(`finalize aborted: branch custody violation for ${childId}: ${custodyError}\n`);
+                    process.exit(1);
+                }
+            }
+        }
+    }
+    // Step 5.7: Unconditional delivery integrity gate
+    // Verifies the delivery branch contains actual implementation work relative to the base branch.
+    // Runs regardless of whether branch custody records were established in cluster state,
+    // closing the gap that allowed PR #93 to claim delivery when implementation was already on main.
+    {
+        const directMainMode = config.loop?.allowBranchDivergence === true;
+        if (!directMainMode) {
+            const clusterStateForIntegrity = (0, store_js_1.readClusterStateSync)(state.cluster_id, repoRoot);
+            const integrityBaseBranch = clusterStateForIntegrity?.base_branch ??
+                config.finalize?.targetBranch ??
+                "main";
+            const childCommits = {};
+            for (const childId of state.completed_children) {
+                const commit = clusterStateForIntegrity?.commits?.[childId] ??
+                    state.completed_children_results?.[childId]?.commit ??
+                    null;
+                if (commit)
+                    childCommits[childId] = commit;
+            }
+            const integrityResult = (0, delivery_integrity_js_1.validateDeliveryIntegrity)({
+                repoRoot,
+                currentBranch: branch,
+                baseBranch: integrityBaseBranch,
+                clusterId: state.cluster_id,
+                completedChildren: state.completed_children,
+                childCommits,
+            });
+            if (!integrityResult.ok) {
+                process.stderr.write(`finalize aborted: delivery integrity check failed (${integrityResult.kind}) — ${integrityResult.reason}\n`);
+                process.exit(1);
+            }
+        }
+    }
+    // Step 6: Tracker Reconciliation
+    // LinearAdapter is sync-in only; only McpBridgeAdapter supports full reconciliation.
+    const trackerType = config.tracker?.adapter;
+    if (!trackerType) {
+        console.log("[6/14] Tracker not configured — skipping reconciliation.");
+    }
+    else if (trackerType === "linear") {
+        console.log("[6/14] Linear adapter is sync-in only — skipping reconciliation (use mcp-bridge for two-way sync).");
+    }
+    else if (trackerType === "mcp-bridge") {
+        console.log("[6/14] Running tracker reconciliation...");
+        try {
+            const localGraph = await local_graph_js_1.LocalGraph.load(state.cluster_id, repoRoot);
+            const { McpBridgeAdapter } = await import("../tracker/adapters/mcp-bridge.js");
+            const trackerAdapter = new McpBridgeAdapter();
+            const trackerSyncService = new index_js_1.TrackerSyncService(trackerAdapter, localGraph, {
+                repoRoot,
+                clusterId: state.cluster_id,
+            });
+            await trackerSyncService.ready;
+            const reconciliationReport = await trackerSyncService.reconcile(dryRun);
+            console.log("Tracker Reconciliation Report:", reconciliationReport);
+            if (reconciliationReport.conflictsDetectedCount > 0 || reconciliationReport.failedMutationsCount > 0) {
+                const summary = reconciliationReport.details.join(" | ");
+                throw new Error(`tracker reconciliation requires attention (conflicts=${reconciliationReport.conflictsDetectedCount}, failed=${reconciliationReport.failedMutationsCount})${summary ? `: ${summary}` : ""}`);
+            }
+        }
+        catch (error) {
+            console.error("Error during tracker reconciliation:", error);
+            process.stderr.write(`finalize aborted: tracker reconciliation failed: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+        }
+    }
+    else {
+        console.warn(`[6/14] Unknown tracker adapter '${trackerType}' — skipping reconciliation.`);
+    }
+    // Step 7: Single final commit: source changes + durable Polaris artifacts
+    console.log("[7/14] Committing durable Polaris state + map..."); // Step count updated
+    const resolvedStateFile = (0, node_path_1.resolve)(stateFile);
+    (0, _06_commit_js_1.stepCommit)(repoRoot, state, resolvedStateFile, reportPath);
+    if (skipDelivery) {
+        console.log("[8–14/14] Delivery skipped (--skip-delivery).");
+        console.log("polaris finalize steps 1–7 complete.");
+        return;
+    }
+    // Step 8: Closeout Librarian gate
+    if (!skipLibrarian) {
+        console.log("[8/14] Checking Closeout Librarian gate...");
+        const librarianBlocker = checkLibrarianGate(repoRoot, state.cluster_id);
+        if (librarianBlocker) {
+            process.stderr.write(`finalize aborted: Closeout Librarian gate failed.\n${librarianBlocker}\n`);
+            process.exit(1);
+        }
+        console.log("[8/14] Closeout Librarian gate passed.");
+    }
+    else {
+        console.log("[8/14] Closeout Librarian gate skipped (--skip-librarian).");
+    }
+    // Step 9: git push
+    console.log("[9/14] Pushing branch...");
+    (0, _07_push_js_1.stepPush)(repoRoot, branch);
+    // Step 10: Create draft PR
+    const prDraft = config.finalize?.prDraft ?? true;
+    console.log("[10/14] Creating draft PR...");
+    const prUrl = (0, _08_create_pr_js_1.stepCreatePr)(repoRoot, branch, state, prDraft);
+    // Step 11: Write PR URL to current-state.json
+    console.log("[11/14] Writing PR URL to state...");
+    state = (0, _09_update_state_js_1.stepUpdateState)(resolvedStateFile, state, prUrl);
+    // Step 12: Append JSONL events
+    console.log("[12/14] Appending JSONL events...");
+    const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
+    const telemetryFile = (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
+    (0, _10_append_jsonl_js_1.stepAppendJsonl)(telemetryFile, state, prUrl);
+    // Step 13: Update Linear parent issue
+    console.log("[13/14] Updating Linear...");
+    const linearEnabled = config.tracker?.linear?.enabled ?? false;
+    const lifecyclePolicy = config.tracker?.lifecyclePolicy;
+    await (0, _11_update_linear_js_1.stepUpdateLinear)(state, branch, prUrl, true, linearEnabled, state.cluster_id, lifecyclePolicy);
+    // Step 14: Archive run snapshot
+    console.log("[14/14] Archiving run snapshot...");
+    (0, _12_archive_js_1.stepArchive)(repoRoot, state, resolvedStateFile, reportPath);
+    console.log("polaris finalize complete.");
+}
+function failMissingSubcommand(command, commandName) {
+    const unknownSubcommand = command.args[0];
+    const message = unknownSubcommand
+        ? `error: unknown command '${unknownSubcommand}' for '${commandName}'. Run '${commandName} --help'.`
+        : `error: missing command for '${commandName}'. Run '${commandName} --help'.`;
+    command.error(message, {
+        code: "commander.missingCommand",
+        exitCode: 1,
+    });
+}
+function createFinalizeCommand(handlers = {}) {
+    const finalizeHandler = handlers.runFinalize ?? runFinalize;
+    const repoRootDefault = handlers.repoRoot ?? process.cwd();
+    const finalize = new commander_1.Command("finalize")
+        .description("manual/operator-triggered delivery; finalize run performs delivery unless --dry-run or --skip-delivery is supplied")
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    finalize.action(() => failMissingSubcommand(finalize, "polaris finalize"));
+    finalize
+        .command("run")
+        .description("mutating: run manual/operator-triggered finalize and perform delivery")
+        .option("-r, --repo-root <path>", "Repository root", repoRootDefault)
+        .option("--state-file <path>", "Path to current-state.json")
+        .option("--dry-run", "non-mutating preview: validate and generate report without committing or pushing")
+        .option("--skip-delivery", "perform local finalize steps only; skip push/PR/Linear/archive")
+        .option("--skip-librarian", "skip the Closeout Librarian gate (backward compatibility only)")
+        .action((options) => {
+        const repoRoot = options.repoRoot;
+        const stateFile = options.stateFile ??
+            (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run", "current-state.json");
+        finalizeHandler({ repoRoot, stateFile, dryRun: options.dryRun, skipDelivery: options.skipDelivery, skipLibrarian: options.skipLibrarian })
+            .catch((err) => {
+            process.stderr.write(`finalize error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        });
+    });
+    return finalize;
+}