ai-delivery-workflow 0.3.0 → 0.5.0

package/skills/ai-delivery-manage-git/scripts/release-git.mjs

@@ -0,0 +1,995 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+function parseArgs(argv) {
+  const options = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const key = argv[index];
+    if (!key.startsWith("--")) throw new Error(`Unexpected argument: ${key}`);
+    const next = argv[index + 1];
+    const value = !next || next.startsWith("--") ? true : next;
+    if (value !== true) index += 1;
+    const previous = options.get(key);
+    options.set(key, previous === undefined ? value : [...(Array.isArray(previous) ? previous : [previous]), value]);
+  }
+  return options;
+}
+
+function option(options, name) {
+  const value = options.get(name);
+  if (Array.isArray(value)) throw new Error(`Option may be supplied only once: ${name}`);
+  return value;
+}
+
+function required(options, name) {
+  const value = option(options, name);
+  if (value === undefined || value === true || String(value).trim() === "") {
+    throw new Error(`Missing required option: ${name}`);
+  }
+  return String(value).trim();
+}
+
+function optional(options, name) {
+  const value = option(options, name);
+  if (value === undefined) return null;
+  if (value === true || String(value).trim() === "") throw new Error(`Option requires a value: ${name}`);
+  return String(value).trim();
+}
+
+function flag(options, name) {
+  const value = option(options, name);
+  if (value === undefined) return false;
+  if (value !== true) throw new Error(`Flag does not accept a value: ${name}`);
+  return true;
+}
+
+function assertKnownOptions(options, allowed) {
+  for (const name of options.keys()) {
+    if (!allowed.has(name)) throw new Error(`Unsupported option: ${name}`);
+  }
+}
+
+function git(repo, args, { allowFailure = false } = {}) {
+  const result = spawnSync("git", args, { cwd: repo, encoding: "utf8", windowsHide: true });
+  if (result.error) throw new Error(`Cannot execute git ${args.join(" ")}: ${result.error.message}`);
+  if (!allowFailure && result.status !== 0) {
+    throw new Error(`Git command failed: git ${args.join(" ")}: ${(result.stderr || result.stdout).trim()}`);
+  }
+  return {
+    status: result.status,
+    stdout: (result.stdout || "").trim(),
+    stderr: (result.stderr || "").trim(),
+  };
+}
+
+function repositoryRoot(input) {
+  const requested = path.resolve(input || process.cwd());
+  return git(requested, ["rev-parse", "--show-toplevel"]).stdout;
+}
+
+function normalizeObjectId(value, label) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(normalized)) {
+    throw new Error(`${label} must be a full immutable Git object ID.`);
+  }
+  return normalized;
+}
+
+function readJsonDocument(repo, value, label) {
+  const input = String(value || "").trim();
+  if (!input) throw new Error(`${label} is required.`);
+  const file = path.resolve(repo, input);
+  let raw;
+  let document;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+    document = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Cannot read ${label} JSON: ${file} (${error.message})`);
+  }
+  if (!document || typeof document !== "object" || Array.isArray(document)) {
+    throw new Error(`${label} must contain a JSON object: ${file}`);
+  }
+  return {
+    file,
+    document,
+    sha256: crypto.createHash("sha256").update(raw).digest("hex"),
+  };
+}
+
+function readProductionVerification(repo, value, releaseId, verifiedCommit, expectedMain = null) {
+  const evidence = readJsonDocument(repo, value, "production_verification");
+  if (evidence.document.schema_version !== 1) {
+    throw new Error(`production_verification requires schema_version 1: ${evidence.file}`);
+  }
+  if (evidence.document.operation !== "production-verification-decision") {
+    throw new Error(`production_verification requires operation production-verification-decision: ${evidence.file}`);
+  }
+  if (evidence.document.release_id !== releaseId) {
+    throw new Error(`production_verification release_id does not match ${releaseId}: ${evidence.file}`);
+  }
+  if (evidence.document.decision !== "released") {
+    throw new Error(`production_verification must record decision released: ${evidence.file}`);
+  }
+  const evidenceCommit = normalizeObjectId(evidence.document.verified_release_commit, "production_verification.verified_release_commit");
+  if (evidenceCommit !== verifiedCommit) {
+    throw new Error(`production_verification binds ${evidenceCommit}, not verified release candidate ${verifiedCommit}.`);
+  }
+  const deployedCommit = normalizeObjectId(evidence.document.deployed_commit, "production_verification.deployed_commit");
+  if (deployedCommit !== verifiedCommit) {
+    throw new Error(`production_verification deployed_commit ${deployedCommit} does not match verified release candidate ${verifiedCommit}.`);
+  }
+  const evidenceExpectedMain = normalizeObjectId(evidence.document.expected_main_commit, "production_verification.expected_main_commit");
+  if (expectedMain !== null) {
+    if (evidenceExpectedMain !== expectedMain) {
+      throw new Error(`production_verification expected_main_commit ${evidenceExpectedMain} does not match R00 commit ${expectedMain}.`);
+    }
+  }
+  return {
+    path: evidence.file,
+    sha256: evidence.sha256,
+    decision: evidence.document.decision,
+    verified_release_commit: evidenceCommit,
+    deployed_commit: deployedCommit,
+    ...(expectedMain === null ? {} : { expected_main_commit: expectedMain }),
+  };
+}
+
+function readCandidateInventory(repo, value, releaseId, lineBranch, sourceCommit, verifiedCommit) {
+  const inventory = readJsonDocument(repo, value, "candidate_inventory");
+  if (inventory.document.schema_version !== 2) {
+    throw new Error(`candidate_inventory requires schema_version 2: ${inventory.file}`);
+  }
+  if (inventory.document.scope !== "product-line") {
+    throw new Error(`candidate_inventory requires scope product-line: ${inventory.file}`);
+  }
+  const productId = String(inventory.document.product_id || "").trim();
+  if (!productId) {
+    throw new Error(`candidate_inventory requires product_id: ${inventory.file}`);
+  }
+  const inventoryLineBranch = String(inventory.document.line_branch || "").trim();
+  if (!inventoryLineBranch) {
+    throw new Error(`candidate_inventory requires line_branch: ${inventory.file}`);
+  }
+  if (inventoryLineBranch !== lineBranch) {
+    throw new Error(`candidate_inventory line_branch ${inventoryLineBranch} does not match ${lineBranch}: ${inventory.file}`);
+  }
+  if (inventoryLineBranch !== `line/${productId}`) {
+    throw new Error(`candidate_inventory line_branch must be line/${productId}: ${inventory.file}`);
+  }
+  if (inventory.document.release_id !== undefined) {
+    throw new Error(`candidate_inventory is product-line scoped and must not define a root release_id: ${inventory.file}`);
+  }
+  const activeId = String(inventory.document.active_candidate_id || "").trim();
+  const activeCommit = normalizeObjectId(inventory.document.active_candidate_commit, "candidate_inventory.active_candidate_commit");
+  if (!activeId) throw new Error(`candidate_inventory requires active_candidate_id: ${inventory.file}`);
+  if (!Array.isArray(inventory.document.candidates)) {
+    throw new Error(`candidate_inventory requires candidates: ${inventory.file}`);
+  }
+  const allowedStatuses = new Set(["active", "release-ready", "verified", "approved", "stale", "released"]);
+  const candidates = inventory.document.candidates.map((candidate, index) => {
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+      throw new Error(`candidate_inventory.candidates[${index}] must be an object: ${inventory.file}`);
+    }
+    const candidateId = String(candidate.candidate_id || "").trim();
+    if (!candidateId) throw new Error(`candidate_inventory.candidates[${index}] requires candidate_id: ${inventory.file}`);
+    const candidateReleaseId = String(candidate.release_id || "").trim();
+    if (!candidateReleaseId) throw new Error(`candidate_inventory.candidates[${index}] requires release_id: ${inventory.file}`);
+    const candidateCommit = normalizeObjectId(candidate.candidate_commit, `candidate_inventory.candidates[${index}].candidate_commit`);
+    const status = String(candidate.status || "").trim();
+    if (!status) throw new Error(`candidate_inventory.candidates[${index}] requires status: ${inventory.file}`);
+    if (!allowedStatuses.has(status)) {
+      throw new Error(`candidate_inventory.candidates[${index}] has unsupported status ${status}: ${inventory.file}`);
+    }
+    return {
+      candidate_id: candidateId,
+      release_id: candidateReleaseId,
+      candidate_commit: candidateCommit,
+      status,
+    };
+  });
+  if (new Set(candidates.map((candidate) => candidate.candidate_id)).size !== candidates.length) {
+    throw new Error(`candidate_inventory contains duplicate candidate_id values: ${inventory.file}`);
+  }
+  const selectableStatuses = new Set(["active", "release-ready", "verified", "approved"]);
+  const active = candidates.find((candidate) => candidate.candidate_id === activeId);
+  if (!active || active.candidate_commit !== activeCommit) {
+    throw new Error(`candidate_inventory active candidate is not represented exactly in candidates: ${inventory.file}`);
+  }
+  if (active.release_id !== releaseId) {
+    throw new Error(`candidate_inventory active candidate ${activeId} does not belong to release ${releaseId}: ${inventory.file}`);
+  }
+  if (!selectableStatuses.has(active.status)) {
+    throw new Error(`candidate_inventory active candidate ${activeId} is not selectable: ${inventory.file}`);
+  }
+  const verifiedCandidate = candidates.find((candidate) => (
+    candidate.release_id === releaseId
+    && candidate.candidate_commit === verifiedCommit
+    && selectableStatuses.has(candidate.status)
+  ));
+  if (!verifiedCandidate) {
+    throw new Error(`candidate_inventory does not include a selectable verified release candidate ${verifiedCommit}: ${inventory.file}`);
+  }
+  if (!isAncestor(repo, activeCommit, sourceCommit) || activeCommit === sourceCommit) {
+    throw new Error(`Release-fix commit ${sourceCommit} must descend from the active candidate ${activeId}.`);
+  }
+  if (!isAncestor(repo, activeCommit, verifiedCommit)) {
+    throw new Error(`Verified release candidate ${verifiedCommit} does not descend from active candidate ${activeId}.`);
+  }
+  const staleCandidateUpdates = candidates
+    .filter((candidate) => selectableStatuses.has(candidate.status) && !isAncestor(repo, sourceCommit, candidate.candidate_commit))
+    .map((candidate) => ({
+      candidate_id: candidate.candidate_id,
+      release_id: candidate.release_id,
+      candidate_commit: candidate.candidate_commit,
+      previous_status: candidate.status,
+      status: "stale",
+      reason: `omits-release-fix:${sourceCommit}`,
+    }));
+  return {
+    path: inventory.file,
+    sha256: inventory.sha256,
+    document: inventory.document,
+    product_id: productId,
+    line_branch: inventoryLineBranch,
+    active_candidate_id: activeId,
+    active_candidate_commit: activeCommit,
+    successor_active_candidate_id: staleCandidateUpdates.some((candidate) => candidate.candidate_id === activeId)
+      ? verifiedCandidate.candidate_id
+      : activeId,
+    successor_active_candidate_commit: staleCandidateUpdates.some((candidate) => candidate.candidate_id === activeId)
+      ? verifiedCandidate.candidate_commit
+      : activeCommit,
+    stale_candidate_updates: staleCandidateUpdates,
+  };
+}
+
+function jsonText(document) {
+  return `${JSON.stringify(document, null, 2)}\n`;
+}
+
+function sha256Text(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function buildSuccessorCandidateInventory(candidateInventory) {
+  const document = JSON.parse(JSON.stringify(candidateInventory.document));
+  const updates = new Map(candidateInventory.stale_candidate_updates.map((candidate) => [candidate.candidate_id, candidate]));
+  for (const candidate of document.candidates) {
+    if (updates.has(candidate.candidate_id)) {
+      candidate.status = "stale";
+      candidate.status_reason = updates.get(candidate.candidate_id).reason;
+    }
+  }
+  document.active_candidate_id = candidateInventory.successor_active_candidate_id;
+  document.active_candidate_commit = candidateInventory.successor_active_candidate_commit;
+  document.supersedes = {
+    path: candidateInventory.path,
+    sha256: candidateInventory.sha256,
+  };
+  return document;
+}
+
+function prepareSuccessorCandidateInventory(repo, value, candidateInventory) {
+  const destination = path.resolve(repo, String(value || "").trim());
+  if (samePath(destination, candidateInventory.path)) {
+    throw new Error("successor_candidate_inventory must not overwrite the immutable candidate_inventory input.");
+  }
+  const document = buildSuccessorCandidateInventory(candidateInventory);
+  const raw = jsonText(document);
+  return {
+    path: destination,
+    document,
+    raw,
+    sha256: sha256Text(raw),
+    schema_version: document.schema_version,
+    scope: document.scope,
+    product_id: document.product_id,
+    line_branch: document.line_branch,
+    active_candidate_id: document.active_candidate_id,
+    active_candidate_commit: document.active_candidate_commit,
+  };
+}
+
+function immutableDocumentConflict(label, destination) {
+  return new Error(`${label} already exists with content that does not match the controlled successor: ${destination}`);
+}
+
+function preflightImmutableDocument(document, apply, label) {
+  if (fs.existsSync(document.path)) {
+    let raw;
+    try {
+      raw = fs.readFileSync(document.path, "utf8");
+    } catch (error) {
+      throw new Error(`Cannot read ${label}: ${document.path} (${error.message})`);
+    }
+    if (sha256Text(raw) !== document.sha256) throw immutableDocumentConflict(label, document.path);
+    return { exists: true, status: "existing-immutable-successor" };
+  }
+  if (!apply) return { exists: false, status: "not-written-dry-run" };
+  fs.mkdirSync(path.dirname(document.path), { recursive: true });
+  try {
+    fs.accessSync(path.dirname(document.path), fs.constants.W_OK);
+  } catch (error) {
+    throw new Error(`Cannot write ${label} directory ${path.dirname(document.path)}: ${error.message}`);
+  }
+  return { exists: false, status: "pending-write" };
+}
+
+function writeImmutableDocument(document, preflight, label) {
+  if (preflight.exists) return { path: document.path, sha256: document.sha256, status: preflight.status };
+  try {
+    fs.writeFileSync(document.path, document.raw, { encoding: "utf8", flag: "wx" });
+    return { path: document.path, sha256: document.sha256, status: "written" };
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    const raced = preflightImmutableDocument(document, true, label);
+    if (!raced.exists) throw error;
+    return { path: document.path, sha256: document.sha256, status: raced.status };
+  }
+}
+
+function resolveCommit(repo, ref, label) {
+  const result = git(repo, ["rev-parse", "--verify", `${ref}^{commit}`], { allowFailure: true });
+  if (result.status !== 0) throw new Error(`${label} does not resolve to a commit: ${ref}`);
+  return result.stdout.toLowerCase();
+}
+
+function resolveBranch(repo, branch) {
+  const result = git(repo, ["rev-parse", "--verify", `refs/heads/${branch}^{commit}`], { allowFailure: true });
+  return result.status === 0 ? result.stdout.toLowerCase() : null;
+}
+
+function assertBranchName(repo, branch, prefix, label) {
+  const normalized = String(branch || "").trim();
+  if (!normalized.startsWith(prefix)) throw new Error(`${label} must start with ${prefix}: ${normalized || "missing"}`);
+  const result = git(repo, ["check-ref-format", "--branch", normalized], { allowFailure: true });
+  if (result.status !== 0) throw new Error(`${label} is not a valid branch name: ${normalized}`);
+  return normalized;
+}
+
+function assertTagName(repo, tag, prefix, label) {
+  const normalized = String(tag || "").trim();
+  if (!normalized.startsWith(prefix)) throw new Error(`${label} must start with ${prefix}: ${normalized || "missing"}`);
+  const result = git(repo, ["check-ref-format", `refs/tags/${normalized}`], { allowFailure: true });
+  if (result.status !== 0) throw new Error(`${label} is not a valid Tag name: ${normalized}`);
+  return normalized;
+}
+
+function assertExactBranchHead(repo, branch, expected, label) {
+  const actual = resolveBranch(repo, branch);
+  if (!actual) throw new Error(`${label} does not exist: ${branch}`);
+  if (actual !== expected) {
+    throw new Error(`${label} drifted: expected ${expected}, found ${actual}. Refresh the release request.`);
+  }
+  return actual;
+}
+
+function assertRemoteBranchHead(remote, branch, expected) {
+  if (!remote) return { checked: false, remote: null, commit: null };
+  const reference = `refs/heads/${branch}`;
+  const result = spawnSync("git", ["ls-remote", "--heads", remote, reference], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(`Cannot validate remote branch ${branch}: ${(result.stderr || result.error?.message || "unknown error").trim()}`);
+  }
+  const commits = (result.stdout || "").split(/\r?\n/).filter(Boolean).map((line) => line.split(/\s+/)[0].toLowerCase());
+  if (commits.length !== 1 || commits[0] !== expected) {
+    throw new Error(`Remote branch ${branch} drifted from expected commit ${expected}. Refresh the release request.`);
+  }
+  return { checked: true, remote, commit: expected };
+}
+
+function isAncestor(repo, ancestor, descendant) {
+  return git(repo, ["merge-base", "--is-ancestor", ancestor, descendant], { allowFailure: true }).status === 0;
+}
+
+function listWorktrees(repo) {
+  const lines = git(repo, ["worktree", "list", "--porcelain"]).stdout.split(/\r?\n/);
+  const worktrees = [];
+  let current = null;
+  const finish = () => {
+    if (current?.path) worktrees.push(current);
+    current = null;
+  };
+  for (const line of lines) {
+    if (!line) {
+      finish();
+    } else if (line.startsWith("worktree ")) {
+      finish();
+      current = { path: line.slice("worktree ".length), branch: null };
+    } else if (line.startsWith("branch ") && current) {
+      current.branch = line.slice("branch ".length);
+    }
+  }
+  finish();
+  return worktrees;
+}
+
+function assertCleanWorktrees(repo) {
+  for (const worktree of listWorktrees(repo)) {
+    const status = git(worktree.path, ["status", "--porcelain=v1", "--untracked-files=all"]);
+    if (status.stdout) throw new Error(`Working tree is not clean: ${worktree.path}`);
+  }
+}
+
+function samePath(left, right) {
+  const normalize = (value) => {
+    const resolved = path.resolve(value).replaceAll("\\", "/");
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  };
+  return normalize(left) === normalize(right);
+}
+
+function targetBranchWorktree(repo, branch) {
+  const ref = `refs/heads/${branch}`;
+  return listWorktrees(repo).find((worktree) => worktree.branch === ref) || null;
+}
+
+function zeroObjectId(repo) {
+  return git(repo, ["rev-parse", "--show-object-format"]).stdout === "sha256" ? "0".repeat(64) : "0".repeat(40);
+}
+
+function createRef(repo, branch, commit) {
+  git(repo, ["update-ref", `refs/heads/${branch}`, commit, zeroObjectId(repo)]);
+}
+
+function updateRef(repo, branch, commit, expected) {
+  git(repo, ["update-ref", `refs/heads/${branch}`, commit, expected]);
+}
+
+function withDetachedWorktree(repo, startCommit, action) {
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "ai-delivery-release-git-"));
+  let added = false;
+  try {
+    git(repo, ["worktree", "add", "--detach", "--quiet", temporary, startCommit]);
+    added = true;
+    return action(temporary);
+  } finally {
+    if (added) git(repo, ["worktree", "remove", "--force", temporary], { allowFailure: true });
+    if (fs.existsSync(temporary)) fs.rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function parentsOf(repo, commit) {
+  const values = git(repo, ["rev-list", "--parents", "-n", "1", commit]).stdout.split(/\s+/).filter(Boolean);
+  return values.slice(1).map((value) => value.toLowerCase());
+}
+
+function treeOf(repo, commit) {
+  return git(repo, ["rev-parse", `${commit}^{tree}`]).stdout.toLowerCase();
+}
+
+function assertExistingCandidate(repo, branch, releaseBase, sourceCommit) {
+  const candidate = resolveBranch(repo, branch);
+  if (!candidate) return null;
+  if (candidate === releaseBase && isAncestor(repo, sourceCommit, releaseBase)) {
+    return { commit: candidate, merge_created: false };
+  }
+  const parents = parentsOf(repo, candidate);
+  if (parents.length !== 2 || parents[0] !== releaseBase || parents[1] !== sourceCommit) {
+    throw new Error(`Existing release branch ${branch} is not the controlled merge of ${releaseBase} and ${sourceCommit}.`);
+  }
+  if (treeOf(repo, candidate) !== treeOf(repo, sourceCommit)) {
+    throw new Error(`Existing release branch ${branch} has an unexpected integration tree.`);
+  }
+  return { commit: candidate, merge_created: true };
+}
+
+function receiptPath(repo, value, apply) {
+  if (!apply) return value ? path.resolve(repo, value) : null;
+  if (!value) throw new Error("--receipt is required with --apply so the Git transition is auditable.");
+  return path.resolve(repo, value);
+}
+
+function readReceipt(destination) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(destination, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("receipt is not an object");
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`Receipt already exists and is not valid JSON: ${destination} (${error.message})`);
+  }
+}
+
+function sameReceiptValue(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function assertReceiptIdentity(existing, expected, destination) {
+  const identityFields = [
+    "schema_version", "operation", "release_id", "production_branch", "release_branch",
+    "release_base_commit", "expected_main_commit", "source_ref", "source_commit",
+    "verified_release_commit", "deployed_commit", "line_branch", "expected_line_commit",
+    "merge_strategy", "source_relation", "production_verification", "candidate_inventory",
+    "successor_candidate_inventory",
+    "stale_candidate_ids", "candidate_status_updates",
+  ];
+  for (const field of identityFields) {
+    if (expected[field] === undefined) continue;
+    if (!sameReceiptValue(existing[field], expected[field])) {
+      throw new Error(`Receipt identity conflicts for ${field}: ${destination}`);
+    }
+  }
+}
+
+function preflightReceipt(receipt, destination, apply) {
+  if (!destination) return null;
+  if (fs.existsSync(destination)) {
+    const existing = readReceipt(destination);
+    assertReceiptIdentity(existing, receipt, destination);
+    return existing;
+  }
+  if (!apply) return null;
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  try {
+    fs.accessSync(path.dirname(destination), fs.constants.W_OK);
+  } catch (error) {
+    throw new Error(`Cannot write receipt directory ${path.dirname(destination)}: ${error.message}`);
+  }
+  return null;
+}
+
+function attachReceipt(receipt, destination, apply, existingReceipt = null) {
+  if (!destination) return receipt;
+  if (!apply) return { ...receipt, receipt: { path: destination, status: "not-written-dry-run" } };
+  const existing = existingReceipt || (fs.existsSync(destination) ? readReceipt(destination) : null);
+  if (existing) {
+    assertReceiptIdentity(existing, receipt, destination);
+    return { ...receipt, receipt: { path: destination, status: "existing-immutable-receipt" } };
+  }
+  try {
+    fs.writeFileSync(destination, `${JSON.stringify(receipt, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    const raced = readReceipt(destination);
+    assertReceiptIdentity(raced, receipt, destination);
+    return { ...receipt, receipt: { path: destination, status: "existing-immutable-receipt" } };
+  }
+  return { ...receipt, receipt: { path: destination, status: "written" } };
+}
+
+function commonOptions(options) {
+  const repo = repositoryRoot(optional(options, "--repo") || process.cwd());
+  const apply = flag(options, "--apply");
+  if (flag(options, "--dry-run") && apply) throw new Error("--apply and --dry-run cannot be used together.");
+  return {
+    repo,
+    apply,
+    remote: optional(options, "--remote"),
+    receipt: receiptPath(repo, optional(options, "--receipt"), apply),
+  };
+}
+
+export function createReleaseCandidate(input) {
+  const repo = repositoryRoot(input.repo || process.cwd());
+  const releaseId = String(input.release_id || "").trim();
+  if (!releaseId) throw new Error("release_id is required.");
+  const releaseBranch = assertBranchName(repo, input.release_branch, `release/${releaseId}-`, "release_branch");
+  const productionBranch = assertBranchName(repo, input.production_branch || "main", "", "production_branch");
+  const sourceTag = assertTagName(repo, input.source_tag, "version-ready/", "source_tag");
+  const expectedMain = normalizeObjectId(input.expected_main, "expected_main");
+  const expectedSource = normalizeObjectId(input.source_commit, "source_commit");
+  const receipt = receiptPath(repo, input.receipt || null, Boolean(input.apply));
+
+  assertCleanWorktrees(repo);
+  assertExactBranchHead(repo, productionBranch, expectedMain, `Production branch ${productionBranch}`);
+  const remoteValidation = assertRemoteBranchHead(input.remote || null, productionBranch, expectedMain);
+  const sourceCommit = resolveCommit(repo, `refs/tags/${sourceTag}`, `Source Tag ${sourceTag}`);
+  if (sourceCommit !== expectedSource) throw new Error(`Source Tag ${sourceTag} drifted: expected ${expectedSource}, found ${sourceCommit}.`);
+  const targetContainsReleaseBase = isAncestor(repo, expectedMain, sourceCommit);
+  const targetAlreadyInReleaseBase = isAncestor(repo, sourceCommit, expectedMain);
+  if (!targetContainsReleaseBase && !targetAlreadyInReleaseBase) {
+    throw new Error(`Captured production branch ${productionBranch} commit ${expectedMain} and ${sourceTag} diverge; recreate the version candidate before release.`);
+  }
+
+  const existing = assertExistingCandidate(repo, releaseBranch, expectedMain, sourceCommit);
+  const baseReceipt = {
+    schema_version: 1,
+    operation: "create-release-candidate",
+    release_id: releaseId,
+    production_branch: productionBranch,
+    release_branch: releaseBranch,
+    release_base_commit: expectedMain,
+    source_ref: sourceTag,
+    source_commit: sourceCommit,
+    merge_strategy: "no-ff-single-version-ready-tag",
+    source_relation: targetContainsReleaseBase ? "target-descends-from-release-base" : "target-already-in-release-base",
+    remote_validation: remoteValidation,
+  };
+  const existingReceipt = preflightReceipt(baseReceipt, receipt, Boolean(input.apply));
+  if (existing) {
+    if (existingReceipt && existingReceipt.candidate_commit !== existing.commit) {
+      throw new Error(`Receipt ${receipt} does not describe the existing release branch ${releaseBranch}.`);
+    }
+    return attachReceipt({
+      ...baseReceipt,
+      status: "idempotent",
+      candidate_commit: existing.commit,
+      merge_commit: existing.merge_created ? existing.commit : null,
+      merge_created: existing.merge_created,
+    }, receipt, Boolean(input.apply), existingReceipt);
+  }
+  if (existingReceipt) {
+    throw new Error(`Receipt ${receipt} exists but release branch ${releaseBranch} is missing; recover the controlled operation before retrying.`);
+  }
+  if (!input.apply) {
+    return attachReceipt({
+      ...baseReceipt,
+      status: "planned",
+      candidate_commit: targetAlreadyInReleaseBase ? expectedMain : null,
+      merge_commit: null,
+      merge_created: targetAlreadyInReleaseBase ? false : null,
+    }, receipt, false);
+  }
+
+  const candidate = targetAlreadyInReleaseBase ? expectedMain : withDetachedWorktree(repo, expectedMain, (worktree) => {
+    git(worktree, ["merge", "--no-ff", "--no-edit", `refs/tags/${sourceTag}`]);
+    const commit = resolveCommit(worktree, "HEAD", "Release candidate");
+    const parents = parentsOf(worktree, commit);
+    if (parents.length !== 2 || parents[0] !== expectedMain || parents[1] !== sourceCommit) {
+      throw new Error("Controlled release merge did not create the expected two-parent candidate.");
+    }
+    if (treeOf(worktree, commit) !== treeOf(worktree, sourceCommit)) {
+      throw new Error("Controlled release merge produced an unexpected candidate tree.");
+    }
+    return commit;
+  });
+  assertExactBranchHead(repo, productionBranch, expectedMain, `Production branch ${productionBranch}`);
+  assertRemoteBranchHead(input.remote || null, productionBranch, expectedMain);
+  createRef(repo, releaseBranch, candidate);
+  return attachReceipt({
+    ...baseReceipt,
+    status: "applied",
+    candidate_commit: candidate,
+    merge_commit: candidate === expectedMain ? null : candidate,
+    merge_created: candidate !== expectedMain,
+  }, receipt, true, existingReceipt);
+}
+
+export function promoteReleaseCandidate(input) {
+  const repo = repositoryRoot(input.repo || process.cwd());
+  const releaseId = String(input.release_id || "").trim();
+  if (!releaseId) throw new Error("release_id is required.");
+  const productionBranch = assertBranchName(repo, input.production_branch || "main", "", "production_branch");
+  const releaseBranch = assertBranchName(repo, input.release_branch, `release/${releaseId}-`, "release_branch");
+  const expectedMain = normalizeObjectId(input.expected_main, "expected_main");
+  const verifiedCommit = normalizeObjectId(input.verified_release_commit, "verified_release_commit");
+  const receipt = receiptPath(repo, input.receipt || null, Boolean(input.apply));
+  const productionVerification = readProductionVerification(
+    repo,
+    input.production_verification,
+    releaseId,
+    verifiedCommit,
+    expectedMain,
+  );
+
+  assertCleanWorktrees(repo);
+  const branchCommit = resolveBranch(repo, releaseBranch);
+  if (branchCommit !== verifiedCommit) {
+    throw new Error(`Release branch ${releaseBranch} does not name the verified candidate ${verifiedCommit}.`);
+  }
+  if (!isAncestor(repo, expectedMain, verifiedCommit)) {
+    throw new Error(`Verified release candidate ${verifiedCommit} does not descend from captured production commit ${expectedMain}.`);
+  }
+  const currentMain = resolveBranch(repo, productionBranch);
+  const baseReceipt = {
+    schema_version: 1,
+    operation: "promote-release-candidate",
+    release_id: releaseId,
+    production_branch: productionBranch,
+    release_branch: releaseBranch,
+    expected_main_commit: expectedMain,
+    verified_release_commit: verifiedCommit,
+    deployed_commit: verifiedCommit,
+    merge_strategy: "fast-forward-production-to-verified-candidate",
+    production_verification: productionVerification,
+  };
+  const existingReceipt = preflightReceipt(baseReceipt, receipt, Boolean(input.apply));
+  if (currentMain === verifiedCommit) {
+    if (currentMain !== expectedMain && !existingReceipt) {
+      throw new Error(`Production branch ${productionBranch} already names the verified candidate without a matching immutable receipt; recover or recreate the release request.`);
+    }
+    if (existingReceipt && existingReceipt.new_main_head !== verifiedCommit) {
+      throw new Error(`Receipt ${receipt} does not describe production branch ${productionBranch} at ${verifiedCommit}.`);
+    }
+    const remoteValidation = assertRemoteBranchHead(input.remote || null, productionBranch, verifiedCommit);
+    return attachReceipt({
+      ...baseReceipt,
+      status: "idempotent",
+      old_main_head: currentMain,
+      new_main_head: currentMain,
+      remote_validation: remoteValidation,
+    }, receipt, Boolean(input.apply), existingReceipt);
+  }
+  if (currentMain !== expectedMain) {
+    throw new Error(`Production branch ${productionBranch} changed after candidate creation: expected ${expectedMain}, found ${currentMain}. Recreate the release candidate.`);
+  }
+  if (existingReceipt) {
+    throw new Error(`Receipt ${receipt} exists but production branch ${productionBranch} has not reached the recorded candidate; recover the controlled operation before retrying.`);
+  }
+  const remoteValidation = assertRemoteBranchHead(input.remote || null, productionBranch, expectedMain);
+  if (!input.apply) {
+    return attachReceipt({
+      ...baseReceipt,
+      status: "planned",
+      old_main_head: currentMain,
+      new_main_head: verifiedCommit,
+      remote_validation: remoteValidation,
+    }, receipt, false);
+  }
+
+  const holder = targetBranchWorktree(repo, productionBranch);
+  if (holder && !samePath(holder.path, repo)) {
+    throw new Error(`Production branch ${productionBranch} is checked out in another worktree: ${holder.path}`);
+  }
+  if (holder) {
+    assertExactBranchHead(repo, productionBranch, expectedMain, `Production branch ${productionBranch}`);
+    git(repo, ["merge", "--ff-only", verifiedCommit]);
+  } else {
+    assertExactBranchHead(repo, productionBranch, expectedMain, `Production branch ${productionBranch}`);
+    assertRemoteBranchHead(input.remote || null, productionBranch, expectedMain);
+    updateRef(repo, productionBranch, verifiedCommit, expectedMain);
+  }
+  const newMain = assertExactBranchHead(repo, productionBranch, verifiedCommit, `Production branch ${productionBranch}`);
+  return attachReceipt({
+    ...baseReceipt,
+    status: "applied",
+    old_main_head: currentMain,
+    new_main_head: newMain,
+    remote_validation: remoteValidation,
+  }, receipt, true, existingReceipt);
+}
+
+export function synchronizeReleaseFix(input) {
+  const repo = repositoryRoot(input.repo || process.cwd());
+  const releaseId = String(input.release_id || "").trim();
+  if (!releaseId) throw new Error("release_id is required.");
+  const sourceRef = assertBranchName(repo, input.source_ref, `release-fix/${releaseId}/`, "source_ref");
+  const lineBranch = assertBranchName(repo, input.line_branch, "line/", "line_branch");
+  const expectedLine = normalizeObjectId(input.expected_line, "expected_line");
+  const expectedSource = normalizeObjectId(input.source_commit, "source_commit");
+  const verifiedCommit = normalizeObjectId(input.verified_release_commit, "verified_release_commit");
+  const receipt = receiptPath(repo, input.receipt || null, Boolean(input.apply));
+
+  assertCleanWorktrees(repo);
+  const sourceCommit = resolveBranch(repo, sourceRef);
+  if (sourceCommit !== expectedSource) {
+    throw new Error(`Release-fix branch ${sourceRef} drifted: expected ${expectedSource}, found ${sourceCommit || "missing"}.`);
+  }
+  if (!isAncestor(repo, sourceCommit, verifiedCommit)) {
+    throw new Error(`Verified release candidate ${verifiedCommit} does not contain release-fix commit ${sourceCommit}.`);
+  }
+  const productionVerification = readProductionVerification(
+    repo,
+    input.production_verification,
+    releaseId,
+    verifiedCommit,
+  );
+  const candidateInventory = readCandidateInventory(
+    repo,
+    input.candidate_inventory,
+    releaseId,
+    lineBranch,
+    sourceCommit,
+    verifiedCommit,
+  );
+  let successorCandidateInventory = null;
+  let successorInventoryPreflight = null;
+  const successorInventoryValue = String(input.successor_candidate_inventory || "").trim();
+  const successorInventoryPath = successorInventoryValue ? path.resolve(repo, successorInventoryValue) : null;
+  if (input.apply && !successorInventoryPath) {
+    throw new Error("--successor-candidate-inventory is required with --apply so stale status changes are immutable.");
+  }
+  if (successorInventoryPath) {
+    successorCandidateInventory = prepareSuccessorCandidateInventory(repo, successorInventoryPath, candidateInventory);
+    if (receipt && samePath(receipt, successorCandidateInventory.path)) {
+      throw new Error("successor_candidate_inventory must not overwrite the operation receipt.");
+    }
+    successorInventoryPreflight = preflightImmutableDocument(
+      successorCandidateInventory,
+      Boolean(input.apply),
+      "successor_candidate_inventory",
+    );
+  }
+  const currentLine = resolveBranch(repo, lineBranch);
+  if (!currentLine) throw new Error(`Development line does not exist: ${lineBranch}`);
+  const baseReceipt = {
+    schema_version: 1,
+    operation: "synchronize-release-fix-to-line",
+    release_id: releaseId,
+    source_ref: sourceRef,
+    source_commit: sourceCommit,
+    verified_release_commit: verifiedCommit,
+    line_branch: lineBranch,
+    expected_line_commit: expectedLine,
+    merge_strategy: "no-ff-merge-release-fix-into-line",
+    production_verification: productionVerification,
+    candidate_inventory: {
+      path: candidateInventory.path,
+      sha256: candidateInventory.sha256,
+      schema_version: 2,
+      scope: candidateInventory.document.scope,
+      product_id: candidateInventory.product_id,
+      line_branch: candidateInventory.line_branch,
+      active_candidate_id: candidateInventory.active_candidate_id,
+      active_candidate_commit: candidateInventory.active_candidate_commit,
+    },
+    ...(successorCandidateInventory ? {
+      successor_candidate_inventory: {
+        path: successorCandidateInventory.path,
+        sha256: successorCandidateInventory.sha256,
+        schema_version: successorCandidateInventory.schema_version,
+        scope: successorCandidateInventory.scope,
+        product_id: successorCandidateInventory.product_id,
+        line_branch: successorCandidateInventory.line_branch,
+        active_candidate_id: successorCandidateInventory.active_candidate_id,
+        active_candidate_commit: successorCandidateInventory.active_candidate_commit,
+      },
+    } : {}),
+    stale_candidate_ids: candidateInventory.stale_candidate_updates.map((candidate) => candidate.candidate_id),
+    candidate_status_updates: candidateInventory.stale_candidate_updates,
+  };
+  const existingReceipt = preflightReceipt(baseReceipt, receipt, Boolean(input.apply));
+  if (isAncestor(repo, sourceCommit, currentLine)) {
+    if (existingReceipt && !isAncestor(repo, sourceCommit, existingReceipt.new_line_head || currentLine)) {
+      throw new Error(`Receipt ${receipt} does not retain release-fix commit ${sourceCommit}.`);
+    }
+    if (existingReceipt && (!successorInventoryPreflight || !successorInventoryPreflight.exists)) {
+      throw new Error(`Receipt ${receipt} requires an exact immutable successor candidate inventory, but it is missing.`);
+    }
+    const remoteValidation = assertRemoteBranchHead(input.remote || null, lineBranch, currentLine);
+    const successorInventoryWrite = input.apply && successorCandidateInventory
+      ? writeImmutableDocument(successorCandidateInventory, successorInventoryPreflight, "successor_candidate_inventory")
+      : successorCandidateInventory
+        ? { path: successorCandidateInventory.path, sha256: successorCandidateInventory.sha256, status: successorInventoryPreflight.status }
+        : null;
+    return attachReceipt({
+      ...baseReceipt,
+      status: "idempotent",
+      old_line_head: currentLine,
+      new_line_head: currentLine,
+      remote_validation: remoteValidation,
+      ...(successorInventoryWrite ? { successor_candidate_inventory_write: successorInventoryWrite } : {}),
+    }, receipt, Boolean(input.apply), existingReceipt);
+  }
+  if (currentLine !== expectedLine) {
+    throw new Error(`Development line ${lineBranch} drifted: expected ${expectedLine}, found ${currentLine}. Replan the release-fix synchronization.`);
+  }
+  if (existingReceipt) {
+    throw new Error(`Receipt ${receipt} exists but development line ${lineBranch} has not incorporated the release fix; recover the controlled operation before retrying.`);
+  }
+  const remoteValidation = assertRemoteBranchHead(input.remote || null, lineBranch, expectedLine);
+  if (!input.apply) {
+    return attachReceipt({
+      ...baseReceipt,
+      status: "planned",
+      old_line_head: currentLine,
+      new_line_head: null,
+      remote_validation: remoteValidation,
+    }, receipt, false);
+  }
+
+  const holder = targetBranchWorktree(repo, lineBranch);
+  if (holder && !samePath(holder.path, repo)) {
+    throw new Error(`Development line ${lineBranch} is checked out in another worktree: ${holder.path}`);
+  }
+  let newLine;
+  if (holder) {
+    assertExactBranchHead(repo, lineBranch, expectedLine, `Development line ${lineBranch}`);
+    git(repo, ["merge", "--no-ff", "--no-edit", `refs/heads/${sourceRef}`]);
+    newLine = resolveCommit(repo, "HEAD", "Development line merge");
+  } else {
+    newLine = withDetachedWorktree(repo, expectedLine, (worktree) => {
+      git(worktree, ["merge", "--no-ff", "--no-edit", `refs/heads/${sourceRef}`]);
+      return resolveCommit(worktree, "HEAD", "Development line merge");
+    });
+    assertExactBranchHead(repo, lineBranch, expectedLine, `Development line ${lineBranch}`);
+    assertRemoteBranchHead(input.remote || null, lineBranch, expectedLine);
+    updateRef(repo, lineBranch, newLine, expectedLine);
+  }
+  if (!isAncestor(repo, sourceCommit, newLine)) throw new Error("Release-fix synchronization did not retain the release-fix commit.");
+  const successorInventoryWrite = writeImmutableDocument(
+    successorCandidateInventory,
+    successorInventoryPreflight,
+    "successor_candidate_inventory",
+  );
+  return attachReceipt({
+    ...baseReceipt,
+    status: "applied",
+    old_line_head: currentLine,
+    new_line_head: newLine,
+    remote_validation: remoteValidation,
+    successor_candidate_inventory_write: successorInventoryWrite,
+  }, receipt, true, existingReceipt);
+}
+
+function candidateInput(options) {
+  assertKnownOptions(options, new Set([
+    "--repo", "--remote", "--receipt", "--apply", "--dry-run", "--release-id", "--release-branch",
+    "--production-branch", "--expected-main", "--source-tag", "--source-commit",
+  ]));
+  const shared = commonOptions(options);
+  return {
+    ...shared,
+    release_id: required(options, "--release-id"),
+    release_branch: required(options, "--release-branch"),
+    production_branch: optional(options, "--production-branch") || "main",
+    expected_main: required(options, "--expected-main"),
+    source_tag: required(options, "--source-tag"),
+    source_commit: required(options, "--source-commit"),
+  };
+}
+
+function promotionInput(options) {
+  assertKnownOptions(options, new Set([
+    "--repo", "--remote", "--receipt", "--apply", "--dry-run", "--release-id", "--release-branch",
+    "--production-branch", "--expected-main", "--verified-release-commit", "--production-verification",
+  ]));
+  const shared = commonOptions(options);
+  return {
+    ...shared,
+    release_id: required(options, "--release-id"),
+    release_branch: required(options, "--release-branch"),
+    production_branch: optional(options, "--production-branch") || "main",
+    expected_main: required(options, "--expected-main"),
+    verified_release_commit: required(options, "--verified-release-commit"),
+    production_verification: required(options, "--production-verification"),
+  };
+}
+
+function releaseFixInput(options) {
+  assertKnownOptions(options, new Set([
+    "--repo", "--remote", "--receipt", "--apply", "--dry-run", "--release-id", "--source-ref",
+    "--source-commit", "--verified-release-commit", "--line-branch", "--expected-line",
+    "--production-verification", "--candidate-inventory", "--successor-candidate-inventory",
+  ]));
+  const shared = commonOptions(options);
+  return {
+    ...shared,
+    release_id: required(options, "--release-id"),
+    source_ref: required(options, "--source-ref"),
+    source_commit: required(options, "--source-commit"),
+    verified_release_commit: required(options, "--verified-release-commit"),
+    line_branch: required(options, "--line-branch"),
+    expected_line: required(options, "--expected-line"),
+    production_verification: required(options, "--production-verification"),
+    candidate_inventory: required(options, "--candidate-inventory"),
+    successor_candidate_inventory: shared.apply
+      ? required(options, "--successor-candidate-inventory")
+      : optional(options, "--successor-candidate-inventory"),
+  };
+}
+
+function main(argv) {
+  const [action, ...rest] = argv;
+  const options = parseArgs(rest);
+  let result;
+  if (action === "create-candidate") result = createReleaseCandidate(candidateInput(options));
+  else if (action === "promote") result = promoteReleaseCandidate(promotionInput(options));
+  else if (action === "sync-release-fix") result = synchronizeReleaseFix(releaseFixInput(options));
+  else {
+    throw new Error("Usage: release-git.mjs <create-candidate|promote|sync-release-fix> [options] [--apply]");
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}