dorfl 0.1.1 → 0.2.0

package/dist/integration-core.js

@@ -14,8 +14,8 @@ import { workBranchRef } from './slug-namespace.js';
 import { isAncestor } from './gc.js';
 /**
  * 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
@@ -151,7 +151,7 @@ export async function performIntegration(input) {
     // handed (caller-agnostic); the `run`-fleet `perRepoMax === 1` downgrade lives
     // 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
@@ -171,8 +171,21 @@ export async function performIntegration(input) {
             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
@@ -196,7 +209,7 @@ export async function performIntegration(input) {
         });
     }
     // 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
@@ -222,7 +235,7 @@ export async function performIntegration(input) {
     // 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).
@@ -270,10 +283,11 @@ export async function performIntegration(input) {
         }
         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,
@@ -287,10 +301,10 @@ export async function performIntegration(input) {
                 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.',
@@ -309,12 +323,12 @@ export async function performIntegration(input) {
         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,
@@ -337,15 +351,15 @@ export async function performIntegration(input) {
                 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.
     //
@@ -399,10 +413,10 @@ export async function performIntegration(input) {
     // 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);
     const defaultMessage = explicitTitle !== undefined
@@ -415,7 +429,7 @@ export async function performIntegration(input) {
     });
     // 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.
@@ -467,7 +481,7 @@ export async function performIntegration(input) {
     // 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);
@@ -501,16 +515,14 @@ export async function performIntegration(input) {
             // 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
@@ -553,7 +565,7 @@ export async function performIntegration(input) {
                     };
                 }
             }
-            // 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
@@ -656,12 +668,12 @@ export async function performIntegration(input) {
         // recovery above can fall through to integrate while a genuine code conflict
         // still routes here.
         async function rebaseConflictRoute() {
-            // 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,
@@ -683,9 +695,9 @@ export async function performIntegration(input) {
                 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.',
@@ -758,9 +770,9 @@ export async function performIntegration(input) {
                     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.',
                 };
@@ -775,7 +787,8 @@ export async function performIntegration(input) {
             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;
@@ -936,9 +949,10 @@ export async function performIntegration(input) {
                 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.`,
@@ -1007,7 +1021,7 @@ export async function performIntegration(input) {
         : await runRebaseToIntegrateTail();
 }
 /**
- * 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
@@ -1017,7 +1031,7 @@ export async function performIntegration(input) {
  * 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
@@ -1071,6 +1085,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 ` +
             `${arbiter}/main (already integrated). No re-push, no double-integrate.`;
@@ -1162,7 +1184,7 @@ async function recoverAlreadyCommitted(params) {
         attempt++;
     }
     // 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 &&
@@ -1173,11 +1195,21 @@ 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;
     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,
@@ -1185,6 +1217,17 @@ 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 = gated.kind === 'prepare' ? 'prepare-failed' : 'gate-failed';
@@ -1207,15 +1250,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
     // primitive the build path uses (no duplication of the integrate mechanism; the
@@ -1226,12 +1297,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,
@@ -1241,6 +1327,33 @@ async function recoverAlreadyCommitted(params) {
         : `Recovered '${slug}': integrated the kept commit from ${branch} ` +
             `(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,
@@ -1278,8 +1391,9 @@ function resolveWorkBranch(cwd, slug, env) {
  *
  * 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 {
     slug;
@@ -1432,8 +1546,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
@@ -1605,7 +1719,7 @@ async function stagedCaptureNotes(cwd, env) {
  * 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
@@ -1620,7 +1734,7 @@ async function stagedCaptureNotes(cwd, env) {
  * 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
@@ -1646,12 +1760,12 @@ const ARBITER_PLACEMENT_FOLDERS = [
  * 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(cwd, arbiter, slug, env) {
@@ -2018,8 +2132,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);
@@ -2064,9 +2178,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 {