dorfl 0.0.0 → 0.1.0

package/dist/advance.js

@@ -0,0 +1,1122 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { workItemPath, workItemRel } from './work-layout.js';
+import { resolveAdvanceArg, SlugResolutionError, } from './slug-namespace.js';
+import { ledgerRead } from './ledger-read.js';
+import { parseFrontmatter } from './frontmatter.js';
+import { parseSidecar, sidecarPathFor, } from './sidecar.js';
+import { classifyTick } from './advance-classify.js';
+import { acquireAdvancingLock, releaseAdvancingLock, } from './advancing-lock.js';
+import { performDo } from './do.js';
+import { harnessSurfaceGate, toNewQuestions, } from './surface-gate.js';
+import { harnessTriageGate } from './triage-gate.js';
+import { autoDispositionObservation, promoteObservation, } from './triage-persist.js';
+import { mintAdr } from './mint-adr.js';
+import { LIFECYCLE_CAS_CONTENTION } from './advancing-lock.js';
+import { decide, DisallowedOutcomeError, } from './decision-engine.js';
+import { APPLY_ALLOWED_OUTCOMES, buildApplyDecisionInput, harnessApplyDecider, } from './apply-decide.js';
+import { persistSurfacedQuestions, } from './surface-persist.js';
+import { applyAnsweredQuestions, } from './apply-persist.js';
+import { detectAnsweredMergeAction, performMergeAction, } from './apply-merge-action.js';
+/**
+ * The **`advance` verb SKELETON** (prd `advance-loop`, task
+ * `advance-verb-resolver`, US #1/5/6/18). `advance` is the SIBLING top-level verb
+ * (NOT a `do` subcommand — `do` subcommands are REJECTED in the prd) that drives
+ * a `work/` item ONE lifecycle rung toward "ready/built", reusing the SAME shared
+ * `prefix:arg` resolver `do` uses (extended with the `obs:` namespace, see
+ * {@link resolveAdvanceArg}).
+ *
+ * This module delivers the **classify → lock → execute SKELETON** — the contract
+ * both drivers (the later one-shot/loop tasks) wrap:
+ *
+ *   1. **classify** — read-only, NO model, NO lock: read the item's two signals
+ *      (`needsAnswers` + the sidecar's answered-state) and call the pure
+ *      {@link classifyTick} to get the rung kind. A CAS loser will have spent ONLY
+ *      this free classification.
+ *   2. **lock** — take the `advancing` CAS borrow ({@link acquireAdvancingLock})
+ *      for the classified rung, keyed on the item's `<type>-<slug>` identity. The
+ *      expensive (agent/model) phase is ALWAYS post-lock, so a loser backs off
+ *      having done ~nothing (a TOCTOU between classify and CAS is harmless — only
+ *      the free classification is wasted, and the loser never starts model work).
+ *   3. **execute** — WINNER ONLY: dispatch the classified rung to the
+ *      {@link RungExecutor} seam, then release the borrow.
+ *
+ * The **rung BODIES** are now ALL filled (their own tasks): `surface`
+ * (`advance-rung-surface`), `apply` (`advance-rung-apply`), and
+ * `triage-observation` (`advance-rung-triage`) dispatch through the clearly-named
+ * executor SEAM ({@link RungExecutor}); the build/task rungs ORCHESTRATE
+ * `do`/`do prd:`. What this verb does NOT do (LATER tasks):
+ *   - The two **DRIVERS** (one-shot sequential / loop) + `-n` + the gate-FAMILY
+ *     WIRING that resolves `autoBuild`/`autoTask`/`observationTriage` and threads
+ *     them into the build/task gate composition — task `advance-drivers-and-gates`.
+ *     (This verb already RESPECTS `observationTriage` in the triage rung — the gate's
+ *     resolution chain + the build/task gate composition is the drivers task.)
+ *   - The bare `advance` (eligible-SET) form — it needs the pool scan / driver, so
+ *     the verb here is a SINGLE named-item tick; the bare form errors clearly
+ *     ("needs the driver task"). See the `## Decisions` block in the task.
+ *
+ * The build-task / task-spec rungs ORCHESTRATE the existing `do` / `do spec:`
+ * machinery ({@link performDo}) — `advance` is a driver layered ON TOP, NEVER a
+ * peer that duplicates the build/task path (ONE build path, ONE task path —
+ * US #6).
+ */
+const DEFAULT_ARBITER = 'origin';
+/**
+ * Map the resolver's namespace onto the sidecar type. The `spec` namespace maps
+ * to the `spec` sidecar type, so `advance spec:<slug>` resolves its
+ * signals/folders (`FOLDERS_FOR_TYPE['spec']`) and orchestrates `do spec:<slug>`.
+ */
+function sidecarTypeFor(namespace) {
+    return namespace === 'observation'
+        ? 'observation'
+        : namespace === 'spec'
+            ? 'spec'
+            : 'task';
+}
+/**
+ * Read an item's two CLASSIFY signals off disk (read-only, NO model, NO lock):
+ *   - `needsAnswers` from the item-body frontmatter (searching the lifecycle
+ *     folders the type may rest in), and
+ *   - the ACTIVE sidecar (`work/questions/<type>-<slug>.md`) parsed when present.
+ *
+ * Identity-keyed: the sidecar path derives PURELY from `<type>-<slug>` (it
+ * survives the item's `git mv`s with no lock-step move). Returns
+ * `needsAnswers:undefined` when no item file is found (the classifier treats it
+ * as "not gated", an ANALYSE rung) — the verb's job here is to wire the two
+ * signals, not to assert the item exists (that is the rung's concern).
+ */
+export function readItemSignals(input) {
+    const { repoPath, type, slug, item } = input;
+    const needsAnswers = readNeedsAnswers(repoPath, type, slug);
+    const sidecarRel = sidecarPathFor(item);
+    const sidecarAbs = join(repoPath, sidecarRel);
+    let sidecar;
+    if (existsSync(sidecarAbs)) {
+        sidecar = parseSidecar(readFileSync(sidecarAbs, 'utf8'));
+    }
+    return { needsAnswers, sidecar };
+}
+/**
+ * The lifecycle folders each item type may rest in (frontmatter source). After
+ * the capstone cut-over (task
+ * `cutover-retire-slicing-advancing-markers-and-trim-folder-sets`) the transient
+ * `tasking/` folder is GONE — a prd rests in `prds/ready` (source) or
+ * `prds/tasked` (tasked); while it is being tasked the body STAYS in
+ * `prds/ready` (the lock no longer moves it), so `tasking/` is never a
+ * frontmatter source.
+ *
+ * STAGING IS INCLUDED (`tasks-backlog` / `prds-proposed`): with `surfaceStaging`
+ * on (the user-visible default) the lifecycle surface pool enumerates
+ * `needsAnswers` items resting in STAGING as `task:`/`prd:` legs
+ * (`lifecycle-gather.ts`). The rung CLASSIFIER's signal read MUST see those
+ * staged bodies, or `needsAnswers` reads back `undefined`, the classifier
+ * mis-routes the item to the BUILD rung, and claim dies with "not found on
+ * origin/main" (observation
+ * `advance-task-folder-set-omits-tasks-backlog-staged-surface-items-misroute-to-build`).
+ * This is the staging-inclusive set its sibling `apply-persist.ts`
+ * (`APPLY_LIFECYCLE_FOLDERS`) already uses — kept in step here. BUILD/claim
+ * eligibility is UNCHANGED (still pool-only; staging items stay non-claimable):
+ * only the rung-classifier's frontmatter-source folders widen.
+ */
+const FOLDERS_FOR_TYPE = {
+    task: ['tasks-backlog', 'tasks-ready', 'in-progress', 'done'],
+    // `spec` rests in the parent-spec regime folders (a `spec:<slug>` legs
+    // frontmatter-source read resolves against these).
+    spec: ['specs-proposed', 'specs-ready', 'specs-tasked'],
+    observation: ['observations'],
+};
+/** Read `needsAnswers` off the FIRST `work/<folder>/<slug>.md` that exists. */
+function readNeedsAnswers(repoPath, type, slug) {
+    for (const folder of FOLDERS_FOR_TYPE[type]) {
+        const abs = workItemPath(repoPath, folder, slug);
+        if (existsSync(abs)) {
+            return parseFrontmatter(readFileSync(abs, 'utf8')).needsAnswers;
+        }
+    }
+    return undefined;
+}
+/**
+ * The PRODUCTION rung executor: build/task rungs ORCHESTRATE the existing
+ * `do`/`do prd:` machinery ({@link performDo}); the `surface`/`apply`/
+ * `triage-observation` rung bodies are filled by their own tasks
+ * ({@link surfaceRung} / {@link applyRung} / {@link triageRung}). It NEVER
+ * re-implements the build/task path — it hands the resolved arg to `performDo`,
+ * which spans both namespaces (the task path is the `do prd:` rung the prd's
+ * 2026-06-09 UPDATE confirms routes through `performIntegration`).
+ */
+export const defaultRungExecutor = {
+    async buildTask(input) {
+        return orchestrateDo(input);
+    },
+    async taskSpec(input) {
+        return orchestrateDo(input);
+    },
+    async triageObservation(input) {
+        return triageRung(input);
+    },
+    async surface(input) {
+        return surfaceRung(input);
+    },
+    async apply(input) {
+        return applyRung(input);
+    },
+};
+/**
+ * ORCHESTRATE `do`/`do spec:` for the build-task / task-spec rungs: hand the
+ * resolved namespaced identity to {@link performDo} (the ONE build path / ONE
+ * task path). `advance` is a driver ON TOP — it does NOT duplicate `do`. The
+ * `do` outcome is mapped back onto the tick's outcome surface.
+ */
+async function orchestrateDo(input) {
+    const { item, context } = input;
+    const base = context.doOptions;
+    if (base === undefined) {
+        // The skeleton can classify + lock + DISPATCH without `do` options wired
+        // (the driver task threads them). Report it honestly rather than crash —
+        // the orchestration TARGET is `performDo`, named here, not re-implemented.
+        return {
+            exitCode: 1,
+            outcome: 'usage-error',
+            message: `advance would ORCHESTRATE \`do ${item}\` for this rung, but no \`do\` ` +
+                `options were threaded into the tick (the driver task wires them).`,
+        };
+    }
+    // The ORCHESTRATION TARGET is `performDo` by DEFAULT (in-place, the cwd checkout
+    // IS the isolation), or the injected {@link AdvanceContext.doDriver} — the
+    // registry-set advance driver threads a PER-MIRROR JOB-WORKTREE driver so the
+    // daemon/CI build runs isolated off the mirror's arbiter. Either way `advance`
+    // ORCHESTRATES `do` (the ONE build path / ONE task path) — it does NOT duplicate it.
+    const driver = context.doDriver ?? performDo;
+    const result = await driver({ ...base, arg: item });
+    return {
+        exitCode: result.exitCode,
+        outcome: result.exitCode === 0 ? 'advanced' : mapDoOutcome(result),
+        message: result.message,
+    };
+}
+/** Map a non-zero `do` result onto the tick's outcome vocabulary. */
+function mapDoOutcome(result) {
+    switch (result.outcome) {
+        case 'lost':
+            return 'lost';
+        case 'contended':
+            return 'contended';
+        default:
+            return 'usage-error';
+    }
+}
+/**
+ * The SURFACE rung BODY (task `advance-rung-surface`, US #32/33): the FIRST rung
+ * filling the executor seam, establishing the spawn→emit→persist pattern the
+ * other rung bodies reuse. Under the `advancing` CAS lock (held by
+ * {@link performAdvance} BEFORE this runs — so the expensive spawn is POST-lock,
+ * winner-only), it:
+ *
+ *   1. spawns a FRESH-CONTEXT agent with `surface-questions` loaded (the
+ *      {@link SurfaceGate} seam, mirroring the review gate's `review` spawn) and
+ *      collects the EMITTED questions — the skill JUDGES, writes nothing; and
+ *   2. has the ENGINE ITSELF write/append them to the sidecar CAS-atomically AND
+ *      set `needsAnswers:true` in the SAME commit
+ *      ({@link persistSurfacedQuestions}) — the engine PERSISTS.
+ *
+ * Append-never-overwrite: a re-surface ADDS `qN+1` and flips a previously-all-
+ * answered sidecar back to not-all-answered (the persist owns that). An EMPTY
+ * emit (the skill's honest "no open judgement") writes nothing and reports it.
+ */
+async function surfaceRung(input) {
+    const { item, context } = input;
+    const note = context.note ?? (() => { });
+    const cwd = context.cwd;
+    // Locate the item file (the only thing the persist needs beyond the questions:
+    // the file to set `needsAnswers:true` on). The sidecar path is identity-derived,
+    // not folder-derived, so only the ITEM file's folder must be found.
+    const itemPath = findItemPath(cwd, input.namespace, input.slug);
+    if (itemPath === undefined) {
+        return vanishedSkip({ rung: 'surface', item });
+    }
+    // 1. SPAWN the fresh-context `surface-questions` agent (the skill JUDGES). The
+    //    expensive model work is POST-lock (the lock is held by `performAdvance`).
+    const gate = context.surfaceGate ?? harnessSurfaceGate();
+    let emit;
+    try {
+        emit = await gate({
+            item,
+            cwd,
+            surfaceModel: context.surfaceModel,
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            outcome: 'usage-error',
+            message: `surface ${item}: the surface-questions agent produced no usable emit (${detail}).`,
+        };
+    }
+    // 2. The ENGINE persists (the skill wrote nothing): append-or-create the sidecar
+    //    + set `needsAnswers:true` in ONE commit (CAS-atomic under the held lock).
+    const persist = context.surfacePersist ?? persistSurfacedQuestions;
+    const result = persist({
+        cwd,
+        item,
+        itemPath,
+        questions: toNewQuestions(emit),
+        note,
+    });
+    if (result.outcome === 'nothing') {
+        // LIMBO DETECTION (task `advance-surface-limbo-observation-loudly-instead-of-
+        // silent-no-op`): an untriaged observation with NO sidecar whose surfacer had
+        // nothing to ask is a TRAP — the human's triage answer may have been recorded
+        // in an in-BODY "Applied answers" block, but the engine reads triage-vs-
+        // settled only from the `triaged:` frontmatter marker (`ledger-read.ts`) and
+        // the promote path only from an answered `disposition: promote` SIDECAR
+        // (`triage-persist.ts`). Without either, the item is untriaged (re-enumerated
+        // every tick), un-surfaceable (nothing to ask), un-promotable (no sidecar) —
+        // a silent exit-0 no-op forever. Surface it LOUDLY instead.
+        const limbo = detectObservationLimbo(input);
+        if (limbo !== undefined) {
+            note(limbo);
+            return { exitCode: 1, outcome: 'usage-error', message: limbo };
+        }
+        return {
+            exitCode: 0,
+            outcome: 'no-op',
+            message: `surface ${item}: no open judgement — nothing surfaced.`,
+        };
+    }
+    return {
+        exitCode: 0,
+        outcome: 'advanced',
+        message: `surfaced ${result.entryCount} question(s) for ${item} → ${result.sidecarPath} ` +
+            `(needsAnswers:true, CAS-atomic).`,
+    };
+}
+/**
+ * Detect the OBSERVATION LIMBO shape (task `advance-surface-limbo-observation-
+ * loudly-instead-of-silent-no-op`): an observation whose triage answer was
+ * (mis-)authored in an in-body "Applied answers" block instead of the sidecar/
+ * frontmatter channels the engine reads. All four conditions must hold:
+ *
+ *   1. the item is an OBSERVATION;
+ *   2. its frontmatter has NO `triaged:` marker (untriaged per `ledger-read.ts`);
+ *   3. there is NO active question sidecar at `work/questions/observation-<slug>.md`;
+ *   4. the surfacer just returned empty (the caller — {@link surfaceRung} — only
+ *      calls this on the persist's `nothing` branch).
+ *
+ * Returns the loud diagnostic to emit (naming BOTH valid channels), or `undefined`
+ * when the shape does not match (the surfacer's empty is then the normal calm no-op).
+ * The engine does NOT (and will not) honour in-body disposition prose — one channel
+ * (the sidecar + `triaged:` frontmatter) keeps the loop honest.
+ */
+function detectObservationLimbo(input) {
+    if (input.namespace !== 'observation')
+        return undefined;
+    const { item, slug, context } = input;
+    const cwd = context.cwd;
+    const itemRel = findItemPath(cwd, input.namespace, slug);
+    if (itemRel === undefined)
+        return undefined;
+    const fm = parseFrontmatter(readFileSync(join(cwd, itemRel), 'utf8'));
+    if (fm.triaged !== undefined && fm.triaged !== '')
+        return undefined;
+    const sidecarRel = sidecarPathFor(item);
+    if (existsSync(join(cwd, sidecarRel)))
+        return undefined;
+    return (`observation \`${slug}\` is in a limbo: no \`triaged:\` frontmatter marker ` +
+        `AND no answered question sidecar at \`${sidecarRel}\`, but the surfacer has ` +
+        `nothing to ask. If a human triage decision (promote-slice / keep / duplicate) ` +
+        `has been recorded in the observation BODY, that channel is INVISIBLE to the ` +
+        `runner — author the sidecar, or set \`triaged:\` in frontmatter. The engine ` +
+        `does not (and will not) honour in-body disposition prose.`);
+}
+/**
+ * The observation TRIAGE rung BODY (task `advance-rung-triage`, US #16/17/23):
+ * the rung the classifier picks for an UNTRIAGED observation (`needsAnswers` not
+ * set, no sidecar). It is QUESTION-GATED BY DEFAULT: it surfaces a promote/keep/
+ * delete question and WAITS — so "is this worth building?" is NEVER decided
+ * autonomously. A CONSERVATIVE `observationTriage: 'auto'`-gated EXCEPTION (US #17,
+ * high bar) may auto-disposition ONLY the no-question cases:
+ *
+ *   - **default (question-gated):** delegate to {@link surfaceRung} — spawn the
+ *     `surface-questions` agent (it emits a PLAIN "what becomes of this signal?"
+ *     question — NO disposition token any more, task
+ *     `agentic-apply-retire-disposition-vocabulary`) and the ENGINE persists the
+ *     sidecar + `needsAnswers`. When the human answers, the AGENTIC apply decision
+ *     (not a stamped token) reads the answer + source and chooses what to DO.
+ *     Surface stays ALWAYS allowed (US #23) — this path runs under `ask`/`off`
+ *     (and `off` + an explicit `obs:` runs in this `ask`-mode).
+ *   - **`auto` exception:** ONLY under `observationTriage: 'auto'`, ask the
+ *     {@link TriageGate} whether the observation is a no-question case. If it emits
+ *     `auto: true` (`duplicate` → DELETE the redundant note; `map` → unambiguous
+ *     map onto an existing item), the engine auto-dispositions it WITHOUT a
+ *     question ({@link autoDispositionObservation}). It NEVER auto-deletes a
+ *     NON-duplicate (a `duplicate` discharges by deletion because it is a
+ *     redundant copy of an already-captured signal — nothing is lost) and NEVER
+ *     auto-promotes a judgement call (`auto: false` ⇒ fall back to the surface
+ *     question). Promotion is ALWAYS a human answer (the apply path).
+ *
+ * Under the `advancing` CAS lock (held by {@link performAdvance} BEFORE this runs),
+ * so the expensive spawn is POST-lock, winner-only.
+ */
+async function triageRung(input) {
+    const { item, context } = input;
+    const note = context.note ?? (() => { });
+    const cwd = context.cwd;
+    // The CONSERVATIVE auto-disposition EXCEPTION — ONLY under `observationTriage:
+    // 'auto'`. Under `'ask'`/`'off'`/unset (including `off` + an EXPLICIT obs:<slug>
+    // that bypassed the selection gate), EVERY untriaged observation surfaces the
+    // question (the always-allowed path), so "worth building?" is never decided
+    // autonomously — `off` + explicit runs in the conservative `ask`-mode.
+    if (context.observationTriage === 'auto') {
+        const itemPath = findItemPath(cwd, input.namespace, input.slug);
+        if (itemPath === undefined) {
+            return vanishedSkip({ rung: 'triage', item });
+        }
+        const gate = context.triageGate ?? harnessTriageGate();
+        let decision;
+        try {
+            decision = await gate({ item, cwd, triageModel: context.triageModel });
+        }
+        catch (err) {
+            // A gate failure is NOT a reason to auto-dispose — fall back to the SAFE
+            // question-gated path (surface the question), never the reverse.
+            const detail = err instanceof Error ? err.message : String(err);
+            note(`triage ${item}: the auto-triage gate produced no usable emit (${detail}); ` +
+                'falling back to the question-gated surface path.');
+            decision = { auto: false };
+        }
+        if (decision.auto === true) {
+            // A no-question case (duplicate / map) — auto-disposition WITHOUT a
+            // question. BOTH discharge the redundant note BY DELETION (a duplicate is a
+            // redundant copy; a map is already covered by the item it maps onto). There
+            // is no resting `triaged:keep` state any more. NEVER auto-deletes a
+            // NON-redundant signal; NEVER auto-promotes.
+            const dispose = context.autoDisposition ?? autoDispositionObservation;
+            const result = dispose({
+                cwd,
+                item,
+                itemPath,
+                kind: decision.kind,
+                existing: decision.existing,
+                reason: decision.reason,
+                note,
+            });
+            return { exitCode: 0, outcome: 'advanced', message: result.message };
+        }
+        // `auto: false` ⇒ a judgement call. Fall through to the surface question.
+    }
+    // DEFAULT (question-gated): surface a PLAIN "what becomes of this signal?"
+    // question + WAIT. This REUSES the surface rung verbatim (the `surface-questions`
+    // skill emits the triage question — NO disposition token any more, task
+    // `agentic-apply-retire-disposition-vocabulary`); the AGENTIC apply decision
+    // reads the human's answer + source and decides what to DO when it is answered.
+    return surfaceRung(input);
+}
+/**
+ * The APPLY rung BODY (task `advance-rung-apply`; AGENTIC apply, task
+ * `agentic-apply-retire-disposition-vocabulary`): when the classifier says `apply`
+ * (ALL sidecar entries answered), apply the HUMAN's answers.
+ *
+ * For a fully-answered OBSERVATION (and no caller-supplied follow-up batch), the
+ * apply rung is now AGENT-DRIVEN: it runs the shared `decide(input, allowedOutcomes)`
+ * engine ({@link decide}) over `(the answered question(s) + the SOURCE item + its
+ * type/context)` via the injected {@link ApplyDecider}, allowing the set
+ * `{task | prd | adr | delete | ask}` (= `{mint-task | mint-prd | mint-adr |
+ * delete-source | ask-follow-up}`; `adr` is now WIRED by task
+ * `agentic-apply-mint-adr-route`, which added the {@link mintAdr} route). The
+ * verdict ROUTES:
+ *   - `ask` → the EXISTING append/re-pause loop ({@link applyAnsweredQuestions}
+ *     with the follow-up appended; `needsAnswers:true` stays, re-pause in one
+ *     commit);
+ *   - `adr` → {@link mintAdr} (mint a SELF-CONTAINED ADR into `docs/adr/` + `git
+ *     rm` the source + sidecar in the SAME atomic commit; the SIBLING route for the
+ *     off-board target);
+ *   - `task` / `prd` → {@link promoteObservation} (mint a SELF-CONTAINED artifact +
+ *     `git rm` the source + sidecar in the SAME atomic commit); the artifact type
+ *     comes from the agent's VERDICT, NOT a human `promote-*` field;
+ *   - `delete` → {@link applyAnsweredQuestions} discharge-by-deletion (`git rm`
+ *     source + sidecar in one revertible commit, the reason in the commit message).
+ *
+ * For a TASK/PRD (answering its OWN open questions) or a caller-supplied follow-up
+ * batch, it delegates straight to {@link applyAnsweredQuestions} (resolve fully /
+ * re-pause) — the lifecycle path is untouched (a task/prd is dropped by its own
+ * lifecycle, not by a question answer).
+ *
+ * Under the `advancing` CAS lock (held by {@link performAdvance} BEFORE this runs
+ * — so the work is POST-lock, winner-only). ALWAYS allowed (no gate). NEVER
+ * invents an answer — it applies ONLY the human-authored `answer:` text; a
+ * subset-answered sidecar is not even classified `apply` (the classifier NO-OPs),
+ * asserted in the persist.
+ */
+async function applyRung(input) {
+    const { item, context } = input;
+    const note = context.note ?? (() => { });
+    const cwd = context.cwd;
+    const itemPath = findItemPath(cwd, input.namespace, input.slug);
+    if (itemPath === undefined) {
+        return vanishedSkip({ rung: 'apply', item });
+    }
+    // RUNNER-ACTION KIND-CHECK (task `apply-rung-merge-disposition`, prd
+    // `land-time-reverify-and-parallel-merge-ceiling`): an answered `kind: merge`
+    // sidecar entry is a DETERMINISTIC land action, NOT a content decision. It
+    // dispatches HERE (a sibling of the agentic `decide()`), keyed off the
+    // question kind + the human's plain `merge | hold | drop` answer, BEFORE the
+    // agentic decider runs. The dispatcher invokes the EXISTING land primitive
+    // (`performIntegration` with `committedRecovery: true` + `freshWorktreeGate:
+    // true`) through the EXISTING per-job worktree seam (`workspace.ts`
+    // `createJob` off the hub mirror) — it does NOT re-implement rebase / verify
+    // / advance and does NOT improvise a worktree or clone.
+    const mergeRoute = await maybeRunMergeAction(input, itemPath);
+    if (mergeRoute !== undefined) {
+        return mergeRoute;
+    }
+    // AGENTIC APPLY for an answered OBSERVATION (the subsumed triage rung): run the
+    // shared decision engine over the answer(s) + source, route the verdict. A
+    // caller-supplied follow-up batch (`applyFollowups`) bypasses the decision and
+    // re-pauses directly (a test/driver hook). TASK/PRD items resolve in place
+    // (their own lifecycle), so they skip the decision and fall through to the
+    // persist below.
+    const runAgenticDecision = input.namespace === 'observation' &&
+        !(context.applyFollowups && context.applyFollowups.length > 0);
+    if (runAgenticDecision) {
+        return applyAgenticDecision(input, itemPath);
+    }
+    const apply = context.applyPersist ?? applyAnsweredQuestions;
+    try {
+        const result = apply({
+            cwd,
+            item,
+            itemPath,
+            appendQuestions: context.applyFollowups,
+            note,
+        });
+        // Map the apply persist's outcome to the rung's outcome. `vanished` is the
+        // F3a clean-exit case (item was gone between capture and write, e.g. a
+        // concurrent promote); benign skip, exitCode 0, distinct from `no-op`.
+        const mapped = result.outcome === 'repaused'
+            ? 'no-op'
+            : result.outcome === 'vanished'
+                ? 'vanished'
+                : 'advanced';
+        return {
+            exitCode: 0,
+            outcome: mapped,
+            message: result.message,
+        };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            outcome: 'usage-error',
+            message: `apply ${item}: ${detail}`,
+        };
+    }
+}
+/**
+ * Dispatch an answered MERGE-QUESTION (a sidecar entry stamped `kind: merge` by
+ * the merge-question surfacer) through the EXISTING land primitive
+ * (`performIntegration` with `committedRecovery: true` + `freshWorktreeGate:
+ * true`) via the EXISTING per-job worktree seam (`workspace.ts` `createJob`).
+ * The deterministic SIBLING of the agentic `decide()` content-decision (PRD
+ * `land-time-reverify-and-parallel-merge-ceiling`, task
+ * `apply-rung-merge-disposition`; Stories #15, #16): a merge-acceptance has no
+ * judgement content (the human's plain `merge | hold | drop` answer IS the
+ * decision; the apply-time re-verify on the rebased tip is the real correctness
+ * gate), so the apply rung KIND-CHECKS the sidecar BEFORE the agentic decider.
+ *
+ * Returns `undefined` when there is no answered `kind: merge` entry to dispatch
+ * (the apply rung then proceeds to the existing path — agentic for
+ * observations, normal `applyAnsweredQuestions` for task/prd content questions).
+ * Returns a {@link RungExecResult} when the dispatcher handled the rung:
+ *
+ *   - `landed` / `already-integrated` ⇒ the kept commit landed on `main` (or
+ *     was already there); the dispatcher FALLS THROUGH to the normal apply path
+ *     so the answer is recorded in the item body + the sidecar is resolved.
+ *   - `refused` ⇒ the LAND was refused (RED re-verify on the rebased tip,
+ *     rebase conflict, or pre-checkout failure); `performIntegration` routed
+ *     the item to needs-attention through its own shared seam, so `main` never
+ *     received a failing tree. The apply rung SHORT-CIRCUITS — the sidecar is
+ *     LEFT IN PLACE so the open answer stays surfaced for a human follow-up.
+ *   - `restale` ⇒ `strictMergeApproval` was ON and the merge-base moved
+ *     between the surfacer's question and this apply; the apply rung appends
+ *     a follow-up question + re-pauses (the human re-confirms against the new
+ *     base).
+ *   - `hold` / `drop` ⇒ no land; fall through to the normal apply path so the
+ *     answer is recorded in body. The branch stays unmerged; a future
+ *     surfacer pass may re-emit a merge-question.
+ */
+async function maybeRunMergeAction(input, itemPath) {
+    const { item, context } = input;
+    const cwd = context.cwd;
+    const note = context.note ?? (() => { });
+    const detected = detectAnsweredMergeAction(cwd, item);
+    if (detected === undefined)
+        return undefined;
+    const handler = context.mergeAction ?? performMergeAction;
+    // The dispatcher needs a `workspacesDir` to cut a per-job worktree (the
+    // `createJob` seam). When unset (a caller that has not threaded it) we
+    // REFUSE cleanly rather than guess: a land without isolation is not the
+    // shape this dispatcher promises.
+    const workspacesDir = context.workspacesDir;
+    if (workspacesDir === undefined && context.mergeAction === undefined) {
+        const message = `apply ${item}: answered merge-question detected (kind=merge, answer=` +
+            `${detected.verb}) but no \`workspacesDir\` is threaded into the apply ` +
+            `rung — the dispatcher needs one to cut the per-job worktree via ` +
+            `\`workspace.ts\` \`createJob\`. NOT landing; the answer stays surfaced.`;
+        note(message);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+    let result;
+    try {
+        result = await handler({
+            action: detected,
+            item,
+            slug: input.slug,
+            cwd,
+            arbiter: context.arbiter ?? DEFAULT_ARBITER,
+            arbiterUrl: context.arbiterUrl,
+            workspacesDir: workspacesDir ?? '',
+            prepare: context.prepare,
+            verify: context.verify,
+            strictMergeApproval: context.strictMergeApproval,
+            note,
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        const message = `apply ${item}: answered merge-question dispatch raised (${detail}); NOT ` +
+            `landing; the answer stays surfaced.`;
+        note(message);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+    if (result.outcome === 'refused') {
+        // `main` never received a failing tree (performIntegration routed the
+        // bounce to needs-attention through its own shared seam). SHORT-CIRCUIT:
+        // leave the sidecar so the open answer stays surfaced — the apply rung
+        // MUST NOT also resolve it (the next surfacer / human will follow up).
+        note(result.message);
+        return { exitCode: 1, outcome: 'usage-error', message: result.message };
+    }
+    if (result.outcome === 'restale') {
+        // `strictMergeApproval` re-surface: append a follow-up question and
+        // re-pause. The previous answer stays recorded in the entry; the human
+        // re-confirms against the new merge-base in the appended question.
+        const apply = context.applyPersist ?? applyAnsweredQuestions;
+        try {
+            const applied = apply({
+                cwd,
+                item,
+                itemPath,
+                appendQuestions: [
+                    {
+                        question: `Merge-base for \`work/${input.slug}\` moved since your last ` +
+                            `answer (strictMergeApproval is ON). Re-confirm: still land?`,
+                        context: result.message,
+                        default: 'merge | hold | drop',
+                        kind: 'merge',
+                    },
+                ],
+                note,
+            });
+            return {
+                exitCode: 0,
+                outcome: 'no-op',
+                message: applied.message,
+            };
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                exitCode: 1,
+                outcome: 'usage-error',
+                message: `apply ${item}: re-surfacing the merge-question failed (${detail}).`,
+            };
+        }
+    }
+    // landed | already-integrated | hold | drop: the dispatcher's action is
+    // done; FALL THROUGH to the normal apply path so the answer is recorded in
+    // the item body + the sidecar is resolved.
+    note(result.message);
+    const apply = context.applyPersist ?? applyAnsweredQuestions;
+    try {
+        const applied = apply({ cwd, item, itemPath, note });
+        const mapped = applied.outcome === 'repaused'
+            ? 'no-op'
+            : applied.outcome === 'vanished'
+                ? 'vanished'
+                : 'advanced';
+        return {
+            exitCode: 0,
+            outcome: mapped,
+            message: `${result.message} ${applied.message}`,
+        };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            outcome: 'usage-error',
+            message: `apply ${item}: ${detail}`,
+        };
+    }
+}
+/**
+ * The cross-tick-window BENIGN SKIP shared by all three rungs that need to
+ * resolve an item file (surface / triage / apply). The lifecycle pool enumerated
+ * the item at scan-time, but by the time this leg ran a sibling parallel leg had
+ * already triaged/settled/deleted it. At the ~33-way CI matrix scale this is a
+ * CALM, EXPECTED condition — making it an exit-1 "a human must reconcile" turned
+ * the matrix into a wall of red. It is now a `vanished` outcome (`exitCode: 0`,
+ * distinguishable from `no-op`) carrying a clear message naming the rung + item.
+ * (See task `observation-identity-is-its-filename-not-a-foreign-slug`.)
+ */
+function vanishedSkip(input) {
+    return {
+        exitCode: 0,
+        outcome: 'vanished',
+        message: `advance classified the '${input.rung}' rung for ${input.item} but its ` +
+            `item file was gone from work/ by the time the leg ran (a sibling leg ` +
+            `likely triaged/settled/deleted it between enumerate and run) — benign ` +
+            `skip.`,
+    };
+}
+/**
+ * Find the item file `work/<folder>/<slug>.md` for a type, across the lifecycle
+ * folders it may rest in (the SAME folder set {@link readNeedsAnswers} searches).
+ * Returns the path RELATIVE to `cwd`, or `undefined` when no file exists.
+ */
+function findItemPath(cwd, namespace, slug) {
+    const type = sidecarTypeFor(namespace);
+    for (const folder of FOLDERS_FOR_TYPE[type]) {
+        const rel = workItemRel(folder, `${slug}.md`);
+        if (existsSync(join(cwd, rel))) {
+            return rel;
+        }
+    }
+    return undefined;
+}
+/**
+ * The AGENTIC apply DECISION for a fully-answered OBSERVATION (task
+ * `agentic-apply-retire-disposition-vocabulary`): run the shared
+ * `decide(input, allowedOutcomes)` engine over the answer(s) + source, then ROUTE
+ * the verdict. The artifact-type selection (task vs prd) comes from the agent's
+ * VERDICT, NOT a human `promote-*` field (which is retired). Replaces the old
+ * `answeredPromoteArtifact` + disposition picker.
+ *
+ *   - `ask` → append the follow-up question(s) + re-pause (the EXISTING loop, via
+ *     {@link applyAnsweredQuestions}'s `appendQuestions`);
+ *   - `task` / `prd` → {@link promoteObservation} (mint self-contained + delete
+ *     source in the same atomic commit);
+ *   - `adr` → {@link mintAdr} (mint a self-contained ADR into `docs/adr/` + delete
+ *     source in the same atomic commit; the SIBLING route for the off-board target,
+ *     task `agentic-apply-mint-adr-route`);
+ *   - `delete` → {@link applyAnsweredQuestions}'s discharge-by-deletion (`git rm`
+ *     source + sidecar in one revertible commit, the reason in the message).
+ *
+ * The allowed set is `{task | prd | adr | delete | ask}`; a verdict outside it is
+ * rejected by the engine's allowed-outcome guard ({@link DisallowedOutcomeError})
+ * and mapped onto a usage-error — never dispatched.
+ */
+async function applyAgenticDecision(input, itemPath) {
+    const { item, context } = input;
+    const note = context.note ?? (() => { });
+    const cwd = context.cwd;
+    const decisionInput = buildApplyDecisionInput({
+        item,
+        type: sidecarTypeFor(input.namespace),
+        itemPath,
+        cwd,
+        model: context.applyModel,
+    });
+    if (decisionInput === undefined) {
+        // No sidecar / item to decide over (a sibling leg removed it between classify
+        // and run) — the same benign clean-exit the persist's vanished branch gives.
+        return vanishedSkip({ rung: 'apply', item });
+    }
+    const decider = context.applyDecide ?? harnessApplyDecider();
+    let verdict;
+    try {
+        verdict = await decide(decisionInput, decider, APPLY_ALLOWED_OUTCOMES);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        // A DisallowedOutcomeError (e.g. a stubbed `adr` verdict) and an agent-failed
+        // parse both degrade HONESTLY onto a usage-error — never a silent dispatch.
+        const label = err instanceof DisallowedOutcomeError
+            ? `apply ${item}: the decision verdict is not an allowed outcome (${detail})`
+            : `apply ${item}: the decision agent produced no usable verdict (${detail})`;
+        return { exitCode: 1, outcome: 'usage-error', message: label };
+    }
+    if (verdict.outcome === 'ask') {
+        // ask-follow-up → the EXISTING append/re-pause loop. One BATCH of follow-ups.
+        const apply = context.applyPersist ?? applyAnsweredQuestions;
+        const question = (verdict.question ?? '').trim();
+        if (question === '') {
+            return {
+                exitCode: 1,
+                outcome: 'usage-error',
+                message: `apply ${item}: the decision agent chose 'ask' but emitted no follow-up question.`,
+            };
+        }
+        try {
+            const result = apply({
+                cwd,
+                item,
+                itemPath,
+                appendQuestions: [{ question }],
+                note,
+            });
+            return {
+                exitCode: 0,
+                outcome: result.outcome === 'vanished' ? 'vanished' : 'no-op',
+                message: result.message,
+            };
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                exitCode: 1,
+                outcome: 'usage-error',
+                message: `apply ${item}: ${detail}`,
+            };
+        }
+    }
+    if (verdict.outcome === 'task' || verdict.outcome === 'spec') {
+        // mint-task / mint-spec → CAS-create a SELF-CONTAINED artifact + delete the
+        // source + sidecar in the SAME commit (delete-on-promote, preserved). The
+        // verdict's drafted body (when present) seeds the new item; else the writer
+        // builds a self-contained body FROM the observation (carrying the answers +
+        // open-question scoping). The artifact type is the agent's VERDICT.
+        const promote = context.promote ?? promoteObservation;
+        const draftedBody = verdict.outcome === 'task' ? verdict.taskBody : verdict.specBody;
+        const draftedSlug = verdict.outcome === 'task' ? verdict.taskSlug : verdict.specSlug;
+        try {
+            const result = await promote({
+                cwd,
+                item,
+                itemPath,
+                artifact: verdict.outcome,
+                newSlug: context.promoteSlug ?? draftedSlug,
+                ...(draftedBody !== undefined && draftedBody.trim() !== ''
+                    ? { stubContent: draftedBody }
+                    : {}),
+                arbiter: context.arbiter,
+                // Lifecycle FAN-OUT: widen the CAS contention budget + jitter the retries
+                // so N parallel promote legs desync (task
+                // `jitter-and-widen-cas-contention-retry-for-lifecycle-fanout`).
+                contention: LIFECYCLE_CAS_CONTENTION,
+                note,
+            });
+            return {
+                exitCode: result.exitCode,
+                outcome: result.outcome === 'promoted'
+                    ? 'advanced'
+                    : result.outcome === 'lost'
+                        ? 'lost'
+                        : result.outcome === 'contended'
+                            ? 'contended'
+                            : 'usage-error',
+                message: result.message,
+            };
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                exitCode: 1,
+                outcome: 'usage-error',
+                message: `apply ${item}: ${detail}`,
+            };
+        }
+    }
+    if (verdict.outcome === 'adr') {
+        // mint-adr → CAS-create a SELF-CONTAINED ADR into `docs/adr/` + delete the
+        // source + sidecar in the SAME commit (delete-on-promote, preserved via the
+        // shared create-CAS). An ADR lives OUTSIDE the work board, so this is the
+        // SIBLING route (NOT a `promoteObservation` artifact type). The verdict's
+        // drafted body (when present) seeds the ADR; else `mintAdr` builds a
+        // self-contained body FROM the observation + the answered question(s).
+        const mint = context.mintAdr ?? mintAdr;
+        const answers = decisionInput.sidecar.entries.map((e) => ({
+            question: e.question,
+            answer: e.answer,
+        }));
+        try {
+            const result = await mint({
+                cwd,
+                item,
+                itemPath,
+                adrSlug: context.promoteSlug ?? verdict.adrSlug,
+                ...(verdict.adrTitle !== undefined ? { adrTitle: verdict.adrTitle } : {}),
+                ...(verdict.adrBody !== undefined && verdict.adrBody.trim() !== ''
+                    ? { adrBody: verdict.adrBody }
+                    : {}),
+                answers,
+                arbiter: context.arbiter,
+                // Lifecycle FAN-OUT: widen the CAS contention budget + jitter the retries
+                // so N parallel mint-adr legs desync (task
+                // `jitter-and-widen-cas-contention-retry-for-lifecycle-fanout`).
+                contention: LIFECYCLE_CAS_CONTENTION,
+                note,
+            });
+            return {
+                exitCode: result.exitCode,
+                outcome: result.outcome === 'minted'
+                    ? 'advanced'
+                    : result.outcome === 'lost'
+                        ? 'lost'
+                        : result.outcome === 'contended'
+                            ? 'contended'
+                            : 'usage-error',
+                message: result.message,
+            };
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                exitCode: 1,
+                outcome: 'usage-error',
+                message: `apply ${item}: ${detail}`,
+            };
+        }
+    }
+    // delete-source → discharge by deletion (DIRECT, no confirm — decision 12). The
+    // human's answer is the source of truth; the deletion is a single revertible
+    // commit with the reason in the message.
+    const apply = context.applyPersist ?? applyAnsweredQuestions;
+    try {
+        const result = apply({
+            cwd,
+            item,
+            itemPath,
+            discharge: { reason: verdict.deleteReason ?? '' },
+            note,
+        });
+        return {
+            exitCode: 0,
+            outcome: result.outcome === 'vanished' ? 'vanished' : 'advanced',
+            message: result.message,
+        };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            outcome: 'usage-error',
+            message: `apply ${item}: ${detail}`,
+        };
+    }
+}
+/**
+ * Run ONE `advance` tick over a SINGLE named item: classify → lock → dispatch →
+ * release. The pure tick the drivers (later tasks) wrap. The expensive phase is
+ * ALWAYS post-lock — a CAS loser backs off having done ONLY the free
+ * classification (it never reaches the executor).
+ */
+export async function performAdvance(options) {
+    const note = options.note ?? (() => { });
+    const cwd = options.cwd;
+    const repoPath = options.repoPath ?? cwd;
+    const arbiter = options.arbiter ?? DEFAULT_ARBITER;
+    // {@link performAdvance} is the SINGLE-item tick. The bare `advance`
+    // (eligible-SET) form is the DRIVER's job ({@link performAdvanceAuto} in
+    // `advance-drivers.ts`, which selects over the pool + runs THIS tick per item) —
+    // the tick itself REQUIRES a named item, so an empty arg here is a usage error
+    // (the CLI dispatches the bare form to the driver before reaching here).
+    if (options.arg === undefined || options.arg.trim() === '') {
+        const message = '`advance` with no item is the eligible-SET form (the one-shot driver). ' +
+            'The single-item tick needs a named item: ' +
+            '`advance <slug>` / `advance prd:<slug>` / `advance obs:<slug>`.';
+        note(message);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+    // 1. RESOLVE the arg via the SHARED resolver (extended with `obs:`). `advance`
+    //    spans task / prd / observation; a collision / bad arg is a loud usage error.
+    let resolved;
+    try {
+        resolved = resolveAdvanceArg({
+            arg: options.arg,
+            repoPath,
+            read: options.read ?? ledgerRead,
+        });
+    }
+    catch (err) {
+        if (err instanceof SlugResolutionError) {
+            return { exitCode: 1, outcome: 'usage-error', message: err.message };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+    const type = sidecarTypeFor(resolved.namespace);
+    const item = `${resolved.namespace}:${resolved.slug}`;
+    // 2. CLASSIFY — read-only, NO model, NO lock. Read the two signals + run the
+    //    pure classifier. This is the ONLY work a CAS loser will have spent.
+    const readSignals = options.readSignals ?? readItemSignals;
+    const signals = readSignals({ repoPath, type, slug: resolved.slug, item });
+    const classification = classifyTick({
+        type,
+        needsAnswers: signals.needsAnswers,
+        sidecar: signals.sidecar,
+    });
+    // A NO-OP (pending sidecar / nothing eligible) or an invariant violation never
+    // takes the lock — there is nothing to execute, so do NOT pay the CAS.
+    if (classification.kind === 'no-op') {
+        const message = `no-op for ${item} (${classification.reason ?? 'nothing to advance'}).`;
+        note(message);
+        return {
+            exitCode: 0,
+            outcome: 'no-op',
+            rung: 'no-op',
+            slug: resolved.slug,
+            message,
+        };
+    }
+    if (classification.kind === 'invariant-violation') {
+        const message = `refusing to advance ${item}: the \`needsAnswers\` flag and the sidecar ` +
+            `disagree (${classification.reason ?? 'invariant violation'}). ` +
+            `A human must reconcile them.`;
+        note(message);
+        return {
+            exitCode: 1,
+            outcome: 'invariant-violation',
+            rung: 'invariant-violation',
+            slug: resolved.slug,
+            message,
+        };
+    }
+    // 3. LOCK — take the `advancing` CAS borrow for the classified rung, keyed on
+    //    the item's `<type>-<slug>` identity. The expensive phase is POST-lock.
+    //
+    //    UNIFIED PER-ITEM LOCK, TREE-LESS RUNGS ONLY (prd
+    //    `ledger-status-per-item-lock-refs` US #1/#3/#18; ADR
+    //    `ledger-status-on-per-item-lock-refs`). The rung kind is KNOWN here
+    //    (`classification.kind`, classified pre-lock), so the tree-less-only policy
+    //    lives HERE — where the rung is known — and `advancing-lock.ts` stays
+    //    rung-agnostic (it only learns "unified or not" via `acquireUnified`). For a
+    //    TREE-LESS rung (`surface`/`apply`/`triage-observation`) the advancing acquire
+    //    ALSO takes the item's unified lock (`action: advance`) — these rungs have NO
+    //    inner `do`, so the unified hold is what realises advance∥claim / advance∥task
+    //    exclusion. For a BUILD-TASK / TASK-PRD rung we do NOT take the unified lock
+    //    at the advance layer: `performAdvance` ORCHESTRATES an inner `performDo` that
+    //    ITSELF acquires the SAME `task-<slug>`/`prd-<slug>` ref (the create-only CAS
+    //    with NO re-entrancy/auto-steal, per the ADR), so taking it here too would
+    //    DEADLOCK the tick against itself. The inner `do`'s claim/task lock IS the
+    //    single exclusion point for those rungs. The `work/advancing/<entry>.md` marker
+    //    CAS is KEPT for ALL rungs (its removal is the capstone task #9).
+    const unifiedForRung = isTreeLessRung(classification.kind);
+    const acquire = options.acquireLock ??
+        ((lockItem) => acquireAdvancingLock({
+            item: lockItem,
+            cwd,
+            arbiter,
+            acquireUnified: unifiedForRung,
+            note,
+        }));
+    const lock = await acquire(item);
+    if (lock.exitCode !== 0) {
+        // A CAS LOSER (exit 2) or contended (exit 3) backs off having spent ONLY the
+        // free classification above — it never reaches the executor.
+        return {
+            exitCode: lock.exitCode,
+            outcome: lock.outcome === 'lost' ? 'lost' : 'contended',
+            rung: classification.kind,
+            slug: resolved.slug,
+            message: lock.message,
+        };
+    }
+    // 4. EXECUTE — WINNER ONLY: dispatch the classified rung to the executor seam,
+    //    then ALWAYS release the borrow (the item never moved; release is clean).
+    const executor = options.executor ?? defaultRungExecutor;
+    const release = options.releaseLock ??
+        ((lockItem) => releaseAdvancingLock({
+            item: lockItem,
+            cwd,
+            arbiter,
+            releaseUnified: unifiedForRung,
+            note,
+        }));
+    try {
+        const exec = await dispatchRung(executor, {
+            item,
+            namespace: resolved.namespace,
+            slug: resolved.slug,
+            classification,
+            context: {
+                cwd,
+                arbiter,
+                doOptions: options.doOptions,
+                doDriver: options.doDriver,
+                surfaceGate: options.surfaceGate,
+                surfaceModel: options.surfaceModel,
+                surfacePersist: options.surfacePersist,
+                applyPersist: options.applyPersist,
+                applyFollowups: options.applyFollowups,
+                applyDecide: options.applyDecide,
+                applyModel: options.applyModel,
+                observationTriage: options.observationTriage,
+                triageGate: options.triageGate,
+                triageModel: options.triageModel,
+                autoDisposition: options.autoDisposition,
+                promote: options.promote,
+                mintAdr: options.mintAdr,
+                promoteSlug: options.promoteSlug,
+                // The answered-merge LAND dispatch context (task
+                // `apply-rung-merge-disposition`): threaded into the apply rung's
+                // kind-check for a `kind: merge` runner-action.
+                workspacesDir: options.workspacesDir,
+                arbiterUrl: options.arbiterUrl,
+                prepare: options.prepare,
+                verify: options.verify,
+                strictMergeApproval: options.strictMergeApproval,
+                mergeAction: options.mergeAction,
+                note,
+            },
+        });
+        return {
+            exitCode: exec.exitCode,
+            outcome: exec.outcome,
+            rung: classification.kind,
+            slug: resolved.slug,
+            message: exec.message,
+        };
+    }
+    finally {
+        await release(item);
+    }
+}
+/**
+ * Is this a TREE-LESS rung (`surface`/`apply`/`triage-observation`) — the rungs
+ * that have NO inner `performDo`, so the advancing acquire must ALSO take the
+ * unified per-item lock (`action: advance`) to realise advance∥claim / advance∥task
+ * exclusion? The build/task rungs (`build-task`/`task-spec`) are the inverse:
+ * their inner `do` holds the SAME unified ref, so the advance layer must NOT take
+ * it (it would deadlock the tick against itself). `no-op`/`invariant-violation`
+ * never reach the lock step. This is the single place the tree-less-only policy
+ * is expressed (the rung is known here); `advancing-lock.ts` stays rung-agnostic.
+ */
+function isTreeLessRung(kind) {
+    return (kind === 'surface' || kind === 'apply' || kind === 'triage-observation');
+}
+/** Dispatch the classified rung to the executor seam (winner-only). */
+function dispatchRung(executor, input) {
+    switch (input.classification.kind) {
+        case 'build-task':
+            return executor.buildTask(input);
+        case 'task-spec':
+            return executor.taskSpec(input);
+        case 'triage-observation':
+            return executor.triageObservation(input);
+        case 'surface':
+            return executor.surface(input);
+        case 'apply':
+            return executor.apply(input);
+        default:
+            // `no-op` / `invariant-violation` never reach here (handled pre-lock).
+            return Promise.resolve({
+                exitCode: 1,
+                outcome: 'usage-error',
+                message: `unexpected rung kind '${input.classification.kind}' at dispatch.`,
+            });
+    }
+}
+//# sourceMappingURL=advance.js.map