dorfl 0.14.2 → 0.15.0

package/src/prompt.ts

@@ -242,6 +242,8 @@ export function wrapper(
 		protocolPath?: string;
 		cwd?: string;
 		promptGuidance?: {testFirst?: boolean};
+		/** The folder the body was resolved from; see {@link retargetBodyFolder}. */
+		taskFolder?: TaskFolder;
 	} = {},
 ): string {
 	const protocolPath = resolveProtocolDoc(
@@ -251,10 +253,72 @@ export function wrapper(
 	);
 	const protocol = readFileSync(protocolPath, 'utf8');
 	const template = extractCanonicalWrapperTemplate(protocol);
-	const resolved = applyPromptGuidance(template, options.promptGuidance);
+	const resolved = retargetSpecFolder(
+		retargetBodyFolder(
+			applyPromptGuidance(template, options.promptGuidance),
+			options.taskFolder,
+		),
+		spec,
+		options.cwd,
+	);
 	return resolved.replace(/<slug>/g, slug).replace(/<spec>/g, spec ?? '<spec>');
 }
 
+/**
+ * Point the wrapper's source-spec mention at the folder the spec ACTUALLY rests
+ * in. The canonical wrapper assumes `work/specs/ready/<spec>.md`, but once a spec
+ * has been tasked it rests in `work/specs/tasked/`, so builds of its tasks were
+ * told to read a file that does not exist. Located with {@link findSpecPath} (the
+ * same ready-then-tasked lookup the per-item prompt-guidance layer uses). No
+ * `cwd`, no spec, or a spec in `specs/ready/` (or nowhere) leaves the text as is.
+ */
+function retargetSpecFolder(
+	template: string,
+	spec: string | undefined,
+	cwd: string | undefined,
+): string {
+	if (spec === undefined || cwd === undefined) {
+		return template;
+	}
+	const found = findSpecPath(cwd, spec);
+	if (found === undefined || found === workItemPath(cwd, 'specs-ready', spec)) {
+		return template;
+	}
+	return template
+		.split(`${workFolderRel('specs-ready')}/<spec>.md`)
+		.join(`${workFolderRel('specs-tasked')}/<spec>.md`);
+}
+
+/**
+ * Point the wrapper's body-path mentions at the folder the body was ACTUALLY
+ * resolved from. The canonical wrapper (CLAIM-PROTOCOL.md) describes the normal
+ * case, a claim from the pool, so it names `work/tasks/ready/<slug>.md`. Under
+ * `do --allow-backlog` the body rests in `work/tasks/backlog/` (and a stranded
+ * continue resolves it from `work/tasks/done/`), and telling the agent the wrong
+ * path made build agents file observations about it.
+ *
+ * A TEXT rewrite of the extracted template, not a new placeholder: a target repo's
+ * adopted `work/protocol/CLAIM-PROTOCOL.md` may predate any placeholder, and the
+ * rewrite still works on it. Pool bodies (`tasks-ready`) and an omitted folder
+ * leave the wrapper byte-identical to the canonical text.
+ */
+function retargetBodyFolder(
+	template: string,
+	folder: TaskFolder | undefined,
+): string {
+	if (folder === undefined || folder === 'tasks-ready') {
+		return template;
+	}
+	const pool = workFolderRel('tasks-ready');
+	const actual = workFolderRel(folder);
+	const poolBare = pool.slice(`${WORK_ROOT}/`.length);
+	return template
+		.split(`${pool}/<slug>.md`)
+		.join(`${actual}/<slug>.md`)
+		.split(`body ${poolBare}/ ->`)
+		.join(`body ${actual}/ ->`);
+}
+
 /**
  * The CONTINUE context that turns the fresh-start assembly into a continue-mode
  * one (the `agent-prompt-continue-context` task). It is OPT-IN state inherited
@@ -434,6 +498,8 @@ export function buildAgentPrompt(
 		cwd?: string;
 		continueContext?: ContinueContext;
 		promptGuidance?: {testFirst?: boolean};
+		/** The folder the task body was resolved from (`ResolvedTask.folder`). */
+		taskFolder?: TaskFolder;
 	} = {},
 ): string {
 	const head = wrapper(slug, spec, options);
@@ -754,5 +820,6 @@ export function renderPrompt(options: PromptOptions): string {
 		protocolPath: options.protocolPath,
 		cwd: options.cwd,
 		promptGuidance: resolvedGuidance,
+		taskFolder: task.folder,
 	});
 }

