dorfl 0.1.1 → 0.2.0

package/src/close-job-template.ts

@@ -1,12 +1,12 @@
 /**
- * The `install-ci` CLOSE-JOB capability (prd `runner-in-ci`, task
+ * The `install-ci` CLOSE-JOB capability (spec `runner-in-ci`, task
  * `install-ci-close-job-workflow`; capability E: close issues when their work
  * lands). This module GENERATES the one fixed workflow file for the close-job and
  * STRUCTURALLY VALIDATES it, mirroring the snapshot-assertion style of
  * `advance-lifecycle-template.ts` / `advance-ci-template.ts` (the package depends on
  * NO YAML lib, so the checks are presence/shape assertions over the raw text).
  *
- * The discipline (from the prd capability-E row + the Out-of-Scope fence):
+ * The discipline (from the spec capability-E row + the Out-of-Scope fence):
  *
  *   - TRIGGER: a MERGE to `main`. There is no native "PR merged" event, so the
  *     workflow uses `push: {branches: [main]}` (NOT `pull_request: closed`): it
@@ -16,7 +16,7 @@
  *     cannot close. (See the `## Decisions` block in the task.)
  *   - The job INVOKES the close machinery via `dorfl close-merged-issues`,
  *     which CONSUMES the UNCHANGED engine pieces: the resolution
- *     (`resolveClosingIssue`), the "prd complete?" query (`prd-complete-query`,
+ *     (`resolveClosingIssue`), the "spec complete?" query (`prd-complete-query`,
  *     done), and `IssueProvider.closeIssue`. CI owns ONLY the job + trigger; it
  *     re-implements NONE of those (the Out-of-Scope fence).
  *   - CI runs IN-PLACE (the CI container IS the isolation): no
@@ -54,7 +54,7 @@ export const CLOSE_JOB_WORKFLOW_PATH = 'workflows/close-job.yml';
  */
 export function generateCloseJobWorkflow(_config: ResolvedCIConfig): string {
 	return `\
-# dorfl — the ISSUE CLOSE-JOB in CI (capability E, prd runner-in-ci).
+# dorfl — the ISSUE CLOSE-JOB in CI (capability E, spec runner-in-ci).
 # EMITTED by \`dorfl install-ci\`; the human commits it. DO NOT hand-edit a
 # copy — re-run install-ci to upgrade the shell.
 #
@@ -69,9 +69,9 @@ export function generateCloseJobWorkflow(_config: ResolvedCIConfig): string {
 # the landed work closes and closes them. CI owns ONLY this job + the trigger; the
 # command CONSUMES the engine's UNCHANGED pieces and re-implements none of them:
 #   * the RESOLUTION (resolveClosingIssue): a lone task closes its own \`issue:\`;
-#     a fanned task reaches the number via \`task.prd: → prd issue:\`.
-#   * the "prd complete?" QUERY (prd-complete-query, done): a prd's issue closes
-#     ONLY when ALL its \`prd:<slug>\` tasks are in work/done/.
+#     a fanned task reaches the number via \`task.spec: → spec issue:\`.
+#   * the "spec complete?" QUERY (prd-complete-query, done): a spec's issue closes
+#     ONLY when ALL its \`spec:<slug>\` tasks are in work/done/.
 #   * the CLOSE (IssueProvider.closeIssue): the atomic comment+close seam — NO
 #     direct \`gh\` in the engine core; any comment rides this close, never the PR
 #     comment seam.
@@ -110,14 +110,14 @@ jobs:
   close-merged-issues:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: ./.github/actions/dorfl-setup
       - name: close issues whose work has landed on main
         # In-place in this checkout (no --isolated/--remote): the CI container IS
         # the isolation. Resolves the closing issue(s) from the work/ tree, runs
-        # the "prd complete?" query for the prd case, and closes via the provider
+        # the "spec complete?" query for the spec case, and closes via the provider
         # seam — all UNCHANGED engine pieces, consumed not re-built.
         env:
           GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}

package/src/close-job.ts

@@ -1,14 +1,14 @@
 /**
- * The CI CLOSE-JOB driver (prd `runner-in-ci`, capability E; task
+ * The CI CLOSE-JOB driver (spec `runner-in-ci`, capability E; task
  * `install-ci-close-job-workflow`). When work lands on `main`, this resolves which
  * source issue(s) the landed work closes and closes them — but it OWNS none of the
  * machinery it relies on. It is the thin JOB that WIRES three UNCHANGED engine
  * pieces together (the Out-of-Scope fence: do NOT re-build them):
  *
  *   - the RESOLUTION — {@link resolveClosingIssue} (`frontmatter.ts`): an artifact
- *     uses `issue:` XOR `prd:`; a lone task closes its own `issue:` directly, a
- *     fanned task reaches the number via `task.prd: → work/prds/<prd>.md prd
- *     issue:`, and `prd:` WINS on a (hand-edited) conflict;
+ *     uses `issue:` XOR `spec:`; a lone task closes its own `issue:` directly, a
+ *     fanned task reaches the number via `task.spec: → work/specs/<spec>.md spec
+ *     issue:`, and `spec:` WINS on a (hand-edited) conflict;
  *   - the QUERY — {@link isSpecComplete} (`spec-complete.ts`, task
  *     `prd-complete-query`, done): a spec is COMPLETE iff ≥1 `spec:<slug>` task AND
  *     all such tasks are in `work/done/`;
@@ -19,12 +19,12 @@
  *
  * The closure conditions, per artifact kind:
  *
- *   - a **lone task** (`issue:`, no `prd:`) that resides in `work/done/` — its PR
+ *   - a **lone task** (`issue:`, no `spec:`) that resides in `work/done/` — its PR
  *     merged, so its own issue closes (reason `completed`);
- *   - a **prd** (`issue:`) — closes ONLY when {@link isSpecComplete} says ALL its
+ *   - a **spec** (`issue:`) — closes ONLY when {@link isSpecComplete} says ALL its
  *     `spec:<slug>` tasks are in `work/done/` (reason `completed`).
  *
- * A prd whose query is NOT yet complete is left OPEN (the final fanned task's
+ * A spec whose query is NOT yet complete is left OPEN (the final fanned task's
  * merge tick closes it). A lone task still outside `work/done/` is skipped. The
  * close DEGRADES (never throws) on a missing/unauthenticated provider, exactly
  * like intake's bounce close — the run reports the real cause and stays exit-0.
@@ -62,7 +62,7 @@ const SPEC_LIFECYCLE_FOLDERS = SPEC_FOLDERS;
 /** Why the close-job acted (or did not act) on a candidate issue. */
 export type CloseDecision =
 	| 'closed' // the issue was closed via the provider seam
-	| 'not-complete' // a prd whose query says it is not yet complete → left open
+	| 'not-complete' // a spec whose query says it is not yet complete → left open
 	| 'not-landed' // a lone task not yet in work/done/ → left open
 	| 'close-failed'; // closure condition held but the provider close degraded
 
@@ -111,9 +111,9 @@ function listMarkdown(repoPath: string, folder: WorkFolderKey): string[] {
 }
 
 /**
- * Read a prd's `issue:` number by slug, scanning the prd folders. Returns
- * `undefined` when no prd with that slug carries an `issue:` (a prd with no source
- * issue, or a typo'd `prd:` hop — degrades to "no issue to close", never crashes).
+ * Read a spec's `issue:` number by slug, scanning the spec folders. Returns
+ * `undefined` when no spec with that slug carries an `issue:` (a spec with no source
+ * issue, or a typo'd `spec:` hop — degrades to "no issue to close", never crashes).
  */
 function specIssueNumber(
 	repoPath: string,
@@ -137,14 +137,14 @@ function specIssueNumber(
  * Resolve the DEDUPLICATED set of closure candidates from the `work/` tree, each
  * via the UNCHANGED {@link resolveClosingIssue}:
  *
- *   - every prd carrying `issue:` (in `work/prds/ready/` or `work/prds/tasked/`) is a
- *     prd-kind candidate keyed on its own `prd:` query;
- *   - every LONE task (`issue:` and NO `prd:`) is an `issue`-kind candidate.
+ *   - every spec carrying `issue:` (in `work/specs/ready/` or `work/specs/tasked/`) is a
+ *     spec-kind candidate keyed on its own `spec:` query;
+ *   - every LONE task (`issue:` and NO `spec:`) is an `issue`-kind candidate.
  *
- * A fanned task carries `prd:` (NOT its own `issue:`), so it reaches the number
- * through its prd's candidate, never as its own — the issue number lives ONLY on
- * the prd. Deduplicated by issue number: a prd enumerated once even though many
- * tasks point at it. Prd candidates are listed before lone-task candidates, each
+ * A fanned task carries `spec:` (NOT its own `issue:`), so it reaches the number
+ * through its spec's candidate, never as its own — the issue number lives ONLY on
+ * the spec. Deduplicated by issue number: a spec enumerated once even though many
+ * tasks point at it. Spec candidates are listed before lone-task candidates, each
  * group slug-sorted, for a deterministic log.
  */
 function resolveCandidates(repoPath: string): {
@@ -165,9 +165,9 @@ function resolveCandidates(repoPath: string): {
 			);
 			const slug = fm.slug ?? basename(file, '.md');
 			const closing = resolveClosingIssue(fm);
-			// A prd's own closing link is its `issue:` (a prd has no `prd:`); on the
-			// hand-edit conflict `prd:` wins via resolveClosingIssue, so only a true
-			// `issue:`-bearing prd becomes a candidate here.
+			// A spec's own closing link is its `issue:` (a spec has no `spec:`); on the
+			// hand-edit conflict `spec:` wins via resolveClosingIssue, so only a true
+			// `issue:`-bearing spec becomes a candidate here.
 			if (closing?.via === 'issue' && !seen.has(closing.issue)) {
 				seen.add(closing.issue);
 				specCandidates.push({issueNumber: closing.issue, via: 'spec', slug});
@@ -175,7 +175,7 @@ function resolveCandidates(repoPath: string): {
 		}
 	}
 
-	// Lone-task candidates: a task with `issue:` and NO `prd:` closes its OWN
+	// Lone-task candidates: a task with `issue:` and NO `spec:` closes its OWN
 	// issue directly when it lands in work/done/.
 	for (const folder of TASK_FOLDERS) {
 		for (const file of listMarkdown(repoPath, folder)) {
@@ -184,9 +184,9 @@ function resolveCandidates(repoPath: string): {
 			);
 			const slug = fm.slug ?? basename(file, '.md');
 			const closing = resolveClosingIssue(fm);
-			// `resolveClosingIssue` returns `via: 'issue'` ONLY when there is no `prd:`
-			// (prd wins on conflict), so a fanned task never lands here — it reaches
-			// its issue through the prd candidate above.
+			// `resolveClosingIssue` returns `via: 'issue'` ONLY when there is no `spec:`
+			// (spec wins on conflict), so a fanned task never lands here — it reaches
+			// its issue through the spec candidate above.
 			if (closing?.via === 'issue' && !seen.has(closing.issue)) {
 				seen.add(closing.issue);
 				taskCandidates.push({issueNumber: closing.issue, via: 'issue', slug});
@@ -222,7 +222,7 @@ function closeComment(via: 'issue' | 'spec', slug: string): string {
 
 /**
  * Run the close-job over a repo's `work/` tree: resolve the closure candidates,
- * apply the per-kind closure condition (a landed lone task; a prd whose
+ * apply the per-kind closure condition (a landed lone task; a spec whose
  * {@link isSpecComplete} query holds), and close the qualifying issues through the
  * {@link IssueProvider.closeIssue} seam (reason `completed`, an informational
  * comment riding the SAME atomic close). REUSES the unchanged resolution + query +

package/src/complete.ts

@@ -13,6 +13,8 @@ import {
 import {ledgerWrite} from './ledger-write.js';
 import {releaseItemLock} from './item-lock.js';
 import {workBranchRef, parseWorkBranchRef} from './slug-namespace.js';
+import {isProvablyMergedForReap} from './gc.js';
+import type {SidecarType} from './sidecar.js';
 import type {ReviewProvider} from './integrator.js';
 import type {IntegrationMode} from './config.js';
 import {runAsync, localMainAheadCount, type RunResult} from './git.js';
@@ -160,7 +162,7 @@ export interface CompleteOptions {
 	 */
 	freshWorktreeGate?: boolean;
 	/**
-	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, prd
+	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, spec
 	 * `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1
 	 * (a)). Threaded verbatim into {@link performIntegration} as `mergeRetries` so
 	 * the resolved per-repo value controls how many re-rebase-and-retry attempts
