dorfl 0.1.1 → 0.2.0

package/dist/cli.js

@@ -51,7 +51,8 @@ import { sweepOrphanSidecars } from './orphan-sidecar.js';
 import { sweepLedgerDuplicates, formatLedgerSweep } from './ledger-lint.js';
 import { status, formatStatus } from './status.js';
 import { ledgerWrite } from './ledger-write.js';
-import { releaseItemLock, reportItemLocks, formatItemLockReport, itemLockReportNeedsAttention, reapStaleItemLocks, formatReapReport, reapReportNeedsAttention, } from './item-lock.js';
+import { releaseItemLock, releaseLiteralLockEntry, reportItemLocks, formatItemLockReport, itemLockReportNeedsAttention, reapStaleItemLocks, formatReapReport, reapReportNeedsAttention, } from './item-lock.js';
+import { migrateStuckLocks, formatMigrateStuckLocksReport, migrateStuckLocksNeedsAttention, } from './migrate-stuck-locks.js';
 import { promoteFromPreBacklog, promoteFromPreSpec, listPromotable, } from './needs-attention.js';
 import { parseSlugArg } from './slug-namespace.js';
 import { dropSource } from './drop-source.js';
@@ -62,6 +63,7 @@ import { installCI } 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 } from './install-skills.js';
 /**
  * Whether `--auto-build` / `--no-auto-build` was explicitly passed on the command
  * line. Commander gives a negatable boolean option a default of `true`, so we
@@ -218,10 +220,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,
         },
@@ -249,11 +251,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,
@@ -261,7 +263,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,
@@ -300,7 +302,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
@@ -396,7 +398,7 @@ function runFlagOverrides(flags, command) {
     // 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).
@@ -409,7 +411,7 @@ function formatItemLine(item) {
 }
 /**
  * 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
@@ -422,8 +424,8 @@ function explicitTasksLandInFromFlag(raw) {
     if (raw === undefined) {
         return undefined;
     }
-    if (raw !== 'pre-backlog' && raw !== 'ready') {
-        throw new Error(`--tasks-land-in must be 'pre-backlog' or 'ready' (got '${raw}').`);
+    if (raw !== 'backlog' && raw !== 'ready') {
+        throw new Error(`--tasks-land-in must be 'backlog' or 'ready' (got '${raw}').`);
     }
     return raw;
 }
@@ -498,7 +500,7 @@ function printPrdToSpecReport(result) {
         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)):`);
@@ -513,11 +515,12 @@ function printLeak(leak) {
 /**
  * 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`
@@ -595,10 +598,10 @@ function buildInteractiveLauncher(flags, configPath, repoPath) {
  * 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, flags, resume) {
-    // 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();
     // `resume --isolated <slug>`: re-engage the slug's RETAINED job worktree (the
@@ -675,6 +678,34 @@ export function buildProgram() {
     program
         .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) => {
+        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)
@@ -907,14 +938,14 @@ export function buildProgram() {
     program
         .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).')
+        .description(`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('--arbiter <remote>', 'name of the arbiter git remote (default: origin)', 'origin')
         .option('--retries <n>', 'cap on push retries when main advances', '3')
         .option('--dry-run', 'show the intended push without mutating the arbiter')
         .option('--ignore-not-ready', 'override the readiness guard: claim despite an unmet blockedBy, and silence the needsAnswers warning (loud, never default)')
         .action(async (rawSlug, flags) => {
-        // Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+        // Task-only command (§3a): accept bare + `task:`, reject `spec:`.
         const slug = resolveTaskOnlySlug(rawSlug);
         // Wrap ONLY this CLI surface's `performClaim` call with the spinner
         // helper (task `claim-cas-spinner`): the push can take seconds, so the
@@ -1022,7 +1053,7 @@ export function buildProgram() {
         const remote = 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);
         const configPath = flags.config ?? defaultConfigPath();
         const { dir: configuredRoot, config } = loadHumanWorktreesDir(configPath);
@@ -1066,10 +1097,10 @@ export function buildProgram() {
     program
         .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.")
+        .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 ${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) => {
-        // 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
@@ -1112,7 +1143,7 @@ export function buildProgram() {
         .option('--no-fresh-worktree-gate', 'run the acceptance gate in the current checkout (the pre-rebase tree) — the opt-out for when the per-gate install cost is too high')
         .option('--merge-retries <n>', 'cross-job merge-serialiser CAS-retry cap (see `run --help`); resolved flag > env > per-repo > global > default 1000.')
         .action(async (rawSlug, flags) => {
-        // 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);
@@ -1133,6 +1164,11 @@ export function buildProgram() {
                 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),
                 },
             });
@@ -1147,6 +1183,9 @@ export function buildProgram() {
                 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,
             });
@@ -1172,7 +1211,7 @@ export function buildProgram() {
                 // `--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.
@@ -1212,7 +1251,7 @@ export function buildProgram() {
             // 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`.
@@ -1243,22 +1282,23 @@ export function buildProgram() {
     program
         .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.')
+        .description("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
         // `do` (zero args = auto-pick), `do <a> <b> …` (named, in sequence), and
         // `do <slug>` (exactly one) all share the one command. `-n <x>` is the count
         // 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.')
+        .argument('[slugs...]', '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('--arbiter <remote>', 'name of the arbiter git remote (default: per-repo/global defaultArbiter)')
         .option('-n, --number <x>', 'AUTO-PICK x eligible items and do them IN SEQUENCE (ordered by selectionOrder, default drain = tasks-first then prds-to-task). Sequential — never a parallelism knob (that is `run`). Mutually exclusive with naming items.')
         .option('--selection-order <order>', 'order the auto-pick pools (build/task/surface/triage; apply is always first): a preset keyword (drain (default) | groom) or an explicit comma-separated pool list (e.g. build,task,surface,triage). Resolved flag > env > per-repo > global > default.')
         .option('--remote <r>', 'run against a REGISTERED repo with NO checkout: materialise a hub mirror + job worktree in the agents\u2019 area (auto-registers an unknown remote), run the pipeline there, then reap (never touches the human area)')
-        .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).")
+        .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 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', 'integrate in merge mode this invocation (mutually exclusive with --propose; overrides config)')
         .option('--propose', 'integrate in propose mode this invocation (default; mutually exclusive with --merge; overrides config)')
-        .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.')
+        .option('--tasks-land-in <where>', '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', 'propose without opening a PR: push the branch but deliberately skip the review request, even on an authed GitHub arbiter (the explicit suppress-PR intent). Resolved flag > env > per-repo > global > default off.')
         .option('--ignore-diverged-main', 'override the in-place divergence guard: run even when local main is ahead of <arbiter>/main (unpushed). The work still lands on the arbiter; local main is left for you to `git rebase`. In-place only; loud, never default.')
         .option('--allow-backlog', 'do task:<slug> ONLY: also FIND, CLAIM, and COMPLETE a task that lives in tasks/backlog/ (staging), driving it in place WITHOUT promoting it to the pool (so no advance leg / run daemon can claim it out from under you). The done-move goes tasks/backlog/ -> tasks/done/ directly (your explicit drive IS the promotion). EXPLICIT-INVOCATION-ONLY: default off, never set by run/auto-pick/advance or config/env.')
@@ -1272,9 +1312,9 @@ export function buildProgram() {
         .option('--no-review', 'do NOT run Gate 2 this invocation (overrides config)')
         .option('--review-model <id>', 'model the Gate-2 review agent runs on (de-correlated from the builder; routing intent). Resolved flag > env > per-repo > global > default.')
         .option('--review-max-rounds <n>', 'bound the revise/review loop; on exhaustion force needs-attention (default 2)')
-        .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).')
-        .option('--no-tasker-loop', 'skip the tasker improver loop on `do prd:<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)')
+        .option('--tasker-loop', '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 spec:<slug>`')
+        .option('--tasker-loop-max <n>', '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>', 'model the tasker improver loop review agent runs on (de-correlated from the tasker; routing intent). Resolved flag > env > per-repo > global > default. DISTINCT from --review-model.')
         .option('--fresh-worktree-gate', 'run the acceptance gate (prepare then verify) against the REBASED tip in a CLEAN throwaway worktree (the tree that actually integrates), so a green gate provably describes the merged artifact. ON by default. Resolved flag > env > per-repo > global > default on.')
         .option('--no-fresh-worktree-gate', "run the acceptance gate in the agent's build worktree (the pre-rebase tree) as before — the opt-out for when the per-gate install cost is too high")
@@ -1331,13 +1371,47 @@ export function buildProgram() {
         // `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).
-        const isolatedNoRemote = flags.isolated === true && flags.remote === undefined;
+        // 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.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
@@ -1359,10 +1433,30 @@ export function buildProgram() {
                     resolveDefaultArbiterForCwd(cwd, global, remoteFlags, override);
                 const resolvedUrl = resolveArbiterUrlFromCheckout(cwd, arbiterName, 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;
@@ -1411,7 +1505,7 @@ export function buildProgram() {
                 // 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`.
@@ -1419,7 +1513,7 @@ export function buildProgram() {
                 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
@@ -1431,7 +1525,7 @@ export function buildProgram() {
                 // 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,
@@ -1448,7 +1542,7 @@ export function buildProgram() {
                         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
@@ -1461,7 +1555,7 @@ export function buildProgram() {
                     : 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,
@@ -1469,6 +1563,11 @@ export function buildProgram() {
                     })
                     : 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),
@@ -1565,7 +1664,7 @@ export function buildProgram() {
             // 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
@@ -1578,11 +1677,11 @@ export function buildProgram() {
             // 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
@@ -1595,7 +1694,7 @@ export function buildProgram() {
             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,
@@ -1619,7 +1718,7 @@ export function buildProgram() {
             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
@@ -1642,11 +1741,16 @@ export function buildProgram() {
             // `--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
@@ -1700,33 +1804,33 @@ export function buildProgram() {
         process.exit(result.exitCode);
     });
     // `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.
     program
         .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).')
-        .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.')
+        .description('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>, 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('--arbiter <remote>', 'name of the arbiter git remote (default: per-repo/global defaultArbiter)')
         .option('-n, --number <x>', 'AUTO-PICK x eligible items and advance them IN SEQUENCE (ordered by selectionOrder, default drain = tasks-first then prds-to-task). Sequential — never a parallelism knob (that is `run` / the CI matrix). Mutually exclusive with naming items.')
         .option('--isolated', "advance in an ISOLATED worktree off THIS repo's arbiter (inferred from cwd) instead of taking over the current checkout, then integrate + reap — the in-place-but-isolated form. Shares the same grammar: 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). Lets you advance from a busy/dirty checkout or anywhere with a participating arbiter.")
         .option('--selection-order <order>', 'order the auto-pick pools (build/task/surface/triage; apply is always first): a preset keyword (drain (default) | groom) or an explicit comma-separated pool list. Resolved flag > env > per-repo > global > default.')
         .option('--observation-triage <mode>', 'the observation-inbox gate (off|ask|auto): off (default) leaves observations untouched (the triage pool is dropped from auto-pick); ask surfaces a promote/keep/delete question for each untriaged observation; auto auto-disposes the no-question cases (duplicate/map) and asks about the rest. Resolved flag > env > per-repo > global > default. An explicit `advance obs:<slug>` bypasses the selection gate and runs in ask-mode (auto-disposes only under `auto`).')
-        .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).')
-        .option('--no-surface-blockers', 'leave a needsAnswers:true task/prd 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.')
+        .option('--surface-blockers', '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/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 (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', 'honour the prior merge-answer and land when the rebased tip re-verifies GREEN even if the merge-base changed (default; the cheap green-re-verify-is-enough path)')
         .option('--merge-questions <mode>', 'the merge-question SURFACER gate (off|ask|auto): off drops the surfacer (only for a repo that lands by some other means); ask (default) enumerates unmerged `work/*` branches and surfaces a merge-question sidecar a human answers; auto self-supplies the `merge` answer and lands via the SAME deterministic apply-time re-verify (the merge-mode-like fast path). SEPARATE axis from --observation-triage with a HIGHER default (a dropped merge-question means pushed work never lands). Resolved flag > env > per-repo > global > default ask.')
         .option('--merge', 'integrate the advanced item(s) in merge mode this invocation (mutually exclusive with --propose; overrides config). The CI merge shape is a SINGLE SEQUENTIAL job, so this rides the `-n`/named-sequence path, never the matrix.')
         .option('--propose', 'integrate the advanced item(s) in propose mode this invocation (default; mutually exclusive with --merge; overrides config). The CI propose shape is the parallel matrix (one PR per item).')
-        .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.')
+        .option('--tasks-land-in <where>', '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', "stream the build agent's high-signal events live by tailing the pi session log (requires harness: pi; READ-ONLY observer — does not change outcome/gate/git). The same view `do --watch` gives, threaded through the build rung; CI uses it so the job log shows the agent working instead of freezing.")
         .action(async (rawSlugs, flags) => {
         // Variadic grammar (mirrors `do`): zero args = AUTO-PICK; one = the single
@@ -1842,7 +1946,7 @@ export function buildProgram() {
                 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`).
@@ -1852,7 +1956,7 @@ export function buildProgram() {
                 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,
@@ -1980,7 +2084,7 @@ export function buildProgram() {
             // 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
@@ -1991,7 +2095,7 @@ export function buildProgram() {
             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,
@@ -2013,6 +2117,10 @@ export function buildProgram() {
             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),
@@ -2109,7 +2217,7 @@ export function buildProgram() {
         .option('--force', 'OVERRIDE the predicate: remove worktrees even with un-saved work (requires --yes; never the default)')
         .option('--yes', 'confirm a destructive --force sweep non-interactively')
         .option('--ledger [repoPath]', 'SWEEP the work/ lifecycle LEDGER instead of job worktrees: REPORT (never delete) every slug present in more than one work/ status folder (the one-slug-one-folder belt-and-suspenders), with its folders + candidate canonical folder, for a HUMAN to resolve. Defaults to the cwd repo.')
-        .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).')
+        .option('--reap-stale-locks', '(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', 'SWEEP the arbiter’s remote work/* BRANCHES instead of job worktrees: delete (via git push --delete, NEVER --force) exactly those PROVABLY MERGED into <arbiter>/main (git merge-base --is-ancestor, the SAME predicate the worktree reaper uses), and RETAIN the rest with a reason. An in-flight/un-merged branch (the recovery point) is NEVER touched. Provider-agnostic plain git — works on a --bare arbiter. The merged-only complement of `requeue --reset`.')
         .option('--arbiter <remote>', '(with --remote-branches) the arbiter git remote whose work/* branches to sweep (default: origin); resolved from --cwd')
         .option('--cwd <dir>', '(with --remote-branches) the local repo/clone whose --arbiter remote points at the arbiter to sweep (default: cwd); only remote refs are read + deleted, never the working tree')
@@ -2118,7 +2226,7 @@ export function buildProgram() {
         .action(async (flags) => {
         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.
@@ -2126,7 +2234,7 @@ export function buildProgram() {
             const repoPath = 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/*`),
@@ -2139,13 +2247,16 @@ export function buildProgram() {
             // 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, flags.arbiter ?? 'origin', process.env);
                 if (flags.json) {
@@ -2164,10 +2275,11 @@ export function buildProgram() {
                         ? blocks.join('\n\n')
                         : 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
                     : 0);
@@ -2202,14 +2314,16 @@ export function buildProgram() {
             // 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)
                 ? 1
@@ -2229,7 +2343,7 @@ export function buildProgram() {
                 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
@@ -2328,7 +2442,7 @@ export function buildProgram() {
             printPrdToSpecReport(result);
         }
         // 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);
@@ -2420,14 +2534,16 @@ export function buildProgram() {
     program
         .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).')
+        .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. 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('--cwd <dir>', 'the repo/working clone whose work/ tree the arbiter remote is resolved FROM (default: cwd) — an ORIGIN SOURCE only; the move is published to the arbiter, never to this tree')
         .option('--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('--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.')
+        .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', '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, flags) => {
-        // Task-only command (§3a): accept bare + `task:`, reject `prd:`.
+        // Task-only command (§3a): accept bare + `task:`, reject `spec:`.
         const slug = resolveTaskOnlySlug(rawSlug);
         const cwd = flags.cwd ?? process.cwd();
         // Route the requeue (default keep+continue / --reset discard / -m handoff)
@@ -2442,6 +2558,12 @@ export function buildProgram() {
         // 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,
@@ -2450,6 +2572,7 @@ export function buildProgram() {
             // `--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}`),
@@ -2460,15 +2583,17 @@ export function buildProgram() {
         }
         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
@@ -2476,7 +2601,7 @@ export function buildProgram() {
     program
         .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.')
+        .description(`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('--cwd <dir>', 'the repo/working clone whose arbiter remote the tree-less move is resolved FROM (default: cwd) — an ORIGIN SOURCE only; the move is published to the arbiter, never to this tree')
         .option('--arbiter <remote>', 'the arbiter git remote the promotion is CAS-published to / the staging folders are listed from (default: origin)')
@@ -2495,7 +2620,7 @@ export function buildProgram() {
                 process.exit(1);
             }
             if (listed.items.length === 0) {
-                console.log(`Nothing staged to promote on ${arbiter}/main (work/pre-backlog/ and work/prds/proposed/ are empty).`);
+                console.log(`Nothing staged to promote on ${arbiter}/main (${workFolderPrefix('tasks-backlog')} and ${workFolderPrefix('specs-proposed')} are empty).`);
                 return;
             }
             console.log('Staged, awaiting promotion (run `promote <item>`):');
@@ -2504,11 +2629,10 @@ export function buildProgram() {
             }
             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(`error: promote takes a task or spec, not an observation ('${rawItem}'). Observations have no agent pool.`);
@@ -2535,7 +2659,7 @@ export function buildProgram() {
     // the `work/advancing/<entry>.md` marker is gone and an advance hold is now just
     // `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
@@ -2548,31 +2672,67 @@ export function buildProgram() {
     // 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).')
+        .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). 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)')
         .option('--arbiter <remote>', 'the arbiter git remote the lock ref is deleted on (default: origin)')
         .action(async (item, flags) => {
         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,
+                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).`);
             return;
@@ -2580,12 +2740,47 @@ export function buildProgram() {
         console.error(`error: ${result.message}`);
         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) => {
+        const cwd = flags.cwd ?? process.cwd();
+        const arbiter = flags.arbiter ?? 'origin';
+        const note = (message) => 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
@@ -2594,8 +2789,7 @@ export function buildProgram() {
     program
         .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).')
-        .option('-c, --config <path>', 'config file path', defaultConfigPath())
+        .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('--cwd <dir>', 'the working clone the revertible delete commit is made in (default: cwd)')
         .option('--reason <text>', 'why you are throwing this away — recorded in the commit MESSAGE (git history is the archive). Optional; recorded as "(no reason given)" when omitted.')
         .action((slug, flags) => {
@@ -2622,7 +2816,7 @@ export function buildProgram() {
     program
         .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.')
+        .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 ${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>', 'the GitHub issue number to intake (e.g. `intake 42`)')
         .option('-c, --config <path>', 'config file path', defaultConfigPath())
         .option('--arbiter <remote>', 'name of the arbiter git remote (default: per-repo/global defaultArbiter)')
@@ -2633,7 +2827,7 @@ export function buildProgram() {
         .option('--propose-spec', 'integrate a spec outcome in propose mode (granular; overrides --merge/--propose for a spec; mutually exclusive with --merge-spec)')
         .option('--merge-task', 'integrate a task outcome in merge mode (granular; overrides --merge/--propose for a task; mutually exclusive with --propose-task)')
         .option('--propose-task', 'integrate a task outcome in propose mode (granular; overrides --merge/--propose for a task; mutually exclusive with --merge-task)')
-        .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.")
+        .option('--origin-trust <trusted|untrusted>', "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>', 'where an intake-authored spec lands: `pre-proposed` (staged, not auto-taskable) or `ready` (the auto-tasking pool). The EXPLICIT operator override at the top of the placement precedence (explicit flag > untrusted-origin forces staging > specsLandIn default > built-in). Resolved flag > env (DORFL_SPECS_LAND_IN) > per-repo > global > built-in.')
         .option('--agent-cmd <cmd>', 'command to run the decision agent')
         .option('--model <id>', 'model the decision agent runs on (routing intent; resolved flag > env > per-repo > global > default)')
@@ -2664,7 +2858,7 @@ export function buildProgram() {
             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
@@ -2715,6 +2909,13 @@ export function buildProgram() {
             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,
@@ -2740,17 +2941,17 @@ export function buildProgram() {
         }
         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).
     program
         .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.')
+        .description('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>', 'the repo working dir whose work/ tree to scan (default: cwd)')
         .option('--gh-bin <bin>', 'the gh CLI binary (default: gh on PATH)')
         .option('--json', 'output the raw result as JSON')
@@ -2867,7 +3068,7 @@ export function buildProgram() {
     remote
         .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.')
+        .description(`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)')
         .action(async (folder, flags) => {
@@ -2918,7 +3119,7 @@ export function buildProgram() {
         .option('--gh-bin <bin>', 'the gh CLI binary (default: gh on PATH)')
         .option('--cwd <dir>', 'the target repo working dir (default: cwd)')
         .option('--install-source <registry|workspace>', 'where the CI installs the CLI from: `registry` (npm install -g, the default) or `workspace` (build from the checked-out source + link onto PATH, for the self-hosting monorepo). Overrides auto-detection in both directions.')
-        .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.')
+        .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 2.')
         .action(async (flags) => {
         const workDir = flags.cwd ?? process.cwd();
         if (flags.installSource !== undefined &&
@@ -2964,8 +3165,64 @@ export function buildProgram() {
             log: (line) => console.error(line),
         });
     });
+    // 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) => {
+        const result = installSkills({ global: flags.local !== true });
+        console.log(formatSkillsAddReport(result, flags.local === true));
+    });
     return program;
 }
+/**
+ * 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, local) {
+    const lines = [];
+    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