dorfl 0.1.1 → 0.2.0

package/src/integration-core.ts

@@ -57,8 +57,8 @@ import {isAncestor} from './gc.js';
  * integrates), so verify-then-review holds on the merged tree, never split across
  * two trees. Any failure routes to needs-attention.
  *
- * It is the CORE in the head / core / tail decomposition (prd
- * `work/prds/tasked/run-do-integrate-convergence.md`): the caller-specific HEAD
+ * It is the CORE in the head / core / tail decomposition (spec
+ * `work/specs/tasked/run-do-integrate-convergence.md`): the caller-specific HEAD
  * (repo/arbiter/branch checks, source resolution, the `recovering` flag) and TAIL
  * (switch-to-main / `syncLocalMain` / delete-local-branch / `--no-switch` / the
  * propose next-step block, or — for `run` — the job-record + worktree reap) stay
@@ -98,7 +98,7 @@ export type IntegrationCoreOutcome =
 /**
  * The CORE's input — everything the band needs, nothing caller-shaped. Every
  * divergence between the human `complete` path and the autonomous `do`/`run` path
- * maps to a FIELD VALUE here, not an `if (caller === …)` branch (prd: "zero
+ * maps to a FIELD VALUE here, not an `if (caller === …)` branch (spec: "zero
  * caller-identity leakage"). In-place vs worktree = `cwd`; arbiter name =
  * `arbiter`; human vs autonomous surfacing = `surfaceArbiter`; do's recovery =
  * `source` + `recovering`; per-repo/lang gate = `verify`.
@@ -108,9 +108,9 @@ export type IntegrationCoreOutcome =
  * task-shaped done-move + title source. The shared band
  * (verify→review→commit→rebase→integrate→propose-PR-with-title/body) is
  * IDENTICAL; only the "which item move + which file to read the title from" step
- * is caller-supplied. This is the seam the `do prd:<slug>` TASKING transition
- * rides (task `slice-output-through-integration`): its "item move" is the prd
- * LIFECYCLE move (`work/prds/ready/<slug>.md → work/prds/tasked/<slug>.md`, residence =
+ * is caller-supplied. This is the seam the `do spec:<slug>` TASKING transition
+ * rides (task `slice-output-through-integration`): its "item move" is the spec
+ * LIFECYCLE move (`work/specs/ready/<slug>.md → work/specs/tasked/<slug>.md`, residence =
  * tasked-ness) plus its EMITTED backlog files — NOT a task done-move. Supplying it
  * makes every integrate-time arg (`--propose`/`--merge`, provider, title/body)
  * apply to tasking BY CONSTRUCTION, because they resolve ONCE here.
@@ -127,7 +127,7 @@ export interface IntegrationLifecycle {
 	/**
 	 * Absolute path to the item file whose `title:` frontmatter seeds the default
 	 * commit summary AND the synthesised propose-mode PR title. For the tasking
-	 * transition this is the held prd (`work/prds/ready/<slug>.md`) — read BEFORE
+	 * transition this is the held spec (`work/specs/ready/<slug>.md`) — read BEFORE
 	 * {@link stage} moves it. IGNORED when {@link title} is supplied (the explicit
 	 * title wins — no file read).
 	 */
