opencode-ruby-upgrader 0.1.0

package/bin/opencode-ruby-upgrader.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { inspectGitCapabilities, inspectWorktree, setupInstructions } from "../src/preflight.js";
+import { startDashboard } from "../src/dashboard.js";
+import { commitValidatedHop, commitValidatedRailsHop, CommitGateError } from "../src/commit-hop.js";
+import { acquireRunLock, readRun, releaseRunLock, RunStateError } from "../src/run-state.js";
+import { beginRailsBridgeRun, beginRun, discardLastRailsIteration, discardPendingRailsAppUpdate, recordDependencyReview, recordExecutedIteration, recordExecutedRailsIteration, recordFrameworkBridge, recordRailsResearch, recordResearch, recordRiskDecision, resumeRun, runStatus, transitionRun } from "../src/controller.js";
+import { inventoryProject } from "../src/inventory.js";
+import { inspectSupplyChain } from "../src/supply-chain.js";
+import { prepareTargetRuntime } from "../src/target-runtime.js";
+
+const [command, ...args] = process.argv.slice(2);
+const option = (name) => { const index = args.indexOf(name); return index >= 0 ? args[index + 1] : undefined; };
+const options = (name) => args.flatMap((argument, index) => argument === name && args[index + 1] ? [args[index + 1]] : []);
+const reportOption = () => option("--report");
+const citation = (value) => { const [title, url] = (value ?? "").split("|"); return { title, url }; };
+const usage = "Usage: opencode-ruby-upgrader <preflight|dashboard|begin|begin-rails-bridge|prepare-target-runtime|status|transition|record-research|record-rails-research|record-risk|record-framework-bridge|record-executed-iteration|record-executed-rails-iteration|discard-pending-app-update|record-dependency-review|inventory|supply-chain|git-capabilities|commit-hop|commit-rails-hop|resume|release-lock> [--help]";
+if (command === "help" || args.includes("--help")) {
+  console.log(`${usage}\n\nUse status --summary for a concise report view. release-lock is stale-session recovery only and requires --force.`);
+} else if (command === "preflight") {
+  const result = inspectWorktree();
+  if (args.includes("--json")) console.log(JSON.stringify(result, null, 2));
+  else if (result.ok && result.mode === "non-git") console.log("✓ No Git repository detected; proceeding without Git checkpoints or worktree isolation.");
+  else if (result.ok) console.log(`✓ Linked worktree: ${result.root}\n✓ Branch: ${result.branch}\n✓ Starting commit: ${result.sha}\n✓ Remote writes: disabled`);
+  else console.error(`${setupInstructions(result)}\n\nPreflight blocked: ${result.reason}`);
+  process.exitCode = result.ok ? 0 : 1;
+} else if (command === "dashboard") {
+  const server = await startDashboard();
+  const address = server.address();
+  console.log(`Ruby Upgrade Workspace: http://127.0.0.1:${address.port}`);
+} else if (command === "begin") {
+  try { console.log(JSON.stringify(beginRun({ target: option("--target"), dryRun: args.includes("--dry-run"), stopAfterHop: args.includes("--stop-after-hop"), allowNonGit: args.includes("--allow-non-git") }), null, 2)); }
+  catch (error) { console.error(`Run start blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "begin-rails-bridge") {
+  try { console.log(JSON.stringify(beginRailsBridgeRun({ rubyReportPath: option("--ruby-report"), dryRun: args.includes("--dry-run"), stopAfterHop: args.includes("--stop-after-hop"), allowNonGit: args.includes("--allow-non-git") }), null, 2)); }
+  catch (error) { console.error(`Rails bridge start blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "prepare-target-runtime") {
+  try {
+    if (!option("--ruby") || args.some((argument) => !["--ruby", "--report", option("--ruby"), option("--report")].includes(argument))) throw new Error("Usage: prepare-target-runtime --ruby <x.y.z> [--report .ruby-upgrades/runs/<run>.json]");
+    console.log(JSON.stringify(prepareTargetRuntime({ ruby: option("--ruby"), reportPath: option("--report") }), null, 2));
+  } catch (error) { console.error(`Target runtime preparation blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "status") {
+  try {
+    const run = runStatus({ reportPath: option("--report") });
+    if (args.includes("--summary")) {
+      const target = run.reportType === "rails_bridge" ? `Rails ${run.targetRails}` : `Ruby ${run.targetRuby}`;
+      const latest = run.iterations.at(-1); const checkpoint = latest?.checkpointSha ? `checkpoint ${latest.checkpointSha.slice(0, 12)}` : "no checkpoint yet";
+      console.log(`${run.title}\n${target} · ${run.status}/${run.phase} · ${checkpoint}\nReport: ${option("--report")}`);
+    } else console.log(JSON.stringify(run, null, 2));
+  }
+  catch (error) { console.error(`Run status failed: ${error.message}`); process.exitCode = 1; }
+} else if (command === "transition") {
+  try { console.log(JSON.stringify(transitionRun({ reportPath: reportOption(), phase: option("--phase"), note: option("--note"), commitSha: option("--commit-sha") }), null, 2)); }
+  catch (error) { console.error(`State transition blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-research") {
+  try { console.log(JSON.stringify(recordResearch({ reportPath: reportOption(), ladder: (option("--ladder") ?? "").split(",").filter(Boolean), citations: options("--citation").map(citation) }), null, 2)); }
+  catch (error) { console.error(`Research recording blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-rails-research") {
+  try { console.log(JSON.stringify(recordRailsResearch({ reportPath: reportOption(), ladder: (option("--ladder") ?? "").split(",").filter(Boolean), citations: options("--citation").map(citation) }), null, 2)); }
+  catch (error) { console.error(`Rails research recording blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-risk") {
+  try { console.log(JSON.stringify(recordRiskDecision({ reportPath: reportOption(), risk: option("--risk"), decision: option("--decision"), evidence: option("--evidence") }), null, 2)); }
+  catch (error) { console.error(`Risk recording blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-framework-bridge") {
+  try { console.log(JSON.stringify(recordFrameworkBridge({ reportPath: reportOption(), rubyFrom: option("--ruby-from"), rubyTo: option("--ruby-to"), railsFrom: option("--rails-from"), railsTo: option("--rails-to"), rationale: option("--rationale"), citations: options("--citation").map(citation) }), null, 2)); }
+  catch (error) { console.error(`Rails compatibility bridge blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-executed-iteration") {
+  try { console.log(JSON.stringify(recordExecutedIteration({ reportPath: reportOption(), iteration: JSON.parse(option("--json") ?? ""), validationCommandId: option("--validation") }), null, 2)); }
+  catch (error) { console.error(`Executed validation blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-executed-rails-iteration") {
+  try { console.log(JSON.stringify(recordExecutedRailsIteration({ reportPath: reportOption(), iteration: JSON.parse(option("--json") ?? ""), testValidationCommandId: option("--validation") }), null, 2)); }
+  catch (error) { console.error(`Executed Rails validation blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "discard-pending-app-update") {
+  try { console.log(JSON.stringify(discardPendingRailsAppUpdate({ reportPath: reportOption(), reason: option("--reason") }), null, 2)); }
+  catch (error) { console.error(`Rails app:update discard blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "discard-last-rails-iteration") {
+  try { console.log(JSON.stringify(discardLastRailsIteration({ reportPath: reportOption(), reason: option("--reason") }), null, 2)); }
+  catch (error) { console.error(`Rails iteration discard blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-dependency-review") {
+  try { console.log(JSON.stringify(recordDependencyReview({ reportPath: reportOption(), compatibility: option("--compatibility"), licenses: option("--licenses") }), null, 2)); }
+  catch (error) { console.error(`Dependency review blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "inventory") {
+  console.log(JSON.stringify(inventoryProject(), null, 2));
+} else if (command === "git-capabilities") {
+  console.log(JSON.stringify(inspectGitCapabilities(), null, 2));
+} else if (command === "supply-chain") {
+  console.log(JSON.stringify(inspectSupplyChain(), null, 2));
+} else if (command === "commit-hop") {
+  const reportIndex = args.indexOf("--report");
+  try {
+    const result = commitValidatedHop({ reportPath: reportIndex >= 0 ? args[reportIndex + 1] : undefined, allowHooks: args.includes("--allow-hooks"), allowBroadLockfile: args.includes("--allow-broad-lockfile"), allowPrivateSources: args.includes("--allow-private-sources") });
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    const prefix = error instanceof CommitGateError ? `Commit blocked (${error.code})` : "Commit failed";
+    console.error(`${prefix}: ${error.message}`);
+    process.exitCode = 1;
+  }
+} else if (command === "commit-rails-hop") {
+  const reportIndex = args.indexOf("--report");
+  try { console.log(JSON.stringify(commitValidatedRailsHop({ reportPath: reportIndex >= 0 ? args[reportIndex + 1] : undefined, allowHooks: args.includes("--allow-hooks"), allowBroadLockfile: args.includes("--allow-broad-lockfile"), allowPrivateSources: args.includes("--allow-private-sources") }), null, 2)); }
+  catch (error) { console.error(`${error instanceof CommitGateError ? `Rails commit blocked (${error.code})` : "Rails commit failed"}: ${error.message}`); process.exitCode = 1; }
+} else if (["resume", "release-lock"].includes(command)) {
+  const reportIndex = args.indexOf("--report");
+  const reportPath = reportIndex >= 0 ? args[reportIndex + 1] : undefined;
+  try {
+    if (!reportPath) throw new RunStateError("Provide --report .ruby-upgrades/runs/<run>.json.", "missing-report-path");
+    if (command === "resume") {
+      console.log(JSON.stringify(resumeRun({ reportPath, continueAfterHop: args.includes("--continue-after-hop") }), null, 2));
+    } else {
+      if (!args.includes("--force")) throw new RunStateError("release-lock is stale-session recovery only. Verify the owner is gone, then rerun with --force.", "force-required");
+      releaseRunLock(process.cwd(), reportPath, readRun(process.cwd(), reportPath).lockNonce);
+      console.log("Upgrade run lock released.");
+    }
+  } catch (error) {
+    const prefix = error instanceof RunStateError ? `Run control blocked (${error.code})` : "Run control failed";
+    console.error(`${prefix}: ${error.message}`);
+    process.exitCode = 1;
+  }
+} else {
+  console.error(usage);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "opencode-ruby-upgrader",
+  "version": "0.1.0",
+  "description": "A safe, evidence-driven Ruby runtime upgrade agent and local migration dashboard for OpenCode",
+  "author": "Priscilla Cournoyer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lilla021/opencode-ruby-upgrader.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lilla021/opencode-ruby-upgrader/issues"
+  },
+  "homepage": "https://github.com/lilla021/opencode-ruby-upgrader#readme",
+  "type": "module",
+  "main": "./src/index.js",
+  "bin": {
+    "opencode-ruby-upgrader": "./bin/opencode-ruby-upgrader.mjs"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "test:opencode": "node tests/opencode-runtime-smoke.mjs"
+  },
+  "files": ["src", "agents", "bin", "README.md", "LICENSE", "SECURITY.md", "PRIVACY.md", "RELEASING.md", "RELEASE_CHECKLIST.md", "RELEASE_NOTES.md", "E2E_EVIDENCE.md"],
+  "keywords": ["opencode", "opencode-plugin", "ruby", "rails", "upgrade", "worktree", "migration"],
+  "engines": { "node": ">=22.5.0" },
+  "license": "MIT",
+  "publishConfig": { "access": "public" }
+}

package/src/commit-hop.js

@@ -0,0 +1,234 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { assertRunLock, readRun } from "./run-state.js";
+import { receiptDigest, worktreeFingerprint } from "./provenance.js";
+
+const text = (cwd, args, env) => execFileSync("git", args, { cwd, env: { ...process.env, ...env }, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+const run = (cwd, args, env) => execFileSync("git", args, { cwd, env: { ...process.env, ...env }, stdio: "ignore" });
+const within = (parent, child) => child === parent || child.startsWith(`${parent}${path.sep}`);
+
+export class CommitGateError extends Error {
+  constructor(message, code) { super(message); this.code = code; }
+}
+
+function gitState(cwd) {
+  const root = text(cwd, ["rev-parse", "--show-toplevel"]);
+  const gitDir = text(cwd, ["rev-parse", "--git-dir"]);
+  const commonDir = text(cwd, ["rev-parse", "--git-common-dir"]);
+  const linked = path.resolve(root, gitDir) !== path.resolve(root, commonDir);
+  const branch = text(cwd, ["branch", "--show-current"]);
+  let defaultBranch;
+  try { defaultBranch = text(cwd, ["config", "--get", "opencode-ruby-upgrader.defaultBranch"]); }
+  catch { defaultBranch = undefined; }
+  return { root, linked, branch, defaultBranch, sha: text(cwd, ["rev-parse", "HEAD"]) };
+}
+
+function readReport(root, reportPath) {
+  const fullPath = path.resolve(root, reportPath);
+  const allowedDirectory = path.join(root, ".ruby-upgrades", "runs");
+  if (!within(allowedDirectory, fullPath) || path.extname(fullPath) !== ".json") {
+    throw new CommitGateError("Report must be a JSON file under .ruby-upgrades/runs/.", "invalid-report-path");
+  }
+  try { return { fullPath, report: readRun(root, reportPath) }; }
+  catch { throw new CommitGateError("The upgrade report is missing or fails the run schema.", "invalid-report"); }
+}
+
+function assertValidatedIteration(report, rails = false) {
+  const iteration = report.iterations?.at(-1);
+  if (rails ? (!report.targetRails || !report.targetRailsPinnedAt || !report.bridge) : (!report.targetRuby || !report.targetPinnedAt)) {
+    throw new CommitGateError("The report must pin its target and bridge evidence before an automatic commit.", "target-not-pinned");
+  }
+  if (!iteration || iteration.status !== "complete" || iteration.tests?.passed !== true) {
+    throw new CommitGateError("The latest hop is not recorded as complete with passing tests.", "validation-missing");
+  }
+  if (iteration.checkpointSha) throw new CommitGateError("The latest iteration already has a checkpoint; record the next hop before committing again.", "iteration-already-checkpointed");
+  if (!Array.isArray(iteration.validationReceipts) || !iteration.validationReceipts.length) {
+    throw new CommitGateError("The latest hop requires an executed validation receipt.", "validation-receipt-missing");
+  }
+  if (!iteration.from || !iteration.to) {
+    throw new CommitGateError("The latest report iteration needs both from and to Ruby versions.", "invalid-iteration");
+  }
+  if (!Array.isArray(iteration.fixes) || !iteration.fixes.length || !Array.isArray(iteration.citations) || !iteration.citations.length || !iteration.tests?.smoke) {
+    throw new CommitGateError("The latest hop requires explained fixes, citations, and smoke-test evidence.", "evidence-missing");
+  }
+  if (rails && !iteration.appUpdateReview) throw new CommitGateError("The latest Rails hop requires reviewed bin/rails app:update evidence.", "app-update-review-missing");
+  return iteration;
+}
+
+function assertExpectedHead(state, report) {
+  if (!report.expectedHead || state.sha !== report.expectedHead) {
+    throw new CommitGateError("HEAD no longer matches the recorded upgrade baseline; refusing to commit mixed changes.", "unexpected-head");
+  }
+}
+
+function stagedSecretPaths(cwd, env) {
+  const tokens = text(cwd, ["diff", "--cached", "--name-status", "-z"], env).split("\0").filter(Boolean);
+  const names = [];
+  for (let i = 0; i < tokens.length; i += 1) {
+    const status = tokens[i];
+    if (/^[MACD]/.test(status)) {
+      if (status.charAt(0) !== "D") names.push(tokens[i + 1]);
+      i += 1;
+    } else if (/^[RC]\d{3}$/.test(status)) {
+      names.push(tokens[i + 2]);
+      i += 2;
+    }
+  }
+  const indicators = [
+    /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/i,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{20,}\b/,
+    /\b(?:xox[baprs]-|npm_|glpat-)[A-Za-z0-9_-]{16,}/,
+    /(?:password|secret|token|api[_-]?key|authorization)\s*[:=]\s*["'][^"'\n]{8,}["']/i
+  ];
+  const flagged = [];
+  for (const name of names) {
+    try {
+      const size = Number(text(cwd, ["cat-file", "-s", `:${name}`], env));
+      if (!Number.isSafeInteger(size) || size > 2 * 1024 * 1024) { flagged.push(name); continue; }
+      const contents = execFileSync("git", ["show", `:${name}`], { cwd, env: { ...process.env, ...env }, encoding: "utf8", maxBuffer: 2 * 1024 * 1024 });
+      if (contents.includes("\0") || indicators.some((pattern) => pattern.test(contents))) flagged.push(name);
+    } catch { flagged.push(name); }
+  }
+  return flagged;
+}
+
+function executableHooks(cwd) {
+  let hooksPath;
+  try { hooksPath = text(cwd, ["config", "--get", "core.hooksPath"]); }
+  catch { hooksPath = text(cwd, ["rev-parse", "--path-format=absolute", "--git-path", "hooks"]); }
+  const directory = path.isAbsolute(hooksPath) ? hooksPath : path.resolve(text(cwd, ["rev-parse", "--show-toplevel"]), hooksPath);
+  try { return fs.readdirSync(directory).filter((name) => !name.endsWith(".sample") && (fs.statSync(path.join(directory, name)).mode & 0o111)); }
+  catch { return []; }
+}
+
+function assertScopedChanges(cwd, iteration, reportPath, env) {
+  const changed = text(cwd, ["diff", "--cached", "--name-only", "-z"], env).split("\0").filter(Boolean);
+  const declared = new Set([...(iteration.files ?? []), reportPath, reportPath.replace(/\.json$/, ".md")]);
+  const unexpected = changed.filter((file) => !declared.has(file));
+  if (unexpected.length) throw new CommitGateError(`Changed files were not declared by this hop: ${unexpected.join(", ")}. Add them with an explanation or stop for review.`, "unexpected-change-scope");
+  if (!changed.length) throw new CommitGateError("There are no migration changes to commit.", "nothing-to-commit");
+  return changed;
+}
+
+function unstageUnrelatedEvidence(cwd, iteration, reportPath, env) {
+  const declared = new Set([...(iteration.files ?? []), reportPath, reportPath.replace(/\.json$/, ".md")]);
+  const staged = text(cwd, ["diff", "--cached", "--name-only", "-z"], env).split("\0").filter(Boolean);
+  const localEvidence = staged.filter((file) => file.startsWith(".ruby-upgrades/") && !declared.has(file));
+  if (localEvidence.length) run(cwd, ["reset", "-q", "HEAD", "--", ...localEvidence], env);
+}
+
+function dependencyGate(cwd, changed, iteration, { allowBroadLockfile, allowPrivateSources }, env) {
+  const lockfiles = changed.filter((file) => /(?:^|\/)(?:Gemfile\.lock|gems\.lock)$/i.test(file));
+  if (lockfiles.length && iteration.dependencyReview?.completed !== true) throw new CommitGateError("A changed lockfile requires dependencyReview.completed: true with compatibility and license findings recorded.", "dependency-review-missing");
+  for (const lockfile of lockfiles) {
+    const lines = text(cwd, ["diff", "--cached", "--numstat", "--", lockfile], env).split("\t");
+    if ((Number(lines[0]) + Number(lines[1])) > 500 && !allowBroadLockfile) throw new CommitGateError(`Lockfile churn in ${lockfile} exceeds 500 changed lines. Review it and explicitly continue with --allow-broad-lockfile.`, "broad-lockfile-churn");
+    const content = execFileSync("git", ["show", `:${lockfile}`], { cwd, env: { ...process.env, ...env }, encoding: "utf8" });
+    const remotes = [...content.matchAll(/^\s*remote:\s*(\S+)\s*$/gm)].map((match) => match[1]);
+    if (remotes.some((remote) => !/^https:\/\/rubygems\.org\/?$/i.test(remote)) && !allowPrivateSources) throw new CommitGateError(`A non-RubyGems source appears in ${lockfile}. Review its trust and explicitly continue with --allow-private-sources.`, "private-dependency-source");
+  }
+  const gemfiles = changed.filter((file) => /(?:^|\/)Gemfile$/i.test(file));
+  for (const gemfile of gemfiles) {
+    const content = execFileSync("git", ["show", `:${gemfile}`], { cwd, env: { ...process.env, ...env }, encoding: "utf8" });
+    if (/(?:git|github|path)\s*:\s*["']/i.test(content) || /\bsource\s*["'](?!https:\/\/rubygems\.org\/?["'])/i.test(content)) {
+      if (!allowPrivateSources) throw new CommitGateError(`A non-standard or non-RubyGems dependency source appears in ${gemfile}. Review its trust and explicitly continue with --allow-private-sources.`, "private-dependency-source");
+    }
+  }
+}
+
+function commit(cwd, message, env) {
+  try { execFileSync("git", ["commit", "-m", message], { cwd, env: { ...process.env, ...env }, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }); }
+  catch (error) {
+    const detail = String(error.stderr ?? error.message);
+    if (/cannot lock ref|is at .+ but expected|reference transaction/i.test(detail)) throw new CommitGateError("Git history changed while the checkpoint was being created. The migration changes were not committed; review the new commit and resume only after explicit review.", "unexpected-head");
+    if (/Author identity unknown|unable to auto-detect email/i.test(detail)) throw new CommitGateError("Git author identity is not configured. Configure user.name and user.email yourself, then resume the run; this tool will not change Git configuration.", "git-identity-missing");
+    if (/gpg failed|failed to sign/i.test(detail)) throw new CommitGateError("Git commit signing failed. Repair your local signing setup or disable it yourself, then resume the run.", "git-signing-failed");
+    throw new CommitGateError(`Git refused the local commit: ${detail.trim()}`, "git-commit-failed");
+  }
+}
+
+function finalTestReceipt(iteration) {
+  return iteration.validationReceipts.findLast((receipt) => receipt.kind === "test" && receipt.exitCode === 0 && receipt.testEvidence?.passed === true);
+}
+
+function assertValidationFingerprint(cwd, iteration) {
+  const receipt = finalTestReceipt(iteration);
+  const current = worktreeFingerprint(cwd);
+  if (!receipt || receipt.worktree.headSha !== current.headSha || receipt.worktree.diffSha256 !== current.diffSha256) {
+    throw new CommitGateError("The working tree changed after final validation; rerun validation before committing.", "validation-fingerprint-mismatch");
+  }
+}
+
+function messageFor(iteration, reportPath, report, rails = false) {
+  const receiptTrailer = iteration.validationReceipts?.length ? [`Validation-Receipt-Digest: sha256:${receiptDigest(iteration.validationReceipts)}`] : [];
+  if (rails) return [
+    `chore(rails): upgrade ${iteration.from} to ${iteration.to}`, "", "Apply the reviewed Rails framework compatibility changes.", `Validation: ${iteration.tests.command || "project test suite"}.`, `Evidence: ${reportPath}`,
+    `Rails-Upgrade-Report: ${reportPath}`, `Rails-Upgrade-Hop: ${iteration.from}->${iteration.to}`, `Rails-App-Update-Reviewed: ${iteration.from}->${iteration.to}`, `Rails-Bridge-Ruby-Report: ${report.bridge.rubyReportPath}`, ...receiptTrailer
+  ].join("\n");
+  return [
+    `chore(ruby): upgrade ${iteration.from} to ${iteration.to}`,
+    "",
+    "Apply the smallest compatible runtime, dependency, and code changes for this Ruby minor-version hop.",
+    `Validation: ${iteration.tests.command || "project test suite"}.`,
+    `Evidence: ${reportPath}`,
+    `Ruby-Upgrade-Report: ${reportPath}`,
+    `Ruby-Upgrade-Hop: ${iteration.from}->${iteration.to}`, ...receiptTrailer
+  ].join("\n");
+}
+
+function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false, allowBroadLockfile = false, allowPrivateSources = false, rails = false }) {
+  if (!reportPath) throw new CommitGateError("Provide --report .ruby-upgrades/runs/<run>.json.", "missing-report-path");
+  const state = gitState(cwd);
+  if (!state.linked || !state.branch || !state.defaultBranch || state.branch === state.defaultBranch) {
+    throw new CommitGateError("Automatic commits require a configured default branch and a different branch in a linked worktree.", "unsafe-worktree");
+  }
+  if (text(cwd, ["diff", "--cached", "--name-only"])) {
+    throw new CommitGateError("The staging area was not empty before the commit gate ran.", "staging-not-clean");
+  }
+  const { fullPath, report } = readReport(state.root, reportPath);
+  if (!report.lockNonce) throw new CommitGateError("The report is missing its active lock capability.", "lock-capability-missing");
+  try { assertRunLock(state.root, reportPath, report.lockNonce); }
+  catch (error) { throw new CommitGateError(error.message, error.code); }
+  const iteration = assertValidatedIteration(report, rails);
+  if (report.schemaVersion !== 2 || report.phase !== "hop_validated" || Boolean(report.reportType === "rails_bridge") !== rails) throw new CommitGateError("The run must use the current schema and transition to hop_validated before an automatic commit.", "phase-not-validated");
+  if (report.branch !== state.branch) throw new CommitGateError("The worktree branch no longer matches the recorded run branch.", "unexpected-branch");
+  assertExpectedHead(state, report);
+  const indexPath = path.resolve(cwd, text(cwd, ["rev-parse", "--git-path", "index"]));
+  const lockPath = `${indexPath}.lock`;
+  const temporaryIndex = path.join(path.dirname(indexPath), `.opencode-ruby-upgrader-${process.pid}-${Date.now()}.index`);
+  try { fs.writeFileSync(lockPath, "", { flag: "wx", mode: 0o600 }); }
+  catch { throw new CommitGateError("The Git index is busy; retry after the other Git operation finishes.", "index-busy"); }
+  const env = { GIT_INDEX_FILE: temporaryIndex };
+  let committed = false;
+  try {
+    run(cwd, ["read-tree", "HEAD"], env);
+    run(cwd, ["add", "--all"], env);
+    const relativeReport = path.relative(state.root, fullPath);
+    unstageUnrelatedEvidence(cwd, iteration, relativeReport, env);
+    const changed = assertScopedChanges(cwd, iteration, relativeReport, env);
+    dependencyGate(cwd, changed, iteration, { allowBroadLockfile, allowPrivateSources }, env);
+    const hooks = executableHooks(cwd);
+    if (hooks.length && !allowHooks) throw new CommitGateError(`Executable Git hooks are active: ${hooks.join(", ")}. Review them and explicitly continue with --allow-hooks.`, "active-git-hooks");
+  const secretPaths = stagedSecretPaths(cwd, env);
+  if (secretPaths.length) {
+    throw new CommitGateError(`Potential credential material detected in: ${secretPaths.join(", ")}. Review it manually; it was not committed.`, "secret-detected");
+  }
+
+  const message = messageFor(iteration, relativeReport, report, rails);
+    assertValidationFingerprint(cwd, iteration);
+    if (text(cwd, ["rev-parse", "HEAD"]) !== report.expectedHead) throw new CommitGateError("HEAD changed while the commit gate was validating; refusing to commit atop unexpected history.", "unexpected-head");
+    commit(cwd, message, env);
+    committed = true;
+    fs.renameSync(temporaryIndex, lockPath);
+    fs.renameSync(lockPath, indexPath);
+    return { sha: text(cwd, ["rev-parse", "HEAD"]), message, branch: state.branch, report: relativeReport };
+  } finally {
+    if (!committed) fs.rmSync(temporaryIndex, { force: true });
+    fs.rmSync(lockPath, { force: true });
+  }
+}
+
+export function commitValidatedHop(options = {}) { return commitValidated(options); }
+export function commitValidatedRailsHop(options = {}) { return commitValidated({ ...options, rails: true }); }