@@ -172,7 +174,7 @@ export interface CompleteOptions {
 	/** Skip the acceptance gate (human-only escape hatch; never used unattended). */
 	skipVerify?: boolean;
 	/**
-	 * **`--allow-backlog`** (prd
+	 * **`--allow-backlog`** (spec
 	 * `do-allow-backlog-drive-staged-tasks-without-promotion`): TREAT a
 	 * `tasks/backlog/`-resident body (staging) as a VALID build source, so a
 	 * staged task driven in place done-moves `tasks/backlog/ → tasks/done/`
@@ -185,7 +187,7 @@ export interface CompleteOptions {
 	 */
 	allowBacklog?: boolean;
 	/**
-	 * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/tasked/review.md`). When
+	 * **Gate 2 — the PR/code review gate** (GATES spec `work/specs/tasked/review.md`). When
 	 * `true`, after the green `verify` and BEFORE the done-move, run the `review`
 	 * SKILL as a FRESH-CONTEXT agent (its own harness launch) and route its verdict:
 	 * `approve` → proceed to done-move/commit/integrate; `block` → route to
@@ -315,9 +317,12 @@ export interface CompleteResult {
 	outcome: CompleteOutcome;
 	/**
 	 * True iff a FAILURE outcome (gate-failed / rebase-conflict) was routed to
-	 * `work/needs-attention/` via the shared mechanism (ADR §12), rather than left
-	 * dangling. Undefined/false on the success, `--skip-verify`, refused, and
-	 * usage-error paths (none of which move the item to needs-attention).
+	 * the shared needs-attention mechanism (ADR §12) — post lock-cutover, the
+	 * per-item lock is amended to `state: stuck` with the reason recorded on the
+	 * lock entry (there is no `work/needs-attention/` folder write anymore),
+	 * rather than the item being left dangling. Undefined/false on the success,
+	 * `--skip-verify`, refused, and usage-error paths (none of which mark the
+	 * item stuck).
 	 */
 	routedToNeedsAttention?: boolean;
 	/** The work branch that was completed, when one was resolved. */
@@ -417,7 +422,7 @@ export async function performComplete(
 		return await runComplete(options, note);
 	} catch (err) {
 		// AUTONOMOUS-STRAND SURFACE (task
-		// `autonomous-integration-refusal-surfaces-not-strands-in-progress`, prd
+		// `autonomous-integration-refusal-surfaces-not-strands-in-progress`, spec
 		// `ledger-integrity` story 7). On the AUTONOMOUS path (`surfaceArbiter` set
 		// — the human-vs-autonomous gate the core's other failures use), a SOURCE-
 		// STRAND `CompleteRefusal` (the slug-is-stuck `nothing to complete`) and the
@@ -489,13 +494,11 @@ function strandRefusalSlug(err: unknown): string | undefined {
 }
 
 /**
- * Surface an autonomous-path strand refusal to `needs-attention/` on the
- * arbiter via the TREE-LESS seam ({@link
- * ledgerWrite.applyTreelessNeedsAttentionTransition}). The mechanism is the
- * one `requeue`/`continue` already use in reverse: fetch `<arbiter>/main`,
- * resolve the slug's actual current folder ON THE ARBITER (arbiter-is-truth),
- * build the one-file `work/<src>/<slug>.md → work/needs-attention/<slug>.md`
- * move on a scratch index, and CAS-publish it. It NEVER touches the caller's
+ * Surface an autonomous-path strand refusal via the TREE-LESS seam ({@link
+ * ledgerWrite.applyTreelessNeedsAttentionTransition}). Post lock-cutover the
+ * seam is a pure LOCK AMEND — the item's per-item lock is moved to
+ * `state: stuck` with the reason on the lock entry; no folder move, no
+ * `work/needs-attention/` write. It NEVER touches the caller's
  * working tree / HEAD / index — important here because the refusal was raised
  * precisely because the working tree does NOT hold an `.md` to `git mv`. It is
  * idempotent (a re-surface of an already-surfaced slug is a no-op) and reports
@@ -523,11 +526,13 @@ async function surfaceAutonomousStrand(params: {
 	});
 	if (surfaced.moved) {
 		const message =
-			`'${slug}' refused (${reason}); surfaced to work/needs-attention/ on ` +
-			`${arbiter}/main so the next autonomous tick does NOT re-claim it.`;
+			`'${slug}' refused (${reason}); surfaced on ${arbiter}/main as a stuck ` +
+			'question (needsAnswers) so the next autonomous tick does NOT re-claim it.';
 		note(message);
+		// PR-2b D3: a clean surface is GREEN (exitCode 0). The autonomous strand
+		// surface is one of the cleanly-surfaced bounce sites this policy applies to.
 		return {
-			exitCode: 1,
+			exitCode: 0,
 			outcome: 'strand-surfaced',
 			routedToNeedsAttention: true,
 			message,
@@ -633,7 +638,7 @@ async function runComplete(
 		);
 	}
 	// The branch HEAD is on when it IS a work branch for this slug (so an explicit
-	// `prd:`-style recovery still completes the branch it is standing on); else
+	// `spec:`-style recovery still completes the branch it is standing on); else
 	// synthesise the task branch.
 	const branch =
 		headParsed && headParsed.slug === slug
@@ -668,15 +673,17 @@ async function runComplete(
 	// removes it from THERE, so the move can never disagree with what the arbiter
 	// holds even when the local tree diverges (ledger-integrity defect 1). The
 	// `source` we pass is the arbiter-content fallback for the degenerate "arbiter
-	// holds nothing" case, not the authority. `in-progress/` is RETAINED below for
-	// the legacy/bounce surfaces that may still source from it until its folder
-	// removal (9c, OUT of this task's scope).
+	// holds nothing" case, not the authority. The legacy `in-progress/` FOLDER PROBE
+	// is GONE (task `finish-in-progress-folder-cutover-remove-legacy-recovery-readers`):
+	// the per-item-lock cutover moved claim OFF writing `work/in-progress/` (the body
+	// rests in `tasks/backlog/`, liveness is the held lock), so nothing writes that
+	// folder anymore and the `existsSync(inProgress)` arm could not fire. Liveness is
+	// the lock, not the folder.
 	const backlog = workItemPath(cwd, 'tasks-ready', slug);
 	const staged = workItemPath(cwd, 'tasks-backlog', slug);
-	const inProgress = workItemPath(cwd, 'in-progress', slug);
 	const done = workItemPath(cwd, 'done', slug);
 	const onBacklog = existsSync(backlog);
-	// `--allow-backlog` drive (prd
+	// `--allow-backlog` drive (spec
 	// `do-allow-backlog-drive-staged-tasks-without-promotion`): a staged task driven
 	// in place RESTS in `tasks/backlog/` (claim never moved it). Detect it as a build
 	// source so the done-move goes `tasks/backlog/ → tasks/done/` DIRECTLY (the
@@ -686,7 +693,6 @@ async function runComplete(
 	// strand `complete` must REFUSE (the honest "not finished, not done" position),
 	// NOT silently integrate — only the deliberate drive promotes from staging.
 	const onPreBacklog = options.allowBacklog === true && existsSync(staged);
-	const onInProgress = existsSync(inProgress);
 	// SELF-RENAMING FOLDER task backstop: the binary-known `work/done/<slug>.md`,
 	// OR — when none of the binary-known ledger folders hold the record — the slug
 	// at a RENAMED done-position the migration agent placed it in (e.g.
@@ -695,13 +701,10 @@ async function runComplete(
 	// resolution is byte-for-byte unchanged.
 	const onDone =
 		existsSync(done) ||
-		(!onBacklog &&
-			!onPreBacklog &&
-			!onInProgress &&
-			recordAtRenamedDonePosition(cwd, slug));
-	// STRANDED-DONE AUTO-RECOVER (prd `ledger-integrity` story 6, the autonomous
-	// half of `finish-already-committed-branch`). When neither in-progress/ nor
-	// needs-attention/ holds the slug on the BRANCH tree BUT done/ does, the work
+		(!onBacklog && !onPreBacklog && recordAtRenamedDonePosition(cwd, slug));
+	// STRANDED-DONE AUTO-RECOVER (spec `ledger-integrity` story 6, the autonomous
+	// half of `finish-already-committed-branch`). When the pool/staging does NOT
+	// hold the slug on the BRANCH tree BUT done/ does, the work
 	// branch was already built + done-moved + committed by a prior run that never
 	// landed on the arbiter (a terminal push failed, or the PR never merged). The
 	// autonomous `do`/`advance`/plain-`complete` path used to refuse this with
@@ -713,8 +716,7 @@ async function runComplete(
 	// `<arbiter>/main` returns `already-integrated` (clean no-op, NEVER a
 	// re-push/double-integrate). Mutually exclusive with the build-path source +
 	// `recovering` flags — the core ignores them when `committedRecovery` is set.
-	const folderShapeStranded =
-		!onBacklog && !onPreBacklog && !onInProgress && onDone;
+	const folderShapeStranded = !onBacklog && !onPreBacklog && onDone;
 	// DIRTY-CONTINUE GATE (task `recover-autodetect-gated-on-nothing-to-commit`).
 	// The folder-shape stranded-done auto-detect is necessary but NOT sufficient on
 	// a CONTINUE: a requeued task whose prior attempt already done-moved the slug
@@ -749,24 +751,19 @@ async function runComplete(
 	// "nothing to complete" CompleteRefusal). We default `source` to `'tasks-ready'`
 	// so `sourcePath` resolves to the canonical pool path the refusal message
 	// names; the refusal fires because that file does not exist on disk.
-	const source: 'tasks-ready' | 'tasks-backlog' | 'in-progress' | 'done' =
-		dirtyContinue
-			? 'done'
-			: onBacklog
-				? 'tasks-ready'
-				: onInProgress
-					? 'in-progress'
-					: onPreBacklog
-						? 'tasks-backlog'
-						: 'tasks-ready';
+	const source: 'tasks-ready' | 'tasks-backlog' | 'done' = dirtyContinue
+		? 'done'
+		: onBacklog
+			? 'tasks-ready'
+			: onPreBacklog
+				? 'tasks-backlog'
+				: 'tasks-ready';
 	const sourcePath =
 		source === 'tasks-ready'
 			? backlog
 			: source === 'tasks-backlog'
 				? staged
-				: source === 'in-progress'
-					? inProgress
-					: done;
+				: done;
 	if (dirtyContinue) {
 		// Announce LOUDLY (parallel to the `committedRecovery` recovery note above):
 		// the autonomous integrate path took the CONTINUE-BUILD branch, not the
@@ -892,7 +889,7 @@ async function runComplete(
 		freshWorktreeGate: options.freshWorktreeGate,
 		// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) — the
 		// git-alone FLOOR of the cross-job land-queue, resolved through the gate-family
-		// precedence chain (prd `land-time-reverify-and-parallel-merge-ceiling` Story
+		// precedence chain (spec `land-time-reverify-and-parallel-merge-ceiling` Story
 		// 5). Threaded so a wide-matrix CI's raised cap actually reaches the merge loop.
 		mergeRetries: options.mergeRetries,
 		skipVerify: options.skipVerify,
@@ -924,9 +921,19 @@ async function runComplete(
 
 	// The FAILURE outcomes map 1:1 onto `complete`'s — the core already note()'d
 	// the reason and did any routing; the tail never runs for them.
+	// PR-2b exit-code policy (spec
+	// `surface-stuck-as-questions-and-retire-stuck-lock-state`, decision #4 / D3):
+	// a cleanly-surfaced bounce is GREEN (`exitCode: 0`) iff its surface transition
+	// SUCCEEDED (`routedToNeedsAttention: true`); a FAILED surface stays non-zero
+	// (retry/resolve). Applies to `prepare-failed`/`gate-failed`/`review-blocked`/
+	// `review-unparseable`/`rebase-conflict`. The empty-diff backstop is owned by
+	// task `empty-diff-bounce-surfaces-dispose-defaulted-question` and is NOT
+	// reached here.
+	const surfaceExit = (routed: boolean | undefined): 0 | 1 =>
+		routed === true ? 0 : 1;
 	if (core.outcome === 'prepare-failed') {
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'prepare-failed',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -935,7 +942,7 @@ async function runComplete(
 	}
 	if (core.outcome === 'gate-failed') {
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'gate-failed',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -944,7 +951,7 @@ async function runComplete(
 	}
 	if (core.outcome === 'review-blocked') {
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'review-blocked',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -958,7 +965,7 @@ async function runComplete(
 		// `do`/`run` tail re-labels its cause `transient-infra` (NOT a reviewer block) off
 		// the parse-failure phrase in `core.reason`.
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'review-unparseable',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -967,7 +974,7 @@ async function runComplete(
 	}
 	if (core.outcome === 'rebase-conflict') {
 		return {
-			exitCode: 1,
+			exitCode: surfaceExit(core.routedToNeedsAttention),
 			outcome: 'rebase-conflict',
 			routedToNeedsAttention: core.routedToNeedsAttention,
 			branch: core.branch,
@@ -983,7 +990,7 @@ async function runComplete(
 		// because the work is already integrated and the branch may or may not
 		// still exist locally.
 		//
-		// CROSS-SUBSTRATE RELEASE (prd `ledger-status-per-item-lock-refs` US #9/#10;
+		// CROSS-SUBSTRATE RELEASE (spec `ledger-status-per-item-lock-refs` US #9/#10;
 		// task `complete-lock-then-durable-main-move-crash-safe`): the durable
 		// `main` record is already terminal (the kept tip is provably on
 		// `<arbiter>/main`), so the per-item lock claim took is now stale: release it
@@ -1021,7 +1028,7 @@ async function runComplete(
 	const commitMessage = core.commitMessage;
 	const mode = result.mode;
 
-	// CROSS-SUBSTRATE RELEASE, gated on the work being DURABLY ON `main` (prd
+	// CROSS-SUBSTRATE RELEASE, gated on the work being DURABLY ON `main` (spec
 	// `ledger-status-per-item-lock-refs` US #9/#10; ADR
 	// `ledger-status-on-per-item-lock-refs`; the trail's Amendment 6; task
 	// `complete-lock-then-durable-main-move-crash-safe`). ORDER MATTERS: the
@@ -1120,6 +1127,43 @@ async function runComplete(
 	// ONE thing the human must act on, so it is emitted as a visually-distinct
 	// block (blank lines + heading + TTY-aware color) ON TOP of the plain summary
 	// note below — cosmetic only; the structured result is unchanged.
+	//
+	// BENIGN ALREADY-LANDED RACE TAIL (task `propose-push-survives-stale-lease-
+	// on-reaped-work-ref`, follow-up
+	// `complete-propose-honour-already-landed-and-rename-continue-branch-module`):
+	// when the integrator's propose push observed a REAPED `work/<slug>` ref AND
+	// the work was provably on `<arbiter>/main`, it returns `alreadyLanded: true`
+	// with a custom `instruction`. In that case NOTHING was pushed and there is
+	// NO ref for a PR to point at, so emitting the generic
+	// `formatProposeNextStep` push+PR block ("Pushed ... Open a PR/MR ...") would
+	// misreport a clean no-op as unfinished work. Surface the integrator's
+	// `instruction` VERBATIM instead — it is already the correct clean-no-op
+	// prose (the CI-dominant recovery path via `performIntegration` already does
+	// the same; this is the sibling `complete.ts` caller's honest report). The
+	// tail (switch-to-main / delete-local-branch / `--no-switch`) is UNCHANGED
+	// — only the emitted next-step + summary text differ.
+	if (result.alreadyLanded === true) {
+		const instruction =
+			result.instruction ??
+			`${branch}: already on ${arbiter}/main (clean no-op).`;
+		const tail = options.noSwitch
+			? `; left on ${branch} (--no-switch).`
+			: deletedLocalBranch
+				? `; switched to main and deleted ${branch}.`
+				: '; switched to main.';
+		const message = `Completed '${slug}': ${instruction}${tail}`;
+		note(message);
+		return {
+			exitCode: 0,
+			outcome: 'completed',
+			branch,
+			commitMessage,
+			mergedToMain: false,
+			switchedTo,
+			deletedLocalBranch,
+			message,
+		};
+	}
 	const color = options.color ?? shouldUseColor(process.stdout);
 	const noteBlock = options.noteBlock ?? note;
 	noteBlock(
@@ -1158,7 +1202,7 @@ async function runComplete(
 /**
  * Release the per-item lock `claim` ALSO acquired (`action: implement`, keyed
  * `task:<slug>`) AFTER the durable `main` move has landed — the SECOND, lock-
- * release half of complete's cross-substrate ordering (prd
+ * release half of complete's cross-substrate ordering (spec
  * `ledger-status-per-item-lock-refs` US #9/#10; task
  * `complete-lock-then-durable-main-move-crash-safe`).
  *
@@ -1316,15 +1360,29 @@ export async function isLocalBranchProvablyOnArbiter(
 	// Refresh remote-tracking refs against the live arbiter (best-effort).
 	await gitSoft(['fetch', '--quiet', arbiter], cwd, env);
 
-	// Merged: tip is an ancestor of <arbiter>/main.
+	// Merged: the tip is provably on <arbiter>/main — fast-path ancestor OR
+	// squash-aware fallback (durable done/dropped record on main + branch
+	// carries nothing main lacks). The SAME predicate `gc.ts`'s worktree reaper
+	// and `reap-branches.ts`'s remote sweep use — do not fork it.
+	const parsed = parseWorkBranchRef(branch);
+	const arbiterMainRef = `${arbiter}/main`;
 	const merged =
-		(
-			await gitSoft(
-				['merge-base', '--is-ancestor', localTip, `${arbiter}/main`],
-				cwd,
-				env,
-			)
-		).status === 0;
+		parsed === undefined
+			? (
+					await gitSoft(
+						['merge-base', '--is-ancestor', localTip, arbiterMainRef],
+						cwd,
+						env,
+					)
+				).status === 0
+			: isProvablyMergedForReap({
+					cwd,
+					tip: localTip,
+					arbiterMain: arbiterMainRef,
+					namespace: parsed.namespace as SidecarType,
+					slug: parsed.slug,
+					env,
+				});
 	if (merged) {
 		return true;
 	}

package/src/concurrency.ts

@@ -49,7 +49,7 @@ export interface RunConcurrentOptions<I, T> {
 /**
  * A per-key async serialiser: `withKeyedLock(key, fn)` runs `fn` to completion
  * before the next caller for the SAME key starts; different keys never block each
- * other. Used to serialise the prd, shared-working-tree CLAIM step PER REPO
+ * other. Used to serialise the spec, shared-working-tree CLAIM step PER REPO
  * inside the otherwise-concurrent tick.
  *
  * Two concurrent claims in ONE repo would prepare their claim micro-commit in the