@@ -137,16 +137,16 @@ export interface IntegrationLifecycle {
 	 * uses THIS as the title source for the default commit summary AND the synthesised
 	 * propose-mode PR title, INSTEAD of reading {@link titlePath}. This is the seam for
 	 * a lifecycle whose output file does NOT yet exist at title-read time — the intake
-	 * lone-task / prd path WRITES `work/backlog/<slug>.md` / `work/prds/ready/<slug>.md` in
+	 * lone-task / spec path WRITES `work/backlog/<slug>.md` / `work/specs/ready/<slug>.md` in
 	 * {@link stage}, which runs AFTER the title read, so a `titlePath` read would race
-	 * the write and fall back to a generic subject. The `do prd:` tasking transition
-	 * leaves this unset (its `titlePath` is an already-existing held prd, read fine).
+	 * the write and fall back to a generic subject. The `do spec:` tasking transition
+	 * leaves this unset (its `titlePath` is an already-existing held spec, read fine).
 	 */
 	title?: string;
 	/**
 	 * STAGE the lifecycle move + emitted files into the index on the current work
 	 * branch (runner-owned git; the agent never does git). For the tasking
-	 * transition: `git mv work/prds/ready/<slug>.md → work/prds/tasked/<slug>.md`
+	 * transition: `git mv work/specs/ready/<slug>.md → work/specs/tasked/<slug>.md`
 	 * (residence = tasked-ness; no marker), and write+`git add` the produced
 	 * `work/backlog/*.md` files. The band's subsequent `git add -A` + atomic commit
 	 * folds this staging
@@ -165,8 +165,8 @@ export interface IntegrationLifecycle {
 
 /**
  * The default LIVENESS CEILING for the merge-mode `${branch}:main` push (the
- * durable promotions `tasks/ready → tasks/done` and, via `lifecycle`, `prds/ready
- * → prds/tasked`). Task `c2-rebase-until-real-on-durable-main-promotions` turned
+ * durable promotions `tasks/ready → tasks/done` and, via `lifecycle`, `specs/ready
+ * → specs/tasked`). Task `c2-rebase-until-real-on-durable-main-promotions` turned
  * the previous SMALL FIXED CAP (was 5, the `run-fleet-claim-integrate-and-sibling-
  * rebase-concurrency-safe` Race-1 budget) into rebase-until-real-conflict: a CLEAN
  * re-rebase no longer counts against a tiny give-up budget — only a GENUINE
@@ -271,7 +271,7 @@ export interface IntegrationCoreInput {
 	 * `work/<type>-<slug>` identity. When omitted, the core derives it from the
 	 * branch HEAD is on (the robust default — the type is encoded IN the name). A
 	 * caller that knows the type explicitly may pass it (e.g. the tasking path
-	 * passes its `work/prds/ready-<slug>`).
+	 * passes its `work/specs/ready-<slug>`).
 	 */
 	branch?: string;
 	/**
@@ -279,7 +279,7 @@ export interface IntegrationCoreInput {
 	 * freshly-built path — since claim no longer moves the body, a freshly-built
 	 * task RESTS in the pool on `main`, task
 	 * `cutover-claim-body-stays-and-complete-sources-from-backlog`),
-	 * `tasks-backlog` (the `--allow-backlog` staged-drive path, prd
+	 * `tasks-backlog` (the `--allow-backlog` staged-drive path, spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`: a human drove a
 	 * STAGED task in place, so the done-move goes `tasks/backlog/ → tasks/done/`
 	 * DIRECTLY — the explicit drive IS the promotion, never bouncing through the
@@ -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
@@ -325,7 +325,7 @@ export interface IntegrationCoreInput {
 	 */
 	recovering: boolean;
 	/**
-	 * **RECOVER an already-committed, already-done-moved STRANDED branch** (prd
+	 * **RECOVER an already-committed, already-done-moved STRANDED branch** (spec
 	 * `ledger-integrity` story 6, the `finish-already-committed-branch` task). When
 	 * `true`, the work is ALREADY committed on the work branch with the task already
 	 * `git mv`'d into `work/done/` (a terminal push failed AFTER steps 2–3, leaving
@@ -564,7 +564,7 @@ export interface IntegrationCoreInput {
 	 * `slice-output-through-integration`). When set, the band reads the title from
 	 * its {@link IntegrationLifecycle.titlePath}, calls its
 	 * {@link IntegrationLifecycle.stage} INSTEAD of the task `git mv → work/done/`,
-	 * and uses the plain rebase ({@link recovering} is irrelevant). The `do prd:`
+	 * and uses the plain rebase ({@link recovering} is irrelevant). The `do spec:`
 	 * TASKING transition supplies it; `do`/`complete`/`run` leave it unset (the
 	 * task done-move is unchanged).
 	 */
@@ -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>`). */
@@ -606,8 +608,8 @@ export interface IntegrationCoreResult {
 	 * needs-attention routing can record the findings as the item-body prose. The
 	 * tasking path (task `slice-acceptance-gate`) reads this: the core's build
 	 * `applyNeedsAttentionTransition` is keyed on a TASK lock, so the tasking path
-	 * routes the prd itself via the lock release's needs-attention redirect (amend the
-	 * `prd:<slug>` unified lock `active -> stuck`, no folder move), using THIS
+	 * routes the spec itself via the lock release's needs-attention redirect (amend the
+	 * `spec:<slug>` unified lock `active -> stuck`, no folder move), using THIS
 	 * findings text as the body. Absent on every non-`review-blocked` outcome. (The
 	 * build path ignores it — its routing already records the findings in-body.)
 	 */
@@ -667,7 +669,7 @@ export async function performIntegration(
 	// in the `run` caller, not here.
 	const freshWorktreeGate = input.freshWorktreeGate === true;
 
-	// RECOVER an already-committed, already-done-moved STRANDED branch (prd
+	// RECOVER an already-committed, already-done-moved STRANDED branch (spec
 	// `ledger-integrity` story 6). The work + the done-move are ALREADY committed on
 	// the work branch (a terminal push failed AFTER steps 2–3); SKIP steps 0–3
 	// (prepare / gate / review / done-move / commit) and run ONLY the
@@ -687,8 +689,21 @@ 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`,
-			// prd `land-time-reverify-and-parallel-merge-ceiling`): the apply-rung
+			// spec `land-time-reverify-and-parallel-merge-ceiling`): the apply-rung
 			// dispatches an answered `merge` through this committed-recovery tail (the
 			// branch already carries its done-move commit, so the build path's
 			// `git mv`+`add -A`+commit would raise `IntegrationNothingStaged`). UNLIKE
@@ -713,7 +728,7 @@ export async function performIntegration(
 	}
 
 	// The file whose `title:` seeds the commit summary + PR title. For a TASKING
-	// transition (a non-task `lifecycle`) this is the held prd it supplies; for a
+	// transition (a non-task `lifecycle`) this is the held spec it supplies; for a
 	// build it is the task in its source folder. Read BEFORE any move.
 	const lifecycle = input.lifecycle;
 	// CONTINUE-BUILD (`source: 'done'`, task
@@ -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,16 +876,16 @@ 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.`,
 			};
 		}
 	}
 
-	// 1b. Gate 2 — the PR/code REVIEW gate (GATES prd `work/prds/tasked/review.md`). It is a
+	// 1b. Gate 2 — the PR/code REVIEW gate (GATES spec `work/specs/tasked/review.md`). It is a
 	//     JUDGEMENT gate layered ON TOP of the deterministic `verify` floor (ADR §8)
 	//     — NEVER a replacement, and ALWAYS verify-THEN-review on the SAME tree.
 	//
@@ -924,10 +940,10 @@ export async function performIntegration(
 	// never be the multi-line commit-subject run-on `--fill` would derive.
 	//
 	// When the lifecycle supplies an EXPLICIT `title`, use it DIRECTLY (no file read):
-	// the intake lone-task / prd path writes its output file in `stage()`, which runs
+	// the intake lone-task / spec path writes its output file in `stage()`, which runs
 	// AFTER this point, so a `titlePath` read would race the write and degrade the
-	// subject/PR title to the generic fallback. The `do prd:` tasking path leaves
-	// `title` unset and keeps reading its already-existing held prd (unchanged).
+	// subject/PR title to the generic fallback. The `do spec:` tasking path leaves
+	// `title` unset and keeps reading its already-existing held spec (unchanged).
 	const explicitTitle = lifecycle?.title;
 	const taskTitle =
 		explicitTitle !== undefined ? explicitTitle : readTaskTitle(sourcePath);
@@ -943,7 +959,7 @@ export async function performIntegration(
 
 	// 2. STAGE the item move into the index. For a build that is the task done-move
 	//    (`work/<source>/<slug>.md → work/done/<slug>.md`); for a TASKING
-	//    transition (a non-task `lifecycle`) it is the caller-supplied prd
+	//    transition (a non-task `lifecycle`) it is the caller-supplied spec
 	//    lifecycle move + emitted backlog files (the runner stages them, the agent
 	//    never does git). Either way the subsequent `git add -A` folds the agent's
 	//    uncommitted work + this staging into ONE atomic commit.
@@ -1001,7 +1017,7 @@ export async function performIntegration(
 	// they are TRACKED, not dropped/untracked. Rule B is extended HERE: the runner REPORTS
 	// exactly which note files landed (honest reporting — what actually reached the commit,
 	// read from the staged set, not assumed). This is the ONE shared place — BOTH the build
-	// path (`do <task>`/`run`/`complete`) and the tasking path (`do prd:`, via the
+	// path (`do <task>`/`run`/`complete`) and the tasking path (`do spec:`, via the
 	// `lifecycle` seam) route through it, so the channel is NOT forked. Zero notes ⇒ no
 	// report (the no-note case is byte-for-byte unchanged).
 	await reportScoopedNotes(cwd, env, note);
@@ -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
@@ -1099,7 +1113,7 @@ export async function performIntegration(
 					};
 				}
 			}
-			// PLAIN rebase. After the per-item-lock cut-over (prd
+			// PLAIN rebase. After the per-item-lock cut-over (spec
 			// `ledger-status-per-item-lock-refs`, tasks 9a–9d) no transient status
 			// lands on a work branch: needs-attention is the lock `state: stuck` (not a
 			// `git mv` to `needs-attention/`), the body rests in `backlog/` while
@@ -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.`,
@@ -1580,7 +1596,7 @@ export async function performIntegration(
 }
 
 /**
- * RECOVER an already-committed, already-done-moved STRANDED branch (prd
+ * RECOVER an already-committed, already-done-moved STRANDED branch (spec
  * `ledger-integrity` story 6, the `finish-already-committed-branch` task). The
  * green work AND the `git mv → work/done/` are ALREADY committed on the work
  * branch (a terminal push failed AFTER `performIntegration`'s steps 2–3), and the
@@ -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
@@ -1635,7 +1651,7 @@ async function recoverAlreadyCommitted(params: {
 	/**
 	 * Run the EXISTING `runFreshWorktreeGate` (`prepare` then `verify`) on the
 	 * rebased tip AFTER the rebase loop and BEFORE `applyCompleteTransition`
-	 * (task `committed-recovery-honours-fresh-worktree-gate`, prd
+	 * (task `committed-recovery-honours-fresh-worktree-gate`, spec
 	 * `land-time-reverify-and-parallel-merge-ceiling`). The original stranded-
 	 * recovery caller (`complete --integration`'s already-built strand) leaves
 	 * this UNSET ⇒ no gate, no extra fetch — byte-identical to before. The
@@ -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
@@ -2322,7 +2456,7 @@ async function stagedCaptureNotes(
  * The DURABLE `work/` status folders a slug's ledger file can resting-live in (the
  * one-slug-one-folder set the invariant is asserted over). After the capstone
  * cut-over (task `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`,
- * prd `ledger-status-per-item-lock-refs`) the ONLY `work/` moves on `main` are the
+ * spec `ledger-status-per-item-lock-refs`) the ONLY `work/` moves on `main` are the
  * durable resting transitions, so the source a build completes FROM is `backlog/`
  * (claim no longer moves the body, task
  * `cutover-claim-body-stays-and-complete-sources-from-backlog`) and the canonical
@@ -2337,7 +2471,7 @@ async function stagedCaptureNotes(
  * The folders {@link readArbiterLedgerPlacement} scans for a slug's source on the
  * arbiter: the durable `LEDGER_STATUS_FOLDERS` (`tasks-ready`/`done`/`cancelled`)
  * PLUS `tasks-backlog` (staging). Staging is included ONLY for the arbiter-side
- * source RESOLUTION of a `--allow-backlog` done-move (prd
+ * source RESOLUTION of a `--allow-backlog` done-move (spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion`) and the one-slug-one-
  * folder guard over the malformed "same slug in `tasks/ready/` AND `tasks/backlog/`"
  * state; it is DELIBERATELY NOT added to the shared `LEDGER_STATUS_FOLDERS` (which
@@ -2384,12 +2518,12 @@ interface ArbiterLedgerPlacement {
  * destination is unambiguous), mirroring the manual `279b542` cleanup.
  *
  * It scans {@link ARBITER_PLACEMENT_FOLDERS} — the durable `LEDGER_STATUS_FOLDERS`
- * PLUS `tasks-backlog`, so a `--allow-backlog` staged drive (prd
+ * PLUS `tasks-backlog`, so a `--allow-backlog` staged drive (spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion`) whose done-move sources
  * from `tasks/backlog/` is DISCOVERED here too (the arbiter is the authority for
  * the actual source folder; the local `source` is the fallback). Including staging
  * also makes the one-slug-one-folder guard cover the malformed "same slug in both
- * `tasks/ready/` and `tasks/backlog/`" state (the prd's decision 5): it FAILS LOUD
+ * `tasks/ready/` and `tasks/backlog/`" state (the spec's decision 5): it FAILS LOUD
  * rather than the resolver silently arbitrating a collision the contract forbids.
  */
 function readArbiterLedgerPlacement(
@@ -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 {