dorfl 0.1.2 → 0.2.1

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
@@ -253,7 +255,7 @@ function buildRegistrySetAdvanceTick(options) {
                 // `taskingIntegration ?? integration`; the build path stays on `integration`.
                 taskingIntegration: config.taskingIntegration,
                 // The TASK-PLACEMENT configured default (`do spec:` tasking output:
-                // `pre-backlog` staged vs `ready` pool). No operator flag on this
+                // `backlog` staged vs `ready` pool). No operator flag on this
                 // registry-driven advance context, so only the configured default rung is
                 // threaded (the resolver still layers untrusted-origin force + built-in floor).
                 tasksLandIn: config.tasksLandIn,
@@ -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;
 }
@@ -516,9 +518,9 @@ function printLeak(leak) {
  * REJECT `spec:` with a clear "operates on tasks, not specs" error. On rejection
  * it prints the error to stderr and exits 1 (the task-only commands never act on
  * a spec). An OMITTED slug (`start`/`complete`/`prompt` infer it from the branch)
- * passes through untouched. (The legacy `prd:` prefix is a DEAD namespace token
+ * passes through untouched. (The legacy ''prd:'' prefix is a DEAD namespace token
  * after the hard cutover — it is neither special-cased nor rejected here; a
- * `prd:<slug>` arg resolves as a bare literal task slug.)
+ * ''prd:<slug>'' arg resolves as a bare literal task slug.)
  *
  * `do` is the ONE command that spans both namespaces; it consumes the full
  * `resolveSlug` (with the cross-namespace collision check) in the `do-in-place`
@@ -676,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)
@@ -908,7 +938,7 @@ 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')
@@ -1067,7 +1097,7 @@ 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 spec substituted). Resolves work/in-progress/<slug>.md then work/backlog/<slug>.md; infers <slug> from a work/<slug> branch when omitted. Read-only, stdout only — the same assembly the autonomous runner feeds agentCmd.")
+        .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 `spec:`.
@@ -1134,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),
                 },
             });
@@ -1148,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,
             });
@@ -1244,7 +1282,7 @@ 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) | 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
@@ -1256,10 +1294,11 @@ export function buildProgram() {
         .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 spec:<slug>` tasking output lands: `pre-backlog` (staged, not agent-eligible) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence (explicit flag > untrusted-origin forces staging > tasksLandIn default > built-in). Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.')
+        .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.')
@@ -1332,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
@@ -1360,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;
@@ -1470,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),
@@ -1643,6 +1741,11 @@ 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),
@@ -1727,7 +1830,7 @@ export function buildProgram() {
         .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 spec:<slug>` tasking output lands: `pre-backlog` (staged) or `ready` (the agent POOL). The EXPLICIT operator override at the top of the placement precedence. Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.')
+        .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
@@ -2014,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),
@@ -2110,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')
@@ -2140,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) {
@@ -2165,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);
@@ -2204,13 +2315,15 @@ export function buildProgram() {
             // human clears a NAMED unified lock via `release-lock`).
             //
             // SCOPED to the ATTENTION verdicts only (spec US#14/#21, ADR
-            // `ledger-status-on-per-item-lock-refs`: this surface is the STUCK /
-            // crash-orphaned lock, NOT every held one): a `kept-stuck` (terminal +
-            // stuck) or a `cleared-stale`-eligible (terminal + stale active = orphaned)
-            // lock fails loud, but a `kept-in-flight` (active, non-terminal) lock is the
-            // NORMAL in-flight state of a healthy concurrent build (read by `status` as
-            // healthy) — it is reported informationally and does NOT make a routine
-            // `gc --ledger` health check exit non-zero.
+            // `ledger-status-on-per-item-lock-refs` § Addendum 2026-07-10: this surface
+            // is the STUCK / crash-orphaned lock, NOT every held one): a `kept-stuck`
+            // (STUCK + NON-terminal — the genuine human-attention case), a
+            // `cleared-stale`-eligible (terminal + stale active = stranded orphan), or
+            // a `cleared-stuck-terminal`-eligible (terminal + stuck = crash-orphan the
+            // reaper can now auto-clear) fails loud, but a `kept-in-flight` (active,
+            // non-terminal) lock is the NORMAL in-flight state of a healthy concurrent
+            // build (read by `status` as healthy) — it is reported informationally
+            // and does NOT make a routine `gc --ledger` health check exit non-zero.
             process.exit(result.duplicates.length > 0 ||
                 itemLockReportNeedsAttention(lockReport)
                 ? 1
@@ -2329,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);
@@ -2421,11 +2534,13 @@ 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 `spec:`.
@@ -2443,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,
@@ -2451,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}`),
@@ -2461,14 +2583,16 @@ 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]` (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 spec
+    // `work/tasks/backlog/<slug>.md → work/tasks/ready/<slug>.md`, a spec
     // `work/specs/proposed/<slug>.md → work/specs/ready/<slug>.md` — as a tree-less CAS on the
     // arbiter, the SAME trust model + mechanism as `requeue`. The agent emits STAGED;
     // only this verb (a human, or the runner) admits it to the pool. With NO argument
@@ -2477,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 spec \`${workFolderPrefix('specs-proposed')}<slug>.md → ${workFolderPrefix('specs-ready')}<slug>.md\`, published as a TREE-LESS compare-and-swap to the arbiter ref (EXACTLY like requeue/claim — it never stages/commits in the cwd tree). The agent only ever CREATES staged; this verb is the gate a human (or the runner) opens. Accepts \`task:<slug>\` / \`spec:<slug>\` / a bare \`<slug>\` (= task). With NO argument, LISTS every promotable item (the tasks in pre-backlog/ + the specs in specs/proposed/ on the arbiter) so you can see what is staged waiting for promotion. Idempotent: promoting an already-pooled slug is a clean no-op success.`)
+        .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)')
@@ -2496,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 ${workFolderPrefix('specs-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>`):');
@@ -2507,7 +2631,7 @@ export function buildProgram() {
         }
         // AN ITEM → promote it. `task:`/`spec:` are explicit; a bare slug defaults to
         // a task (mirrors `requeue`). An `obs:`/`observation:` prefix is rejected
-        // (observations have no pool). A legacy `prd:` prefix is a DEAD namespace token
+        // (observations have no pool). A legacy ''prd:'' prefix is a DEAD namespace token
         // after the hard cutover — it resolves as a bare literal task slug, not a spec.
         const parsed = parseSlugArg(rawItem);
         if (parsed.explicit === 'observation') {
@@ -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>` / `spec:<slug>` / `obs:<slug>` / a bare `<slug>` (= task). Idempotent — re-running on an already-cleared lock is a clean exit-0 no-op (deleting the lock ref is “all locks released”, recoverable). NEVER `--force`. Discoverable via `gc --ledger` (it REPORTS every lingering lock, never deletes).')
+        .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);
     });
+    // `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
@@ -2595,7 +2790,6 @@ export function buildProgram() {
         .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>` / `spec:<slug>` / `obs:<slug>` / a bare `<slug>` = task), `git rm`s the source AND its sidecar together, and records your --reason in the commit MESSAGE (git history is the archive). A single revertible commit, so a wrong delete is recoverable via `git revert`. DISTINCT from `remote rm` (the hub-mirror deleter). A LOCAL working-tree commit (like the apply rung); it does not touch the arbiter — push/integrate it as you normally would. If the named source is already gone it is a clean no-op (nothing to throw away).')
-        .option('-c, --config <path>', 'config file path', defaultConfigPath())
         .option('--cwd <dir>', 'the working clone the revertible delete commit is made in (default: cwd)')
         .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)')
@@ -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,
@@ -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