dorfl 0.1.1 → 0.2.0

package/src/repo-config.ts

@@ -2,6 +2,7 @@ import {readFileSync, existsSync} from 'node:fs';
 import {join} from 'node:path';
 import {
 	mergeConfig,
+	validateDeadlineConfig,
 	warnDeprecatedConfigKeys,
 	type Config,
 	type PartialConfig,
@@ -61,23 +62,23 @@ export const REPO_CONFIG_FILENAME = brand.repoConfigFilename;
  */
 export const REPO_ALLOWED_KEYS = [
 	'integration',
-	// `taskingIntegration` (the per-TRANSITION override for the prd→tasks TASKING
+	// `taskingIntegration` (the per-TRANSITION override for the spec→tasks TASKING
 	// transition ONLY) is a genuine repo property exactly like `integration`: whether
-	// THIS repo tasks a prd straight onto `main` (task FILES land, no PR) while it
+	// THIS repo tasks a spec straight onto `main` (task FILES land, no PR) while it
 	// still BUILDS each task as a reviewable PR is agreed by all collaborators +
 	// travels with the repo. Resolved per-repo through the SAME chain as
 	// `integration`, then falls back to `integration` when unset. DISTINCT from
-	// intake's per-EMITTED-TYPE `{task, prd}` resolver (front door, author-trust):
+	// intake's per-EMITTED-TYPE `{task, spec}` resolver (front door, author-trust):
 	// this is a per-lifecycle-transition knob, inside the boundary, config-resolved.
 	'taskingIntegration',
-	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — staging vs pool, prd
+	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — staging vs pool, spec
 	// `staging-pool-position-gate-and-trust-model` US #5) is a genuine repo property
 	// exactly like `taskingIntegration`/`integration`: whether THIS repo's tasker
-	// output lands STAGED (`pre-backlog/`, review-without-PR human-promote path) or
+	// output lands STAGED (`tasks/backlog/`, review-without-PR human-promote path) or
 	// straight in the agent-eligible POOL (`ready/`, trusted fast-path) is agreed
 	// by all collaborators + travels with the repo. Resolved per-repo through the
 	// SAME chain as `taskingIntegration` (flag > env > per-repo > global > built-in
-	// `pre-backlog`). DISTINCT from intake's per-emitted-type stamps (front door):
+	// `backlog`). DISTINCT from intake's per-emitted-type stamps (front door):
 	// this is a per-lifecycle PLACEMENT knob, inside the trust boundary,
 	// config-resolved. Fed into the shared placement resolver as the
 	// configured-default rung (`src/placement.ts`).
@@ -91,7 +92,7 @@ export const REPO_ALLOWED_KEYS = [
 	// through the SAME chain as `tasksLandIn` (flag `--specs-land-in` > env
 	// `DORFL_SPECS_LAND_IN` > per-repo > global > built-in). Fed into the shared
 	// placement resolver as the configured-default rung for the spec lifecycle
-	// (`src/placement.ts`). The sole spec-placement key after the prd → spec HARD
+	// (`src/placement.ts`). The sole spec-placement key after the ''prd'' → `spec` HARD
 	// CUTOVER (the legacy `prdsLandIn` key is GONE — clean break, no accepted alias).
 	'specsLandIn',
 	// `noPR` (the PR-INTENT axis — push the branch but deliberately skip the PR) is
@@ -116,7 +117,7 @@ export const REPO_ALLOWED_KEYS = [
 	'autoBuild',
 	// `autoTask` (may an agent auto-task undeclared prds in this repo?) is a
 	// genuine repo property — the tasking-autonomy mirror of `autoBuild`
-	// (`work/prds/auto-task.md`), resolved per-repo through the same chain.
+	// (`work/specs/auto-task.md`), resolved per-repo through the same chain.
 	'autoTask',
 	// `observationTriage` (the 3-state `off|ask|auto` gate over the observation
 	// INBOX) is a genuine repo property — the observation-side question-surfacing
@@ -125,7 +126,7 @@ export const REPO_ALLOWED_KEYS = [
 	// boolean (no alias; no external users owed a migration window, 2026-06-12).
 	'observationTriage',
 	// `mergeQuestions` (the 3-state `off|ask|auto` gate over the MERGE-QUESTION
-	// SURFACER — prd `land-time-reverify-and-parallel-merge-ceiling` Story 17 /
+	// SURFACER — spec `land-time-reverify-and-parallel-merge-ceiling` Story 17 /
 	// task `merge-questions-gate-axis`) is a genuine repo property exactly like
 	// `observationTriage`: whether THIS repo's unmerged `work/*` branches surface
 	// as merge-questions (and whether they auto-land) is agreed by all
@@ -136,13 +137,13 @@ export const REPO_ALLOWED_KEYS = [
 	// (flag > env > per-repo > global > default `ask`).
 	'mergeQuestions',
 	// `surfaceBlockers` (the BOOLEAN gate over DECLARED blocked work — whether a
-	// task/prd carrying `needsAnswers:true` is rendered into a question sidecar) is a
+	// task/spec carrying `needsAnswers:true` is rendered into a question sidecar) is a
 	// genuine repo property — the blocked-work side of the question-surfacing gate
 	// family (ADR `ci-config-policy-and-gate-family`), the orthogonal peer of
 	// `observationTriage`, resolved per-repo through the same chain as `autoBuild`.
 	'surfaceBlockers',
 	// `surfaceStaging` (the BOOLEAN gate-family member that widens SURFACE into
-	// STAGING — prd `staging-surface-and-apply-promote-safety` F2) is a genuine
+	// STAGING — spec `staging-surface-and-apply-promote-safety` F2) is a genuine
 	// repo property exactly like its siblings (`surfaceBlockers`/`autoBuild`):
 	// whether THIS repo inspects staging for questions is agreed by all
 	// collaborators + travels with the repo. Default `true`; resolved per-repo
@@ -161,8 +162,8 @@ export const REPO_ALLOWED_KEYS = [
 	// (machine paths/commands), so they are rejected below.
 	'model',
 	'harness',
-	// Gate 2 (PR/code review) policy is a genuine repo property (GATES prd
-	// `work/prds/tasked/review.md`), resolved per-repo like `integration`/`autoBuild`:
+	// Gate 2 (PR/code review) policy is a genuine repo property (GATES spec
+	// `work/specs/tasked/review.md`), resolved per-repo like `integration`/`autoBuild`:
 	// whether this repo runs Gate 2 (`review`), which model the review agent runs
 	// on (`reviewModel`), and the revise↔review loop bound (`reviewMaxRounds`).
 	// `reviewModel` is routing intent (not auth), so — like `model` — it is
@@ -185,7 +186,7 @@ export const REPO_ALLOWED_KEYS = [
 	// artifact (and pays the per-gate install cost) is agreed by all collaborators
 	// + travels with the repo. Resolved per-repo through the SAME chain.
 	'freshWorktreeGate',
-	// `mergeRetries` (the cross-job merge serialiser's CAS-retry cap — prd
+	// `mergeRetries` (the cross-job merge serialiser's CAS-retry cap — spec
 	// `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a))
 	// is a genuine repo property exactly like `freshWorktreeGate`: "how many
 	// re-rebase-and-retry attempts before a contender bounces to needs-attention"
@@ -195,7 +196,7 @@ export const REPO_ALLOWED_KEYS = [
 	// CAS still costs only a re-rebase + re-gate retry, never a `--force`.
 	'mergeRetries',
 	// `strictMergeApproval` (the OPT-IN strictness layered on the OQ6
-	// stale-approval default — prd `land-time-reverify-and-parallel-merge-ceiling`
+	// stale-approval default — spec `land-time-reverify-and-parallel-merge-ceiling`
 	// sidecar OQ6 / task `strict-merge-approval-gate`) is a genuine repo property
 	// exactly like `mergeQuestions`/`mergeRetries`: whether THIS repo re-surfaces
 	// the merge-question on a merge-base change (the host-agnostic analogue of
@@ -207,6 +208,16 @@ export const REPO_ALLOWED_KEYS = [
 	// default or shape. The re-surface vs. land branch is
 	// `apply-rung-merge-disposition`'s consumer, never here.
 	'strictMergeApproval',
+	// `agentDeadlineMinutes` / `checkpointHeadroomMinutes` / `maxAutoCheckpoints`
+	// (spec `graceful-pre-timeout-wip-checkpoint`) are genuine repo properties:
+	// how long an agent session runs before checkpointing, and how much head-room
+	// the GitHub backstop leaves above it, are agreed by all collaborators + travel
+	// with the repo. The dynamic GitHub `timeout-minutes` cap is rendered by the
+	// `enumerate` job at run time FROM this committed config, so an edit reflects
+	// EVERYWHERE (internal deadline AND GitHub cap) with no install-ci re-run.
+	'agentDeadlineMinutes',
+	'checkpointHeadroomMinutes',
+	'maxAutoCheckpoints',
 	// `promptGuidance` (the NUDGE namespace — prompt-text knobs that strengthen
 	// the worker's in-band wrapper line, e.g. `testFirst`) is a genuine repo
 	// property: "is this repo nudged toward test-first?" travels with the repo
@@ -257,9 +268,42 @@ export type RepoRejectedKey = (typeof REPO_REJECTED_KEYS)[number];
 
 const ALLOWED_SET = new Set<string>(REPO_ALLOWED_KEYS);
 
-/** The path to a repo's `.dorfl.json` (repo root + filename). */
+/**
+ * The LEGACY per-repo config filename (`.dorfl.json`, the original dotfile form)
+ * still honoured on READ for backward compatibility. Reads prefer
+ * {@link REPO_CONFIG_FILENAME} (`dorfl.json`) and fall back to this; writes /
+ * `setup` use the preferred name. Derived from the single brand identity so a
+ * rename flips it in lockstep (see `brand.ts`).
+ */
+export const REPO_CONFIG_FILENAME_LEGACY = brand.repoConfigFilenameLegacy;
+
+/**
+ * Resolve which per-repo config file a repo USES: the PREFERRED
+ * `dorfl.json` if present, else the LEGACY `.dorfl.json` if present, else the
+ * preferred path (the location a missing file WOULD live / be created at). So a
+ * repo that already committed the legacy dotfile keeps working, while a fresh
+ * repo (and every write) uses the plain name. If BOTH exist, the preferred
+ * `dorfl.json` wins (a deliberate, documented precedence, not a merge).
+ */
+export function resolveRepoConfigPath(repoPath: string): string {
+	const preferred = join(repoPath, REPO_CONFIG_FILENAME);
+	if (existsSync(preferred)) {
+		return preferred;
+	}
+	const legacy = join(repoPath, REPO_CONFIG_FILENAME_LEGACY);
+	if (existsSync(legacy)) {
+		return legacy;
+	}
+	return preferred;
+}
+
+/**
+ * The path to a repo's config file. Prefers the plain `dorfl.json`, falls back
+ * to the legacy `.dorfl.json` when only that exists (see
+ * {@link resolveRepoConfigPath}).
+ */
 export function repoConfigPath(repoPath: string): string {
-	return join(repoPath, REPO_CONFIG_FILENAME);
+	return resolveRepoConfigPath(repoPath);
 }
 
 /** The result of reading (and filtering) a repo's `.dorfl.json`. */
@@ -542,6 +586,11 @@ export function resolveRepoConfigFromLoaded(
 		...envOverrides(env),
 		...(flags ?? {}),
 	});
+	// Fail-loud range validation for the deadline / backstop / ceiling triple
+	// (spec `graceful-pre-timeout-wip-checkpoint`): a bad value from ANY layer
+	// (flag / env / per-repo / global) throws with a clear message naming the
+	// field + range — NEVER silently clamped.
+	validateDeadlineConfig(config);
 	return {
 		config,
 		rejected: repo.rejected,

package/src/repo-mirror.ts

@@ -5,6 +5,7 @@ import type {Config, PartialConfig} from './config.js';
 import type {ConfigOverrideMap} from './config-override.js';
 import {
 	REPO_CONFIG_FILENAME,
+	REPO_CONFIG_FILENAME_LEGACY,
 	loadRepoConfigFromContent,
 	resolveRepoConfigFromLoaded,
 	type LoadedRepoConfig,
@@ -247,7 +248,28 @@ export function readRepoConfigFromMirrorMain(
 	mirrorDir: string,
 	env?: NodeJS.ProcessEnv,
 ): string | undefined {
-	const spec = `main:${REPO_CONFIG_FILENAME}`;
+	// Prefer the plain `dorfl.json`; fall back to the legacy `.dorfl.json` when the
+	// preferred name is absent on `main` (a repo that committed the dotfile before
+	// dual-support). A genuine read fault on the FIRST attempt propagates; a
+	// path-missing on the first falls through to the legacy attempt.
+	const preferred = showConfigOnMain(mirrorDir, REPO_CONFIG_FILENAME, env);
+	if (preferred !== undefined) {
+		return preferred;
+	}
+	return showConfigOnMain(mirrorDir, REPO_CONFIG_FILENAME_LEGACY, env);
+}
+
+/**
+ * `git show main:<filename>` in a mirror, returning the bytes, or `undefined`
+ * when the PATH is absent on `main` (the expected config-less / wrong-name case).
+ * A genuine fault (unresolvable `main` / bad object) throws.
+ */
+function showConfigOnMain(
+	mirrorDir: string,
+	filename: string,
+	env?: NodeJS.ProcessEnv,
+): string | undefined {
+	const spec = `main:${filename}`;
 	const res = run('git', ['show', spec], mirrorDir, {env});
 	if (res.status === 0) {
 		return res.stdout;

package/src/review-gate.ts

@@ -1,6 +1,7 @@
 import {NullHarness, substituteModel, type Harness} from './harness.js';
 import {launchWithOptionalWatch} from './agent-launch.js';
 import {boundaryLine} from './watch-session.js';
+import {workItemRel} from './work-layout.js';
 import {
 	parseReviewVerdict,
 	ReviewParseError,
@@ -18,7 +19,7 @@ export {
 } from './review-verdict.js';
 
 /**
- * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/tasked/review.md`), the
+ * **Gate 2 — the PR/code review gate** (GATES spec `work/specs/tasked/review.md`), the
  * JUDGEMENT layer that rides ON TOP of the deterministic `verify` floor (ADR §8).
  *
  * After the green `verify` and BEFORE the done-move, `complete`/`do` invoke the
@@ -110,7 +111,7 @@ export function buildReviewPrompt(slug: string): string {
 	return [
 		`You are a FRESH-CONTEXT reviewer (Gate 2 — PR/code review). Review the`,
 		`code changes on this work branch AGAINST the task that specified them`,
-		`(work/in-progress/${slug}.md or work/done/${slug}.md) and its source prd.`,
+		`(work/in-progress/${slug}.md or work/done/${slug}.md) and its source spec.`,
 		``,
 		reviewDisciplinePrompt(),
 		``,
@@ -150,7 +151,7 @@ export function buildReviewPrompt(slug: string): string {
 		`comment on the PR — write it FOR a human landing there, NOT as scratch`,
 		`thinking. LEAD with the verdict ("Approved" or "Blocked") and then give the`,
 		`lenses' reasoning and the destination check ("merged as written, do we reach`,
-		`the task/prd goal?"). Write it deliberately; do NOT narrate your process`,
+		`the task/spec goal?"). Write it deliberately; do NOT narrate your process`,
 		`("Let me check…"). Keep it TIGHT: aim for a few short sentences and DO NOT`,
 		`exceed ~1500 characters — a long, multi-paragraph field is exactly what`,
 		`corrupts the JSON on large diffs; say less, not more. It is plain text inside`,
@@ -247,10 +248,10 @@ export function harnessReviewGate(
  * Render the TASK-SET acceptance-gate PROMPT — the task-path mirror of
  * {@link buildReviewPrompt} (task `slice-acceptance-gate`). Instead of
  * reviewing a code diff against ONE task, this instructs a FRESH-CONTEXT
- * agent to review the WHOLE candidate SET of tasks produced for prd `slug`,
+ * agent to review the WHOLE candidate SET of tasks produced for spec `slug`,
  * using the **review discipline**'s SET-OF-TASKS lens (coherence / dependency
  * graph / gaps + overlap / "if every task is built exactly as written, do we
- * reach the system the prd describes, and is each task
+ * reach the system the spec describes, and is each task
  * correct-if-implemented?"). It emits the SAME unified `ReviewVerdict` shape
  * so {@link parseReviewVerdict} reads it identically.
  *
@@ -265,24 +266,24 @@ export function harnessReviewGate(
 export function buildTaskAcceptancePrompt(slug: string): string {
 	return [
 		`You are a FRESH-CONTEXT reviewer (the task-SET ACCEPTANCE GATE). Review`,
-		`the candidate tasks this tasking run produced for the prd "${slug}" — the`,
+		`the candidate tasks this tasking run produced for the spec "${slug}" — the`,
 		`new/changed candidate task files on this work branch — AGAINST their source`,
-		`prd (work/prds/ready/${slug}.md — the held prd stays in prds/ready/ while it is being`,
+		`spec (${workItemRel('specs-ready', `${slug}.md`)} — the held spec stays in specs/ready/ while it is being`,
 		`tasked).`,
 		``,
 		reviewDisciplinePrompt(),
 		``,
 		`Review the WHOLE SET as a SET, not each task in isolation. The set-level`,
 		`framings the review discipline names:`,
-		`  - COHERENCE — do the tasks speak the prd's (and the system's) language`,
-		`    consistently; no task re-means or forks a concept another task/the prd`,
+		`  - COHERENCE — do the tasks speak the spec's (and the system's) language`,
+		`    consistently; no task re-means or forks a concept another task/the spec`,
 		`    already owns?`,
 		`  - DEPENDENCY GRAPH — is the \`blockedBy\`/ordering graph sound (acyclic, the`,
 		`    keystone first, each task's stated blockers really land its premise)?`,
-		`  - GAPS + OVERLAP — does the set COVER the prd with no missing piece, and`,
+		`  - GAPS + OVERLAP — does the set COVER the spec with no missing piece, and`,
 		`    without two tasks doing the same work or fighting over the same seam?`,
 		`  - CORRECT-IF-IMPLEMENTED — if EVERY task is built EXACTLY as written, do we`,
-		`    reach the system the prd describes, and is each task individually`,
+		`    reach the system the spec describes, and is each task individually`,
 		`    correct-if-implemented (no task that compiles but builds the wrong thing)?`,
 		``,
 		`This is a TERMINAL one-shot accept/reject gate: do NOT edit any task, do NOT`,

package/src/review-verdict.ts

@@ -4,7 +4,7 @@
  * (`work/protocol/REVIEW-PROTOCOL.md`, source-of-truth
  * `skills/setup/protocol/REVIEW-PROTOCOL.md`).
  *
- * This is the keystone of the `runner-invoked-disciplines-into-protocol` prd
+ * This is the keystone of the `runner-invoked-disciplines-into-protocol` spec
  * (task 1, D4): every runner-invoked review prompt builder
  * ({@link buildReviewPrompt}, {@link buildTaskAcceptancePrompt} in
  * `review-gate.ts`; {@link buildLoneTaskReviewPrompt} in `intake.ts`;
@@ -84,7 +84,7 @@ export interface ReviewVerdict {
 	questions?: string[];
 	/** For the tasker improver loop: specific tasks to emit `needsAnswers: true`. */
 	uncertainTasks?: UncertainTask[];
-	/** For the tasker improver loop: route the WHOLE prd to needs-attention. */
+	/** For the tasker improver loop: route the WHOLE spec to needs-attention. */
 	decompositionUnclear?: {questions: string[]};
 }
 
@@ -397,7 +397,7 @@ export function reviewDisciplinePrompt(): string {
 		'(the in-band, protocol-native review protocol every set-up repo carries;',
 		'the human-facing pointer is `skills/review/SKILL.md`). Apply its lenses',
 		'IN ORDER, ENDING in the destination check ("if this is built/merged',
-		'exactly as written, do we end up with the system the prd/task',
+		'exactly as written, do we end up with the system the spec/task',
 		'goal describes?"). Be ADVERSARIAL; verify against what ACTUALLY LANDED',
 		'(the bytes on disk), not intent. Weight findings by REAL impact \u2014 the',
 		'lenses find candidates, impact decides severity (a technically-true nit',

package/src/run.ts

@@ -31,7 +31,11 @@ import {
 	parseStopSentinel,
 	isWorkBranchDiffEmpty,
 	emptyDiffStopReason,
+	emptyDiffDisposeEnvelope,
+	type AgentStopKind,
 } from './agent-stop.js';
+import {surfaceStuckToNeedsAttention} from './needs-attention.js';
+import {resolveItemPathByIdentity} from './item-path.js';
 import {
 	classifyFailureCause,
 	failureCauseLabel,
@@ -190,6 +194,7 @@ export type ItemStatus =
 	| 'surface-unmoved' // the tree-less surface to needs-attention did NOT land on the arbiter (lost the CAS race / no arbiter) — the item is STILL in-progress on the arbiter; retry/resolve
 	| 'agent-failed' // the agent ran but produced bad/empty output (the conservative generic), OR the cause is unknown
 	| 'transient-infra' // a harness-surfaced model/connection outage (post-retry) or a git/provider outage — RETRY the same work (FAILURE-CAUSE axis)
+	| 'needs-reauth' // a credential expired / was revoked (OAuth refresh) — retry cannot help; a human must RE-AUTH (FAILURE-CAUSE axis)
 	| 'config-error' // a thrown CORE wiring/config error (e.g. review on, no reviewGate) — fix the WIRING, not the task (FAILURE-CAUSE axis)
 	| 'agent-stopped'; // the agent DELIBERATELY stopped (task drifted) OR produced no change — gate + Gate-2 skipped
 
@@ -457,6 +462,7 @@ export async function runOnce(options: RunOnceOptions): Promise<RunOnceResult> {
 			// are the same agent/run-failure routed to needs-attention, just labelled
 			// by cause).
 			i.status === 'transient-infra' ||
+			i.status === 'needs-reauth' ||
 			i.status === 'config-error' ||
 			// The surface to needs-attention did NOT land (lost the CAS race); the item
 			// is still in-progress on the arbiter — a genuine FAILURE (not a clean
@@ -709,16 +715,19 @@ async function runOneItem(
 		//     `work/<slug>` tip == the arbiter tip (the kept branch, unchanged,
 		//     after-commit). The DURABLE artifact is that branch on the arbiter + the
 		//     main surface (ADR §14: the job worktree is a disposable cache; recovery
-		//     flows through the branch + folder-native surfaces, NOT by editing the
-		//     worktree). So the surface is purely the one-file `in-progress/ →
-		//     needs-attention/` ledger move + reason — no branch push, no worktree
-		//     mutation. Because the branch is provably on the arbiter, the §4 reap
+		//     flows through the branch + lock surfaces, NOT by editing the
+		//     worktree). So the surface is purely the lock amend to `state: stuck` +
+		//     reason (post lock-cutover — no `in-progress/ → needs-attention/` folder
+		//     move, no branch push, no worktree
+		//     mutation). Because the branch is provably on the arbiter, the §4 reap
 		//     predicate still HOLDS and this worktree is reaped — more §14-aligned.
 		if (tree.continueRebaseConflict) {
 			const reason =
 				`continuing the kept ${tree.branch}: rebase onto the latest main ` +
-				'conflicted (aborted, never auto-resolved) — resolve against the latest ' +
-				'main, or `requeue --reset` to discard and start fresh';
+				'conflicted (aborted, never auto-resolved) — run `requeue --reconcile` ' +
+				'to non-destructively re-sync the mirror and retry the rebase (keeps ' +
+				'the work). Last resort: `requeue --reset` DESTRUCTIVELY discards the ' +
+				'branch and starts fresh.';
 			updateJobRecord(tree.dir, {state: 'needs-attention', reason});
 			const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
 				cwd: tree.dir,
@@ -747,9 +756,10 @@ async function runOneItem(
 			const reason =
 				`continuing the kept ${tree.branch}: publishing the rebased work branch ` +
 				`to the arbiter failed terminally (${tree.continuePushFailure}) — the ` +
-				'kept branch is left intact on the arbiter (recoverable); `requeue` to ' +
-				'retry once the churn settles, or `requeue --reset` to discard and start ' +
-				'fresh';
+				'kept branch is left intact on the arbiter (recoverable); ' +
+				'`requeue --reconcile` to non-destructively re-sync the mirror and ' +
+				'retry once the churn settles (keeps the work). Last resort: ' +
+				'`requeue --reset` DESTRUCTIVELY discards the branch and starts fresh.';
 			updateJobRecord(tree.dir, {state: 'needs-attention', reason});
 			const surfaced = await ledgerWrite.applyTreelessNeedsAttentionTransition({
 				cwd: tree.dir,
@@ -765,7 +775,7 @@ async function runOneItem(
 		}
 
 		// 3. Build the prompt — the SAME dual-use assembly `dorfl prompt`
-		//    emits: the canonical wrapper (+ source prd) + the task's ## Prompt.
+		//    emits: the canonical wrapper (+ source spec) + the task's ## Prompt.
 		let prompt: string;
 		try {
 			// CONTINUE-aware resolution: only on a continue (the job continued a kept
@@ -801,7 +811,7 @@ async function runOneItem(
 					})
 				: undefined;
 			// Thread the resolved per-repo nudge through the per-item override layer
-			// (a task or prd may pin `promptGuidance.testFirst` in its frontmatter,
+			// (a task or spec may pin `promptGuidance.testFirst` in its frontmatter,
 			// superseding the repo policy for THIS item) before the wrapper is built.
 			const itemGuidance = resolvePromptGuidanceForItem({
 				cwd: tree.dir,
@@ -862,24 +872,31 @@ async function runOneItem(
 		//     the arbiter) and SKIPS the gate + Gate-2 (the whole `performIntegration`
 		//     band) — a clean STOP is NOT "a build that changed nothing".
 		const sentinel = parseStopSentinel(agent.output);
-		const stopReason =
+		const stopReason: {kind: AgentStopKind; reason: string} | undefined =
 			sentinel !== undefined
-				? sentinel.reason
+				? {kind: 'sentinel', reason: sentinel.reason}
 				: (await isWorkBranchDiffEmpty({
 							cwd: tree.dir,
 							arbiter: tree.arbiterRemote,
 							env: gitEnv,
 					  }))
-					? emptyDiffStopReason(slug)
+					? {kind: 'empty-diff', reason: emptyDiffStopReason(slug)}
 					: undefined;
 		if (stopReason !== undefined) {
-			return await saveAgentStop(base, tree, slug, stopReason, ctx);
+			return await saveAgentStop(
+				base,
+				tree,
+				slug,
+				stopReason.reason,
+				stopReason.kind,
+				ctx,
+			);
 		}
 
 		// 5–7 (CONVERGED). The whole gate → review → done-move → commit → rebase →
 		// integrate band — plus the needs-attention routing on any failure — now runs
 		// through the SHARED `performIntegration` core (`integration-core.ts`, the
-		// run/do convergence prd). `run` no longer forks its own gate / done-move /
+		// run/do convergence spec). `run` no longer forks its own gate / done-move /
 		// completion commit / `Integrator`+`integrateWithRebase`: that closed all
 		// three drift instances at once (the fleet now gets the review gate, the PR
 		// title/body, AND the per-repo language-agnostic `verify` gate instead of the
@@ -954,7 +971,7 @@ async function runOneItem(
 				// (`do`/`--isolated`/`--remote`/`complete`) already pass it unconditionally.
 				freshWorktreeGate: config.freshWorktreeGate,
 				// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) —
-				// the git-alone FLOOR of the cross-job land queue (prd `land-time-reverify-
+				// the git-alone FLOOR of the cross-job land queue (spec `land-time-reverify-
 				// and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). Threaded
 				// from the per-repo resolved config so a wide-matrix CI's raised cap actually
 				// reaches the merge loop — across separate `run` fleet jobs the CAS loop IS
@@ -1138,9 +1155,10 @@ function runAgent(
  * This mirrors `do.ts`'s `saveAgentFailure`: route the failure through the SAME
  * ledger write seam's needs-attention transition the gate-fail / integrate-
  * conflict bounces use — which (with the arbiter) saves the agent's work as a wip
- * commit, `git mv`s the item to needs-attention/ with the failure detail recorded
- * as the reason, surfaces the move-only commit on the arbiter's `main`
- * (OBSERVABLE), AND pushes the `work/<slug>` branch (RECOVERABLE — the durable
+ * commit, then — post lock-cutover — amends the item's per-item lock to
+ * `state: stuck` with the failure detail as the reason on the lock entry
+ * (OBSERVABLE; the `needs-attention/` folder move is retired), AND pushes the
+ * `work/<slug>` branch (RECOVERABLE — the durable
  * artifact a requeue-continue lands the next agent on; continue-detection reads
  * <arbiter>/work/<slug> ahead of main). The push is best-effort — an unreachable
  * arbiter leaves the retained worktree + the local commits standing (the genuinely
@@ -1194,8 +1212,9 @@ function failureCauseToItemStatus(cause: FailureCause): ItemStatus {
 
 /**
  * Build the HONEST {@link ItemResult} for a CONTINUE-site surface that did NOT
- * land on the arbiter (`{moved: false}`). The tree-less `in-progress/ →
- * needs-attention/` move lost the CAS race against a busy arbiter (its
+ * land on the arbiter (`{moved: false}`). The tree-less stuck-lock amend (post
+ * lock-cutover — `state: stuck` + reason, in place of the retired `in-progress/ →
+ * needs-attention/` move) lost the CAS race against a busy arbiter (its
  * contention-retry cap exhausted) or had no arbiter to publish to, so the item is
  * STILL in-progress on the arbiter — reporting a clean `needs-attention` would
  * mislead (it claims the surface landed, when it did not). The DISTINCT
@@ -1236,9 +1255,36 @@ async function saveAgentStop(
 	tree: IsolatedTree,
 	slug: string,
 	reason: string,
+	kind: AgentStopKind,
 	ctx: OneItemContext,
 ): Promise<ItemResult> {
 	updateJobRecord(tree.dir, {state: 'needs-attention', reason});
+	// EMPTY-DIFF branch (spec resolved decision #2, task
+	// `empty-diff-bounce-surfaces-dispose-defaulted-question`): surface a sidecar
+	// carrying an engine-authored DISPOSE-DEFAULTED envelope question on
+	// `<arbiter>/main` (via the PR-1 tree-less surface primitive) and release the
+	// lock — NOT the general lock-stuck bounce path. "Nothing to do" is a
+	// non-deterministic LLM judgement, so a blind requeue would infinite-loop;
+	// the surfaced sidecar + `needsAnswers:true` on `main` parks the item as a
+	// human-visible question a `dispose` answer settles to `tasks/cancelled/`.
+	if (kind === 'empty-diff') {
+		const item = `task:${slug}`;
+		const itemPath = resolveItemPathByIdentity(tree.dir, item);
+		if (itemPath !== undefined) {
+			await surfaceStuckToNeedsAttention({
+				cwd: tree.dir,
+				slug,
+				item,
+				itemPath,
+				reason,
+				envelope: emptyDiffDisposeEnvelope({item, reason}),
+				arbiter: tree.arbiterRemote,
+				env: ctx.gitEnv ?? ctx.env,
+			});
+			return {...base, status: 'agent-stopped', detail: reason};
+		}
+		// Fallthrough (body missing) — fall through to the lock-stuck bounce below.
+	}
 	await ledgerWrite.applyNeedsAttentionTransition({
 		cwd: tree.dir,
 		slug,
@@ -1262,7 +1308,7 @@ export function defaultRunWorkspace(): string {
  * One supervised TICK over the registry, as a swappable unit. Today the tick IS
  * `runOnce` (claim+build+integrate a concurrent batch of eligible TASKS). The
  * loop ({@link runLoop}) is deliberately written against this signature — NOT
- * against `runOnce` directly — so the advance-loop prd can later swap the tick
+ * against `runOnce` directly — so the advance-loop spec can later swap the tick
  * (build / task / triage / surface / apply) WITHOUT re-architecting the loop
  * (the forward-pointer: the loop owns concurrency/scheduling, the tick owns one
  * item's work). The loop never reaches inside a tick.