opencode-ruby-upgrader 0.1.0

package/src/controller.js

@@ -0,0 +1,273 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { inspectGitCapabilities, inspectWorktree } from "./preflight.js";
+import { inventoryProject } from "./inventory.js";
+import { inspectSupplyChain } from "./supply-chain.js";
+import { acquireRunLock, assertRunLock, readRun, releaseRunLock, writeRun } from "./run-state.js";
+import { executeValidation } from "./validation-executor.js";
+import { receiptDigest } from "./provenance.js";
+
+const rubyVersion = /^\d+\.\d+(?:\.\d+)?$/;
+const railsVersion = /^\d+(?:\.\d+)+$/;
+const runName = () => `${new Date().toISOString().replace(/[:.]/g, "-")}-${crypto.randomUUID()}.json`;
+const transitions = {
+  initialized: ["inventory_complete", "blocked", "paused"], inventory_complete: ["research_complete", "blocked", "paused"],
+  research_complete: ["hop_validated", "blocked", "paused"], hop_validated: ["committed", "blocked", "paused"],
+  committed: ["hop_validated", "complete", "blocked", "paused"], paused: ["inventory_complete", "research_complete", "hop_validated", "committed", "blocked"], blocked: ["inventory_complete", "research_complete", "hop_validated", "paused"], complete: []
+};
+const series = (value) => value.split(".").slice(0, 2).join(".");
+const git = (root, args) => execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+const minorNumber = (value) => { const [major, minor] = series(value).split(".").map(Number); return major * 1000 + minor; };
+const railsMinorNumber = (value) => { const [major, minor] = series(value).split(".").map(Number); return major * 1000 + minor; };
+const contiguousRailsHop = (from, to) => railsMinorNumber(to) === railsMinorNumber(from) + 1 || (Number(to.split(".")[0]) === Number(from.split(".")[0]) + 1 && Number(to.split(".")[1]) === 0);
+const rubyMajorBoundaries = new Map([[2, 7], [3, 4]]);
+const contiguousRubyHop = (from, to) => {
+  const [fromMajor, fromMinor] = series(from).split(".").map(Number); const [toMajor, toMinor] = series(to).split(".").map(Number);
+  return minorNumber(to) === minorNumber(from) + 1 || (toMajor === fromMajor + 1 && toMinor === 0 && rubyMajorBoundaries.get(fromMajor) === fromMinor);
+};
+const requiredRisksFor = (supplyChain, gitCapabilities) => [
+  ...(supplyChain.privateSources.length ? ["private-dependency-sources"] : []),
+  ...(gitCapabilities.shallow ? ["shallow-clone"] : []), ...(gitCapabilities.sparseCheckout ? ["sparse-checkout"] : []),
+  ...(gitCapabilities.submodules ? ["submodules"] : []), ...(gitCapabilities.lfsConfigured ? ["git-lfs"] : [])
+];
+const assertApprovedRisks = (run) => {
+  const decisions = new Map(run.riskDecisions.map((risk) => [risk.risk, risk.decision]));
+  if ((run.requiredRisks ?? []).some((risk) => decisions.get(risk) !== "approved") || [...decisions.values()].some((decision) => decision !== "approved")) throw new Error("Resolve every detected risk with an explicit approval before recording a routine iteration.");
+};
+
+export function beginRun({ root = process.cwd(), target, dryRun = false, stopAfterHop = false, allowNonGit = false } = {}) {
+  if (!target || !rubyVersion.test(target)) throw new Error("Provide --target as a Ruby version such as 3.4 or 3.4.1.");
+  const preflight = inspectWorktree(root); const inventory = inventoryProject(root); const supplyChain = inspectSupplyChain(root); const gitCapabilities = inspectGitCapabilities(root);
+  const plan = { preflight, inventory, supplyChain, gitCapabilities, targetRuby: target, dryRun, stopAfterHop };
+  if (dryRun || !preflight.ok) return plan;
+  if (!inventory.supported || inventory.requiresDecision) throw new Error("A durable migration requires a Gemfile and a recognized executable test adapter. Supply an explicit validation command through a future reviewed adapter instead of guessing.");
+  if (preflight.mode === "non-git" && !allowNonGit) throw new Error("Non-Git runs need explicit consent: rerun begin with --allow-non-git after reviewing the loss of worktree isolation and checkpoint commits.");
+  const reportPath = path.join(".ruby-upgrades", "runs", runName());
+  const requiredRisks = requiredRisksFor(supplyChain, gitCapabilities);
+  const report = {
+    schemaVersion: 2, validationReceiptsRequired: true, runId: crypto.randomUUID(), title: `Ruby migration to ${target}`, status: "in_progress", phase: "initialized", startedAt: new Date().toISOString(), targetRuby: target, targetPinnedAt: new Date().toISOString(),
+    branch: preflight.branch ?? null, worktreeRoot: preflight.root ?? root, startingSha: preflight.sha ?? null, expectedHead: preflight.sha ?? null, control: { stopAfterHop }, inventory, supplyChain, gitCapabilities,
+    research: { ladder: [], citations: [] }, requiredRisks, riskDecisions: [], frameworkBridge: null, summary: ["Run initialized; official-source research and compatibility ladder pending."], iterations: [], sessionSummary: ""
+  };
+  const lock = acquireRunLock(root, reportPath); report.lockNonce = lock.nonce;
+  try { writeRun(root, reportPath, report); } catch (error) { releaseRunLock(root, reportPath, lock.nonce); throw error; }
+  return { ...plan, reportPath, report, lock };
+}
+
+export function runStatus({ root = process.cwd(), reportPath }) { return readRun(root, reportPath); }
+
+export function beginRailsBridgeRun({ root = process.cwd(), rubyReportPath, dryRun = false, stopAfterHop = false, allowNonGit = false } = {}) {
+  const rubyRun = readRun(root, rubyReportPath);
+  if (rubyRun.reportType === "rails_bridge" || rubyRun.phase !== "blocked" || rubyRun.status !== "blocked" || !rubyRun.frameworkBridge) throw new Error("A Rails bridge can start only from a blocked Ruby run with an approved compatibility bridge.");
+  const preflight = inspectWorktree(root); const inventory = inventoryProject(root); const supplyChain = inspectSupplyChain(root); const gitCapabilities = inspectGitCapabilities(root); const bridge = rubyRun.frameworkBridge;
+  const plan = { preflight, inventory, supplyChain, gitCapabilities, bridge, dryRun, stopAfterHop };
+  if (dryRun || !preflight.ok) return plan;
+  if (!inventory.rails?.resolvedVersion || series(inventory.rails.resolvedVersion) !== series(bridge.railsFrom)) throw new Error("The current Gemfile.lock must still resolve the Rails version recorded by the blocked Ruby run.");
+  if (preflight.mode === "non-git" && !allowNonGit) throw new Error("Non-Git Rails bridges need explicit consent: rerun with --allow-non-git.");
+  if (preflight.mode !== "non-git" && (preflight.branch !== rubyRun.branch || preflight.sha !== rubyRun.expectedHead)) throw new Error("Rails bridge must start on the blocked Ruby run's recorded branch and checkpoint SHA.");
+  const reportPath = path.join(".ruby-upgrades", "runs", runName());
+  const report = { schemaVersion: 2, validationReceiptsRequired: true, reportType: "rails_bridge", runId: crypto.randomUUID(), title: `Rails bridge ${bridge.railsFrom} to ${bridge.railsTo}`, status: "in_progress", phase: "initialized", startedAt: new Date().toISOString(), targetRails: bridge.railsTo, targetRailsPinnedAt: new Date().toISOString(), branch: preflight.branch ?? null, worktreeRoot: preflight.root ?? root, startingSha: preflight.sha ?? null, expectedHead: preflight.sha ?? null, control: { stopAfterHop }, inventory, supplyChain, gitCapabilities, bridge: { rubyReportPath, rubyRunId: rubyRun.runId, rubyFrom: bridge.rubyFrom, rubyTo: bridge.rubyTo, railsFrom: bridge.railsFrom, railsTo: bridge.railsTo, approvedAt: bridge.recordedAt }, research: { ladder: [], citations: [] }, riskDecisions: [], requiredRisks: requiredRisksFor(supplyChain, gitCapabilities), summary: ["Rails bridge initialized from blocked Ruby compatibility decision."], iterations: [], sessionSummary: "" };
+  const lock = acquireRunLock(root, reportPath); report.lockNonce = lock.nonce;
+  try { writeRun(root, reportPath, report); } catch (error) { releaseRunLock(root, reportPath, lock.nonce); throw error; }
+  return { ...plan, reportPath, report, lock };
+}
+
+export function recordResearch({ root = process.cwd(), reportPath, ladder, citations }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (!Array.isArray(ladder) || !ladder.length || ladder.some((version) => !rubyVersion.test(version))) throw new Error("Research requires a Ruby-version ladder.");
+  if (series(ladder.at(-1)) !== series(run.targetRuby)) throw new Error("The research ladder must end at the pinned target Ruby series.");
+  if (ladder.some((version, index) => index > 0 && !contiguousRubyHop(ladder[index - 1], version))) throw new Error("The research ladder must advance exactly one Ruby minor series per hop.");
+  const declared = run.inventory.rubyDeclarations.map((declaration) => declaration.value).find(Boolean);
+  if (declared && series(ladder[0]) !== series(declared)) throw new Error("The research ladder must begin at the project’s detected Ruby version.");
+  if (!Array.isArray(citations) || !citations.length || citations.some((citation) => !citation?.title || !/^https:\/\//.test(citation.url ?? ""))) throw new Error("Research requires at least one HTTPS official-source citation.");
+  run.research = { ladder, citations }; writeRun(root, reportPath, run); return run;
+}
+
+export function recordRailsResearch({ root = process.cwd(), reportPath, ladder, citations }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType !== "rails_bridge") throw new Error("Rails research belongs only to a Rails bridge report.");
+  if (!Array.isArray(ladder) || ladder.length < 2 || ladder.some((version) => !railsVersion.test(version)) || series(ladder[0]) !== series(run.bridge.railsFrom) || series(ladder.at(-1)) !== series(run.targetRails) || ladder.some((version, index) => index > 0 && !contiguousRailsHop(ladder[index - 1], version))) throw new Error("Rails research must provide contiguous minor-version hops from the recorded Rails version to targetRails.");
+  if (!Array.isArray(citations) || !citations.length || citations.some((citation) => !citation?.title || !/^https:\/\//.test(citation.url ?? ""))) throw new Error("Rails research requires HTTPS citations.");
+  run.research = { ladder, citations }; writeRun(root, reportPath, run); return run;
+}
+
+export function recordRiskDecision({ root = process.cwd(), reportPath, risk, decision, evidence = "" }) {
+  if (!risk || !["approved", "paused", "blocked"].includes(decision)) throw new Error("Risk decisions require a risk and approved, paused, or blocked decision.");
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce); run.riskDecisions.push({ risk, decision, evidence, recordedAt: new Date().toISOString() }); writeRun(root, reportPath, run); return run;
+}
+
+export function recordFrameworkBridge({ root = process.cwd(), reportPath, rubyFrom, rubyTo, railsFrom, railsTo, rationale, citations }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (!["research_complete", "committed"].includes(run.phase)) throw new Error("Record a Rails compatibility bridge only after research or a committed Ruby checkpoint and before a blocked Ruby hop.");
+  if (run.frameworkBridge) throw new Error("This run already has an approved Rails compatibility bridge; complete it in a separately scoped Rails migration.");
+  if (![rubyFrom, rubyTo].every((version) => rubyVersion.test(version)) || ![railsFrom, railsTo].every((version) => railsVersion.test(version))) throw new Error("A Rails compatibility bridge requires Ruby and Rails from/to versions.");
+  if (series(rubyFrom) !== series(run.iterations.at(-1)?.to ?? run.research.ladder[0]) || series(rubyTo) !== series(run.research.ladder[run.research.ladder.findIndex((version) => series(version) === series(rubyFrom)) + 1])) throw new Error("Rails compatibility bridge must describe the next researched Ruby hop.");
+  if (!run.inventory.rails?.resolvedVersion) throw new Error("Rails compatibility bridges require a resolved Rails version from Gemfile.lock.");
+  if (series(railsFrom) !== series(run.inventory.rails.resolvedVersion)) throw new Error("Rails compatibility bridge must begin at the detected Rails version.");
+  if (!rationale || !Array.isArray(citations) || !citations.length || citations.some((citation) => !citation?.title || !/^https:\/\//.test(citation.url ?? ""))) throw new Error("Rails compatibility bridge requires a rationale and HTTPS citations.");
+  run.frameworkBridge = { status: "approved", rubyFrom, rubyTo, railsFrom, railsTo, rationale, citations, recordedAt: new Date().toISOString() };
+  run.summary = [...run.summary, `User approved a separately scoped Rails ${railsFrom} → ${railsTo} bridge before Ruby ${rubyFrom} → ${rubyTo}.`];
+  writeRun(root, reportPath, run); return run;
+}
+
+function recordIterationInternal({ root = process.cwd(), reportPath, iteration, executed = false }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType === "rails_bridge") throw new Error("Use record-rails-iteration for a Rails bridge report.");
+  if (run.validationReceiptsRequired && !executed) throw new Error("New reports require record-executed-iteration so validation receipts are created by the executor.");
+  if (run.phase !== "research_complete" && run.phase !== "committed") throw new Error("Record iterations only after research or a prior checkpoint.");
+  assertApprovedRisks(run);
+  if (run.iterations.length && (run.phase !== "committed" || !run.iterations.at(-1).checkpointSha)) throw new Error("Each iteration requires exactly one checkpoint before the next iteration.");
+  const expectedFrom = run.iterations.at(-1)?.to ?? run.research.ladder[0];
+  const fromIndex = run.research.ladder.findIndex((version) => series(version) === series(expectedFrom));
+  const expectedTo = run.research.ladder[fromIndex + 1];
+  if (!iteration || fromIndex < 0 || !expectedTo || series(iteration.from) !== series(expectedFrom) || series(iteration.to) !== series(expectedTo)) throw new Error("Iteration must advance exactly one researched Ruby minor series from the prior ladder point.");
+  run.iterations.push({ ...iteration, status: "complete" }); writeRun(root, reportPath, run); return run;
+}
+
+export function recordIteration(options = {}) { return recordIterationInternal(options); }
+
+function recordRailsIterationInternal({ root = process.cwd(), reportPath, iteration, executed = false }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType !== "rails_bridge" || !["research_complete", "committed"].includes(run.phase)) throw new Error("Record Rails iterations only after Rails research or a prior Rails checkpoint.");
+  if (run.validationReceiptsRequired && !executed) throw new Error("New reports require record-executed-rails-iteration so validation receipts are created by the executor.");
+  assertApprovedRisks(run);
+  if (run.iterations.length && (run.phase !== "committed" || !run.iterations.at(-1).checkpointSha)) throw new Error("Each iteration requires exactly one checkpoint before the next iteration.");
+  const expectedFrom = run.iterations.at(-1)?.to ?? run.research.ladder[0]; const index = run.research.ladder.findIndex((version) => series(version) === series(expectedFrom)); const expectedTo = run.research.ladder[index + 1];
+  if (!iteration || !expectedTo || series(iteration.from) !== series(expectedFrom) || series(iteration.to) !== series(expectedTo) || !iteration.appUpdateReview) throw new Error("Rails iteration must advance exactly one researched Rails minor and include app:update review evidence.");
+  run.iterations.push({ ...iteration, status: "complete" }); writeRun(root, reportPath, run); return run;
+}
+
+export function recordRailsIteration(options = {}) { return recordRailsIterationInternal(options); }
+
+export function recordExecutedIteration({ root = process.cwd(), reportPath, iteration, validationCommandId }) {
+  const run = validationPreflight(root, reportPath, false); const receipt = executeValidation({ root, inventory: run.inventory, commandId: validationCommandId });
+  if (receipt.kind !== "test" || receipt.exitCode !== 0 || receipt.testEvidence?.passed !== true) throw new Error(`Validation failed; receipt ${receipt.id} was not recorded as a passing hop.`);
+  return recordIterationInternal({ root, reportPath, executed: true, iteration: { ...iteration, tests: { ...receipt.testEvidence, smoke: iteration?.tests?.smoke }, validationReceipts: [receipt] } });
+}
+
+export function recordExecutedRailsIteration({ root = process.cwd(), reportPath, iteration, testValidationCommandId }) {
+  const run = validationPreflight(root, reportPath, true);
+  if (!run.pendingAppUpdate) {
+    const updateReceipt = executeValidation({ root, inventory: run.inventory, commandId: "rails-app-update" });
+    if (updateReceipt.exitCode !== 0) throw new Error("app:update failed; Rails hop was not recorded.");
+    run.pendingAppUpdate = updateReceipt;
+    writeRun(root, reportPath, run);
+    return { pendingReview: true, receipt: updateReceipt };
+  }
+  const updateReceipt = run.pendingAppUpdate;
+  const review = { ...iteration?.appUpdateReview, receiptId: updateReceipt.id, executedAt: updateReceipt.startedAt, worktree: updateReceipt.worktree };
+  if (!validRailsReviewForExecution(review, updateReceipt)) throw new Error("Review app:update after it executes and bind the review to its receipt and working-tree fingerprint.");
+  const testReceipt = executeValidation({ root, inventory: run.inventory, commandId: testValidationCommandId });
+  if (testReceipt.kind !== "test" || testReceipt.exitCode !== 0 || testReceipt.testEvidence?.passed !== true) throw new Error("Final validation failed; Rails hop was not recorded.");
+  const recorded = recordRailsIterationInternal({ root, reportPath, executed: true, iteration: { ...iteration, tests: { ...testReceipt.testEvidence, smoke: iteration?.tests?.smoke }, validationReceipts: [updateReceipt, testReceipt], appUpdateReview: review } });
+  delete recorded.pendingAppUpdate;
+  writeRun(root, reportPath, recorded);
+  return recorded;
+}
+
+export function discardPendingRailsAppUpdate({ root = process.cwd(), reportPath, reason }) {
+  if (!reason?.trim()) throw new Error("Discarding app:update evidence requires a review reason.");
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType !== "rails_bridge" || !run.pendingAppUpdate) throw new Error("No pending Rails app:update receipt exists for this bridge.");
+  run.discardedAppUpdates = [...(run.discardedAppUpdates ?? []), { receipt: run.pendingAppUpdate, reason: reason.trim(), discardedAt: new Date().toISOString() }];
+  delete run.pendingAppUpdate;
+  run.summary = [...run.summary, `Discarded a reviewed app:update result: ${reason.trim()}`];
+  writeRun(root, reportPath, run); return run;
+}
+
+export function discardLastRailsIteration({ root = process.cwd(), reportPath, reason }) {
+  if (!reason?.trim()) throw new Error("Discarding a recorded Rails iteration requires a review reason.");
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType !== "rails_bridge" || run.phase !== "hop_validated" || run.pendingAppUpdate) throw new Error("Discard the latest validated, uncommitted Rails iteration only while the bridge hop is validated with no pending app:update.");
+  const iteration = run.iterations.at(-1);
+  if (!iteration || iteration.checkpointSha) throw new Error("There is no validated, uncommitted Rails iteration to discard.");
+  run.discardedIterations = [...(run.discardedIterations ?? []), { iteration, reason: reason.trim(), discardedAt: new Date().toISOString() }];
+  run.iterations = run.iterations.slice(0, -1);
+  run.phase = run.iterations.length ? "committed" : "research_complete";
+  run.summary = [...run.summary, `Discarded the latest validated Rails iteration (${iteration.from} -> ${iteration.to}) to re-validate the hop: ${reason.trim()}`];
+  writeRun(root, reportPath, run); return run;
+}
+
+export function recordDependencyReview({ root = process.cwd(), reportPath, compatibility, licenses }) {
+  if (!compatibility?.trim() || !licenses?.trim()) throw new Error("Dependency review requires compatibility and license findings.");
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  const iteration = run.iterations?.at(-1);
+  if (run.phase !== "hop_validated" || !iteration || iteration.checkpointSha) throw new Error("Record dependency review only for the latest validated, uncommitted hop.");
+  iteration.dependencyReview = { completed: true, compatibility: compatibility.trim(), licenses: licenses.trim(), reviewedAt: new Date().toISOString() };
+  run.summary = [...run.summary, "Recorded dependency compatibility and license review for the validated hop."];
+  writeRun(root, reportPath, run); return run;
+}
+
+function validRailsReviewForExecution(review, receipt) { return review?.command === "bin/rails app:update" && review.receiptId === receipt.id && review.executedAt === receipt.startedAt && review.worktree?.diffSha256 === receipt.worktree.diffSha256 && !Number.isNaN(Date.parse(review.reviewedAt ?? "")) && Date.parse(review.reviewedAt) >= Date.parse(receipt.finishedAt); }
+
+function validationPreflight(root, reportPath, rails) {
+  const run = readRun(root, reportPath);
+  assertRunLock(root, reportPath, run.lockNonce);
+  if (Boolean(run.reportType === "rails_bridge") !== rails || !["research_complete", "committed"].includes(run.phase)) throw new Error("Validation can run only for the active report type after research or a prior checkpoint.");
+  assertApprovedRisks(run);
+  if (run.iterations.length && (run.phase !== "committed" || !run.iterations.at(-1).checkpointSha)) throw new Error("Each iteration requires exactly one checkpoint before validation can run again.");
+  return run;
+}
+
+function assertCompletion(run) {
+  const final = run.iterations.at(-1);
+  const target = run.reportType === "rails_bridge" ? run.targetRails : run.targetRuby;
+  if (!final || series(final.to) !== series(target)) throw new Error("A run can complete only after the final validated iteration reaches its pinned target.");
+  if (series(run.research.ladder.at(-1)) !== series(target)) throw new Error("Research ladder does not reach its pinned target.");
+  if (run.riskDecisions.some((risk) => risk.decision !== "approved")) throw new Error("Unresolved risks prevent completion.");
+  if (final.checkpointSha !== run.expectedHead) throw new Error("The final iteration must be committed through the checkpoint gate before completion.");
+}
+
+function verifyCheckpoint(root, reportPath, run, commitSha) {
+  if (run.gitCapabilities?.supported !== true || !run.branch || !run.expectedHead) throw new Error("Non-Git runs cannot claim Git checkpoints or complete through the checkpoint lifecycle.");
+  const head = git(root, ["rev-parse", "HEAD"]);
+  if (head !== commitSha) throw new Error("Checkpoint SHA must be the current Git HEAD created by commit-hop.");
+  if (git(root, ["branch", "--show-current"]) !== run.branch) throw new Error("Checkpoint branch no longer matches the recorded run branch.");
+  if (git(root, ["rev-parse", `${head}^`]) !== run.expectedHead) throw new Error("Checkpoint must be a direct child of the prior recorded checkpoint.");
+  const iteration = run.iterations.at(-1);
+  const message = git(root, ["log", "-1", "--format=%B"]);
+  const prefix = run.reportType === "rails_bridge" ? "Rails" : "Ruby";
+  if (!message.includes(`${prefix}-Upgrade-Report: ${reportPath}`) || !message.includes(`${prefix}-Upgrade-Hop: ${iteration.from}->${iteration.to}`) || (iteration.validationReceipts?.length && !message.includes(`Validation-Receipt-Digest: sha256:${receiptDigest(iteration.validationReceipts)}`)) || (prefix === "Rails" && (!message.includes(`Rails-App-Update-Reviewed: ${iteration.from}->${iteration.to}`) || !message.includes(`Rails-Bridge-Ruby-Report: ${run.bridge.rubyReportPath}`)))) throw new Error("Checkpoint commit does not carry the required run and hop trailers.");
+}
+
+export function transitionRun({ root = process.cwd(), reportPath, phase, note = "", commitSha = "" }) {
+  if (!Object.hasOwn(transitions, phase)) throw new Error(`Unknown run phase: ${phase}.`);
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce); const current = run.phase;
+  if (current === "blocked" && run.frameworkBridge) throw new Error("A Ruby run blocked by a Rails bridge is terminal; complete the bridge and start a fresh Ruby run.");
+  if (!transitions[current]?.includes(phase)) throw new Error(`Cannot transition from ${current} to ${phase}.`);
+  if (phase === "research_complete" && (!run.research.ladder.length || !run.research.citations.length)) throw new Error("Record research and citations before completing research.");
+  if (phase === "hop_validated" && (run.iterations.at(-1)?.tests?.passed !== true || !run.iterations.at(-1)?.validationReceipts?.length)) throw new Error("A hop requires passing tests and executed validation receipts.");
+  if (phase === "hop_validated" && run.iterations.at(-1)?.checkpointSha) throw new Error("A checkpointed iteration cannot be validated again; record the next hop first.");
+  if (phase === "committed") {
+    if (!/^[a-f0-9]{40}$/i.test(commitSha)) throw new Error("Record the checkpoint SHA after commit-hop.");
+    const iteration = run.iterations.at(-1); if (!iteration || iteration.checkpointSha) throw new Error("A committed transition requires one uncheckpointed iteration.");
+    verifyCheckpoint(root, reportPath, run, commitSha);
+    iteration.checkpointSha = commitSha; run.expectedHead = commitSha;
+  }
+  if (phase === "complete") assertCompletion(run);
+  if (phase === "paused") run.resumePhase = current;
+  if (phase === "committed" && run.control.stopAfterHop && run.iterations.length === 1) { run.resumePhase = "committed"; phase = "paused"; }
+  run.phase = phase; run.status = phase === "complete" ? "complete" : phase === "blocked" ? "blocked" : phase === "paused" ? "paused" : "in_progress";
+  if (note) run.summary = [...run.summary, note]; writeRun(root, reportPath, run);
+  if (["complete", "blocked", "paused"].includes(phase)) releaseRunLock(root, reportPath, run.lockNonce);
+  return run;
+}
+
+export function resumeRun({ root = process.cwd(), reportPath, continueAfterHop = false }) {
+  const run = readRun(root, reportPath);
+  if (run.status === "complete") throw new Error("This run is complete; start a new run instead.");
+  if (run.frameworkBridge && run.phase === "blocked") throw new Error("This Ruby run is blocked by an approved Rails bridge and cannot resume. Complete the linked Rails bridge, then begin a fresh Ruby run.");
+  if (run.phase === "paused" && !transitions.paused.includes(run.resumePhase)) throw new Error("Paused run has no safe resume phase.");
+  if (run.control.stopAfterHop && run.iterations.length >= 1 && run.resumePhase === "committed" && !continueAfterHop) throw new Error("This run stopped after its requested hop. Resume with explicit --continue-after-hop only after user review.");
+  if (continueAfterHop) run.control.stopAfterHop = false;
+  const lock = acquireRunLock(root, reportPath); run.lockNonce = lock.nonce;
+  try {
+   if (run.phase === "paused") {
+    run.phase = run.resumePhase; run.status = "in_progress"; delete run.resumePhase; writeRun(root, reportPath, run);
+   }
+  } catch (error) { releaseRunLock(root, reportPath, lock.nonce); throw error; }
+  return { lock, run: readRun(root, reportPath) };
+}
+
+export const runPhases = Object.freeze(Object.keys(transitions));

