dorfl 0.1.2 → 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;
@@ -392,7 +399,7 @@ function buildRegistrySetAdvanceTick(options: {
 				// `taskingIntegration ?? integration`; the build path stays on `integration`.
 				taskingIntegration: config.taskingIntegration,
 				// The TASK-PLACEMENT configured default (`do spec:` tasking output:
-				// `pre-backlog` staged vs `ready` pool). No operator flag on this
+				// `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,
@@ -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 spec:` 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;
@@ -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.
@@ -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;
 }
@@ -982,9 +993,9 @@ interface CloseMergedIssuesFlags {
  * 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
+ * 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.)
+ * ''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`
@@ -1164,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)
@@ -1516,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(
@@ -1789,7 +1838,7 @@ 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 spec 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]',
@@ -1927,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),
 					},
 				});
@@ -1941,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,
 				});
@@ -2040,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) | 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
@@ -2070,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',
@@ -2082,7 +2143,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--tasks-land-in <where>',
-			'where `do spec:<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',
@@ -2221,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
@@ -2258,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;
@@ -2369,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),
@@ -2550,6 +2675,11 @@ 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),
@@ -2685,7 +2815,7 @@ export function buildProgram(): Command {
 		)
 		.option(
 			'--tasks-land-in <where>',
-			'where `advance spec:<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',
@@ -2996,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),
@@ -3115,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',
@@ -3160,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,
@@ -3190,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
@@ -3233,13 +3371,15 @@ export function buildProgram(): Command {
 				// human clears a NAMED unified lock via `release-lock`).
 				//
 				// SCOPED to the ATTENTION verdicts only (spec 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.
+				// `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)
@@ -3386,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);
@@ -3498,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(
@@ -3509,9 +3649,14 @@ 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>',
@@ -3533,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,
@@ -3541,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}`),
@@ -3551,7 +3705,9 @@ 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}`);
 		});
 
@@ -3559,7 +3715,7 @@ export function buildProgram(): Command {
 	// `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 spec
+	// `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
@@ -3569,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 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 pre-backlog/ + the specs in 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.`,
+			`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(
@@ -3597,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 ${workFolderPrefix('specs-proposed')} are empty).`,
+						`Nothing staged to promote on ${arbiter}/main (${workFolderPrefix('tasks-backlog')} and ${workFolderPrefix('specs-proposed')} are empty).`,
 					);
 					return;
 				}
@@ -3610,7 +3766,7 @@ export function buildProgram(): Command {
 
 			// 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
+			// (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') {
@@ -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>` / `spec:<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);
 		});
 
+	// `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
@@ -3723,7 +3967,6 @@ export function buildProgram(): Command {
 		.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>` / `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>',
@@ -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,
@@ -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