package/src/reap-branches.ts

@@ -1,5 +1,9 @@
 import {run} from './git.js';
 import {isProvablyMergedForReap} from './gc.js';
+import {
+	classifyTerminalItemLocks,
+	reconcileTerminalItemLocks,
+} from './item-lock.js';
 import {parseWorkBranchRef} from './slug-namespace.js';
 import type {SidecarType} from './sidecar.js';
 
@@ -178,6 +182,9 @@ export function sweepRemoteMergedBranches(
 			input.cwd,
 			{env},
 		);
+		// WRITE-SEAM EXEMPT: `gc --remote-branches` runs in a no-agent job (or by
+		// a human), never in a CI agent job, so this merged-branch delete stays a
+		// direct push (task `ci-split-route-direct-writes-through-seams`).
 		const del = run(
 			'git',
 			['push', input.arbiter, '--delete', branch],
@@ -209,6 +216,106 @@ export function sweepRemoteMergedBranches(
 	return {reaped, retained, wouldReap};
 }
 
+export interface SweepTerminalItemLocksInput {
+	/**
+	 * A local repo (a checkout or a hub mirror) whose `<arbiter>` remote points at
+	 * the arbiter whose per-item locks to sweep. Only refs are read + deleted.
+	 */
+	cwd: string;
+	/** The arbiter remote name (the SAME one the branch sweep targets). */
+	arbiter: string;
+	/** Sink for human-readable progress notes (per released / kept lock). */
+	note?: (message: string) => void;
+	/** Only REPORT which locks WOULD be released (the `--dry-run` preview). */
+	dryRun?: boolean;
+	env?: NodeJS.ProcessEnv;
+}
+
+export interface SweepTerminalItemLocksResult {
+	/** Lock entries whose item is terminal on main and whose ref was deleted. */
+	released: string[];
+	/** On `dryRun`, the lock entries that WOULD be released (nothing deleted). */
+	wouldRelease: string[];
+	/** Lock entries left HELD because the item is not terminal on main. */
+	kept: string[];
+	/**
+	 * Locks left HELD because their classification or release faulted, including
+	 * a lease REJECTED because the ref moved between the read and the delete.
+	 */
+	errors: {entry: string; message: string}[];
+}
+
+/**
+ * Release every per-item lock whose item is already TERMINAL on the arbiter's
+ * `main` (task `ci-releases-locks-of-terminal-items`). It rides the SAME
+ * `gc --remote-branches` invocation the scheduled `reap-merged-branches` CI job
+ * runs, so the locks a merged propose PR leaves behind stop accumulating in CI
+ * (where no later claim of that item ever comes to release them) WITHOUT any
+ * change to the generated workflows.
+ *
+ * It is NOT a second mechanism: it is exactly the terminal-lock reconcile behind
+ * `status --reconcile-locks` and the claim path
+ * ({@link reconcileTerminalItemLocks}): ONE predicate (the item's body rests in a
+ * terminal folder on `<arbiter>/main`), every delete leased on the sha that was
+ * read (`--force-with-lease`, never forced), every uncertainty resolved towards
+ * KEEPING the lock. SCOPE is the one arbiter the branch sweep targets (the
+ * `<arbiter>` remote of `cwd`). `dryRun` uses the read-only twin
+ * ({@link classifyTerminalItemLocks}). Best-effort and never throws.
+ */
+export async function sweepTerminalItemLocks(
+	input: SweepTerminalItemLocksInput,
+): Promise<SweepTerminalItemLocksResult> {
+	const note = input.note ?? (() => {});
+	const out: SweepTerminalItemLocksResult = {
+		released: [],
+		wouldRelease: [],
+		kept: [],
+		errors: [],
+	};
+	try {
+		if (input.dryRun === true) {
+			const classified = await classifyTerminalItemLocks(
+				input.cwd,
+				input.arbiter,
+				input.env,
+			);
+			out.wouldRelease = classified.terminal.map((l) => l.entry);
+			out.kept = classified.inFlight.map((l) => l.entry);
+			out.errors = classified.errors;
+		} else {
+			const rec = await reconcileTerminalItemLocks(
+				input.cwd,
+				input.arbiter,
+				input.env,
+			);
+			out.released = rec.released;
+			const errored = new Set(rec.errors.map((e) => e.entry));
+			// `kept` in the reconcile report ALSO lists a terminal lock whose release
+			// was refused; that one is reported under `errors` instead, so the two
+			// lists here stay disjoint.
+			out.kept = rec.kept.filter((entry) => !errored.has(entry));
+			out.errors = rec.errors;
+		}
+	} catch (err) {
+		out.errors.push({
+			entry: '(locks)',
+			message: err instanceof Error ? err.message : String(err),
+		});
+	}
+	for (const entry of out.wouldRelease) {
+		note(
+			`Would release lock ${entry} (item terminal on main) on ${input.arbiter}.`,
+		);
+	}
+	for (const entry of out.released) {
+		note(`Released lock ${entry} (item terminal on main) on ${input.arbiter}.`);
+	}
+	for (const e of out.errors) {
+		note(`Kept lock ${e.entry}: ${e.message}`);
+	}
+	return out;
+}
+
 /** Push a retained branch into the result + emit its note. */
 function retain(
 	retained: RetainedBranch[],

package/src/ref-write.ts

@@ -0,0 +1,324 @@
+import {runAsync, type RunResult} from './git.js';
+import {
+	pushContinuedBranchWithStaleLeaseRetry,
+	type ContinuedPushResult,
+} from './continue-branch.js';
+import {
+	routeToNeedsAttention,
+	deleteRemoteWorkBranchIfPresent,
+	type RouteToNeedsAttentionOptions,
+	type RouteToNeedsAttentionResult,
+	type DeleteRemoteWorkBranchOptions,
+	type DeleteRemoteWorkBranchResult,
+} from './needs-attention.js';
+import {
+	pushTreelessResult,
+	type PushTreelessResultParams,
+} from './advance-treeless-publish.js';
+
+/**
+ * The **ref-write seam**: the sibling of the ledger-transition write seam
+ * ({@link import('./ledger-write.js').LedgerWriteStrategy}) for every network
+ * write a CI code path reaches that is NOT a `work/` ledger transition, the
+ * review provider, the issue provider or the integrator: the per-item lock ref
+ * create / amend / leased delete, the continued work-branch rebase push, the
+ * work-branch save (commit WIP + push, without a surface), the remote work-branch
+ * delete, the tasking candidates branch push, the tree-less `HEAD:main`
+ * publish and the Git LFS object upload.
+ *
+ * Why it exists (spec `ci-agent-job-without-write-token`, ADR
+ * `ci-agent-job-holds-no-write-token`, task
+ * `ci-split-route-direct-writes-through-seams`): the CI phase mode records every
+ * write in the agent phase and performs it in the apply phase, so every write
+ * must be VISIBLE at a seam. Before this seam these sites pushed directly.
+ *
+ * It is a PURE REFACTOR, the same shape as the ledger seam: exactly ONE strategy
+ * ({@link currentRefWrite}) that does exactly what each call site did before (the
+ * same git argument lists, the same helpers), no mode, no config. Each method is
+ * named for the write's INTENT, not the git plumbing, so a recording strategy can
+ * capture "what was about to be written" rather than a raw argument list.
+ *
+ * A test swaps a method with `vi.spyOn(refWrite, '<method>')` (the same pattern
+ * the `ledgerWrite` / `ledgerRead` seams use). The guard test
+ * `write-sites-through-seams.test.ts` fails on any new direct `git push` or `gh`
+ * write outside the seam implementations and the documented exempt sites.
+ */
+export interface RefWriteStrategy {
+	/**
+	 * CREATE a per-item lock ref on the arbiter: push `<commit>:<ref>` with the
+	 * create-only lease `--force-with-lease=<ref>:` (succeeds iff the ref is
+	 * absent). Returns the raw push result; the caller interprets it (`acquired`
+	 * vs contended). CI phase: lock.
+	 */
+	createLockRef(input: LockRefCreateInput): Promise<RunResult>;
+	/**
+	 * DELETE a held per-item lock ref on the arbiter, leased on the sha the caller
+	 * read (`push --delete <ref> --force-with-lease=<ref>:<expectedSha>`). CI
+	 * phase: apply (the lease is on the lock job's `lockSha`).
+	 */
+	deleteLockRef(input: LockRefDeleteInput): Promise<RunResult>;
+	/**
+	 * REPLACE a held per-item lock ref on the arbiter with a new lock commit,
+	 * leased on the sha the caller read (`push <commit>:<ref>
+	 * --force-with-lease=<ref>:<expectedSha>`): the amend of a held lock (the
+	 * propose-kept marker, and the answered-merge takeover of a lock carrying
+	 * it). A concurrent change to the ref rejects the push; it is never forced.
+	 * CI phase: lock (the takeover) and apply (the marker).
+	 */
+	replaceLockRef(input: LockRefReplaceInput): Promise<RunResult>;
+	/**
+	 * Push the CONTINUED (rebased) kept `work/<slug>` branch with a lease on the
+	 * tip observed before the rebase, surviving a stale lease by re-fetching and
+	 * re-rebasing (see {@link pushContinuedBranchWithStaleLeaseRetry}). Throws
+	 * exactly as that helper does. CI phase: apply (ADR decision 7).
+	 */
+	pushContinuedBranch(input: ContinuedBranchPushInput): ContinuedPushResult;
+	/**
+	 * Push an already-rebased work branch ONCE with a lease on the tip observed
+	 * earlier (`<commit>:refs/heads/<branch>
+	 * --force-with-lease=refs/heads/<branch>:<expectedTip>`), with NO retry and NO
+	 * re-rebase: a stale lease is returned for the caller to report. The CI apply
+	 * phase's continue push (ADR `ci-agent-job-holds-no-write-token` decision 7:
+	 * the agent job rebased the kept branch locally, and the lease is the lock
+	 * job's `continueTip`). CI phase: apply.
+	 */
+	pushLeasedWorkBranch(input: LeasedWorkBranchPushInput): Promise<RunResult>;
+	/**
+	 * SAVE the work branch: commit any uncommitted work as a wip commit and push
+	 * the work branch to the arbiter, WITHOUT surfacing the item (the recoverable
+	 * half of a needs-attention route, see {@link routeToNeedsAttention}). Used by
+	 * the deadline checkpoint save. CI phase: apply.
+	 */
+	saveWorkBranch(
+		input: RouteToNeedsAttentionOptions,
+	): Promise<RouteToNeedsAttentionResult>;
+	/**
+	 * DELETE the remote `work/task-<slug>` branch on the arbiter (write-through:
+	 * local refs first, then the arbiter delete; already-gone is tolerated, see
+	 * {@link deleteRemoteWorkBranchIfPresent}). CI phase: apply.
+	 */
+	deleteRemoteWorkBranch(
+		input: DeleteRemoteWorkBranchOptions,
+	): Promise<DeleteRemoteWorkBranchResult>;
+	/**
+	 * Push the tasking candidates branch (`work/spec-<slug>`) to the arbiter, a
+	 * plain `git push <arbiter> <branch>` (best-effort at the caller). CI phase:
+	 * apply.
+	 */
+	pushTaskingCandidatesBranch(
+		input: TaskingCandidatesPushInput,
+	): Promise<RunResult>;
+	/**
+	 * Publish a tree-less rung's local commit to the arbiter's `main` (`git push
+	 * HEAD:main` with the bounded re-fetch + rebase retry, never `--force`, see
+	 * {@link pushTreelessResult}). CI phase: apply.
+	 */
+	publishTreelessResult(input: PushTreelessResultParams): Promise<void>;
+	/**
+	 * UPLOAD Git LFS objects already in `cwd`'s local LFS store to the arbiter's
+	 * LFS endpoint (`git lfs push --object-id <arbiter> <oids>`, in batches),
+	 * BEFORE any ref that points at them (ADR `ci-agent-job-holds-no-write-token`
+	 * decision 6). Returns the first failing batch's result, else the last one.
+	 * CI phase: apply.
+	 */
+	pushLfsObjects(input: LfsObjectsPushInput): Promise<RunResult>;
+}
+
+/** Input of {@link RefWriteStrategy.pushLfsObjects}. */
+export interface LfsObjectsPushInput {
+	/** The arbiter remote name (its LFS endpoint comes from `cwd`'s config and `.lfsconfig`). */
+	arbiter: string;
+	/** The sha256 oids to upload (each already in the local store). */
+	oids: readonly string[];
+	/** Working clone the push runs in. */
+	cwd: string;
+	/** Environment for the child git process. */
+	env: NodeJS.ProcessEnv | undefined;
+}
+
+/** How many oids one `git lfs push --object-id` is given. */
+const LFS_PUSH_BATCH = 100;
+
+/** Input of {@link RefWriteStrategy.createLockRef}. */
+export interface LockRefCreateInput {
+	/** The arbiter remote name. */
+	arbiter: string;
+	/** The full lock ref (`refs/dorfl/lock/<entry>`). */
+	ref: string;
+	/** The prepared (parentless) lock commit to publish at {@link ref}. */
+	commit: string;
+	/** Working clone the push runs in. */
+	cwd: string;
+	/** Environment for the child git process. */
+	env: NodeJS.ProcessEnv | undefined;
+}
+
+/** Input of {@link RefWriteStrategy.deleteLockRef}. */
+export interface LockRefDeleteInput {
+	/** The arbiter remote name. */
+	arbiter: string;
+	/** The full lock ref (`refs/dorfl/lock/<entry>`). */
+	ref: string;
+	/** The ref's sha the caller read; the delete is leased on it. */
+	expectedSha: string;
+	/** Working clone the push runs in. */
+	cwd: string;
+	/** Environment for the child git process. */
+	env: NodeJS.ProcessEnv | undefined;
+}
+
+/** Input of {@link RefWriteStrategy.replaceLockRef}. */
+export interface LockRefReplaceInput {
+	/** The arbiter remote name. */
+	arbiter: string;
+	/** The full lock ref (`refs/dorfl/lock/<entry>`). */
+	ref: string;
+	/** The prepared (parentless) lock commit to publish at {@link ref}. */
+	commit: string;
+	/** The ref's sha the caller read; the replace is leased on it. */
+	expectedSha: string;
+	/** Working clone the push runs in. */
+	cwd: string;
+	/** Environment for the child git process. */
+	env: NodeJS.ProcessEnv | undefined;
+}
+
+/** Input of {@link RefWriteStrategy.pushContinuedBranch}. */
+export type ContinuedBranchPushInput = Parameters<
+	typeof pushContinuedBranchWithStaleLeaseRetry
+>[0];
+
+/** Input of {@link RefWriteStrategy.pushLeasedWorkBranch}. */
+export interface LeasedWorkBranchPushInput {
+	/** The arbiter remote name. */
+	arbiter: string;
+	/** The work branch (`work/task-<slug>`), unqualified. */
+	branch: string;
+	/** The commit to publish as the branch's tip. */
+	commit: string;
+	/** The branch tip the caller observed on the arbiter; the push is leased on it. */
+	expectedTip: string;
+	/** Working clone the push runs in. */
+	cwd: string;
+	/** Environment for the child git process. */
+	env: NodeJS.ProcessEnv | undefined;
+}
+
+/** Input of {@link RefWriteStrategy.pushTaskingCandidatesBranch}. */
+export interface TaskingCandidatesPushInput {
+	/** The arbiter remote name. */
+	arbiter: string;
+	/** The candidates branch (`work/spec-<slug>`). */
+	branch: string;
+	/** Working clone the push runs in. */
+	cwd: string;
+	/** Environment for the child git process. */
+	env: NodeJS.ProcessEnv | undefined;
+}
+
+/**
+ * The ONLY ref-write strategy: current behaviour, the exact git argument lists
+ * and helpers the call sites used before they were routed through the seam.
+ */
+export const currentRefWrite: RefWriteStrategy = {
+	createLockRef({arbiter, ref, commit, cwd, env}) {
+		return runAsync(
+			'git',
+			['push', arbiter, `${commit}:${ref}`, `--force-with-lease=${ref}:`],
+			cwd,
+			{env},
+		);
+	},
+
+	deleteLockRef({arbiter, ref, expectedSha, cwd, env}) {
+		return runAsync(
+			'git',
+			[
+				'push',
+				arbiter,
+				'--delete',
+				ref,
+				`--force-with-lease=${ref}:${expectedSha}`,
+			],
+			cwd,
+			{env},
+		);
+	},
+
+	replaceLockRef({arbiter, ref, commit, expectedSha, cwd, env}) {
+		return runAsync(
+			'git',
+			[
+				'push',
+				arbiter,
+				`${commit}:${ref}`,
+				`--force-with-lease=${ref}:${expectedSha}`,
+			],
+			cwd,
+			{env},
+		);
+	},
+
+	pushContinuedBranch(input) {
+		return pushContinuedBranchWithStaleLeaseRetry(input);
+	},
+
+	pushLeasedWorkBranch({arbiter, branch, commit, expectedTip, cwd, env}) {
+		const ref = `refs/heads/${branch}`;
+		return runAsync(
+			'git',
+			[
+				'push',
+				arbiter,
+				`${commit}:${ref}`,
+				`--force-with-lease=${ref}:${expectedTip}`,
+			],
+			cwd,
+			{env},
+		);
+	},
+
+	saveWorkBranch(input) {
+		return routeToNeedsAttention(input);
+	},
+
+	deleteRemoteWorkBranch(input) {
+		return deleteRemoteWorkBranchIfPresent(input);
+	},
+
+	pushTaskingCandidatesBranch({arbiter, branch, cwd, env}) {
+		return runAsync('git', ['push', arbiter, branch], cwd, {env});
+	},
+
+	publishTreelessResult(input) {
+		return pushTreelessResult(input);
+	},
+
+	async pushLfsObjects({arbiter, oids, cwd, env}) {
+		let last: RunResult = {status: 0, stdout: '', stderr: ''};
+		for (let i = 0; i < oids.length; i += LFS_PUSH_BATCH) {
+			last = await runAsync(
+				'git',
+				[
+					'lfs',
+					'push',
+					'--object-id',
+					arbiter,
+					...oids.slice(i, i + LFS_PUSH_BATCH),
+				],
+				cwd,
+				{env},
+			);
+			if (last.status !== 0) return last;
+		}
+		return last;
+	},
+};
+
+/**
+ * The active ref-write strategy. There is exactly one (current behaviour); this
+ * indirection is the seam's single insertion point, NOT a selectable mode. Call
+ * sites go through `refWrite.<method>(...)` so a test (and later the CI phase
+ * mode) can replace a method on this object.
+ */
+export const refWrite: RefWriteStrategy = {...currentRefWrite};

package/src/repo-config.ts

@@ -176,16 +176,15 @@ export const REPO_ALLOWED_KEYS = [
 	// same chain as `integration`/`autoBuild`. It REPLACES the old `autoTriage`
 	// boolean (no alias; no external users owed a migration window, 2026-06-12).
 	'observationTriage',
-	// `mergeQuestions` (the 3-state `off|ask|auto` gate over the MERGE-QUESTION
+	// `mergeQuestions` (the 2-state `off|ask` gate over the MERGE-QUESTION
 	// SURFACER — spec `land-time-reverify-and-parallel-merge-ceiling` Story 17 /
 	// task `merge-questions-gate-axis`) is a genuine repo property exactly like
 	// `observationTriage`: whether THIS repo's unmerged `work/*` branches surface
-	// as merge-questions (and whether they auto-land) is agreed by all
-	// collaborators + travels with the repo. SEPARATE axis from
-	// `observationTriage` (never rides it) with a HIGHER default (`ask`, never
-	// `off` — a dropped merge-question means pushed work never lands). Resolved
-	// per-repo through the SAME precedence chain as the rest of the gate family
-	// (flag > env > per-repo > global > default `ask`).
+	// as merge-questions is agreed by all collaborators + travels with the repo.
+	// SEPARATE axis from `observationTriage` (never rides it) with a HIGHER
+	// default (`ask`, never `off`: a dropped merge-question means pushed work
+	// never lands). Resolved per-repo through the SAME precedence chain as the
+	// rest of the gate family (env > per-repo > global > default `ask`).
 	'mergeQuestions',
 	// `surfaceBlockers` (the BOOLEAN gate over DECLARED blocked work — whether a
 	// task/spec carrying `needsAnswers:true` is rendered into a question sidecar) is a
@@ -256,7 +255,8 @@ export const REPO_ALLOWED_KEYS = [
 	// is agreed by all collaborators in a wide-matrix CI repo + travels with the
 	// repo. Resolved per-repo through the SAME chain as `freshWorktreeGate`
 	// (flag > env > per-repo > global > default). Safety is unchanged — a lost
-	// CAS still costs only a re-rebase + re-gate retry, never a `--force`.
+	// CAS still costs only a re-rebase and a retried push (no re-gate), never a
+	// `--force`.
 	'mergeRetries',
 	// `strictMergeApproval` (the OPT-IN strictness layered on the OQ6
 	// stale-approval default — spec `land-time-reverify-and-parallel-merge-ceiling`