package/src/dashboard-page.js

@@ -0,0 +1,16 @@
+export const dashboardPage = String.raw`<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Ruby Upgrade Workspace</title>
+<style>
+:root{color-scheme:dark}*{box-sizing:border-box}body{margin:0;background:#101114;color:#e9e9ed;font:15px ui-sans-serif,system-ui,-apple-system,sans-serif;line-height:1.45}main{max-width:1080px;margin:auto;padding:56px 28px 90px}h1{font-size:34px;letter-spacing:-.7px;margin:0 0 7px}h2{font-size:20px;margin:12px 0 4px}.sub,small{color:#a8acb7}.card{background:#191b20;border:1px solid #30333b;border-radius:12px;padding:20px;margin:15px 0;box-shadow:0 8px 30px #0002}.tag{display:inline-block;background:#302028;color:#ffb7ba;border-radius:99px;padding:4px 9px;font-size:12px;margin-right:6px}.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(135px,1fr));gap:10px;margin:16px 0}.metric{background:#121419;border-radius:9px;padding:10px}.metric b{display:block;color:#fff;font-size:17px;overflow-wrap:anywhere}.iteration{border-top:1px solid #30333b;margin-top:16px;padding-top:14px}ul{padding-left:21px;margin:9px 0}pre{white-space:pre-wrap;color:#c9ccd4;font:13px ui-monospace,SFMono-Regular,monospace}a{color:#ff9da1}code{background:#252831;padding:2px 4px;border-radius:4px}
+</style></head><body><main><h1>Ruby Upgrade Workspace</h1><p class="sub">Local-only migration evidence, test health, and source citations.</p><div id="app"></div></main><script>
+const esc=value=>String(value??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+const safeUrl=value=>/^https?:\/\//.test(String(value))?esc(value):'#';
+const metric=(label,value)=>'<div class="metric"><small>'+esc(label)+'</small><b>'+esc(value??'—')+'</b></div>';
+const testValue=(tests,key,fallback='—')=>tests&&tests[key]!==undefined&&tests[key]!==null?tests[key]:fallback;
+fetch('/api/runs').then(response=>response.json()).then(runs=>{
+ const app=document.querySelector('#app');
+ if(!runs.length){app.innerHTML='<article class="card"><b>No upgrade runs yet.</b><p>Run <code>/ruby-upgrade</code> from a linked Git worktree. Evidence will appear under <code>.ruby-upgrades/runs/</code>.</p></article>';return;}
+ app.innerHTML=runs.map(run=>{const iterations=run.iterations||[];const latest=iterations.at(-1)||{};const tests=latest.tests||{};const commits=(run.localCommits||[]).map(sha=>'<code>'+esc(sha)+'</code>').join(' ')||'No local commit found yet.';const target=run.reportType==='rails_bridge'?'Rails '+(run.targetRails||'target unknown'):'Ruby '+(run.targetRuby||'target unknown');const bridge=run.reportType==='rails_bridge'?'<p><b>Blocked Ruby hop:</b> '+esc(run.bridge?.rubyFrom)+' → '+esc(run.bridge?.rubyTo)+' · <code>'+esc(run.bridge?.rubyReportPath)+'</code></p>':'';const details=iterations.map(iteration=>{const itTests=iteration.tests||{};const fixes=(iteration.fixes||[]).map(fix=>'<li><b>'+esc((fix.files||[]).join(', ')||'Migration fix')+'</b><br>'+esc(fix.explanation)+'</li>').join('')||'<li>No code or dependency fixes recorded.</li>';const citations=(iteration.citations||[]).map(citation=>'<a href="'+safeUrl(citation.url)+'" target="_blank" rel="noreferrer">'+esc(citation.title||citation.url)+'</a>').join(' · ')||'No citations recorded.';const appUpdate=iteration.appUpdateReview?'<p><small>app:update: '+esc(iteration.appUpdateReview.outcome)+' — '+esc(iteration.appUpdateReview.summary)+'</small></p>':'';const receipts=(iteration.validationReceipts||[]).map(receipt=>{const digest=receipt.output&&receipt.output.redactedSha256?receipt.output.redactedSha256.slice(0,16):'';const meta=['kind:'+esc(receipt.kind||'—'),'exit:'+esc(receipt.exitCode??'—'),(receipt.durationMs?'ms:'+esc(receipt.durationMs):'')].filter(Boolean).join(' · ');return '<li><code>'+meta+'</code>'+((receipt.testEvidence&&receipt.testEvidence.passed===true)?' <b>[PASS]</b>':'')+'<br><small>digest <code>'+esc(digest||'—')+'</code> · '+(receipt.environment?esc(receipt.environment.imageRef||receipt.environment.ruby||'')+' · <code>'+esc(receipt.environment.imageId||receipt.environment.id||'')+'</code>':'')+'</small></li>';}).join('');const review=iteration.dependencyReview&&iteration.dependencyReview.completed?'<p><small>Dependency review: '+esc(iteration.dependencyReview.compatibility||'completed')+(iteration.dependencyReview.licenses?' · '+esc(iteration.dependencyReview.licenses):'')+'</small></p>':'';return '<section class="iteration"><b>'+esc(iteration.from)+' → '+esc(iteration.to)+' · '+esc(iteration.status)+'</b><div class="grid">'+metric('Test result',itTests.passed===true?'Passed':itTests.passed===false?'Failed':'—')+metric('Smoke check',testValue(itTests,'smoke'))+metric('Coverage',testValue(itTests,'coveragePercent',null)===null?'—':testValue(itTests,'coveragePercent')+'%')+'</div><ul>'+fixes+'</ul>'+review+((iteration.validationReceipts&&iteration.validationReceipts.length)?'<p><b>Receipts</b></p><ul>'+receipts+'</ul>':'')+appUpdate+'<br><small>Sources: '+citations+'</small></section>';}).join('');return '<article class="card"><span class="tag">'+esc(run.status||'unknown')+'</span><span class="tag">'+esc(target)+'</span><h2>'+esc(run.title||run.file)+'</h2><p class="sub">'+esc(run.startedAt||'Unknown start')+' · '+esc(run.branch||'Unknown branch')+'</p><div class="grid">'+metric('Tests',testValue(tests,'count'))+metric('Coverage',testValue(tests,'coveragePercent',null)===null?'—':testValue(tests,'coveragePercent')+'%')+metric('Duration',testValue(tests,'durationSeconds',null)===null?'—':testValue(tests,'durationSeconds')+'s')+metric('Smoke check',testValue(tests,'smoke'))+'</div><pre>'+esc((run.summary||[]).join('\n'))+'</pre>'+bridge+details+'<p><b>Local commits:</b> '+commits+'</p><p><b>Session:</b> '+esc(run.sessionSummary||'—')+'</p></article>';}).join('');
+}).catch(error=>{document.querySelector('#app').innerHTML='<article class="card">Could not load upgrade reports: '+esc(error.message)+'</article>';});
+</script></body></html>`;

