dorfl 0.1.1 → 0.2.0

package/src/cli.ts

@@ -121,6 +121,7 @@ import {status, formatStatus} from './status.js';
 import {ledgerWrite} from './ledger-write.js';
 import {
 	releaseItemLock,
+	releaseLiteralLockEntry,
 	reportItemLocks,
 	formatItemLockReport,
 	itemLockReportNeedsAttention,
@@ -128,6 +129,11 @@ import {
 	formatReapReport,
 	reapReportNeedsAttention,
 } from './item-lock.js';
+import {
+	migrateStuckLocks,
+	formatMigrateStuckLocksReport,
+	migrateStuckLocksNeedsAttention,
+} from './migrate-stuck-locks.js';
 import {
 	promoteFromPreBacklog,
 	promoteFromPreSpec,
@@ -146,6 +152,7 @@ import {installCI, type WizardPrompts} from './install-ci.js';
 import {GitHubCIContext} from './install-ci-github.js';
 import {loadCapabilityRegistry} from './install-ci-core.js';
 import {performCloseMergedIssues} from './close-job.js';
+import {installSkills, type InstallSkillsResult} from './install-skills.js';
 
 interface ScanFlags {
 	config?: string;
@@ -353,10 +360,10 @@ function buildRegistrySetAdvanceTick(options: {
 		lifecycleGates: {
 			triage: config.observationTriage !== 'off',
 			surface: config.surfaceBlockers,
-			// `surfaceStaging` widens the SURFACE candidate set into STAGING (prd
+			// `surfaceStaging` widens the SURFACE candidate set into STAGING (spec
 			// `staging-surface-and-apply-promote-safety` F2). Default `true` — a
-			// tasked `needsAnswers` task in `tasks/backlog/` (or prd in
-			// `prds/proposed/`) surfaces its questions BEFORE promotion. BUILD/claim
+			// tasked `needsAnswers` task in `tasks/backlog/` (or spec in
+			// `specs/proposed/`) surfaces its questions BEFORE promotion. BUILD/claim
 			// stays pool-only either way.
 			surfaceStaging: config.surfaceStaging,
 		},
@@ -388,11 +395,11 @@ function buildRegistrySetAdvanceTick(options: {
 				identity: config.identity,
 				autoTask: config.autoTask,
 				integration: config.integration,
-				// The per-TRANSITION TASKING override: the `do prd:` tasking path threads
+				// The per-TRANSITION TASKING override: the `do spec:` tasking path threads
 				// `taskingIntegration ?? integration`; the build path stays on `integration`.
 				taskingIntegration: config.taskingIntegration,
-				// The TASK-PLACEMENT configured default (`do prd:` tasking output:
-				// `pre-backlog` staged vs `ready` pool). No operator flag on this
+				// The TASK-PLACEMENT configured default (`do spec:` tasking output:
+				// `backlog` staged vs `ready` pool). No operator flag on this
 				// registry-driven advance context, so only the configured default rung is
 				// threaded (the resolver still layers untrusted-origin force + built-in floor).
 				tasksLandIn: config.tasksLandIn,
@@ -400,7 +407,7 @@ function buildRegistrySetAdvanceTick(options: {
 				verify: config.verify,
 				// Single-job build path: gate the REBASED tip (the default) unconditionally.
 				freshWorktreeGate: config.freshWorktreeGate,
-				// Cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-
+				// Cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-
 				// parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)) — resolved per-repo
 				// and threaded so the registry-driven advance path's `do` inherits it.
 				mergeRetries: config.mergeRetries,
@@ -439,7 +446,7 @@ function buildRegistrySetAdvanceTick(options: {
 				triageGate: harnessTriageGate({harness, agentCmd: config.agentCmd}),
 				triageModel: config.model,
 				// The ANSWERED-MERGE LAND DISPATCH context (task
-				// `apply-rung-merge-disposition`, prd `land-time-reverify-and-parallel-
+				// `apply-rung-merge-disposition`, spec `land-time-reverify-and-parallel-
 				// merge-ceiling`): the dispatcher cuts a per-job worktree via
 				// `workspace.ts` `createJob` off the hub mirror (so we thread the resolved
 				// `workspacesDir` + the real arbiter URL — the per-mirror tree-less
@@ -544,7 +551,7 @@ interface RunFlags extends ScanFlags {
 	reviewMaxRounds?: string;
 	/** `--fresh-worktree-gate` / `--no-fresh-worktree-gate` — gate the REBASED tip in a clean throwaway worktree (ON by default). */
 	freshWorktreeGate?: boolean;
-	/** `--merge-retries <n>` — the cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). */
+	/** `--merge-retries <n>` — the cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). */
 	mergeRetries?: string;
 }
 
@@ -583,7 +590,7 @@ function runFlagOverrides(flags: RunFlags, command?: Commander): PartialConfig {
 	// fleet conditional lives in `runOnce`, not in this flag mapping).
 	Object.assign(overrides, freshWorktreeGateFlagOverrides(flags));
 	// `--merge-retries <n>` rides the SAME chain: the cross-job merge-serialiser
-	// CAS-retry cap (prd `land-time-reverify-and-parallel-merge-ceiling` Story 5 /
+	// CAS-retry cap (spec `land-time-reverify-and-parallel-merge-ceiling` Story 5 /
 	// Applied Answer q1 (a)). The `run` fleet inherits the resolved cap through
 	// the converged `performIntegration` core (config.mergeRetries threads into
 	// the merge loop, replacing the bare `DEFAULT_MERGE_RETRIES` fallback).
@@ -661,7 +668,7 @@ interface CompleteFlags {
 	reviewMaxRounds?: string;
 	/** `--fresh-worktree-gate` / `--no-fresh-worktree-gate` — gate the REBASED tip in a clean throwaway worktree (ON by default). */
 	freshWorktreeGate?: boolean;
-	/** `--merge-retries <n>` — the cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). */
+	/** `--merge-retries <n>` — the cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). */
 	mergeRetries?: string;
 	/** `--isolated`: finish the slug's retained job worktree (the stranded-branch recover). */
 	isolated?: boolean;
@@ -670,7 +677,7 @@ interface CompleteFlags {
 
 /**
  * Resolve the EXPLICIT operator placement override from `--tasks-land-in <where>`
- * (the top of the `do prd:` tasking-placement precedence — task
+ * (the top of the `do spec:` tasking-placement precedence — task
  * `runner-deterministic-slice-placement-policy-and-precedence`). Mirrors the
  * `flagMode === 'merge'` ⇒ `explicitMerge: true` shape: it contributes
  * `explicitTasksLandIn` ONLY when the operator actually typed the flag, so an
@@ -681,13 +688,13 @@ interface CompleteFlags {
  */
 function explicitTasksLandInFromFlag(
 	raw: string | undefined,
-): 'pre-backlog' | 'ready' | undefined {
+): 'backlog' | 'ready' | undefined {
 	if (raw === undefined) {
 		return undefined;
 	}
-	if (raw !== 'pre-backlog' && raw !== 'ready') {
+	if (raw !== 'backlog' && raw !== 'ready') {
 		throw new Error(
-			`--tasks-land-in must be 'pre-backlog' or 'ready' (got '${raw}').`,
+			`--tasks-land-in must be 'backlog' or 'ready' (got '${raw}').`,
 		);
 	}
 	return raw;
@@ -726,8 +733,10 @@ interface DoFlags {
 	config?: string;
 	arbiter?: string;
 	remote?: string;
-	/** `--isolated`: build in a job worktree off THIS repo's arbiter (no checkout takeover). */
+	/** `--isolated`: build in a job worktree off THIS repo's arbiter (no checkout takeover). Since `make-isolated-default-build-mode` this is the DEFAULT; the flag remains accepted as a redundant explicit opt-IN alias (D3). */
 	isolated?: boolean;
+	/** `--in-place`: opt OUT of the new default (isolated off the arbiter) and build in the CURRENT checkout, restoring today's dirty-tree-refusing in-place behaviour (D3). */
+	inPlace?: boolean;
 	/** `-n <x>`: do x eligible items in sequence (auto-pick form). */
 	number?: string;
 	/** `--selection-order <order>`: a preset keyword (drain/groom) or comma-separated pool order. */
@@ -742,7 +751,7 @@ interface DoFlags {
 	strictMergeApproval?: boolean;
 	merge?: boolean;
 	propose?: boolean;
-	/** `--tasks-land-in <pre-backlog|ready>`: the explicit operator placement override for `do prd:` tasking output (top of the placement precedence). Resolves into the `tasksLandIn` config key. */
+	/** `--tasks-land-in <backlog|ready>`: the explicit operator placement override for `do spec:` tasking output (top of the placement precedence). Resolves into the `tasksLandIn` config key. */
 	tasksLandIn?: string;
 	/** `--no-pr` ⇒ commander stores `pr === false` (the suppress-PR intent). */
 	pr?: boolean;
@@ -758,15 +767,15 @@ interface DoFlags {
 	review?: boolean;
 	reviewModel?: string;
 	reviewMaxRounds?: string;
-	/** `--tasker-loop` / `--no-tasker-loop` — the tasker improver loop on/off toggle (`do prd:` path). Resolves into the `taskerLoop` config key. */
+	/** `--tasker-loop` / `--no-tasker-loop` — the tasker improver loop on/off toggle (`do spec:` path). Resolves into the `taskerLoop` config key. */
 	taskerLoop?: boolean;
-	/** `--tasker-loop-max <n>` — the tasker improver loop's in-context convergence cap (`do prd:` path). Resolves into the `taskerLoopMax` config key. */
+	/** `--tasker-loop-max <n>` — the tasker improver loop's in-context convergence cap (`do spec:` path). Resolves into the `taskerLoopMax` config key. */
 	taskerLoopMax?: string;
-	/** `--tasker-loop-model <id>` — the tasker improver loop reviewer's de-correlated model (`do prd:` path). Resolves into the `taskerLoopModel` config key. */
+	/** `--tasker-loop-model <id>` — the tasker improver loop reviewer's de-correlated model (`do spec:` path). Resolves into the `taskerLoopModel` config key. */
 	taskerLoopModel?: string;
 	/** `--fresh-worktree-gate` / `--no-fresh-worktree-gate` — gate the REBASED tip in a clean throwaway worktree (ON by default). */
 	freshWorktreeGate?: boolean;
-	/** `--merge-retries <n>` — the cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). */
+	/** `--merge-retries <n>` — the cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)). */
 	mergeRetries?: string;
 }
 
@@ -783,7 +792,7 @@ interface IntakeFlags {
 	proposeTask?: boolean;
 	/**
 	 * `--origin-trust <trusted|untrusted>` — the author-trust verdict the CI shell
-	 * passes IN so `intake` STAMPS the emitted prd/task (task
+	 * passes IN so `intake` STAMPS the emitted spec/task (task
 	 * `untrusted-origin-forces-build-propose`). `intake` does NOT resolve trust; the
 	 * shell derives it from the SAME `author_association` case as the integration
 	 * flags. UNSET (a local intake) ⇒ emit unstamped ⇒ human/trusted.
@@ -886,7 +895,7 @@ function printPrdToSpecReport(result: PrdToSpecResult): void {
 		return;
 	}
 	if (result.leaks.length === 0) {
-		console.log('Leak scan: GREEN (no surviving prd data ref).');
+		console.log('Leak scan: GREEN (no surviving spec data ref).');
 	} else {
 		console.error(`Leak scan: FAILED (${result.leaks.length} leak(s)):`);
 		for (const leak of result.leaks) {
@@ -916,6 +925,8 @@ interface RequeueFlags {
 	cwd?: string;
 	arbiter?: string;
 	reset?: boolean;
+	reconcile?: boolean;
+	rebase?: boolean;
 	message?: string;
 }
 
@@ -929,10 +940,10 @@ interface ReleaseLockFlags {
 	config?: string;
 	cwd?: string;
 	arbiter?: string;
+	entry?: string;
 }
 
 interface DropFlags {
-	config?: string;
 	cwd?: string;
 	reason?: string;
 }
@@ -979,11 +990,12 @@ interface CloseMergedIssuesFlags {
 /**
  * Resolve a task-only command's slug argument through the §3a namespace guard
  * (`resolveTaskOnlyArg`): accept bare (= task) + `task:` (explicit alias),
- * REJECT `spec:` with a clear "operates on tasks, not specs" error (and the
- * legacy `prd:` with "operates on tasks, not prds", still accepted through the
- * cutover). On rejection it prints the error to stderr and exits 1 (the task-only
- * commands never act on a spec). An OMITTED slug (`start`/`complete`/`prompt`
- * infer it from the branch) passes through untouched.
+ * REJECT `spec:` with a clear "operates on tasks, not specs" error. On rejection
+ * it prints the error to stderr and exits 1 (the task-only commands never act on
+ * a spec). An OMITTED slug (`start`/`complete`/`prompt` infer it from the branch)
+ * passes through untouched. (The legacy ''prd:'' prefix is a DEAD namespace token
+ * after the hard cutover — it is neither special-cased nor rejected here; a
+ * ''prd:<slug>'' arg resolves as a bare literal task slug.)
  *
  * `do` is the ONE command that spans both namespaces; it consumes the full
  * `resolveSlug` (with the cross-namespace collision check) in the `do-in-place`
@@ -1067,14 +1079,14 @@ function buildInteractiveLauncher(
  * switching to its `work/<slug>` branch WITHOUT claiming). The runtime
  * difference is exactly the `resume` flag — `resume` forces it on (its only mode
  * is to re-engage), while `start` honours the (now hidden) `--resume` alias.
- * Both are task-only (§3a: accept bare + `task:`, reject `prd:`).
+ * Both are task-only (§3a: accept bare + `task:`, reject `spec:`).
  */
 async function runStartAction(
 	rawSlug: string | undefined,
 	flags: StartFlags,
 	resume: boolean,
 ): Promise<void> {
-	// Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+	// Task-only command (§3a): accept bare + `task:`, reject `spec:`.
 	const slug = resolveTaskOnlySlug(rawSlug);
 	const cwd = process.cwd();
 
@@ -1163,6 +1175,44 @@ export function buildProgram(): Command {
 		.name(brand.bin)
 		.description('Autonomous parallel agents over file-based work/ queues.');
 
+	// `dorfl config --json` (spec `graceful-pre-timeout-wip-checkpoint` — step 5):
+	// print the RESOLVED per-repo config as JSON, so BOTH the advance-lifecycle
+	// workflow's `enumerate` job (which reads it to emit the dynamic
+	// `githubTimeout` output) AND a human debugging a config-precedence question
+	// share ONE honest primitive. A focused honest primitive — NOT overloaded
+	// onto `scan`. Runs in the cwd (in-place), so the resolution chain reads THIS
+	// repo's committed `dorfl.json` exactly like `scan --here`.
+	program
+		.command('config')
+		.helpGroup(HEADLINE_GROUP)
+		.description(
+			"Print the resolved config for the current repo (flag > env > per-repo > global > default). Consumed by the advance-lifecycle workflow's enumerate job to emit the dynamic GitHub timeout backstop (agentDeadlineMinutes + checkpointHeadroomMinutes) at run time from the committed dorfl.json — so editing dorfl.json reflects everywhere (internal deadline AND GitHub cap) on the next tick, no install-ci re-run.",
+		)
+		.option('-c, --config <path>', 'config file path', defaultConfigPath())
+		.option(
+			'--arbiter <remote>',
+			'name of the arbiter git remote (default: per-repo/global defaultArbiter)',
+		)
+		.option('--json', 'output the resolved config as JSON')
+		.action(
+			async (flags: {config?: string; arbiter?: string; json?: boolean}) => {
+				if (flags.json !== true) {
+					console.error(
+						'error: `dorfl config` currently supports only --json output. Pass --json.',
+					);
+					process.exit(1);
+				}
+				const cwd = process.cwd();
+				const {global, override} = loadGlobalAndOverride(flags.config);
+				const resolved = resolveRepoConfig({
+					repoPath: cwd,
+					global,
+					override,
+				}).config;
+				console.log(JSON.stringify(resolved, null, 2));
+			},
+		);
+
 	program
 		.command('scan')
 		.helpGroup(HEADLINE_GROUP)
@@ -1515,7 +1565,7 @@ export function buildProgram(): Command {
 		.command('claim')
 		.helpGroup(ADVANCED_GROUP)
 		.description(
-			'Atomically claim a work/backlog/<slug>.md item via a compare-and-swap push to the arbiter (in-process; mirrors scripts/claim.sh).',
+			`Atomically claim a ${workFolderPrefix('tasks-ready')}<slug>.md item via a compare-and-swap push to the arbiter (in-process; mirrors scripts/claim.sh).`,
 		)
 		.argument('<slug>', 'the slug of the backlog item to claim')
 		.option(
@@ -1530,7 +1580,7 @@ export function buildProgram(): Command {
 			'override the readiness guard: claim despite an unmet blockedBy, and silence the needsAnswers warning (loud, never default)',
 		)
 		.action(async (rawSlug: string, flags: ClaimFlags) => {
-			// Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+			// Task-only command (§3a): accept bare + `task:`, reject `spec:`.
 			const slug = resolveTaskOnlySlug(rawSlug) as string;
 			// Wrap ONLY this CLI surface's `performClaim` call with the spinner
 			// helper (task `claim-cas-spinner`): the push can take seconds, so the
@@ -1736,7 +1786,7 @@ export function buildProgram(): Command {
 				flags.remote !== undefined && flags.remote.trim() !== ''
 					? flags.remote
 					: undefined;
-			// Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+			// Task-only command (§3a): accept bare + `task:`, reject `spec:`.
 			const theSlug = resolveTaskOnlySlug(rawSlug) as string;
 
 			const configPath = flags.config ?? defaultConfigPath();
@@ -1788,14 +1838,14 @@ export function buildProgram(): Command {
 		.command('prompt')
 		.helpGroup(ADVANCED_GROUP)
 		.description(
-			"Print to stdout the work-agent prompt for a task: the canonical CLAIM-PROTOCOL wrapper + the task's own ## Prompt (with <slug> and source prd substituted). Resolves work/in-progress/<slug>.md then work/backlog/<slug>.md; infers <slug> from a work/<slug> branch when omitted. Read-only, stdout only — the same assembly the autonomous runner feeds agentCmd.",
+			`Print to stdout the work-agent prompt for a task: the canonical CLAIM-PROTOCOL wrapper + the task's own ## Prompt (with <slug> and source spec substituted). Resolves work/in-progress/<slug>.md then ${workFolderPrefix('tasks-ready')}<slug>.md; infers <slug> from a work/<slug> branch when omitted. Read-only, stdout only — the same assembly the autonomous runner feeds agentCmd.`,
 		)
 		.argument(
 			'[slug]',
 			'the slug to render (inferred from a work/<slug> branch if omitted)',
 		)
 		.action((rawSlug: string | undefined) => {
-			// Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+			// Task-only command (§3a): accept bare + `task:`, reject `spec:`.
 			const slug = resolveTaskOnlySlug(rawSlug);
 			// Resolve the `promptGuidance` NUDGE namespace through the SAME chain the
 			// gate family uses (env > per-repo > global > default), so e.g. a
@@ -1902,7 +1952,7 @@ export function buildProgram(): Command {
 			'cross-job merge-serialiser CAS-retry cap (see `run --help`); resolved flag > env > per-repo > global > default 1000.',
 		)
 		.action(async (rawSlug: string | undefined, flags: CompleteFlags) => {
-			// Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+			// Task-only command (§3a): accept bare + `task:`, reject `spec:`.
 			const slug = resolveTaskOnlySlug(rawSlug);
 			const cwd = process.cwd();
 			const {global, override} = loadGlobalAndOverride(flags.config);
@@ -1926,6 +1976,11 @@ export function buildProgram(): Command {
 					override,
 					flags: {
 						...(flagMode ? {integration: flagMode} : {}),
+						// `--merge-retries <n>` rides the SAME gate-family precedence chain on
+						// the isolated-recovery path so a wide-matrix CI's raised cap actually
+						// reaches the land tail here too (task
+						// `thread-merge-retries-cross-task-and-ratify-default`).
+						...mergeRetriesFlagOverrides(flags),
 						...noPRFlagOverrides(flags),
 					},
 				});
@@ -1940,6 +1995,9 @@ export function buildProgram(): Command {
 					workspacesDir: flags.workspace ?? isoConfig.workspacesDir,
 					integration: isoConfig.integration,
 					noPR: isoConfig.noPR,
+					// The resolved cross-job CAS-retry cap threaded through so the isolated-
+					// recovery land tail respects the per-repo cap (same chain as `complete`).
+					mergeRetries: isoConfig.mergeRetries,
 					note: (message) => console.error(`>> ${message}`),
 					env: process.env,
 				});
@@ -1966,7 +2024,7 @@ export function buildProgram(): Command {
 					// `--fresh-worktree-gate`/`--no-fresh-worktree-gate` rides the SAME chain.
 					...freshWorktreeGateFlagOverrides(flags),
 					// `--merge-retries <n>` rides the SAME chain: the cross-job merge-serialiser
-					// CAS-retry cap (prd `land-time-reverify-and-parallel-merge-ceiling` Story 5
+					// CAS-retry cap (spec `land-time-reverify-and-parallel-merge-ceiling` Story 5
 					// / Applied Answer q1 (a)).
 					...mergeRetriesFlagOverrides(flags),
 					// `--no-pr` (the PR-INTENT axis) rides the SAME chain.
@@ -2006,7 +2064,7 @@ export function buildProgram(): Command {
 				// a single-job path, so the resolved flag is passed UNCONDITIONALLY (no
 				// fleet downgrade).
 				freshWorktreeGate: config.freshWorktreeGate,
-				// Cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-
+				// Cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-
 				// parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)) — the resolved
 				// per-repo value reaches the merge loop via `performComplete`→
 				// `performIntegration`.
@@ -2039,7 +2097,7 @@ export function buildProgram(): Command {
 		.command('do')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'The per-repo WORKER (the CI command): claim + onboard onto work/<slug>, run the agent, gate, integrate, and exit. In the CURRENT checkout by default (refuses on a dirty tree, integrates in-place). With --remote <r>: against a REGISTERED repo with NO checkout — materialise a hub mirror + job worktree in the agents\u2019 area, run the same pipeline there, then reap. do <slug> | do task:<slug> | do spec:<slug> (the tasking path; the legacy prd:<slug> is still accepted) | do (auto-pick one) | do <a> <b> (those, in sequence) | do -n <x> (x eligible, in sequence). Auto-pick draws TASKS-FIRST then SPECS-to-task by default (per-repo selectionOrder reorders the pools). --propose (default) / --merge resolved at integrate-time. Supersedes ar-run.sh.',
+			"The per-repo WORKER (the CI command): claim + onboard onto work/<slug>, run the agent, gate, integrate, and exit. Builds in an ISOLATED job worktree off THIS repo's arbiter by DEFAULT (task `make-isolated-default-build-mode` — the cwd is the origin SOURCE only; the human working tree is never written). --in-place opts OUT (build in the current checkout, refusing a dirty tree — today's pre-flip behaviour). --isolated remains accepted as a redundant explicit opt-in alias. With --remote <r>: against a REGISTERED repo with NO checkout — materialise a hub mirror + job worktree in the agents\u2019 area, run the same pipeline there, then reap. do <slug> | do task:<slug> | do spec:<slug> (the tasking path) | do (auto-pick one) | do <a> <b> (those, in sequence) | do -n <x> (x eligible, in sequence). Auto-pick draws TASKS-FIRST then SPECS-to-task by default (per-repo selectionOrder reorders the pools). --propose (default) / --merge resolved at integrate-time. Supersedes ar-run.sh.",
 		)
 		// EXTENSIBLE argument grammar (the three do-* tasks grow this one block):
 		// `do-autopick` widens the single optional positional into a VARIADIC one so
@@ -2048,7 +2106,7 @@ export function buildProgram(): Command {
 		// for the auto-pick form. `do` stays SEQUENTIAL (parallelism is `run`).
 		.argument(
 			'[slugs...]',
-			'the item(s) to do: bare (= the task), task:<slug>, or spec:<slug> (task the spec; the legacy prd:<slug> is still accepted). Zero args = auto-pick; multiple = do them in sequence.',
+			'the item(s) to do: bare (= the task), task:<slug>, or spec:<slug> (task the spec). Zero args = auto-pick; multiple = do them in sequence.',
 		)
 		.option('-c, --config <path>', 'config file path', defaultConfigPath())
 		.option(
@@ -2069,7 +2127,11 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--isolated',
-			"build in an ISOLATED job worktree off THIS repo's arbiter (inferred from cwd) instead of taking over the current checkout, then integrate + reap \u2014 the in-place-but-isolated form. Shares the same grammar as the no-checkout forms: a single named item, multiple named items (in sequence), AND -n/auto-pick over the mirror-side eligible-pool scan. Always SEQUENTIAL (parallelism is `run` / the CI matrix). Orthogonal to --remote (a foreign repo); with --remote, remote wins (isolation is already implied).",
+			"build in an ISOLATED job worktree off THIS repo's arbiter (inferred from cwd) instead of taking over the current checkout, then integrate + reap \u2014 NOW THE DEFAULT since `make-isolated-default-build-mode`; the flag remains accepted as a redundant explicit opt-IN alias (some scripts/skills pin it, and it is harmless once implied). Shares the same grammar as the no-checkout forms: a single named item, multiple named items (in sequence), AND -n/auto-pick over the mirror-side eligible-pool scan. Always SEQUENTIAL (parallelism is `run` / the CI matrix). Orthogonal to --remote (a foreign repo); with --remote, remote wins (isolation is already implied). Mutually exclusive with --in-place (contradictory intents).",
+		)
+		.option(
+			'--in-place',
+			"OPT OUT of the new isolated default: build in the CURRENT checkout (integrates in place, refuses a dirty tree) \u2014 today's pre-flip behaviour, now explicit. Mutually exclusive with --isolated (contradictory intents) and with --remote (there is no local checkout to take over). Use this for the edit-locally-then-build loop; the default (isolated off the arbiter) never writes the cwd working tree.",
 		)
 		.option(
 			'--merge',
@@ -2081,7 +2143,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--tasks-land-in <where>',
-			'where `do prd:<slug>` tasking output lands: `pre-backlog` (staged, not agent-eligible) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence (explicit flag > untrusted-origin forces staging > tasksLandIn default > built-in). Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.',
+			'where `do spec:<slug>` tasking output lands: `backlog` (staged, not agent-eligible) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence (explicit flag > untrusted-origin forces staging > tasksLandIn default > built-in). Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.',
 		)
 		.option(
 			'--no-pr',
@@ -2134,15 +2196,15 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--tasker-loop',
-			'run the tasker IMPROVER loop on `do prd:<slug>` (review→edit→converge over the produced task set). ON by default; --no-tasker-loop skips it. DISTINCT from the acceptance gate (--review).',
+			'run the tasker IMPROVER loop on `do spec:<slug>` (review→edit→converge over the produced task set). ON by default; --no-tasker-loop skips it. DISTINCT from the acceptance gate (--review).',
 		)
 		.option(
 			'--no-tasker-loop',
-			'skip the tasker improver loop on `do prd:<slug>`',
+			'skip the tasker improver loop on `do spec:<slug>`',
 		)
 		.option(
 			'--tasker-loop-max <n>',
-			'cap the tasker improver loop on `do prd:<slug>` (in-context review passes); on exhaustion with blockers, reject via needsAnswers / route the prd to needs-attention (default 3)',
+			'cap the tasker improver loop on `do spec:<slug>` (in-context review passes); on exhaustion with blockers, reject via needsAnswers / route the spec to needs-attention (default 3)',
 		)
 		.option(
 			'--tasker-loop-model <id>',
@@ -2220,14 +2282,52 @@ export function buildProgram(): Command {
 			// `remote-do-reads-per-repo-config-from-arbiter-main`). Only the whitelisted
 			// `REPO_ALLOWED_KEYS` are layered (host-only keys stay global/flag/env-only,
 			// rejected by the SAME `repo-config.ts` split).
+			// Mutually-exclusive intent guards for the three FORM flags (task
+			// `make-isolated-default-build-mode`, D3): `--in-place` opts OUT of the new
+			// isolated default, `--isolated` is the redundant explicit opt-IN alias,
+			// `--remote <r>` targets a foreign repo. `--in-place` + `--isolated` is
+			// contradictory (build here vs build off the arbiter); `--in-place` + `--remote`
+			// is nonsensical (there is no local checkout to take over). Reject loudly
+			// rather than silently prefer one.
+			if (flags.inPlace === true && flags.isolated === true) {
+				console.error(
+					'error: --in-place and --isolated are contradictory (build in the current ' +
+						"checkout vs build in a worktree off this repo's arbiter). Pick one.",
+				);
+				process.exit(1);
+			}
+			if (flags.inPlace === true && flags.remote !== undefined) {
+				console.error(
+					'error: --in-place builds in the CURRENT checkout; --remote <r> targets a ' +
+						'REGISTERED repo with NO checkout. Pick one.',
+				);
+				process.exit(1);
+			}
+			// The DEFAULT flip (task `make-isolated-default-build-mode`): with no
+			// `--remote` and no `--in-place`, `do <slug>` builds in an ISOLATED job
+			// worktree off THIS repo's arbiter — the SAME no-checkout path `--isolated`
+			// already used. The cwd is the origin SOURCE only (arbiter-remote resolution
+			// + per-repo config), never written. `--isolated` remains accepted as a
+			// redundant explicit opt-IN alias (D3). `--in-place` opts out to today's
+			// in-checkout path (the fall-through below). See ADR §3.
 			const isolatedNoRemote =
-				flags.isolated === true && flags.remote === undefined;
+				flags.remote === undefined && flags.inPlace !== true;
+			// Whether the user DEFAULTED into isolated (no form flag typed) vs typed
+			// `--isolated` explicitly. Only used to tune the no-arbiter error message so
+			// the default path names `--in-place` as its natural escape (D2).
+			const defaultedToIsolated = isolatedNoRemote && flags.isolated !== true;
 			if (flags.remote !== undefined || isolatedNoRemote) {
 				// The form's user-facing name + canonical usage, for the shared error
-				// messages below (so `--isolated` errors read in its own terms).
-				const form = isolatedNoRemote ? '--isolated' : '--remote';
+				// messages below (so isolated errors read in the form's own terms).
+				const form = isolatedNoRemote
+					? defaultedToIsolated
+						? 'do'
+						: '--isolated'
+					: '--remote';
 				const usage = isolatedNoRemote
-					? '`do --isolated <slug>`'
+					? defaultedToIsolated
+						? '`do <slug>`'
+						: '`do --isolated <slug>`'
 					: '`do --remote <r> <slug>`';
 				// The no-checkout forms now support the SAME variadic grammar the in-place
 				// form does: a single NAMED item, MULTIPLE named items (sequential), and
@@ -2257,12 +2357,33 @@ export function buildProgram(): Command {
 						identityEnv(bootstrapIdentity, process.env),
 					);
 					if (resolvedUrl === undefined) {
-						console.error(
-							`error: --isolated builds in a worktree off this repo's arbiter ` +
-								`('${arbiterName}'), but no such arbiter remote is configured/found ` +
-								`here. Run inside a participating repo (a clone with an arbiter ` +
-								`remote), or use --remote <url> to target another repo.`,
-						);
+						// Isolated needs an arbiter to build off. Two message variants:
+						//   - defaulted-to-isolated (no form flag typed) leads with the DEFAULT
+						//     and names `--in-place` as the natural local escape (D2). This is
+						//     the ERROR-not-silent-degrade behaviour the flip requires: a repo
+						//     with no arbiter must NOT be quietly built in-place invisibly.
+						//   - explicit `--isolated` keeps its own terms (the user asked for
+						//     isolation deliberately) but ALSO surfaces `--in-place` alongside
+						//     `--remote <url>` as the two escapes.
+						if (defaultedToIsolated) {
+							console.error(
+								`error: no arbiter is configured for this repo ` +
+									`(no '${arbiterName}' remote), and \`do\` now defaults to ` +
+									`building in an ISOLATED worktree off THIS repo's arbiter ` +
+									`(task \`make-isolated-default-build-mode\`). Configure an ` +
+									`arbiter (e.g. \`dorfl remote add <url>\`), pass --in-place ` +
+									`to build in the current checkout, or use --remote <url> to ` +
+									`target another repo.`,
+							);
+						} else {
+							console.error(
+								`error: --isolated builds in a worktree off this repo's arbiter ` +
+									`('${arbiterName}'), but no such arbiter remote is configured/found ` +
+									`here. Run inside a participating repo (a clone with an arbiter ` +
+									`remote), pass --in-place to build in the current checkout, or ` +
+									`use --remote <url> to target another repo.`,
+							);
+						}
 						process.exit(1);
 					}
 					effectiveRemote = resolvedUrl;
@@ -2310,7 +2431,7 @@ export function buildProgram(): Command {
 					// Host-only runner IDENTITY — scopes git/provider ops only (not the
 					// agent launch); absent ⇒ ambient.
 					identity: remoteConfig.identity,
-					// `do --remote prd:<slug>` tasking-gate policy (task-build path ignores it).
+					// `do --remote spec:<slug>` tasking-gate policy (task-build path ignores it).
 					autoTask: remoteConfig.autoTask,
 					// The resolved `promptGuidance` nudge — threaded into the remote worker
 					// prompt (runRemotePipeline → buildAgentPrompt), mirroring in-place `do`.
@@ -2318,7 +2439,7 @@ export function buildProgram(): Command {
 					integration: remoteConfig.integration,
 					// EXPLICIT `--merge` override for the untrusted-origin build-propose rule.
 					explicitMerge: flagMode === 'merge',
-					// Per-TRANSITION TASKING override (the `do --remote prd:` tasking path).
+					// Per-TRANSITION TASKING override (the `do --remote spec:` tasking path).
 					taskingIntegration: remoteConfig.taskingIntegration,
 					// TASK-PLACEMENT: the configured default + the EXPLICIT operator override
 					// (`--tasks-land-in`), the top of the placement precedence — mirrors
@@ -2330,7 +2451,7 @@ export function buildProgram(): Command {
 					// Single-job build path: gate the REBASED tip (the default) unconditionally.
 					freshWorktreeGate: remoteConfig.freshWorktreeGate,
 					// Cross-job merge-serialiser CAS-retry cap (resolved through the per-repo
-					// chain on the arbiter-side `.dorfl.json` too) — prd
+					// chain on the arbiter-side `.dorfl.json` too) — spec
 					// `land-time-reverify-and-parallel-merge-ceiling` Story 5.
 					mergeRetries: remoteConfig.mergeRetries,
 					noPR: remoteConfig.noPR,
@@ -2347,7 +2468,7 @@ export function buildProgram(): Command {
 								agentCmd: remoteConfig.agentCmd,
 							})
 						: undefined,
-					// The tasker IMPROVER loop on the `do --remote prd:` path is ON by default
+					// The tasker IMPROVER loop on the `do --remote spec:` path is ON by default
 					// (auto-tasking has no `verify` floor, so the loop is the task path's
 					// quality engine). `--tasker-loop`/`--no-tasker-loop` gates wiring the seam;
 					// `taskerLoopMax`/`taskerLoopModel` resolve per-repo (flag > env > per-repo
@@ -2360,7 +2481,7 @@ export function buildProgram(): Command {
 						: undefined,
 					taskerLoopMax: remoteConfig.taskerLoopMax,
 					taskerLoopModel: remoteConfig.taskerLoopModel,
-					// The task-SET ACCEPTANCE GATE on the `do --remote prd:` path too.
+					// The task-SET ACCEPTANCE GATE on the `do --remote spec:` path too.
 					taskReviewGate: remoteConfig.review
 						? harnessTaskAcceptanceGate({
 								harness: remoteHarness,
@@ -2368,6 +2489,11 @@ export function buildProgram(): Command {
 							})
 						: undefined,
 					watch: flags.watch === true,
+					// The dorfl-internal agent deadline + anti-loop ceiling (spec
+					// `graceful-pre-timeout-wip-checkpoint`). Threaded from the RESOLVED
+					// remote-repo config (its committed `dorfl.json` on <arbiter>/main).
+					agentDeadlineMinutes: remoteConfig.agentDeadlineMinutes,
+					maxAutoCheckpoints: remoteConfig.maxAutoCheckpoints,
 					color: shouldUseColor(process.stdout),
 					note: (message) => console.error(`>> ${message}`),
 					noteBlock: (message) => console.error(message),
@@ -2472,7 +2598,7 @@ export function buildProgram(): Command {
 				// ops (claim, push, integrate, `gh`) — NEVER the agent launch. Absent ⇒
 				// ambient (today's behaviour). Mapped Config → DoOptions like model/agentCmd.
 				identity: config.identity,
-				// `do prd:<slug>` tasking-gate policy (the task-build path ignores it).
+				// `do spec:<slug>` tasking-gate policy (the task-build path ignores it).
 				autoTask: config.autoTask,
 				// The resolved `promptGuidance` NUDGE namespace (e.g. `testFirst`),
 				// threaded into the worker prompt by performDo → buildAgentPrompt so a
@@ -2485,11 +2611,11 @@ export function buildProgram(): Command {
 				// typed `--merge` (`flagMode`), never when `merge` came from config — so an
 				// untrusted-origin task still forces propose under a config `merge`.
 				explicitMerge: flagMode === 'merge',
-				// Per-TRANSITION TASKING override: the `do prd:` tasking path threads
+				// Per-TRANSITION TASKING override: the `do spec:` tasking path threads
 				// `taskingIntegration ?? integration`; the task-build path stays on
 				// `integration`. Unset ⇒ tasking falls back to `integration` (today's behaviour).
 				taskingIntegration: config.taskingIntegration,
-				// TASK-PLACEMENT (`do prd:` tasking output): the configured default rung +
+				// TASK-PLACEMENT (`do spec:` tasking output): the configured default rung +
 				// the EXPLICIT operator override `--tasks-land-in` (top of the precedence).
 				// `explicitTasksLandIn` is set ONLY when the flag was typed (mirrors
 				// `explicitMerge`), so an untrusted-origin staging force still wins under a
@@ -2502,7 +2628,7 @@ export function buildProgram(): Command {
 				verify: config.verify,
 				// Single-job build path: gate the REBASED tip (the default) unconditionally.
 				freshWorktreeGate: config.freshWorktreeGate,
-				// Cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-
+				// Cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-
 				// parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)) — resolved per-repo
 				// and threaded to `performComplete`→`performIntegration`.
 				mergeRetries: config.mergeRetries,
@@ -2526,7 +2652,7 @@ export function buildProgram(): Command {
 				reviewGate: config.review
 					? harnessReviewGate({harness, agentCmd: config.agentCmd})
 					: undefined,
-				// The tasker IMPROVER loop on the `do prd:` tasking path is ON by default
+				// The tasker IMPROVER loop on the `do spec:` tasking path is ON by default
 				// (auto-tasking has no `verify` floor — the loop is the task path's quality
 				// engine). `--tasker-loop`/`--no-tasker-loop` gates wiring the seam;
 				// `taskerLoopMax`/`taskerLoopModel` resolve per-repo (flag > env > per-repo
@@ -2549,12 +2675,17 @@ export function buildProgram(): Command {
 				// `--watch`: tail the pi session log live (pi harness only; the
 				// performDo guard errors clearly on any other adapter). READ-ONLY.
 				watch: flags.watch === true,
+				// The dorfl-internal agent deadline + anti-loop ceiling (spec
+				// `graceful-pre-timeout-wip-checkpoint`). Threaded from the resolved
+				// per-repo config so an edit to dorfl.json reflects on the NEXT tick.
+				agentDeadlineMinutes: config.agentDeadlineMinutes,
+				maxAutoCheckpoints: config.maxAutoCheckpoints,
 				color: shouldUseColor(process.stdout),
 				note: (message) => console.error(`>> ${message}`),
 				noteBlock: (message) => console.error(message),
 			};
 
-			// `--allow-backlog` is EXPLICIT-SINGLE-TASK-ONLY (prd
+			// `--allow-backlog` is EXPLICIT-SINGLE-TASK-ONLY (spec
 			// `do-allow-backlog-drive-staged-tasks-without-promotion`, decision 4): it
 			// drives ONE named staged task in place. It must NOT combine with the
 			// AUTO-PICK (zero-args / -n) or MULTI-ITEM forms — those select FROM the
@@ -2615,11 +2746,11 @@ export function buildProgram(): Command {
 		});
 
 	// `advance` — the SIBLING top-level verb (NOT a `do` subcommand; `do`
-	// subcommands + a standalone `task` verb are REJECTED in prd `advance-loop`).
+	// subcommands + a standalone `task` verb are REJECTED in spec `advance-loop`).
 	// It reuses the SAME shared `prefix:arg` resolver `do` uses, EXTENDED with the
 	// `obs:` namespace, and wires the classify → lock → execute SKELETON: classify
 	// the rung (read-only, no model, no lock), take the `advancing` CAS borrow, then
-	// dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do prd:` (never a
+	// dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do spec:` (never a
 	// duplicate), surface/apply/triage dispatch to a named executor seam later
 	// tasks fill. The DRIVERS (one-shot/loop) + `-n` + per-action gates and the
 	// rung BODIES are LATER tasks; the bare eligible-SET form errors clearly here.
@@ -2627,11 +2758,11 @@ export function buildProgram(): Command {
 		.command('advance')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'Advance work/ item(s) one lifecycle rung toward ready/built (PRD advance-loop), the SEQUENTIAL one-shot driver over the advance tick. advance <slug> (bare = the task) | advance spec:<slug> (the spec tasking rung; the legacy prd:<slug> is still accepted) | advance obs:<slug> (triage an observation) | advance (auto-pick one eligible) | advance <a> <b> (those, in sequence) | advance -n <x> (x eligible, in sequence). Each item: classify (read-only, no model, no lock) → take the `advancing` CAS lock → dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do spec:`, surface/apply always run, triage respects observationTriage (off|ask|auto). The bare/`-n` selection respects the per-action gates (build→autoBuild, task→autoTask, triage→observationTriage); `-n` is ALWAYS sequential (parallelism is `run` / the CI matrix).',
+			'Advance work/ item(s) one lifecycle rung toward ready/built (SPEC advance-loop), the SEQUENTIAL one-shot driver over the advance tick. advance <slug> (bare = the task) | advance spec:<slug> (the spec tasking rung) | advance obs:<slug> (triage an observation) | advance (auto-pick one eligible) | advance <a> <b> (those, in sequence) | advance -n <x> (x eligible, in sequence). Each item: classify (read-only, no model, no lock) → take the `advancing` CAS lock → dispatch winner-only — build/task rungs ORCHESTRATE `do`/`do spec:`, surface/apply always run, triage respects observationTriage (off|ask|auto). The bare/`-n` selection respects the per-action gates (build→autoBuild, task→autoTask, triage→observationTriage); `-n` is ALWAYS sequential (parallelism is `run` / the CI matrix).',
 		)
 		.argument(
 			'[slugs...]',
-			'the item(s) to advance: bare (= the task), task:<slug>, spec:<slug> (the legacy prd:<slug> is still accepted), or obs:<slug> (an observation). Zero args = auto-pick one eligible; multiple = advance them in sequence.',
+			'the item(s) to advance: bare (= the task), task:<slug>, spec:<slug>, or obs:<slug> (an observation). Zero args = auto-pick one eligible; multiple = advance them in sequence.',
 		)
 		.option('-c, --config <path>', 'config file path', defaultConfigPath())
 		.option(
@@ -2656,15 +2787,15 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--surface-blockers',
-			'the declared-blocked-work gate (the orthogonal peer of --observation-triage): render a task/prd carrying needsAnswers:true into an answerable question sidecar (the needsAnswers-blocked pool is enumerated into auto-pick). Resolved flag > env > per-repo > global > default off. An explicit `advance <slug>`/`advance prd:<slug>` bypasses this selection gate and surfaces regardless. Does NOT gate apply (an answered sidecar still applies) or needs-attention (always on).',
+			'the declared-blocked-work gate (the orthogonal peer of --observation-triage): render a task/spec carrying needsAnswers:true into an answerable question sidecar (the needsAnswers-blocked pool is enumerated into auto-pick). Resolved flag > env > per-repo > global > default off. An explicit `advance <slug>`/`advance spec:<slug>` bypasses this selection gate and surfaces regardless. Does NOT gate apply (an answered sidecar still applies) or needs-attention (always on).',
 		)
 		.option(
 			'--no-surface-blockers',
-			'leave a needsAnswers:true task/prd silently blocked (default; the blocked pool is dropped from auto-pick)',
+			'leave a needsAnswers:true task/spec silently blocked (default; the blocked pool is dropped from auto-pick)',
 		)
 		.option(
 			'--strict-merge-approval',
-			'opt in to the host-agnostic "dismiss stale approvals on base change" discipline (prd `land-time-reverify-and-parallel-merge-ceiling` sidecar OQ6): when the merge-base CHANGED between the human’s merge-answer and the apply step, RE-SURFACE the merge-question (clear the answer back to no-answer; re-author the question on main/runner under the advancing lock) instead of auto-landing on a green re-verify. Default OFF (a green re-verify is trusted as sufficient; honour the prior answer). Story #16’s RED-re-verify refusal is UNCHANGED and independent of this flag. Resolved flag > env > per-repo > global > default off.',
+			'opt in to the host-agnostic "dismiss stale approvals on base change" discipline (spec `land-time-reverify-and-parallel-merge-ceiling` sidecar OQ6): when the merge-base CHANGED between the human’s merge-answer and the apply step, RE-SURFACE the merge-question (clear the answer back to no-answer; re-author the question on main/runner under the advancing lock) instead of auto-landing on a green re-verify. Default OFF (a green re-verify is trusted as sufficient; honour the prior answer). Story #16’s RED-re-verify refusal is UNCHANGED and independent of this flag. Resolved flag > env > per-repo > global > default off.',
 		)
 		.option(
 			'--no-strict-merge-approval',
@@ -2684,7 +2815,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--tasks-land-in <where>',
-			'where `advance prd:<slug>` tasking output lands: `pre-backlog` (staged) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence. Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.',
+			'where `advance spec:<slug>` tasking output lands: `backlog` (staged) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence. Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.',
 		)
 		.option(
 			'--watch',
@@ -2820,7 +2951,7 @@ export function buildProgram(): Command {
 					integration: remoteConfig.integration,
 					// EXPLICIT `--merge` override for the untrusted-origin build-propose rule.
 					explicitMerge: flagMode === 'merge',
-					// Per-TRANSITION TASKING override (the isolated `do --remote prd:` path).
+					// Per-TRANSITION TASKING override (the isolated `do --remote spec:` path).
 					taskingIntegration: remoteConfig.taskingIntegration,
 					// TASK-PLACEMENT: configured default + EXPLICIT `--tasks-land-in` override
 					// (set only when typed, mirroring `explicitMerge`).
@@ -2830,7 +2961,7 @@ export function buildProgram(): Command {
 					verify: remoteConfig.verify,
 					// Single-job build path: gate the REBASED tip (the default) unconditionally.
 					freshWorktreeGate: remoteConfig.freshWorktreeGate,
-					// Cross-job merge-serialiser CAS-retry cap — prd
+					// Cross-job merge-serialiser CAS-retry cap — spec
 					// `land-time-reverify-and-parallel-merge-ceiling` Story 5.
 					mergeRetries: remoteConfig.mergeRetries,
 					noPR: remoteConfig.noPR,
@@ -2962,7 +3093,7 @@ export function buildProgram(): Command {
 				// EXPLICIT `--merge` override for the untrusted-origin build-propose rule (a
 				// bare `advance` auto-pick passes no flag ⇒ unset ⇒ untrusted forces propose).
 				explicitMerge: flagMode === 'merge',
-				// Per-TRANSITION TASKING override (the `do prd:` tasking path threads
+				// Per-TRANSITION TASKING override (the `do spec:` tasking path threads
 				// `taskingIntegration ?? integration`; the build path stays on `integration`).
 				taskingIntegration: config.taskingIntegration,
 				// TASK-PLACEMENT: configured default + EXPLICIT `--tasks-land-in` override
@@ -2973,7 +3104,7 @@ export function buildProgram(): Command {
 				verify: config.verify,
 				// Single-job build path: gate the REBASED tip (the default) unconditionally.
 				freshWorktreeGate: config.freshWorktreeGate,
-				// Cross-job merge-serialiser CAS-retry cap (prd `land-time-reverify-and-
+				// Cross-job merge-serialiser CAS-retry cap (spec `land-time-reverify-and-
 				// parallel-merge-ceiling` Story 5 / Applied Answer q1 (a)).
 				mergeRetries: config.mergeRetries,
 				noPR: config.noPR,
@@ -2995,6 +3126,10 @@ export function buildProgram(): Command {
 				taskReviewGate: config.review
 					? harnessTaskAcceptanceGate({harness, agentCmd: config.agentCmd})
 					: undefined,
+				// The dorfl-internal agent deadline + anti-loop ceiling (spec
+				// `graceful-pre-timeout-wip-checkpoint`). Threaded from resolved config.
+				agentDeadlineMinutes: config.agentDeadlineMinutes,
+				maxAutoCheckpoints: config.maxAutoCheckpoints,
 				color: shouldUseColor(process.stdout),
 				note: (message) => console.error(`>> ${message}`),
 				noteBlock: (message) => console.error(message),
@@ -3114,7 +3249,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--reap-stale-locks',
-			'(with --ledger) OPT-IN: also CLEAR every STALE terminal lock the report finds (a held `active` per-item lock whose item is already TERMINAL on <arbiter>/main — the `cleared-stale` class) via the SAME leased delete `release-lock` uses, so one command sweeps all orphaned terminal locks instead of N hand-run release-locks. SCOPED to `cleared-stale` ONLY: a `kept-stuck` (terminal + stuck) or a `kept-in-flight` (active, non-terminal) lock is NEVER reaped, even with this flag. A concurrent change to a lock ref makes its leased delete REJECT (reported), never --force. WITHOUT this flag `gc --ledger` stays report-only (fail-loud, deletes nothing).',
+			'(with --ledger) OPT-IN: also CLEAR every ORPHAN lock the report finds via the SAME leased delete `release-lock` uses, so one command sweeps all orphaned locks instead of N hand-run release-locks. Reaps the `cleared-stale` class: a held `active` lock that is EITHER terminal on `<arbiter>/main` (stranded between the durable move and the release) OR non-terminal + SURFACED (`needsAnswers:true` + sidecar on `<arbiter>/main`) = the crash-window orphan the ordered bounce transition leaves when step 1 lands but step 2 never runs. A `kept-in-flight` (active + non-terminal + NOT surfaced — a healthy build) is NEVER reaped, even with this flag. A concurrent change to a lock ref makes its leased delete REJECT (reported), never --force. WITHOUT this flag `gc --ledger` stays report-only (fail-loud, deletes nothing).',
 		)
 		.option(
 			'--remote-branches',
@@ -3137,7 +3272,7 @@ export function buildProgram(): Command {
 			const config = resolveGlobalConfig(loadConfig(flags.config), {});
 			const workspacesDir = flags.workspace ?? config.workspacesDir;
 
-			// The `gc`-STYLE ledger SWEEP (prd `ledger-integrity` story 3): a SEPARATE
+			// The `gc`-STYLE ledger SWEEP (spec `ledger-integrity` story 3): a SEPARATE
 			// surface from the worktree reaper below — it REPORTS one-slug-one-folder
 			// violations in a repo's `work/` lifecycle ledger and NEVER deletes (a human
 			// resolves each). Distinct `work/`: the ledger, not the execution substrate.
@@ -3146,7 +3281,7 @@ export function buildProgram(): Command {
 					typeof flags.ledger === 'string' ? flags.ledger : process.cwd();
 				const result = sweepLedgerDuplicates(repoPath);
 				// The UNIFIED-LOCK stuck/orphaned-lock REPORT (task
-				// `release-lock-verb-and-gc-stuck-report`, prd
+				// `release-lock-verb-and-gc-stuck-report`, spec
 				// `ledger-status-per-item-lock-refs` US #12/#13/#14): generalises the
 				// advancing-marker report from advancing-only to the unified per-item
 				// lock. The locks live on the ARBITER ref (`refs/dorfl/lock/*`),
@@ -3159,13 +3294,16 @@ export function buildProgram(): Command {
 				// clearing (no auto-sweep; a human asserts a lock is dead via
 				// `release-lock`).
 				// OPT-IN SWEEP (`--reap-stale-locks`): the WRITE twin of the report. A
-				// human asserting "clear the dead TERMINAL locks now": for EXACTLY the
-				// `cleared-stale` class (terminal-on-main + active = stranded) perform the
-				// SAME leased delete `release-lock` / the recovery use, so one command
-				// sweeps every orphaned terminal lock. A `kept-stuck` / `kept-in-flight`
-				// lock is NEVER reaped (scope fence); a concurrent change makes a clear
-				// REJECT (reported `lost`), never --force. WITHOUT the flag the surface
-				// below stays report-only (fail-loud, deletes nothing).
+				// human asserting "clear the dead TERMINAL locks now": for BOTH
+				// terminal-on-main orphan classes (task `reaper-reap-terminal-stuck-lock-orphans`;
+				// ADR `ledger-status-on-per-item-lock-refs` § Addendum 2026-07-10) — the
+				// stranded `cleared-stale` AND the stuck-terminal `cleared-stuck-terminal`
+				// crash-orphan — perform the SAME leased delete `release-lock` / the
+				// recovery use, so one command sweeps every orphaned terminal lock. A
+				// `kept-stuck` (STUCK + NON-terminal) / `kept-in-flight` lock is NEVER
+				// reaped (scope fence); a concurrent change makes a clear REJECT (reported
+				// `lost`), never --force. WITHOUT the flag the surface below stays
+				// report-only (fail-loud, deletes nothing).
 				if (flags.reapStaleLocks) {
 					const reap = await reapStaleItemLocks(
 						flags.cwd ?? repoPath,
@@ -3189,10 +3327,11 @@ export function buildProgram(): Command {
 								: formatLedgerSweep(result),
 						);
 					}
-					// Fail-loud AFTER the sweep: a `kept-stuck` (rightly left for a human) or
-					// a `lost`/`error` (a stale lock whose leased delete lost the race) still
-					// needs attention; a clean sweep that reaped every stale lock and left
-					// only healthy in-flight holds exits 0.
+					// Fail-loud AFTER the sweep: a `kept-stuck` (STUCK + non-terminal —
+					// rightly left for a human) or a `lost`/`error` (an orphan lock whose
+					// leased delete lost the race) still needs attention; a clean sweep
+					// that reaped every orphan lock (stale OR stuck-terminal) and left only
+					// healthy in-flight holds exits 0.
 					process.exit(
 						result.duplicates.length > 0 || reapReportNeedsAttention(reap)
 							? 1
@@ -3231,14 +3370,16 @@ export function buildProgram(): Command {
 				// ALL are REPORTED here (never auto-deleted — no automatic sweep exists; a
 				// human clears a NAMED unified lock via `release-lock`).
 				//
-				// SCOPED to the ATTENTION verdicts only (prd US#14/#21, ADR
-				// `ledger-status-on-per-item-lock-refs`: this surface is the STUCK /
-				// crash-orphaned lock, NOT every held one): a `kept-stuck` (terminal +
-				// stuck) or a `cleared-stale`-eligible (terminal + stale active = orphaned)
-				// lock fails loud, but a `kept-in-flight` (active, non-terminal) lock is the
-				// NORMAL in-flight state of a healthy concurrent build (read by `status` as
-				// healthy) — it is reported informationally and does NOT make a routine
-				// `gc --ledger` health check exit non-zero.
+				// SCOPED to the ATTENTION verdicts only (spec US#14/#21, ADR
+				// `ledger-status-on-per-item-lock-refs` § Addendum 2026-07-10: this surface
+				// is the STUCK / crash-orphaned lock, NOT every held one): a `kept-stuck`
+				// (STUCK + NON-terminal — the genuine human-attention case), a
+				// `cleared-stale`-eligible (terminal + stale active = stranded orphan), or
+				// a `cleared-stuck-terminal`-eligible (terminal + stuck = crash-orphan the
+				// reaper can now auto-clear) fails loud, but a `kept-in-flight` (active,
+				// non-terminal) lock is the NORMAL in-flight state of a healthy concurrent
+				// build (read by `status` as healthy) — it is reported informationally
+				// and does NOT make a routine `gc --ledger` health check exit non-zero.
 				process.exit(
 					result.duplicates.length > 0 ||
 						itemLockReportNeedsAttention(lockReport)
@@ -3261,7 +3402,7 @@ export function buildProgram(): Command {
 					dryRun: flags.dryRun === true,
 					note: (message) => console.error(`>> ${message}`),
 				});
-				// The ORPHAN-SIDECAR sweep (prd
+				// The ORPHAN-SIDECAR sweep (spec
 				// `agentic-question-resolution-retire-disposition-vocabulary`, US #10) rides
 				// the SAME `--remote-branches` invocation the SCHEDULED CI lifecycle workflow
 				// runs (`dorfl gc --remote-branches --arbiter origin`) — so the reap of a
@@ -3385,7 +3526,7 @@ export function buildProgram(): Command {
 			}
 
 			// Exit non-zero on a REFUSAL (quiescence gate) or a non-green leak scan
-			// (a converted tree that still carries a dangling `prd` ref). A clean
+			// (a converted tree that still carries a dangling ''prd'' ref). A clean
 			// dry-run or a green migration exits 0.
 			if (result.refused || result.leaks.length > 0) {
 				process.exit(1);
@@ -3497,7 +3638,7 @@ export function buildProgram(): Command {
 		.command('requeue <slug>')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'Requeue a STUCK task to the backlog for re-claiming (ADR §12/§14). Recovers a task whose per-item lock is held — stuck (the resolved-recovery path: a previously-routed needs-attention item, now lock `state: stuck`) OR active (a claim that never surfaced — an un-surfaced abort, a killed run, or an in-place requeue note). The body rests in work/tasks/backlog/<slug>.md (claim never moves it under the per-item-lock model); requeue releases the lock so the item is claimable again. The release is published as a TREE-LESS compare-and-swap to the arbiter ref, EXACTLY like claim — it NEVER stages or commits in the cwd working tree, so a requeue in a shared checkout can never sweep up a concurrent writer’s uncommitted files. DEFAULT = keep + continue: leave the work/<slug> branch UNTOUCHED so the next claim CONTINUES from its tip (rebased onto fresh main at onboard-time). --reset = discard + fresh: delete the remote work/<slug> branch FIRST (then release the lock) so the next claim starts fresh (guarded; never the default). -m/--message appends a dated handoff note to the item body (both modes; append-only).',
+			'Requeue a STUCK task to the backlog for re-claiming (ADR §12/§14). Recovers a task whose per-item lock is held — stuck (the resolved-recovery path: a previously-routed needs-attention item, now lock `state: stuck`) OR active (a claim that never surfaced — an un-surfaced abort, a killed run, or an in-place requeue note). The body rests in work/tasks/backlog/<slug>.md (claim never moves it under the per-item-lock model); requeue releases the lock so the item is claimable again. The release is published as a TREE-LESS compare-and-swap to the arbiter ref, EXACTLY like claim — it NEVER stages or commits in the cwd working tree, so a requeue in a shared checkout can never sweep up a concurrent writer’s uncommitted files. Escalation ladder (least to most destructive): (1) DEFAULT = keep + continue: leave the work/<slug> branch UNTOUCHED so the next claim CONTINUES from its tip (rebased onto fresh main at onboard-time); if the work/<slug> branch is not on the arbiter (never pushed, or a prior --reset already deleted it), default requeue succeeds anyway with a fresh-claim note. (2) --reconcile (alias --rebase) = NON-DESTRUCTIVE recovery: re-sync the mirror to the arbiter (prune-fetch) and RETRY the rebase of the kept branch onto latest arbiter/main in a scratch worktree; on a clean rebase, push the reconciled tip back (--force-with-lease, work branch only) and release the lock; on a genuine content conflict AFTER the clean re-sync, leave the item stuck and the branch UNTOUCHED (nothing deleted) so the human can retry when the churn settles. NEVER deletes the remote branch. (3) --reset = DESTRUCTIVE last resort: delete the remote work/<slug> branch FIRST (then release the lock) so the next claim starts fresh (guarded; never the default). -m/--message appends a dated handoff note to the item body (all modes; append-only).',
 		)
 		.option('-c, --config <path>', 'config file path', defaultConfigPath())
 		.option(
@@ -3508,16 +3649,21 @@ export function buildProgram(): Command {
 			'--arbiter <remote>',
 			'the arbiter git remote the tree-less move is CAS-published to (default: origin). --cwd resolves this remote; the move is never written to the cwd tree.',
 		)
+		.option(
+			'--reconcile',
+			'NON-DESTRUCTIVE recovery (middle rung, between the default keep+continue and the destructive --reset): re-sync the mirror to the arbiter (prune-fetch) and RETRY the rebase of the kept work/<slug> onto latest arbiter/main in a scratch worktree; on success, push the reconciled tip back with --force-with-lease and release the lock; on a genuine content conflict after the clean re-sync, leave the item stuck and the branch UNTOUCHED (nothing deleted). NEVER deletes the remote branch. Incompatible with --reset.',
+		)
+		.option('--rebase', 'alias of --reconcile (canonical name)')
 		.option(
 			'--reset',
-			'DISCARD the kept work: delete the remote work/<slug> branch FIRST, then move to backlog so the next claim starts FRESH (guarded; a deliberate departure from the never-delete-the-remote-branch invariant). Never the default.',
+			'DESTRUCTIVE last resort: DISCARD the kept work by deleting the remote work/<slug> branch FIRST, then move to backlog so the next claim starts FRESH (guarded; a deliberate departure from the never-delete-the-remote-branch invariant). Never the default; try --reconcile first.',
 		)
 		.option(
 			'-m, --message <note>',
 			'append a dated handoff note to the item body for the next agent (append-only; applies to both default and --reset)',
 		)
 		.action(async (rawSlug: string, flags: RequeueFlags) => {
-			// Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+			// Task-only command (§3a): accept bare + `task:`, reject `spec:`.
 			const slug = resolveTaskOnlySlug(rawSlug) as string;
 			const cwd = flags.cwd ?? process.cwd();
 			// Route the requeue (default keep+continue / --reset discard / -m handoff)
@@ -3532,6 +3678,14 @@ export function buildProgram(): Command {
 			// call site, rather than relying on the seam's silent `?? process.env`
 			// default by omission (the implicit fallback that made `requeue`'s human
 			// attribution accidental rather than declared).
+			const reconcile = flags.reconcile === true || flags.rebase === true;
+			if (reconcile && flags.reset) {
+				console.error(
+					'error: --reconcile and --reset are mutually exclusive ' +
+						'(non-destructive recovery vs destructive last resort). Pick one.',
+				);
+				process.exit(1);
+			}
 			const result = await ledgerWrite.applyReturnToBacklogTransition({
 				cwd,
 				slug,
@@ -3540,6 +3694,7 @@ export function buildProgram(): Command {
 				// `--cwd` is purely the ORIGIN SOURCE the remote is resolved from.
 				arbiter: flags.arbiter ?? 'origin',
 				reset: flags.reset,
+				reconcile,
 				message: flags.message,
 				env: process.env,
 				note: (message) => console.error(`>> ${message}`),
@@ -3550,16 +3705,18 @@ export function buildProgram(): Command {
 			}
 			const how = result.deletedRemoteBranch
 				? ` (--reset: deleted the remote ${workBranchRef('task', slug)} branch; next claim starts fresh)`
-				: ' (kept the work branch; next claim continues from its tip)';
+				: result.reconciled
+					? ` (--reconcile: re-synced mirror + rebased ${workBranchRef('task', slug)} onto latest main and pushed the reconciled tip back; next claim continues from it)`
+					: ' (kept the work branch; next claim continues from its tip)';
 			console.log(`Requeued '${slug}' to backlog for re-claiming.${how}`);
 		});
 
-	// `promote [item]` (prd `staging-pool-position-gate-and-trust-model`, tasks
+	// `promote [item]` (spec `staging-pool-position-gate-and-trust-model`, tasks
 	// `pre-backlog-staging-folder-and-promote-step-a` /
 	// `pre-prd-staging-pool-split-and-untrusted-prd-placement`): the HUMAN/runner-
 	// owned verb that moves a STAGED item into its agent-eligible POOL — a task
-	// `work/pre-backlog/<slug>.md → work/backlog/<slug>.md`, a prd
-	// `work/prds/proposed/<slug>.md → work/prds/ready/<slug>.md` — as a tree-less CAS on the
+	// `work/tasks/backlog/<slug>.md → work/tasks/ready/<slug>.md`, a spec
+	// `work/specs/proposed/<slug>.md → work/specs/ready/<slug>.md` — as a tree-less CAS on the
 	// arbiter, the SAME trust model + mechanism as `requeue`. The agent emits STAGED;
 	// only this verb (a human, or the runner) admits it to the pool. With NO argument
 	// it LISTS what is promotable (the "what is staged waiting for me?" discovery), so
@@ -3568,7 +3725,7 @@ export function buildProgram(): Command {
 		.command('promote [item]')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'Admit a STAGED item into its agent-eligible POOL (the runner/human side of the staging gate): a task `work/pre-backlog/<slug>.md → work/backlog/<slug>.md`, a prd `work/prds/proposed/<slug>.md → work/prds/ready/<slug>.md`, published as a TREE-LESS compare-and-swap to the arbiter ref (EXACTLY like requeue/claim — it never stages/commits in the cwd tree). The agent only ever CREATES staged; this verb is the gate a human (or the runner) opens. Accepts `task:<slug>` / `prd:<slug>` / a bare `<slug>` (= task). With NO argument, LISTS every promotable item (the tasks in pre-backlog/ + the prds in prds/proposed/ on the arbiter) so you can see what is staged waiting for promotion. Idempotent: promoting an already-pooled slug is a clean no-op success.',
+			`Admit a STAGED item into its agent-eligible POOL (the runner/human side of the staging gate): a task \`${workFolderPrefix('tasks-backlog')}<slug>.md → ${workFolderPrefix('tasks-ready')}<slug>.md\`, a spec \`${workFolderPrefix('specs-proposed')}<slug>.md → ${workFolderPrefix('specs-ready')}<slug>.md\`, published as a TREE-LESS compare-and-swap to the arbiter ref (EXACTLY like requeue/claim — it never stages/commits in the cwd tree). The agent only ever CREATES staged; this verb is the gate a human (or the runner) opens. Accepts \`task:<slug>\` / \`spec:<slug>\` / a bare \`<slug>\` (= task). With NO argument, LISTS every promotable item (the tasks in ${workFolderPrefix('tasks-backlog')} + the specs in ${workFolderPrefix('specs-proposed')} on the arbiter) so you can see what is staged waiting for promotion. Idempotent: promoting an already-pooled slug is a clean no-op success.`,
 		)
 		.option('-c, --config <path>', 'config file path', defaultConfigPath())
 		.option(
@@ -3596,7 +3753,7 @@ export function buildProgram(): Command {
 				}
 				if (listed.items.length === 0) {
 					console.log(
-						`Nothing staged to promote on ${arbiter}/main (work/pre-backlog/ and work/prds/proposed/ are empty).`,
+						`Nothing staged to promote on ${arbiter}/main (${workFolderPrefix('tasks-backlog')} and ${workFolderPrefix('specs-proposed')} are empty).`,
 					);
 					return;
 				}
@@ -3607,11 +3764,10 @@ export function buildProgram(): Command {
 				return;
 			}
 
-			// AN ITEM → promote it. `task:`/`spec:` are explicit (the legacy `prd:`
-			// prefix is still ACCEPTED as an input alias through the cutover — the
-			// contract task drops it); a bare slug defaults to a task (mirrors
-			// `requeue`). An `obs:`/`observation:` prefix is rejected (observations have
-			// no pool).
+			// AN ITEM → promote it. `task:`/`spec:` are explicit; a bare slug defaults to
+			// a task (mirrors `requeue`). An `obs:`/`observation:` prefix is rejected
+			// (observations have no pool). A legacy ''prd:'' prefix is a DEAD namespace token
+			// after the hard cutover — it resolves as a bare literal task slug, not a spec.
 			const parsed = parseSlugArg(rawItem);
 			if (parsed.explicit === 'observation') {
 				console.error(
@@ -3648,7 +3804,7 @@ export function buildProgram(): Command {
 	// `action: advance` on the UNIFIED per-item lock, so `release-lock <item>` (below)
 	// is the SOLE named human release for ALL holds (implement/task/advance).
 
-	// `release-lock <item>` (task `release-lock-verb-and-gc-stuck-report`, prd
+	// `release-lock <item>` (task `release-lock-verb-and-gc-stuck-report`, spec
 	// `ledger-status-per-item-lock-refs` US #14): the HUMAN-invoked named release of
 	// a stuck/orphaned UNIFIED per-item lock (`refs/dorfl/lock/<entry>`) —
 	// the GENERALISATION of `release-advancing` from the advancing-only marker to
@@ -3661,13 +3817,29 @@ export function buildProgram(): Command {
 	// Idempotent: deleting an absent ref is a clean exit-0 "nothing to clear"
 	// (`not-held`), NOT a failure — deleting the lock ref(s) is "all locks released"
 	// and recoverable (the work is safe on the `work/<slug>` branches + `main`).
+	//
+	// ESCAPE HATCH (`--entry <literal>`, task
+	// `release-lock-entry-escape-hatch-and-literal-entry-reporting`): the item
+	// positional is OPTIONAL because a lock whose entry name is NOT derivable from
+	// any current item-form (a PRE-CUTOVER `slice-<slug>` / `prd-<slug>` entry minted
+	// before the slice→task / `prd-to-spec` vocabulary cutover) is UN-NAMEABLE through
+	// the item-form path. `--entry` takes the literal `<entry>` VERBATIM (bypassing
+	// the namespace mapping) so a human can still NAME + clear such an orphan without
+	// the raw `git push origin --delete refs/dorfl/lock/…` plumbing. It reuses the
+	// SAME leased-delete path (`releaseLiteralLockEntry` → the shared entry-keyed
+	// core), so the trust model is unchanged: the human still asserts liveness.
+	// EXACTLY ONE of {item positional, --entry} must be given.
 	program
-		.command('release-lock <item>')
+		.command('release-lock [item]')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'Clear a NAMED stuck/orphaned UNIFIED per-item lock (refs/dorfl/lock/<entry>) by DELETING the ref on the arbiter — the recovery verb for a lock the system orphaned (a crashed build/task/advance that left the hold behind). The generalisation of `release-advancing` from the advancing marker to the ONE lock per item. Same trust model as `requeue`: a HUMAN asserts the lock is dead by NAMING it; the tool never guesses liveness (the lock has NO heartbeat, so there is NO automatic sweep / age-based reaper anywhere). Accepts the same item forms as the lock API: `task:<slug>` / `prd:<slug>` / `obs:<slug>` / a bare `<slug>` (= task). Idempotent — re-running on an already-cleared lock is a clean exit-0 no-op (deleting the lock ref is “all locks released”, recoverable). NEVER `--force`. Discoverable via `gc --ledger` (it REPORTS every lingering lock, never deletes).',
+			'Clear a NAMED stuck/orphaned UNIFIED per-item lock (refs/dorfl/lock/<entry>) by DELETING the ref on the arbiter — the recovery verb for a lock the system orphaned (a crashed build/task/advance that left the hold behind). The generalisation of `release-advancing` from the advancing marker to the ONE lock per item. Same trust model as `requeue`: a HUMAN asserts the lock is dead by NAMING it; the tool never guesses liveness (the lock has NO heartbeat, so there is NO automatic sweep / age-based reaper anywhere). Accepts the same item forms as the lock API: `task:<slug>` / `spec:<slug>` / `obs:<slug>` / a bare `<slug>` (= task). ESCAPE HATCH: `--entry <literal>` (no item positional) targets a LITERAL entry name directly, bypassing the namespace mapping — for a lock whose entry name is not derivable from any current item-form (a pre-vocabulary-cutover `slice-<slug>` / `prd-<slug>` prefix, or a future rename); this is the supported way to clear such orphans, so the raw `git push origin --delete refs/dorfl/lock/…` plumbing is no longer required. Idempotent — re-running on an already-cleared lock is a clean exit-0 no-op (deleting the lock ref is “all locks released”, recoverable). NEVER `--force`. Discoverable via `gc --ledger` (it REPORTS every lingering lock and, for a pre-cutover entry, the exact `release-lock --entry <literal>` invocation).',
 		)
 		.option('-c, --config <path>', 'config file path', defaultConfigPath())
+		.option(
+			'--entry <literal>',
+			'ESCAPE HATCH: the LITERAL lock-entry name (`refs/dorfl/lock/<literal>`) to release VERBATIM, bypassing the namespace mapping — for a lock whose entry name is not derivable from any current item-form (a pre-cutover `slice-<slug>` / `prd-<slug>` entry). Mutually exclusive with the item positional (give EXACTLY one). Validated to `[A-Za-z0-9._-]+` (no slashes/whitespace) so it cannot escape the lock namespace.',
+		)
 		.option(
 			'--cwd <dir>',
 			'the repo/working clone whose arbiter remote the lock ref is DELETED on (default: cwd)',
@@ -3676,26 +3848,54 @@ export function buildProgram(): Command {
 			'--arbiter <remote>',
 			'the arbiter git remote the lock ref is deleted on (default: origin)',
 		)
-		.action(async (item: string, flags: ReleaseLockFlags) => {
+		.action(async (item: string | undefined, flags: ReleaseLockFlags) => {
 			const cwd = flags.cwd ?? process.cwd();
 			const arbiter = flags.arbiter ?? 'origin';
-			const result = await releaseItemLock({
-				item,
-				cwd,
-				arbiter,
-				env: process.env,
-			});
+			// MUTUAL EXCLUSION: exactly one of {item positional, --entry}. BOTH or
+			// NEITHER is a usage error (non-zero exit, actionable message) — the
+			// item-form and the literal escape hatch are two ways to name ONE lock, not
+			// combinable.
+			if (item !== undefined && flags.entry !== undefined) {
+				console.error(
+					'error: give EITHER an item (task:<slug> / spec:<slug> / obs:<slug> / <slug>) OR --entry <literal>, not both.',
+				);
+				process.exit(1);
+			}
+			if (item === undefined && flags.entry === undefined) {
+				console.error(
+					'error: name the lock to release — an item (task:<slug> / spec:<slug> / obs:<slug> / <slug>) OR --entry <literal> for a pre-cutover entry with no current item-form.',
+				);
+				process.exit(1);
+			}
+			// The LITERAL escape-hatch path (`--entry`): take the entry name verbatim,
+			// bypassing the namespace mapping, and reuse the SAME leased-delete core.
+			const result =
+				flags.entry !== undefined
+					? await releaseLiteralLockEntry({
+							entry: flags.entry,
+							cwd,
+							arbiter,
+							env: process.env,
+						})
+					: await releaseItemLock({
+							item: item as string,
+							cwd,
+							arbiter,
+							env: process.env,
+						});
 			if (result.outcome === 'released') {
 				console.log(
 					`Released lock '${result.entry}' (${result.ref} deleted on ${arbiter}; the item itself was untouched — it rests on main / its work/<slug> branch).`,
 				);
 				return;
 			}
-			// IDEMPOTENT exit semantics: `releaseItemLock` returns `not-held` when the
+			// IDEMPOTENT exit semantics: the release returns `not-held` when the
 			// ref is ALREADY absent. For a HUMAN re-running the verb on an
 			// already-cleared lock that is the CORRECT "nothing to clear" outcome —
 			// deleting the lock ref(s) is "all locks released" and recoverable — so map
-			// it to a clean exit-0 with an honest message (NOT a failure).
+			// it to a clean exit-0 with an honest message (NOT a failure). The message
+			// names the LITERAL entry (`refs/dorfl/lock/<entry>`) so an operator can
+			// copy-paste it straight back into a `--entry` invocation.
 			if (result.outcome === 'not-held') {
 				console.log(
 					`No lock to release for '${result.entry}' (${result.ref} is already absent on ${arbiter} — “all locks released”, recoverable).`,
@@ -3706,12 +3906,56 @@ export function buildProgram(): Command {
 			process.exit(1);
 		});
 
-	// `drop <slug>` (prd `agentic-question-resolution-retire-disposition-vocabulary`,
+	// `migrate-stuck-locks` (spec `surface-stuck-as-questions-and-retire-stuck-lock-state`,
+	// resolved decision #3, user story 5; task `migrate-existing-stuck-locks-one-shot`):
+	// the ONE-SHOT ROLLOUT migration that converts every pre-existing `stuck` lock
+	// ref (an item bounced under the OLD model, before `retire-stuck-lock-state`)
+	// into the new resting shape (`needsAnswers:true` + `stuck`-kind sidecar on
+	// `<arbiter>/main` + lock released) via the SAME surface-first-release-second
+	// transition the new bounce uses. Idempotent (a re-run finds no legacy stuck
+	// ref → clean no-op) and bare-arbiter-safe (a ref is a ref). Its own verb (not
+	// folded into `gc --ledger`) because it is a one-shot rollout event with WRITE
+	// semantics on `main`, distinct from `gc`'s report-oriented + terminal-orphan
+	// reap surface — the two are different natures and their exit-code contracts
+	// stay separate.
+	program
+		.command('migrate-stuck-locks')
+		.helpGroup(ADVANCED_GROUP)
+		.description(
+			'ONE-SHOT rollout migration: convert every pre-existing `stuck` per-item lock ref (`refs/dorfl/lock/<entry>` written under the retired `stuck` lock state) into the new resting shape — a `needsAnswers:true` item body + a `stuck`-kind `work/questions/<entry>.md` sidecar on `<arbiter>/main`, with the lock ref released — via the SAME surface-first-release-second transition a fresh bounce uses. Idempotent: re-running finds no legacy `stuck` ref (the current lock module never writes `state: stuck`) and is a clean no-op. Bare-arbiter safe (a ref is a ref). Skips a pre-cutover `slice-*` / `prd-*` entry with no current item-form (clear those via `release-lock --entry <literal>`) and NEVER --force-deletes a lock. Exits non-zero only when a surface CAS lost the race or a read/plumbing fault prevented migration.',
+		)
+		.option(
+			'--cwd <dir>',
+			'the local repo/clone whose --arbiter remote the lock refs are read + mutated on (default: cwd); the working tree is never touched (the surface transition is tree-less)',
+		)
+		.option(
+			'--arbiter <remote>',
+			'the arbiter git remote the migration reads + mutates (default: origin)',
+		)
+		.action(async (flags: {cwd?: string; arbiter?: string}) => {
+			const cwd = flags.cwd ?? process.cwd();
+			const arbiter = flags.arbiter ?? 'origin';
+			const note = (message: string) => console.error(`>> ${message}`);
+			const report = await migrateStuckLocks({
+				cwd,
+				arbiter,
+				env: process.env,
+				note,
+			});
+			for (const line of formatMigrateStuckLocksReport(report)) {
+				console.log(line);
+			}
+			if (migrateStuckLocksNeedsAttention(report)) {
+				process.exit(1);
+			}
+		});
+
+	// `drop <slug>` (spec `agentic-question-resolution-retire-disposition-vocabulary`,
 	// US #5/#11; task `direct-delete-question-cli-helper`): the DIRECT "throw it
 	// away" verb — `git rm` a source item AND its question sidecar (when present) in
 	// ONE revertible commit, the reason in the commit MESSAGE (git history is the
 	// archive). It does NOT round-trip through the decision engine or spawn an agent
-	// (that is the SEPARATE agentic `delete-source` verdict in apply-persist.ts);
+	// (that is the SEPARATE agentic `dispose` verdict in apply-persist.ts);
 	// this is the human/skill/CLI no-ceremony delete of decision 7. DISTINCT from
 	// the existing `remote rm` (the hub-MIRROR deleter) — different concern, no
 	// collision. A LOCAL one-commit primitive over the working tree (like apply): it
@@ -3721,9 +3965,8 @@ export function buildProgram(): Command {
 		.command('drop <slug>')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'DIRECTLY delete a source item + its question sidecar (when present) in ONE revertible commit — the "I just want to throw this away" path that does NOT round-trip through the decision engine or any agent. Resolves the source by its namespaced identity (`task:<slug>` / `prd:<slug>` / `obs:<slug>` / a bare `<slug>` = task), `git rm`s the source AND its sidecar together, and records your --reason in the commit MESSAGE (git history is the archive). A single revertible commit, so a wrong delete is recoverable via `git revert`. DISTINCT from `remote rm` (the hub-mirror deleter). A LOCAL working-tree commit (like the apply rung); it does not touch the arbiter — push/integrate it as you normally would. If the named source is already gone it is a clean no-op (nothing to throw away).',
+			'DIRECTLY delete a source item + its question sidecar (when present) in ONE revertible commit — the "I just want to throw this away" path that does NOT round-trip through the decision engine or any agent. Resolves the source by its namespaced identity (`task:<slug>` / `spec:<slug>` / `obs:<slug>` / a bare `<slug>` = task), `git rm`s the source AND its sidecar together, and records your --reason in the commit MESSAGE (git history is the archive). A single revertible commit, so a wrong delete is recoverable via `git revert`. DISTINCT from `remote rm` (the hub-mirror deleter). A LOCAL working-tree commit (like the apply rung); it does not touch the arbiter — push/integrate it as you normally would. If the named source is already gone it is a clean no-op (nothing to throw away).',
 		)
-		.option('-c, --config <path>', 'config file path', defaultConfigPath())
 		.option(
 			'--cwd <dir>',
 			'the working clone the revertible delete commit is made in (default: cwd)',
@@ -3767,7 +4010,7 @@ export function buildProgram(): Command {
 		.command('intake')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'Front-of-funnel: turn a GitHub issue into the right work/ artifact. Reads issue #N + its comment thread via the issue seam (gh), runs a prompt→verdict decision, and dispatches it: a clear, small issue → a proposed work/backlog/<slug>.md PR carrying an `issue: N` closure link (read by a future CI close-job; not `Fixes #N`). GATE-FREE — your explicit invocation IS the authorization (autoTask/autoBuild do NOT apply), exactly as `do`. A LOCAL one-shot AND the SAME command CI schedules. PER-OUTCOME integration modes (the artifact TYPE is decided at runtime): --merge/--propose set BOTH; --merge-spec/--propose-spec and --merge-task/--propose-task override per type; granular overrides the aggregate; unset ⇒ propose for both.',
+			`Front-of-funnel: turn a GitHub issue into the right work/ artifact. Reads issue #N + its comment thread via the issue seam (gh), runs a prompt→verdict decision, and dispatches it: a clear, small issue → a proposed ${workFolderPrefix('tasks-ready')}<slug>.md PR carrying an \`issue: N\` closure link (read by a future CI close-job; not \`Fixes #N\`). GATE-FREE — your explicit invocation IS the authorization (autoTask/autoBuild do NOT apply), exactly as \`do\`. A LOCAL one-shot AND the SAME command CI schedules. PER-OUTCOME integration modes (the artifact TYPE is decided at runtime): --merge/--propose set BOTH; --merge-spec/--propose-spec and --merge-task/--propose-task override per type; granular overrides the aggregate; unset ⇒ propose for both.`,
 		)
 		.argument(
 			'<number>',
@@ -3808,7 +4051,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--origin-trust <trusted|untrusted>',
-			"the author-trust verdict to STAMP onto the emitted prd/task (origin: issue + originTrust: <value>), so an untrusted origin survives the merge boundary and later forces the task's BUILD transition to propose. CI's intake.yml derives it from the SAME author_association case as the integration flags. UNSET (a local intake) ⇒ emitted unstamped (human/trusted) — the human running intake IS the checkpoint.",
+			"the author-trust verdict to STAMP onto the emitted spec/task (origin: issue + originTrust: <value>), so an untrusted origin survives the merge boundary and later forces the task's BUILD transition to propose. CI's intake.yml derives it from the SAME author_association case as the integration flags. UNSET (a local intake) ⇒ emitted unstamped (human/trusted) — the human running intake IS the checkpoint.",
 		)
 		.option(
 			'--specs-land-in <where>',
@@ -3859,7 +4102,7 @@ export function buildProgram(): Command {
 				console.error(`>> ${resolved.message}`);
 			}
 			const config = resolved.config;
-			// Resolve the PER-OUTCOME integration modes (prd US #9): `intake` decides
+			// Resolve the PER-OUTCOME integration modes (spec US #9): `intake` decides
 			// the artifact TYPE at runtime, so a single --merge/--propose can't express
 			// a type-conditional policy. The granular flags override the aggregate; an
 			// UNSET type falls back to the per-repo/global `integration` (the SAME chain
@@ -3916,6 +4159,13 @@ export function buildProgram(): Command {
 				cwd,
 				arbiter: flags.arbiter ?? config.defaultArbiter,
 				integration: modes,
+				// The resolved cross-job CAS-retry cap (config `mergeRetries`). `intake`
+				// has no `--merge-retries` flag today (task
+				// `thread-merge-retries-cross-task-and-ratify-default` deliberately does
+				// NOT add one — intake is unattended-CI-first, env + per-repo cover the
+				// need); env + per-repo + global fold into `config.mergeRetries` via the
+				// SAME chain, and unset falls through to the engine default.
+				mergeRetries: config.mergeRetries,
 				// The origin-trust stamp the CI shell passes IN (unset ⇒ unstamped).
 				originTrust,
 				noPR: config.noPR,
@@ -3941,10 +4191,10 @@ export function buildProgram(): Command {
 			process.exit(result.exitCode);
 		});
 
-	// 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`). The thin JOB the emitted close-job workflow
 	// invokes on a merge to main: resolve which source issue(s) the landed work
-	// closes (resolveClosingIssue), run the "prd complete?" query for the prd case
+	// closes (resolveClosingIssue), run the "spec complete?" query for the spec case
 	// (prd-complete-query, done), and close via the IssueProvider seam — all
 	// UNCHANGED engine pieces, CONSUMED not re-built (the Out-of-Scope fence). CI
 	// owns ONLY the job + trigger. Local-runnable too (a manual catch-up close).
@@ -3952,7 +4202,7 @@ export function buildProgram(): Command {
 		.command('close-merged-issues')
 		.helpGroup(ADVANCED_GROUP)
 		.description(
-			'Close source issues whose work has landed on main (CI capability E, prd runner-in-ci). Resolves each closing issue from the work/ tree (resolveClosingIssue: a lone task closes its own `issue:`; a fanned task reaches the number via `task.prd: → prd issue:`), runs the existing "prd complete?" query for the prd case (closes ONLY when ALL its prd:<slug> tasks are in work/done/), and closes via the IssueProvider seam (atomic comment+close; NO direct gh). Re-implements NONE of the resolution/query/close — it WIRES them. Invoked by the emitted close-job workflow on a merge to main; DEGRADES (never crashes) on a missing/unauthenticated gh.',
+			'Close source issues whose work has landed on main (CI capability E, spec runner-in-ci). Resolves each closing issue from the work/ tree (resolveClosingIssue: a lone task closes its own `issue:`; a fanned task reaches the number via `task.spec: → spec issue:`), runs the existing "spec complete?" query for the spec case (closes ONLY when ALL its spec:<slug> tasks are in work/done/), and closes via the IssueProvider seam (atomic comment+close; NO direct gh). Re-implements NONE of the resolution/query/close — it WIRES them. Invoked by the emitted close-job workflow on a merge to main; DEGRADES (never crashes) on a missing/unauthenticated gh.',
 		)
 		.option(
 			'--cwd <dir>',
@@ -4108,7 +4358,7 @@ export function buildProgram(): Command {
 		.command('find <folder>')
 		.helpGroup(HEADLINE_GROUP)
 		.description(
-			'Discover work/-participating repos under <folder> (a populated work/backlog/), then toggle-add the chosen ones via `remote add`. Interactive multi-select by default; --yes adds ALL discovered repos non-interactively.',
+			`Discover work/-participating repos under <folder> (a populated ${workFolderPrefix('tasks-ready')}), then toggle-add the chosen ones via \`remote add\`. Interactive multi-select by default; --yes adds ALL discovered repos non-interactively.`,
 		)
 		.option('-c, --config <path>', 'config file path', defaultConfigPath())
 		.option('--yes', 'add all discovered participating repos (no prompt)')
@@ -4184,7 +4434,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--max-parallel <n>',
-			'cap on CONCURRENT advance-lifecycle matrix legs (the propose/merge `max-parallel`). Each leg is a full agent session, so a large fan-out can exhaust the model provider rate limit + thrash the CAS. Default 4.',
+			'cap on CONCURRENT advance-lifecycle matrix legs (the propose/merge `max-parallel`). Each leg is a full agent session, so a large fan-out can exhaust the model provider rate limit + thrash the CAS. Default 2.',
 		)
 		.action(async (flags: InstallCiFlags) => {
 			const workDir = flags.cwd ?? process.cwd();
@@ -4211,6 +4461,7 @@ export function buildProgram(): Command {
 				}
 				maxParallel = n;
 			}
+
 			const ctx = new GitHubCIContext({
 				workDir,
 				repo: flags.repo,
@@ -4241,9 +4492,89 @@ export function buildProgram(): Command {
 			});
 		});
 
+	// The `skills` group (ADR `skill-install-vendors-incur-agents-map`): install the
+	// packaged dorfl skills (`from-idea`, `setup`, ...) into the OPERATOR's OWN
+	// harness dirs. Distinct from any target-repo propagation (ADR
+	// `methodology-and-skills` §6 — skills don't travel into target repos; only
+	// `work/protocol/` does). Only `add` is exposed in this pass — `list`/`remove`
+	// are deferred until we have a real use case (the vendored `install()` is
+	// idempotent, so `add` alone covers upgrade + drift-repair; a future `remove`
+	// would map onto the vendored `remove()` and is intentionally out of scope
+	// here to keep the CLI surface minimal).
+	const skills = program
+		.command('skills')
+		.helpGroup(HEADLINE_GROUP)
+		.description(
+			"Install the packaged dorfl skills (`from-idea`, `setup`, ...) into the operator's own agent harness(es). Installs into your OWN harness dirs (~/.agents/skills/ + per-harness symlinks) — this is operator tooling, NOT target-repo propagation (skills don't travel into `work/` repos; only `work/protocol/` does).",
+		);
+
+	skills
+		.command('add')
+		.helpGroup(HEADLINE_GROUP)
+		.description(
+			'Copy the packaged dorfl skills into the canonical `~/.agents/skills/` (global; `--local` scopes to <cwd>/.agents/skills/) and symlink each detected non-universal harness (Claude Code, Cursor, Windsurf, ...) to it. Idempotent; re-run to pick up new/updated skills.',
+		)
+		.option(
+			'--local',
+			'install project-locally into <cwd>/.agents/skills/ (and each detected harness\u2019s PROJECT dir) instead of globally into ~/.agents/skills/. Default: global.',
+		)
+		.action((flags: SkillsAddFlags) => {
+			const result = installSkills({global: flags.local !== true});
+			console.log(formatSkillsAddReport(result, flags.local === true));
+		});
+
 	return program;
 }
 
+interface SkillsAddFlags {
+	/**
+	 * `--local`: project-local install (canonical base `<cwd>/.agents/skills/`)
+	 * instead of the global `~/.agents/skills/` default. Named to mirror the
+	 * `remote add --local` sibling ('local' = "scope to here") and the vendored
+	 * `install()`'s `global: false` semantic. Chosen over `--project` /
+	 * `--here` / `--global` inversion for consistency with the existing verb.
+	 */
+	local?: boolean;
+}
+
+/**
+ * Human-readable report for `dorfl skills add`. Prints the SOURCE the skills
+ * were read from, each canonical install path (one per skill), and each
+ * non-universal harness placement (symlink | copy) with its absolute path.
+ * Universal harnesses read from the canonical dir directly and need no line.
+ * Output goes to stdout; the shape is stable enough for a human to audit "what
+ * landed where" but is NOT a machine contract (no JSON mode in this pass).
+ */
+export function formatSkillsAddReport(
+	result: InstallSkillsResult,
+	local: boolean,
+): string {
+	const lines: string[] = [];
+	const scope = local ? 'project-local' : 'global';
+	lines.push(`Installed dorfl skills (${scope}) from ${result.sourceDir}:`);
+	if (result.paths.length === 0) {
+		lines.push('  (no skills found in source)');
+	} else {
+		for (const p of result.paths.slice().sort()) {
+			lines.push(`  ${p}`);
+		}
+	}
+	if (result.agents.length === 0) {
+		lines.push(
+			'Harnesses: no non-universal harness detected (universal harnesses read from the canonical dir directly).',
+		);
+	} else {
+		lines.push('Harnesses:');
+		for (const a of result.agents.slice().sort((x, y) => {
+			const byAgent = x.agent.localeCompare(y.agent);
+			return byAgent !== 0 ? byAgent : x.path.localeCompare(y.path);
+		})) {
+			lines.push(`  ${a.agent}: ${a.mode} -> ${a.path}`);
+		}
+	}
+	return lines.join('\n');
+}
+
 /**
  * A readline-backed {@link WizardPrompts} for the interactive `install-ci`
  * wizard. Prompts go to stderr (stdout is reserved for any machine output); a