dorfl 0.1.2 → 0.2.0

package/src/integration-core.ts

@@ -313,8 +313,8 @@ export interface IntegrationCoreInput {
 	// like a normal build.
 	source: 'tasks-ready' | 'tasks-backlog' | 'in-progress' | 'done';
 	/**
-	 * Vestigial: was `true` when completing FROM `work/needs-attention/` (a
-	 * recovery finish under the legacy folder model). The per-item-lock cutover
+	 * Vestigial: was `true` when completing FROM the retired `needs-attention/`
+	 * folder (a recovery finish under the legacy folder model). The per-item-lock cutover
 	 * (`cutover-needs-attention-becomes-lock-stuck-recovery-surface`) retired
 	 * that folder — a stuck item is now the lock `state: stuck` and the body
 	 * stays in `tasks/ready/`, so a recovery `complete` is structurally a normal
@@ -579,9 +579,11 @@ export interface IntegrationCoreResult {
 	/** What the core resolved (the tail maps this 1:1 onto its own outcome). */
 	outcome: IntegrationCoreOutcome;
 	/**
-	 * True iff a FAILURE outcome was routed to `work/needs-attention/` via the
-	 * shared mechanism. False on the success path and when a failure was NOT moved
-	 * (e.g. a red re-gate that stays put in recovery).
+	 * True iff a FAILURE outcome was routed through the shared needs-attention
+	 * mechanism — post lock-cutover, the per-item lock was amended to
+	 * `state: stuck` with the reason on the lock entry (no folder move). False
+	 * on the success path and when a failure was NOT surfaced (e.g. a red
+	 * re-gate that stays put in recovery).
 	 */
 	routedToNeedsAttention: boolean;
 	/** The work branch that was processed (`work/<slug>`). */
@@ -687,6 +689,19 @@ export async function performIntegration(
 			recoveryRebaseJitterMs: input.recoveryRebaseJitterMs,
 			recoveryRebaseSleep: input.recoveryRebaseSleep,
 			recoveryRebaseRandom: input.recoveryRebaseRandom,
+			// GATE-2 REVIEW on the recovery path (task
+			// `committed-recovery-always-reviews`): a stranded already-complete
+			// branch is NOT "already reviewed" — its earlier attempt's PR never
+			// merged and Gate 2 may never have run on it. So when `review` is on we
+			// MUST run Gate 2 on the rebased tip here too (the SAME reasoning that
+			// forces the re-verify: `<arbiter>/main` moved, the merged tree is new).
+			// Pass the whole `input` so the recovery tail can call `runGate2Review`
+			// with the identical gate/model/watch/round wiring the build path uses.
+			input,
+			// PR BODY on the recovery path: the recovery has NO fresh agent output
+			// (no rebuild), so carry whatever `body` the caller supplied so the PR
+			// gets a description instead of degrading to a blank `gh --fill`.
+			body: input.body,
 			// Answered-merge land (task `committed-recovery-honours-fresh-worktree-gate`,
 			// spec `land-time-reverify-and-parallel-merge-ceiling`): the apply-rung
 			// dispatches an answered `merge` through this committed-recovery tail (the
@@ -740,7 +755,7 @@ export async function performIntegration(
 	// passes no flag, so there an untrusted-origin task RELIABLY forces propose.
 	//
 	// SCOPE: the task BUILD transition ONLY. It NEVER fires for a `lifecycle`
-	// transition (tasking / intake-emit — a prd/task FILE landing on main is inert;
+	// transition (tasking / intake-emit — a spec/task FILE landing on main is inert;
 	// intake's OWN per-emit resolver already decided that mode), and the source file
 	// here is the task being built. A `trusted`/unset task ⇒ untouched (zero
 	// behaviour change for the normal human path).
@@ -793,10 +808,11 @@ export async function performIntegration(
 		}
 		if (!prep.passed) {
 			const reason = `prepare (env-prep) failed (exit ${prep.exitCode})`;
-			// Bounce from in-progress/ straight to needs-attention/ (the SAME seam a red
-			// gate uses) — recording the prepare-failed reason + committing the move
-			// (with the agent's uncommitted work) as ONE atomic transition. We NEVER
-			// run `verify` on an env that could not be made ready.
+			// Mark the item stuck on its per-item lock (the SAME seam a red gate uses)
+			// — recording the prepare-failed reason on the lock entry + saving the
+			// agent's uncommitted work as a wip commit (post lock-cutover: a lock amend,
+			// no `in-progress/ → needs-attention/` folder move). We NEVER run `verify`
+			// on an env that could not be made ready.
 			const routed = await ledgerWrite.applyNeedsAttentionTransition({
 				cwd,
 				slug,
@@ -810,10 +826,10 @@ export async function performIntegration(
 				routedToNeedsAttention: routed.moved,
 				branch,
 				reason: routed.moved
-					? `Env-prep (prepare) failed (exit ${prep.exitCode}); routed '${slug}' ` +
-						'to work/needs-attention/ (the environment could not be made ready, ' +
+					? `Env-prep (prepare) failed (exit ${prep.exitCode}); marked '${slug}' ` +
+						'stuck on its per-item lock (the environment could not be made ready, ' +
 						'so the acceptance gate was NOT run). Fix the prepare command, then ' +
-						'return it to backlog/.'
+						'`requeue` to release the stuck lock.'
 					: `Env-prep (prepare) failed (exit ${prep.exitCode}); not completing ` +
 						`'${slug}' (the environment could not be made ready, so the ` +
 						'acceptance gate was NOT run). Fix the prepare command, then retry.',
@@ -832,12 +848,12 @@ export async function performIntegration(
 		note('Running the acceptance gate (verify)…');
 		const gate = await runVerify({cwd, verify: input.verify, env});
 		if (!gate.passed) {
-			// Don't leave the item dangling in in-progress/: route it to
-			// needs-attention/ with the reason (ADR §12) THROUGH the ledger write
-			// seam's needs-attention transition. The item has NOT been committed/moved
-			// yet, so the move bounces it straight from in-progress/ — recording the
-			// reason + committing the move (with the agent's uncommitted work) as ONE
-			// atomic transition. No partial state.
+			// Don't leave the item dangling: mark it stuck on its per-item lock with
+			// the reason (ADR §12) THROUGH the ledger write seam's needs-attention
+			// transition. Post lock-cutover this is a lock amend (`state: stuck` + the
+			// reason on the lock entry, no `in-progress/ → needs-attention/` folder
+			// move) plus saving the agent's uncommitted work as a wip commit. No
+			// partial state.
 			const reason = `acceptance gate failed (exit ${gate.exitCode})`;
 			const routed = await ledgerWrite.applyNeedsAttentionTransition({
 				cwd,
@@ -860,9 +876,9 @@ export async function performIntegration(
 				routedToNeedsAttention: routed.moved,
 				branch,
 				reason: routed.moved
-					? `Acceptance gate failed (exit ${gate.exitCode}); routed '${slug}' ` +
-						'to work/needs-attention/ (surfaced by status; return to backlog/ ' +
-						'once resolved). Fix the work, or use --skip-verify to override.'
+					? `Acceptance gate failed (exit ${gate.exitCode}); marked '${slug}' ` +
+						'stuck on its per-item lock (surfaced by status; `requeue` once ' +
+						'resolved). Fix the work, or use --skip-verify to override.'
 					: `Acceptance gate failed (exit ${gate.exitCode}); not completing ` +
 						`'${slug}'. Fix the work, or use --skip-verify to override.`,
 			};
@@ -1038,16 +1054,14 @@ export async function performIntegration(
 			// 4. Rebase-before-integrate (ADR §10): rebase the work branch onto the
 			//    latest <arbiter>/main. Clean → continue. Conflict → abort + stop.
 			//
-			//    RECOVERY reconciliation: when completing FROM needs-attention/, the work
-			//    branch's history still carries the original `in-progress → needs-attention`
-			//    MOVE-ONLY commit, and `<arbiter>/main` was SURFACED with that same move
-			//    (the item is in needs-attention/ on main). Replaying that historical move
-			//    onto main conflicts (main has no in-progress/<slug>.md) — exactly the
-			//    rebase conflict the human hit doing this by hand. So we DROP that move-only
-			//    commit during the rebase: the replay becomes `wip + (needs-attention →
-			//    done)`, which applies cleanly onto the surfaced main (it HAS the item in
-			//    needs-attention/). The done-move thus SUPERSEDES the surfaced state — no
-			//    leftover/conflicting on-`main` surface for the human to resolve.
+			//    RECOVERY reconciliation: post the per-item-lock cut-over, a stuck item's
+			//    body never moved into a `needs-attention/` folder (stuck is the lock
+			//    `state: stuck`; the body rests in `backlog/`), so a recovery `complete`'s
+			//    kept branch carries NO historical `in-progress → needs-attention`
+			//    move-only commit to drop and `<arbiter>/main` holds no surface move to
+			//    conflict with. The old recovery drop (`rebaseDroppingNeedsAttentionSurface`,
+			//    drop-bookkeeping-rebase) is deleted; recovery is now the SAME plain replay
+			//    onto `<arbiter>/main` as any other build (see the plain-rebase note below).
 			// Fetch the arbiter's `main` into the `<arbiter>/main` remote-tracking ref
 			// EXPLICITLY. A `run` JOB WORKTREE is cut from a bare hub mirror whose remote
 			// has no fetch refspec (so `<arbiter>/main` would not otherwise resolve / would
@@ -1209,12 +1223,12 @@ export async function performIntegration(
 		// recovery above can fall through to integrate while a genuine code conflict
 		// still routes here.
 		async function rebaseConflictRoute(): Promise<IntegrationCoreResult> {
-			// Then route the item to needs-attention/ with the conflict reason (ADR
-			// §12) THROUGH the ledger write seam's needs-attention transition, rather
-			// than leaving it dangling in done/. The done-move was already committed
-			// above, so the item sits in work/done/; the move bounces it from there and
-			// commits the in-progress→needs-attention move (here done→needs-attention)
-			// as ONE transition. No partial state.
+			// Then mark the item stuck on its per-item lock with the conflict reason
+			// (ADR §12) THROUGH the ledger write seam's needs-attention transition,
+			// rather than leaving it dangling. Post lock-cutover this is a lock amend
+			// (`state: stuck` + the reason on the lock entry, no `done/ →
+			// needs-attention/` folder move); the done-move already committed above
+			// stands. No partial state.
 			const reason = `rebase onto ${arbiter}/main conflicted (aborted, never auto-resolved)`;
 			const routed = await ledgerWrite.applyNeedsAttentionTransition({
 				cwd,
@@ -1236,9 +1250,9 @@ export async function performIntegration(
 				commitMessage,
 				reason: routed.moved
 					? `Rebasing ${branch} onto ${arbiter}/main conflicted; the rebase was ` +
-						`aborted (never auto-resolved) and '${slug}' was routed to ` +
-						'work/needs-attention/ (surfaced by status). Resolve against the ' +
-						'latest main, then return it to backlog/ and re-run.'
+						`aborted (never auto-resolved) and '${slug}' was marked stuck on ` +
+						'its per-item lock (surfaced by status). Resolve against the latest ' +
+						'main, then `requeue` to release the stuck lock and re-run.'
 					: `Rebasing ${branch} onto ${arbiter}/main conflicted; the rebase was ` +
 						'aborted (never auto-resolved). Resolve against the latest main, ' +
 						'then re-run complete.',
@@ -1318,9 +1332,9 @@ export async function performIntegration(
 					branch,
 					commitMessage,
 					reason: routed.moved
-						? `${what} on the rebased tip; routed '${slug}' to ` +
-							'work/needs-attention/ (surfaced by status; return to backlog/ ' +
-							'once resolved). Fix the work, or use --skip-verify to override.'
+						? `${what} on the rebased tip; marked '${slug}' stuck on its ` +
+							'per-item lock (surfaced by status; `requeue` once resolved). ' +
+							'Fix the work, or use --skip-verify to override.'
 						: `${what} on the rebased tip; not completing '${slug}'. Fix the ` +
 							'work, or use --skip-verify to override.',
 				};
@@ -1335,7 +1349,8 @@ export async function performIntegration(
 			if (gated.review) {
 				if (gated.review.kind === 'blocked') {
 					// The done-move was already committed (steps 2–3), so the slug sits in
-					// work/done/; the routing bounced it from there to needs-attention/.
+					// work/done/; the routing marked it stuck on its per-item lock (post
+					// lock-cutover — a lock amend, no folder move).
 					return gated.review.result;
 				}
 				approvedVerdict = gated.review.verdict;
@@ -1503,9 +1518,10 @@ export async function performIntegration(
 				commitMessage,
 				reason: routed.moved
 					? `Integrating ${branch} onto ${arbiter}/main kept hitting a ` +
-						`non-fast-forward push (a sibling advanced main); '${slug}' was routed ` +
-						`to work/needs-attention/ (surfaced by status). Resolve against the ` +
-						`latest main, then return it to backlog/ and re-run.`
+						`non-fast-forward push (a sibling advanced main); '${slug}' was ` +
+						`marked stuck on its per-item lock (surfaced by status). Resolve ` +
+						`against the latest main, then \`requeue\` to release the stuck ` +
+						`lock and re-run.`
 					: `Integrating ${branch} onto ${arbiter}/main kept hitting a ` +
 						`non-fast-forward push (a sibling advanced main). Resolve against the ` +
 						`latest main, then re-run complete.`,
@@ -1590,7 +1606,7 @@ export async function performIntegration(
  * primitive the build path uses.
  *
  * RE-GATE on the REBASED TIP (task `committed-recovery-honours-fresh-worktree-
- * gate`, prd `land-time-reverify-and-parallel-merge-ceiling`): when the caller
+ * gate`, spec `land-time-reverify-and-parallel-merge-ceiling`): when the caller
  * sets `freshWorktreeGate` (and not `skipVerify`), the EXISTING
  * `runFreshWorktreeGate` runs on the rebased tip AFTER the rebase loop and
  * BEFORE `applyCompleteTransition`, mirroring the build path's
@@ -1653,6 +1669,23 @@ async function recoverAlreadyCommitted(params: {
 	prepare?: VerifyConfig;
 	/** Acceptance gate config for the fresh gate (mirrors the build path). */
 	verify?: VerifyConfig;
+	/**
+	 * The full integration input, threaded so the recovery tail can run Gate 2
+	 * (`runGate2Review`) with the identical gate/model/watch/round wiring the
+	 * build path uses (task `committed-recovery-always-reviews`). Gate 2 runs on
+	 * the rebased tip when `input.review` is on and the fresh gate ran green — a
+	 * stranded already-complete branch is NOT trusted as already-reviewed (its
+	 * earlier attempt never merged). Optional so the pre-existing non-review
+	 * callers (and tests) that do not thread it stay byte-identical.
+	 */
+	input?: IntegrationCoreInput;
+	/**
+	 * The propose-mode PR BODY (task `committed-recovery-always-reviews`): the
+	 * recovery has NO fresh agent output (no rebuild), so the caller passes
+	 * whatever advisory body it has so the PR carries a description instead of a
+	 * blank `gh --fill`. Undefined ⇒ today's `--fill` fallback.
+	 */
+	body?: string;
 	/**
 	 * Autonomous needs-attention surface (mirrors the build path): when set, a
 	 * red rebased-tip gate cherry-picks the bounce onto `main` + pushes the
@@ -1704,6 +1737,14 @@ async function recoverAlreadyCommitted(params: {
 	// (`isAncestor` is the SAME reachability predicate `gc.ts` uses; do not fork it.)
 	// KEPT before the retry loop: a no-op MUST short-circuit before we burn any
 	// re-fetch/re-rebase budget.
+	//
+	// DELIBERATELY the RAW ancestry predicate, NOT `isProvablyMergedForReap`
+	// (task `reap-squash-merged-remote-work-branches`, ratified): this is an
+	// integration-IDEMPOTENCY check, not reap-safety. A squash-landed LOOKALIKE
+	// whose tip is NOT genuinely reachable would falsely read "already
+	// integrated" here and skip a needed rebase/re-push. The squash-aware helper
+	// is scoped to reap-safety ONLY; see gc.ts `isProvablyMergedForReap` and
+	// work/notes/observations/reap-squash-helper-scope-2026-07-10.md.
 	if (isAncestor(cwd, tip, `refs/remotes/${arbiter}/main`, env)) {
 		const message =
 			`Nothing to recover for '${slug}': its work branch tip is already on ` +
@@ -1801,7 +1842,7 @@ async function recoverAlreadyCommitted(params: {
 	}
 
 	// FRESH-WORKTREE GATE on the REBASED TIP (task `committed-recovery-honours-
-	// fresh-worktree-gate`, prd `land-time-reverify-and-parallel-merge-ceiling`):
+	// fresh-worktree-gate`, spec `land-time-reverify-and-parallel-merge-ceiling`):
 	// when `freshWorktreeGate` is set (the answered-merge land caller) and not
 	// `--skip-verify`, re-run the acceptance gate on the rebased tip BEFORE we
 	// integrate, mirroring the build path's `freshWorktreeGate && !skipVerify &&
@@ -1812,13 +1853,23 @@ async function recoverAlreadyCommitted(params: {
 	// clean-rebase-but-broken merge. With `freshWorktreeGate` UNSET (the original
 	// stranded-recovery caller, whose pre-strand build already gated) this whole
 	// block is skipped and behaviour is byte-identical to before.
+	// Carry an approved Gate-2 verdict (when review ran) so its authored `review`
+	// prose is posted as a PR comment AFTER the integrate below — the SAME audit
+	// trail the build path keeps (task `committed-recovery-always-reviews`).
+	let approvedVerdict: ReviewVerdict | undefined;
 	if (params.freshWorktreeGate && !params.skipVerify) {
 		const tip = (
 			await gitSoft(['rev-parse', '--verify', '--quiet', 'HEAD'], cwd, env)
 		).stdout.trim();
-		// No `review:` callback here: the recovery tail re-verifies an already-
-		// reviewed, already-committed result, so Gate-2 review semantics do not
-		// apply on this path.
+		// GATE-2 REVIEW callback (task `committed-recovery-always-reviews`): when
+		// `input.review` is on, run Gate 2 on the rebased tip AFTER the green verify
+		// — EXACTLY the build path's fresh-gate `review:` callback. A stranded
+		// already-complete branch is NOT trusted as already-reviewed (its earlier
+		// attempt's PR never merged, and Gate 2 may never have run on it); the same
+		// reasoning that forces the re-verify here (`<arbiter>/main` moved, so the
+		// merged tree is new) forces the re-review. The needs-attention ROUTING
+		// targets `cwd` (the work branch + ledger), identical to the build path.
+		const reviewInput = params.input;
 		const gated = await runFreshWorktreeGate({
 			cwd,
 			commit: tip,
@@ -1826,6 +1877,19 @@ async function recoverAlreadyCommitted(params: {
 			verify: params.verify,
 			env,
 			note,
+			review:
+				reviewInput?.review === true
+					? (reviewCwd) =>
+							runGate2Review({
+								reviewCwd,
+								input: reviewInput,
+								slug,
+								branch,
+								cwd,
+								env,
+								note,
+							})
+					: undefined,
 		});
 		if (!gated.passed) {
 			const outcome: IntegrationCoreOutcome =
@@ -1851,15 +1915,43 @@ async function recoverAlreadyCommitted(params: {
 				routedToNeedsAttention: routed.moved,
 				branch,
 				reason: routed.moved
-					? `${what} on the rebased tip during committed-recovery; routed ` +
-						`'${slug}' to work/needs-attention/ (surfaced by status; return ` +
-						'to backlog/ once resolved). Fix the work, or use --skip-verify ' +
+					? `${what} on the rebased tip during committed-recovery; marked ` +
+						`'${slug}' stuck on its per-item lock (surfaced by status; ` +
+						'`requeue` once resolved). Fix the work, or use --skip-verify ' +
 						'to override.'
 					: `${what} on the rebased tip during committed-recovery; not ` +
 						`completing '${slug}'. Fix the work, or use --skip-verify to ` +
 						'override.',
 			};
 		}
+		// GATE-2 REVIEW outcome on the rebased tip: a BLOCK routes to needs-attention
+		// exactly as the build path (only the reviewed tree moved, not the routing).
+		// On APPROVE: carry the verdict for the post-integrate PR comment and write
+		// the per-run non-blocking-nits observation. UNLIKE the build path this branch
+		// integrates the ALREADY-committed kept tip (no upcoming done-move/commit to
+		// sweep the nits file into), so we FOLD the observation into the kept commit
+		// via `commit --amend` — mirroring the build path's fresh-gate amend so the
+		// nits still land in the SAME commit that integrates (no separate commit).
+		if (gated.review) {
+			if (gated.review.kind === 'blocked') {
+				return gated.review.result;
+			}
+			approvedVerdict = gated.review.verdict;
+			const nitsBefore = await stagedCaptureNotes(cwd, env);
+			writeReviewNitsObservation({
+				cwd,
+				slug,
+				findings: gated.review.verdict?.findings ?? [],
+				note,
+			});
+			await gitHard(['add', '-A'], cwd, env);
+			if (!(await nothingStaged(cwd, env))) {
+				const nitsAfter = await stagedCaptureNotes(cwd, env);
+				if (nitsAfter.length > nitsBefore.length) {
+					await gitHard(['commit', '-q', '--amend', '--no-edit'], cwd, env);
+				}
+			}
+		}
 	}
 
 	// Integrate the rebased kept commit through the SAME complete-transition
@@ -1872,12 +1964,27 @@ async function recoverAlreadyCommitted(params: {
 		(params.openPr
 			? bridgeProvider(params.openPr)
 			: selectProvider({arbiterUrl: await arbiterUrl(cwd, arbiter, env)}));
+	// PR TITLE + BODY on the recovery path (task `committed-recovery-always-
+	// reviews`): the stranded branch already holds the task in `work/done/`, so
+	// synthesise the SAME single-line `<type>(<slug>): <title>` PR title the build
+	// path does (from the done-resident task file, never agent text) and scaffold
+	// the task-pointer body around the caller-supplied advisory `body`. Undefined
+	// body ⇒ `composeProposeBody` returns undefined ⇒ the provider degrades to
+	// `gh --fill` (no regression); a supplied body gives the PR a real description
+	// instead of the blank one the recovery path used to open.
+	const prTitle = synthesiseProposeTitle({
+		type: (params.input?.type ?? DEFAULT_TYPE).trim() || DEFAULT_TYPE,
+		slug,
+		title: readTaskTitle(workItemPath(cwd, 'done', slug)),
+	});
 	const integration = await ledgerWrite.applyCompleteTransition({
 		arbiter,
 		branch,
 		mode,
 		provider,
 		noPR: params.noPR,
+		title: prTitle,
+		body: composeProposeBody({slug, body: params.body}),
 		deleteMergedHead: true,
 		cwd,
 		env,
@@ -1889,6 +1996,32 @@ async function recoverAlreadyCommitted(params: {
 					`(absorbed a moving ${arbiter}/main across ${attempt} re-fetch+re-` +
 					`rebase attempt${attempt === 1 ? '' : 's'}).`,
 	);
+	// Post the Gate-2 review as a PR comment (task `committed-recovery-always-
+	// reviews`): the SAME post-integrate audit trail the build path keeps — the
+	// approved verdict's authored `review` prose, on the opened PR. Advisory only
+	// (a block never reaches here — it returned above); the same URL/branch
+	// precedence the build path uses (parsed url wins; else a branch-resolved
+	// fallback when a PR opened but its url was unparseable). `postPRComment*`
+	// never throws. A clean no-op in merge mode / push-only propose (no PR).
+	if (approvedVerdict?.review !== undefined) {
+		if (integration.url !== undefined) {
+			const posted = provider.postPRComment({
+				cwd,
+				url: integration.url,
+				body: approvedVerdict.review,
+				env,
+			});
+			note(posted.instruction);
+		} else if (integration.requestOpened) {
+			const posted = provider.postPRCommentOnBranch({
+				cwd,
+				branch,
+				body: approvedVerdict.review,
+				env,
+			});
+			note(posted.instruction);
+		}
+	}
 	return {
 		outcome: 'completed',
 		routedToNeedsAttention: false,
@@ -1931,8 +2064,9 @@ function resolveWorkBranch(
  *
  * Carries the {@link slug} so the autonomous-strand surface in `complete.ts`
  * (which catches this error in `performComplete`'s outer try/catch, OUTSIDE the
- * `runComplete` slug scope) can publish the `in-progress/ → needs-attention/`
- * tree-less move without re-deriving the slug from the error message.
+ * `runComplete` slug scope) can mark the item stuck on its per-item lock (post
+ * lock-cutover — the tree-less lock amend, no `in-progress/ → needs-attention/`
+ * folder move) without re-deriving the slug from the error message.
  */
 export class IntegrationNothingStaged extends Error {
 	constructor(
@@ -2113,8 +2247,8 @@ export function composeProposeBody(input: {
  * On a review APPROVE that carries ≥1 NON-BLOCKING finding, write ONE per-run
  * observation `work/notes/observations/review-nits-<slug>-<YYYY-MM-DD>.md` capturing all
  * of this run's non-blocking nits, so they get a durable, contract-native home
- * instead of evaporating (the block path already routes BLOCKING findings to
- * needs-attention/; the approve path dropped non-blocking ones — see
+ * instead of evaporating (the block path already records BLOCKING findings as the
+ * stuck reason on the item's per-item lock; the approve path dropped non-blocking ones — see
  * `work/findings/review-nonblocking-findings-disposition.md`).
  *
  * The RUNNER writes it (the review agent stays write-free). It is a PLAIN
@@ -2841,8 +2975,8 @@ async function runGate2Review(params: {
 			});
 			const message = routed.moved
 				? `PR/code review (Gate 2) produced an UNPARSEABLE verdict for '${slug}'; ` +
-					'routed it to work/needs-attention/ (work branch pushed + surfaced; ' +
-					'transient-infra — re-run). NOT integrated.'
+					'marked it stuck on its per-item lock (work branch pushed + lock ' +
+					'surfaced; transient-infra — re-run). NOT integrated.'
 				: `PR/code review (Gate 2) produced an UNPARSEABLE verdict for '${slug}'; ` +
 					'NOT integrating.';
 			note(message);
@@ -2888,9 +3022,9 @@ async function runGate2Review(params: {
 			note,
 		});
 		const message = routed.moved
-			? `PR/code review (Gate 2) blocked '${slug}'; routed it to ` +
-				'work/needs-attention/ (surfaced by status; the blocking findings are ' +
-				'recorded in the item body). NOT integrated.'
+			? `PR/code review (Gate 2) blocked '${slug}'; marked it stuck on its ` +
+				'per-item lock (surfaced by status; the blocking findings are ' +
+				'recorded on the lock entry). NOT integrated.'
 			: `PR/code review (Gate 2) blocked '${slug}'; NOT integrating.`;
 		note(message);
 		return {

package/src/integrator.ts

@@ -1,6 +1,8 @@
 import type {IntegrationMode} from './config.js';
 import {git, run} from './git.js';
-import {isAncestor} from './gc.js';
+import {isAncestor, isProvablyMergedForReap} from './gc.js';
+import {parseWorkBranchRef} from './slug-namespace.js';
+import type {SidecarType} from './sidecar.js';
 import type {BackoffOptions, Sleep} from './retry-backoff.js';
 import {pushProposeBranchWithStaleLeaseRetry} from './continue-branch.js';
 
@@ -135,7 +137,7 @@ export interface OpenRequestInput {
 	 * When present a provider passes it verbatim (e.g. `gh pr create --body`)
 	 * instead of `--fill`'s empty/commit-derived description. Typically the build
 	 * agent's final summary, optionally under a runner-scaffolded header (a pointer
-	 * to `work/done/<slug>.md` + the prd/ADR it serves). Absent ⇒ today's `--fill`
+	 * to `work/done/<slug>.md` + the spec/ADR it serves). Absent ⇒ today's `--fill`
 	 * (no regression). This is the BODY-AT-OPEN surface; a follow-up PR COMMENT is
 	 * a separate provider method.
 	 */
@@ -681,13 +683,24 @@ function deleteMergedHeadBranch(input: IntegrateInput): void {
 	);
 	const headSha = parseLsRemoteSha(ls.stdout);
 	if (headSha !== undefined) {
-		const isMerged = run(
-			'git',
-			['merge-base', '--is-ancestor', headSha, `refs/remotes/${arbiter}/main`],
-			input.cwd,
-			{env},
-		);
-		if (isMerged.status !== 0) {
+		// Provably-merged-for-reap = fast-path ancestor OR squash-aware fallback
+		// (durable done/dropped record on <arbiter>/main + branch carries nothing
+		// main lacks). The SAME predicate the `gc.ts` worktree reaper and the
+		// `reap-branches.ts` remote sweep use — do not fork it.
+		const parsed = parseWorkBranchRef(branch);
+		const arbiterMainRef = `refs/remotes/${arbiter}/main`;
+		const provablyMerged =
+			parsed === undefined
+				? isAncestor(input.cwd, headSha, arbiterMainRef, env)
+				: isProvablyMergedForReap({
+						cwd: input.cwd,
+						tip: headSha,
+						arbiterMain: arbiterMainRef,
+						namespace: parsed.namespace as SidecarType,
+						slug: parsed.slug,
+						env,
+					});
+		if (!provablyMerged) {
 			return; // NOT provably merged (a racing un-merged amend) — never reap.
 		}
 	}

package/src/isolation.ts

@@ -111,11 +111,11 @@ export interface PrepareInput {
 	/** The work slug being processed (→ branch `work/<type>-<slug>`). */
 	slug: string;
 	/**
-	 * The item TYPE — `'task'` for a build (intake/`do task:`), `'prd'` for a
+	 * The item TYPE — `'task'` for a build (intake/`do task:`), `'spec'` for a
 	 * spec-tasking run (`do spec:`). It NAMESPACES the work branch via
 	 * {@link workBranchRef} so a same-slug task and spec never collide on the
 	 * arbiter branch. Defaults to `'task'` (the overwhelmingly-common build
-	 * path); the spec-tasking path passes `'prd'` explicitly.
+	 * path); the spec-tasking path passes `'spec'` explicitly.
 	 */
 	type?: SlugNamespace;
 	/**
@@ -394,6 +394,15 @@ export function inPlaceStrategy(options: {
  * path uses before force-resetting the work branch onto the claim commit. A
  * not-yet-fetched or rolled-back arbiter main that does NOT reach the claim must
  * fail fast here, never silently build on a stale base.
+ *
+ * DELIBERATELY the RAW `--is-ancestor` predicate, NOT the squash-aware
+ * `isProvablyMergedForReap` (task `reap-squash-merged-remote-work-branches`,
+ * ratified): this is a claim-REACHABILITY guard, not reap-safety. It demands
+ * GENUINE ancestry of the claim commit; a done-record-on-main match would
+ * defeat its whole purpose (refusing to build on a stale base). The
+ * squash-aware helper is scoped to reap-safety ONLY; this module's reap-lane
+ * (`reapJob` → `evaluateDeletionSafety`) is where it belongs. See
+ * work/notes/observations/reap-squash-helper-scope-2026-07-10.md.
  */
 function assertClaimCommitReachable(
 	checkout: string,