package/src/dashboard.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { dashboardPage } from "./dashboard-page.js";
+import { readRun } from "./run-state.js";
+
+const MAX_RUN_FILES = 250;
+const MAX_RUN_BYTES = 1024 * 1024;
+
+function localCommitLinks(root) {
+  try {
+    const output = execFileSync("git", ["log", "--max-count=250", "--format=%H%x1f%B%x1e"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 2 * 1024 * 1024 });
+    return output.split("\x1e").reduce((links, entry) => {
+      const [sha, message] = entry.split("\x1f");
+      const match = message?.match(/^(?:Ruby|Rails)-Upgrade-Report:\s+(.+)$/m);
+      if (sha && match) (links[match[1].trim()] ??= []).push(sha);
+      return links;
+    }, {});
+  } catch { return {}; }
+}
+
+export function readUpgradeRuns(root = process.cwd()) {
+  const directory = path.join(root, ".ruby-upgrades", "runs");
+  if (!fs.existsSync(directory)) return [];
+  const commits = localCommitLinks(root);
+  return fs.readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .flatMap((entry) => {
+      const filePath = path.join(directory, entry.name);
+      try {
+        if (fs.statSync(filePath).size > MAX_RUN_BYTES) return [];
+        const relativePath = path.join(".ruby-upgrades", "runs", entry.name);
+        const parsed = readRun(root, relativePath);
+        const { lockNonce, ...report } = parsed;
+        return [{ ...report, file: entry.name, localCommits: commits[relativePath] ?? [] }];
+      }
+      catch { return []; }
+    })
+    .sort((a, b) => String(b.startedAt ?? "").localeCompare(String(a.startedAt ?? "")))
+    .slice(0, MAX_RUN_FILES);
+}
+
+export function startDashboard({ root = process.cwd(), port = 0 } = {}) {
+  const server = http.createServer((request, response) => {
+    const securityHeaders = {
+      "cache-control": "no-store",
+      "x-content-type-options": "nosniff",
+      "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+    };
+    if (request.method !== "GET") {
+      response.writeHead(405, { ...securityHeaders, allow: "GET", "content-type": "text/plain; charset=utf-8" });
+      return response.end("Method not allowed");
+    }
+    if (request.url === "/api/runs") {
+      response.writeHead(200, { ...securityHeaders, "content-type": "application/json; charset=utf-8" });
+      return response.end(JSON.stringify(readUpgradeRuns(root)));
+    }
+    if (request.url === "/" || request.url === "/index.html") {
+      response.writeHead(200, { ...securityHeaders, "content-type": "text/html; charset=utf-8" });
+      return response.end(dashboardPage);
+    }
+    response.writeHead(404, { ...securityHeaders, "content-type": "text/plain; charset=utf-8" });
+    response.end("Not found");
+  });
+  return new Promise((resolve) => server.listen(port, "127.0.0.1", () => resolve(server)));
+}

package/src/index.js

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function readAgentPrompt() {
+  const cli = `node ${path.join(packageRoot, "bin", "opencode-ruby-upgrader.mjs")}`;
+  return fs.readFileSync(path.join(packageRoot, "agents", "ruby-upgrade.md"), "utf8")
+    .replace(/^---[\s\S]*?---\s*/m, "")
+    .replaceAll("opencode-ruby-upgrader ", `${cli} `)
+    .trim();
+}
+
+export default async function RubyUpgradePlugin() {
+  return {
+    config: async (cfg) => {
+      cfg.agent ??= {};
+      if (!cfg.agent["ruby-upgrade"]) {
+        cfg.agent["ruby-upgrade"] = {
+          mode: "primary",
+          color: "#cc342d",
+          description: "Principal-level, evidence-driven Ruby and Rails runtime migration specialist.",
+          prompt: readAgentPrompt(),
+          permission: {
+            read: "allow", edit: "allow", glob: "allow", grep: "allow",
+            webfetch: "allow", question: "allow", todowrite: "allow",
+            bash: {
+              "*": "ask",
+              "git *": "deny",
+              "git status*": "allow",
+              "git diff*": "allow",
+              "git log*": "allow",
+              "git show*": "allow",
+              "git rev-parse*": "allow",
+              "git branch --show-current": "allow",
+              "git worktree list*": "allow",
+              "git push*": "deny",
+              "git -C * push*": "deny",
+              "git fetch*": "deny",
+              "git remote*": "deny",
+              "git checkout*": "deny",
+              "git switch*": "deny",
+              "git reset*": "deny",
+              "git clean*": "deny",
+              "git rebase*": "deny",
+              "git merge*": "deny",
+              "bundle --version*": "allow",
+              "bundle check*": "allow",
+               "bundle install*": "ask",
+               "bundle update *": "ask",
+               "bundle exec rspec*": "ask",
+               "bundle exec rails test*": "ask",
+               "bundle exec rake test*": "ask",
+              "bundle exec rake db:*": "deny",
+                "bin/rails test*": "ask",
+                "./bin/rails test*": "ask",
+               "bin/rails app:update": "ask",
+               "ruby --version*": "allow",
+               [`node ${path.join(packageRoot, "bin", "opencode-ruby-upgrader.mjs")} preflight*`]: "allow",
+               [`node ${path.join(packageRoot, "bin", "opencode-ruby-upgrader.mjs")} prepare-target-runtime --ruby *`]: "ask",
+               "opencode-ruby-upgrader preflight*": "allow",
+                "opencode-ruby-upgrader begin --target *": "ask",
+                "opencode-ruby-upgrader begin-rails-bridge --ruby-report *": "ask",
+                "opencode-ruby-upgrader prepare-target-runtime --ruby *": "ask",
+              "opencode-ruby-upgrader status --report *": "allow",
+               "opencode-ruby-upgrader transition --report *": "ask",
+              "opencode-ruby-upgrader inventory": "allow",
+              "opencode-ruby-upgrader supply-chain": "allow",
+              "opencode-ruby-upgrader git-capabilities": "allow",
+                "opencode-ruby-upgrader record-research --report *": "ask",
+                "opencode-ruby-upgrader record-rails-research --report *": "ask",
+                "opencode-ruby-upgrader record-risk --report *": "ask",
+                "opencode-ruby-upgrader record-framework-bridge --report *": "ask",
+                "opencode-ruby-upgrader record-iteration --report *": "ask",
+                "opencode-ruby-upgrader record-rails-iteration --report *": "ask",
+                "opencode-ruby-upgrader record-executed-iteration --report *": "ask",
+                 "opencode-ruby-upgrader record-executed-rails-iteration --report *": "ask",
+                 "opencode-ruby-upgrader discard-pending-app-update --report *": "ask",
+                 "opencode-ruby-upgrader discard-last-rails-iteration --report *": "ask",
+                 "opencode-ruby-upgrader record-dependency-review --report *": "ask",
+                 "opencode-ruby-upgrader commit-hop --report *": "ask",
+                "opencode-ruby-upgrader commit-rails-hop --report *": "ask",
+               "opencode-ruby-upgrader resume --report *": "ask",
+               "opencode-ruby-upgrader release-lock --report *": "ask",
+              "*;*": "deny",
+              "*&&*": "deny",
+              "*||*": "deny",
+              "*|*": "deny",
+              "*$(*": "deny",
+              "*`*": "deny",
+              "git push*": "deny",
+              "gh *": "deny",
+              "npm publish*": "deny",
+              "gem push*": "deny",
+              "bundle exec rake release*": "deny"
+            }
+          }
+        };
+      }
+
+      cfg.command ??= {};
+      if (!cfg.command["ruby-upgrade"]) {
+        cfg.command["ruby-upgrade"] = {
+          description: "Safely migrate this Ruby project to the latest stable Ruby release.",
+          agent: "ruby-upgrade",
+          template: "Begin the Ruby migration preflight. User context: $ARGUMENTS"
+        };
+      }
+    }
+  };
+}

package/src/inventory.js

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const exists = (root, file) => fs.existsSync(path.join(root, file));
+const read = (root, file) => exists(root, file) ? fs.readFileSync(path.join(root, file), "utf8") : "";
+
+export function inventoryProject(root = process.cwd()) {
+  const gemfile = read(root, "Gemfile");
+  const lockfile = read(root, "Gemfile.lock");
+  const rubyFiles = [".ruby-version", ".tool-versions", ".mise.toml", "Gemfile", "Dockerfile"].filter((file) => exists(root, file));
+  const rubyDeclarations = rubyFiles.map((file) => {
+    const contents = read(root, file);
+    const match = contents.match(/(?:^|\s)(?:ruby\s*[= ]\s*["']?|ruby\s+|FROM\s+ruby:)(\d+\.\d+(?:\.\d+)?)/mi) ?? (file === ".ruby-version" ? contents.match(/^\s*(\d+\.\d+(?:\.\d+)?)\s*$/m) : null);
+    return { file, value: match?.[1] ?? null };
+  });
+  const rspec = exists(root, "spec") || /\brspec\b/i.test(gemfile);
+  const declaredRails = gemfile.match(/\bgem\s+["']rails["']\s*,?\s*["']?([~<>= ]*\d+\.\d+(?:\.\d+)?)/i)?.[1]?.trim() ?? null;
+  const resolvedRails = lockfile.match(/^ {4}rails \((\d+(?:\.\d+)+)\)$/m)?.[1] ?? null;
+  const rails = /\bgem\s+["']rails["']/i.test(gemfile) || Boolean(resolvedRails);
+  const minitest = exists(root, "test") || /\bminitest\b/i.test(gemfile);
+  const commands = rspec ? ["bundle exec rspec"] : rails ? [exists(root, "bin/rails") ? "bin/rails test" : "bundle exec rails test"] : minitest ? ["bundle exec rake test"] : [];
+  const ci = [".github/workflows", ".gitlab-ci.yml", ".circleci", "Jenkinsfile", "azure-pipelines.yml"].filter((file) => exists(root, file));
+  const deploy = ["Dockerfile", "docker-compose.yml", "Procfile", "app.json", "render.yaml", "fly.toml", "config/deploy.yml"].filter((file) => exists(root, file));
+  return {
+    root, supported: exists(root, "Gemfile"), framework: rails ? "rails" : "ruby", testFramework: rspec ? "rspec" : minitest ? "minitest" : "unknown",
+    rubyDeclarations, rails: rails ? { declaredVersion: declaredRails, resolvedVersion: resolvedRails } : null, recommendedCommands: commands, ci, deploy,
+    requiresDecision: !exists(root, "Gemfile") || commands.length === 0,
+    reason: !exists(root, "Gemfile") ? "No Gemfile found." : commands.length === 0 ? "No recognized test adapter found." : undefined
+  };
+}

package/src/preflight.js

@@ -0,0 +1,69 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+function git(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function configuredDefaultBranch(cwd) {
+  try { return git(cwd, ["config", "--get", "opencode-ruby-upgrader.defaultBranch"]); }
+  catch { return undefined; }
+}
+
+export function inspectWorktree(cwd = process.cwd()) {
+  try {
+    try { git(cwd, ["--version"]); }
+    catch (error) { return { ok: false, reason: "git-unavailable", detail: error.message }; }
+    if (git(cwd, ["rev-parse", "--is-inside-work-tree"]) !== "true") {
+      return { ok: true, mode: "non-git", root: cwd };
+    }
+    const root = git(cwd, ["rev-parse", "--show-toplevel"]);
+    const gitDir = git(cwd, ["rev-parse", "--git-dir"]);
+    const commonDir = git(cwd, ["rev-parse", "--git-common-dir"]);
+    const linkedWorktree = path.resolve(root, gitDir) !== path.resolve(root, commonDir);
+    const branch = git(cwd, ["branch", "--show-current"]);
+    const sha = git(cwd, ["rev-parse", "HEAD"]);
+    const dirty = Boolean(git(cwd, ["status", "--porcelain", "--", ".", ":(exclude).ruby-upgrades"]));
+    const defaultBranch = configuredDefaultBranch(cwd);
+    if (!linkedWorktree) return { ok: false, reason: "primary-checkout", root, branch, sha, defaultBranch };
+    if (!branch) return { ok: false, reason: "detached-head", root, sha, defaultBranch };
+    if (!defaultBranch) return { ok: false, reason: "default-branch-unconfigured", root, branch, sha };
+    if (branch === defaultBranch) return { ok: false, reason: "default-branch", root, branch, sha, defaultBranch };
+    if (dirty) return { ok: false, reason: "dirty-worktree", root, branch, sha, defaultBranch };
+    return { ok: true, mode: "linked-worktree", root, branch, sha, gitDir, commonDir };
+  } catch (error) {
+    if (/not a git repository/i.test(error.message)) return { ok: true, mode: "non-git", root: cwd };
+    return { ok: false, reason: "git-preflight-failed", detail: error.message };
+  }
+}
+
+export function setupInstructions(result) {
+  const repo = result.root ? path.basename(result.root) : "your-repository";
+  return [
+    "Ruby upgrades run only in a user-created linked Git worktree.",
+    "Configure the repository default branch before starting:",
+    "  git config opencode-ruby-upgrader.defaultBranch <default-branch>",
+    "From your primary checkout, create a branch and linked worktree yourself:",
+    `  git branch ruby-upgrade/ruby-<target>`,
+    `  git worktree add ../${repo}-ruby-<target> ruby-upgrade/ruby-<target>`,
+    `  cd ../${repo}-ruby-<target> && opencode`,
+    "The agent will not create, switch, merge, push, or otherwise manage branches/remotes."
+  ].join("\n");
+}
+
+export function inspectGitCapabilities(cwd = process.cwd()) {
+  try {
+    const root = git(cwd, ["rev-parse", "--show-toplevel"]);
+    const value = (args, fallback = false) => { try { return git(cwd, args); } catch { return fallback; } };
+    const submodules = fs.existsSync(path.join(root, ".gitmodules"));
+    return {
+      supported: true,
+      shallow: value(["rev-parse", "--is-shallow-repository"]) === "true",
+      sparseCheckout: value(["config", "--bool", "core.sparseCheckout"]) === "true",
+      submodules,
+      lfsConfigured: value(["config", "--get-regexp", "^filter\\.lfs\\."]) !== false,
+      recommendation: submodules || value(["rev-parse", "--is-shallow-repository"]) === "true" || value(["config", "--bool", "core.sparseCheckout"]) === "true" ? "Pause for repository-topology review before migration." : "Standard Git topology."
+    };
+  } catch { return { supported: false, recommendation: "Not a Git repository." }; }
+}

package/src/provenance.js

@@ -0,0 +1,21 @@
+import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+export function receiptDigest(receipts = []) {
+  return crypto.createHash("sha256").update(JSON.stringify(canonical(receipts))).digest("hex");
+}
+
+export function worktreeFingerprint(root = process.cwd()) {
+  const git = (args) => execFileSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+  const headSha = git(["rev-parse", "HEAD"]).trim();
+  const diff = git(["diff", "--binary", "HEAD", "--", ":(exclude).ruby-upgrades"]);
+  const untracked = git(["ls-files", "--others", "--exclude-standard", "-z", "--", ":(exclude).ruby-upgrades"])
+    .split("\0").filter(Boolean).map((file) => `${file}\0${git(["hash-object", "--", file]).trim()}`).join("\0");
+  return { algorithm: "sha256", headSha, diffSha256: crypto.createHash("sha256").update(`${diff}\0${untracked}`).digest("hex") };
+}