dorfl 0.1.2 → 0.2.0

package/dist/advance.js

@@ -18,6 +18,7 @@ import { APPLY_ALLOWED_OUTCOMES, buildApplyDecisionInput, harnessApplyDecider, }
 import { persistSurfacedQuestions, } from './surface-persist.js';
 import { applyAnsweredQuestions, } from './apply-persist.js';
 import { detectAnsweredMergeAction, performMergeAction, } from './apply-merge-action.js';
+import { detectAnsweredStuckAction, performStuckAction, } from './apply-stuck-action.js';
 /**
  * The **`advance` verb SKELETON** (spec `advance-loop`, task
  * `advance-verb-resolver`, US #1/5/6/18). `advance` is the SIBLING top-level verb
@@ -223,7 +224,7 @@ function mapDoOutcome(result) {
  * 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) {
+async function surfaceRung(input, surfaceOpts = {}) {
     const { item, context } = input;
     const note = context.note ?? (() => { });
     const cwd = context.cwd;
@@ -234,50 +235,80 @@ async function surfaceRung(input) {
     if (itemPath === undefined) {
         return vanishedSkip({ rung: 'surface', item });
     }
+    // DETERMINISTIC BASE QUESTIONS (the triage rung's "always ask" contract): the
+    // caller may pass engine-built questions that MUST be surfaced regardless of the
+    // agent. They are added ONLY on the FIRST pass (no sidecar yet) — on a re-surface
+    // the sidecar already carries them, and `appendQuestions` does NOT dedup, so
+    // re-adding would duplicate. When base questions are present the agent is
+    // ADDITIVE ONLY and its flake/empty is NON-FATAL (the base question still lands).
+    const baseQuestions = surfaceOpts.baseQuestions ?? [];
+    const hasBase = baseQuestions.length > 0;
+    const sidecarExists = existsSync(join(cwd, sidecarPathFor(item)));
+    const baseToAdd = hasBase && !sidecarExists ? baseQuestions : [];
     // 1. SPAWN the fresh-context `surface-questions` agent (the skill JUDGES). The
     //    expensive model work is POST-lock (the lock is held by `performAdvance`).
+    //
+    // SHORT-CIRCUIT (primary/load-bearing half of task
+    // `surface-short-circuit-already-triaged-observations-and-harden-skill-empty-emit`):
+    // an OBSERVATION with provably no open judgement (frontmatter `needsAnswers` NOT
+    // true, no non-empty `## Open questions` section, no pending sidecar) — the
+    // typical shape of a decision-record / already-triaged note — deterministically
+    // yields `{questions: []}` WITHOUT round-tripping the flaky surface-questions
+    // agent (source observation
+    // `surface-questions-agent-still-emits-no-parseable-questions-on-decision-record-obs-2026-07-10`).
+    // The loud-error contract from
+    // `advance-surface-limbo-observation-loudly-instead-of-silent-no-op` is
+    // PRESERVED for the observations that DO reach the agent — this only spares the
+    // ones that provably have nothing to ask. Conservative: fires only on
+    // observations; tasks/specs still always ask.
     const gate = context.surfaceGate ?? harnessSurfaceGate();
     let emit;
-    try {
-        emit = await gate({
-            item,
-            cwd,
-            surfaceModel: context.surfaceModel,
-        });
+    if (isNothingToSurfaceObservation(cwd, input, itemPath, sidecarExists)) {
+        note(`surface ${item}: auto-triaged (no open questions, no sidecar) — skipped agent.`);
+        emit = { questions: [] };
     }
-    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}).`,
-        };
+    else {
+        try {
+            emit = await gate({
+                item,
+                cwd,
+                surfaceModel: context.surfaceModel,
+            });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            if (!hasBase) {
+                return {
+                    exitCode: 1,
+                    outcome: 'usage-error',
+                    message: `surface ${item}: the surface-questions agent produced no usable emit (${detail}).`,
+                };
+            }
+            // The agent flaked but we have a deterministic base question to surface: the
+            // flake is NON-FATAL. Treat the agent's extras as empty and carry on (the
+            // base triage question still lands, so the human can triage via the sidecar).
+            note(`surface ${item}: the surface-questions agent produced no usable emit ` +
+                `(${detail}); surfacing the deterministic question(s) only.`);
+            emit = { questions: [] };
+        }
     }
     // 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).
+    //    Base questions FIRST (q1…), then the agent's additive extras.
     const persist = context.surfacePersist ?? persistSurfacedQuestions;
     const result = persist({
         cwd,
         item,
         itemPath,
-        questions: toNewQuestions(emit),
+        questions: [...baseToAdd, ...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 };
-        }
+        // The agent had nothing to ask AND there was no base question to add (a
+        // task/spec surface, or a re-surface whose base question is already present).
+        // This is the calm "no open judgement" no-op — no sidecar written. (There is
+        // no "limbo" any more: the triage rung ALWAYS passes a base question on the
+        // first pass, so an untriaged observation can never fall here empty-handed.)
         return {
             exitCode: 0,
             outcome: 'no-op',
@@ -292,42 +323,105 @@ async function surfaceRung(input) {
     };
 }
 /**
- * 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:
+ * Would this OBSERVATION provably surface `{questions: []}` — i.e. is there no
+ * open judgement anywhere on it? Cheap read-only predicate the surface rung uses
+ * to skip the flaky agent round-trip for already-triaged / decision-record notes
+ * (task
+ * `surface-short-circuit-already-triaged-observations-and-harden-skill-empty-emit`;
+ * source observation
+ * `surface-questions-agent-still-emits-no-parseable-questions-on-decision-record-obs-2026-07-10`).
  *
- *   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).
+ * Fires ONLY when ALL of these hold (conservative — err on the side of STILL
+ * calling the agent if uncertain):
+ *   - the item's namespace is `observation` (tasks/specs are out of scope here —
+ *     they carry no engine-owned base question and a false-positive there would
+ *     silently drop a real question the author asked for);
+ *   - the item body's frontmatter does NOT set `needsAnswers: true` (an author
+ *     who set the flag is explicitly asking for the agent's pass);
+ *   - the body carries no non-empty `## Open questions` section (empty /
+ *     whitespace-only sections don't count as judgement);
+ *   - there is no pending open-question sidecar for the item (same signal the
+ *     classifier's invariant-1 read uses — the sidecar path is identity-derived).
  *
- * 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.
+ * The decision-record shape (a `Decision (…)` line and/or `## Alternatives
+ * considered` section) is a HINT, not required — the four conditions above are
+ * load-bearing on their own.
  */
-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.`);
+function isNothingToSurfaceObservation(cwd, input, itemPath, sidecarExists) {
+    if (input.namespace !== 'observation') {
+        return false;
+    }
+    if (sidecarExists) {
+        return false;
+    }
+    let content;
+    try {
+        content = readFileSync(join(cwd, itemPath), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const fm = parseFrontmatter(content);
+    if (fm.needsAnswers === true) {
+        return false;
+    }
+    if (hasNonEmptyOpenQuestionsSection(content)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Does the body carry a non-empty `## Open questions` section? Tolerates the
+ * `## Open questions to NOT guess` variant the capture-signal skill writes (same
+ * pattern the triage split uses). Whitespace-only / "none" markers count as
+ * empty.
+ */
+function hasNonEmptyOpenQuestionsSection(content) {
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    const startIdx = lines.findIndex((l) => /^##\s+Open questions\b/i.test(l));
+    if (startIdx === -1) {
+        return false;
+    }
+    let endIdx = lines.length;
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        if (/^##\s+/.test(lines[i])) {
+            endIdx = i;
+            break;
+        }
+    }
+    const body = lines
+        .slice(startIdx + 1, endIdx)
+        .join('\n')
+        .trim();
+    if (body === '') {
+        return false;
+    }
+    // A single "none" / "n/a" marker line — treat as empty (author signalled "no
+    // open judgement" explicitly).
+    if (/^(?:none|n\/a|-|_+)\.?$/i.test(body)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * The DETERMINISTIC triage question the triage rung ALWAYS surfaces for an
+ * untriaged observation (the "no limbo, ever" contract). It is engine-built (NOT
+ * LLM output), so it can never be zeroed out or flake: every untriaged observation
+ * gets exactly this question, and the human answers it via the sidecar — a record,
+ * a rationale note, and a fresh-bug signal are all treated identically (the human
+ * decides the disposition). The `surface-questions` agent runs ADDITIVELY on top,
+ * adding any extra pointed questions it extracts from the body.
+ */
+export function buildTriageBaseQuestion() {
+    return {
+        question: 'What should become of this observation? Reply with a disposition and a ' +
+            'reason: resolve (settle it, keep the note on record — say why), promote ' +
+            '(mint a task / spec / adr — say which and why), delete (redundant or ' +
+            'obsolete — say why), or duplicate (maps onto an existing item — name it).',
+        context: 'The engine records your disposition from the answer (no token needed); an ' +
+            'answered promote mints the artifact, resolve keeps the note settled, ' +
+            'delete/duplicate discharge it.',
+    };
 }
 /**
  * The observation TRIAGE rung BODY (task `advance-rung-triage`, US #16/17/23):
@@ -362,6 +456,27 @@ async function triageRung(input) {
     const { item, context } = input;
     const note = context.note ?? (() => { });
     const cwd = context.cwd;
+    // SETTLED GUARD: a `triaged:` frontmatter marker means a human already
+    // dispositioned this observation, so it DROPS OUT of the triage pool. The pool
+    // enumeration already excludes it, but an EXPLICIT `obs:<slug>` bypasses the pool
+    // gate and still classifies as `triage-observation` — so re-check the marker here
+    // and no-op rather than surfacing a FRESH triage question on an already-settled
+    // note. (Replaces the old `detectObservationLimbo` special-case: there is no
+    // limbo any more — an UNtriaged observation always surfaces the deterministic
+    // question below; a SETTLED one is a calm no-op here.)
+    {
+        const itemRel = findItemPath(cwd, input.namespace, input.slug);
+        if (itemRel !== undefined) {
+            const fm = parseFrontmatter(readFileSync(join(cwd, itemRel), 'utf8'));
+            if (fm.triaged !== undefined && fm.triaged !== '') {
+                return {
+                    exitCode: 0,
+                    outcome: 'no-op',
+                    message: `triage ${item}: already triaged (triaged:${fm.triaged}) — nothing to do.`,
+                };
+            }
+        }
+    }
     // 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
@@ -410,7 +525,12 @@ async function triageRung(input) {
     // 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);
+    //
+    // ALWAYS-ASK (the "no limbo" contract): pass the DETERMINISTIC triage question as
+    // the base question, so an untriaged observation ALWAYS surfaces it (q1) even if
+    // the `surface-questions` agent emits empty or flakes. The agent is ADDITIVE:
+    // any pointed questions it extracts from the body are appended after q1.
+    return surfaceRung(input, { baseQuestions: [buildTriageBaseQuestion()] });
 }
 /**
  * The APPLY rung BODY (task `advance-rung-apply`; AGENTIC apply, task
@@ -421,8 +541,9 @@ async function triageRung(input) {
  * 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-spec | mint-adr |
- * delete-source | ask-follow-up}`; `adr` is now WIRED by task
+ * `{task | spec | adr | dispose | resolve | ask}` (= `{mint-task | mint-spec |
+ * mint-adr | dispose-source | resolve-no-mint | 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}
@@ -431,11 +552,22 @@ async function triageRung(input) {
  *   - `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 +
+ *   - `task` / `spec` → {@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).
+ *   - `resolve` → {@link applyAnsweredQuestions} resolve-fully (harvest answers
+ *     into the body, clear `needsAnswers`, delete the sidecar; the note is
+ *     RETAINED — the sibling of `dispose` that mints nothing but keeps the note);
+ *   - `dispose` → {@link applyAnsweredQuestions} regime-polymorphic disposal
+ *     (task `apply-disposition-delete-to-dispose-regime-polymorphic`, spec
+ *     `surface-stuck-as-questions-and-retire-stuck-lock-state` decision #5): an
+ *     OBSERVATION is `git rm`-ed in one revertible commit (notes leave by
+ *     deletion; reason in the message); a TASK is `git mv`-ed to
+ *     `tasks/cancelled/` (RETAINED, `reason:` written into the moved body); a
+ *     SPEC is `git mv`-ed to `specs/dropped/` (RETAINED). Making `dispose`
+ *     polymorphic (rather than a literal `delete`) makes "a task cannot be
+ *     hard-deleted by the apply rung, only disposed to its terminal" true BY
+ *     CONSTRUCTION.
  *
  * For a TASK/SPEC (answering its OWN open questions) or a caller-supplied follow-up
  * batch, it delegates straight to {@link applyAnsweredQuestions} (resolve fully /
@@ -470,6 +602,25 @@ async function applyRung(input) {
     if (mergeRoute !== undefined) {
         return mergeRoute;
     }
+    // RUNNER-ACTION KIND-CHECK for `kind: 'stuck'` (task
+    // `apply-resolve-reset-flag-discards-work-branch`, spec
+    // `surface-stuck-as-questions-and-retire-stuck-lock-state` decision #6): a
+    // bounced TASK surfaces as a `kind: 'stuck'` question; the human's plain
+    // `keep | reset | cancel` answer drives one of the three deterministic
+    // verbs. The DIRECT SIBLING of `maybeRunMergeAction` above (there is NO
+    // agentic decider on the TASK apply path — `runAgenticDecision` fires only
+    // for observations — so a bounced task's answer MUST be sourced from a
+    // deterministic parse+dispatch, not a widened decider). `keep` and `reset`
+    // fall through to the normal fall-through persist (with the branch
+    // pre-deleted on `reset` via the SHARED
+    // `deleteRemoteWorkBranchIfPresent`); `cancel` dispatches through
+    // `applyAnsweredQuestions`' `dispose` option (task →
+    // `tasks/cancelled/`); `refused` short-circuits with the sidecar left in
+    // place for a re-answer.
+    const stuckRoute = await maybeRunStuckAction(input, itemPath);
+    if (stuckRoute !== undefined) {
+        return stuckRoute;
+    }
     // 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
@@ -595,8 +746,13 @@ async function maybeRunMergeAction(input, itemPath) {
         // 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).
+        // Outcome tag `merge-refused` (task `merge-action-nits-followup` nit 2):
+        // distinct from `usage-error` — which is reserved for genuine caller-usage
+        // errors (e.g. the workspacesDir-unset guard above) — so reviewers can
+        // grep the refusal-on-rebased-tip signal without confusing it with a
+        // misuse. `exitCode: 1` preserved.
         note(result.message);
-        return { exitCode: 1, outcome: 'usage-error', message: result.message };
+        return { exitCode: 1, outcome: 'merge-refused', message: result.message };
     }
     if (result.outcome === 'restale') {
         // `strictMergeApproval` re-surface: append a follow-up question and
@@ -661,6 +817,105 @@ async function maybeRunMergeAction(input, itemPath) {
         };
     }
 }
+/**
+ * Dispatch an answered STUCK-QUESTION (a sidecar entry stamped `kind: 'stuck'`
+ * by the bounce-surface path) through the deterministic
+ * {@link performStuckAction} sibling. The DIRECT SIBLING of
+ * {@link maybeRunMergeAction} for the `kind: 'stuck'` axis (task
+ * `apply-resolve-reset-flag-discards-work-branch`, spec
+ * `surface-stuck-as-questions-and-retire-stuck-lock-state` decision #6):
+ *
+ *   - `keep`   -> fall through to today's normal `applyAnsweredQuestions`
+ *                 resolve (branch untouched; continue-from-WIP);
+ *   - `reset`  -> the SHARED `deleteRemoteWorkBranchIfPresent` primitive
+ *                 discards the remote `work/task-<slug>` FIRST, then the
+ *                 normal fall-through persist clears `needsAnswers`. Safely
+ *                 IDEMPOTENT when no branch exists (an item never built) —
+ *                 an `already-gone` push is tolerated as a no-op;
+ *   - `cancel` -> fall through to the normal persist with the `dispose`
+ *                 option (`git mv -> tasks/cancelled/`), the answer text
+ *                 recorded as the human's reason;
+ *   - `refused` -> a REAL push-delete failure aborted the discard;
+ *                  SHORT-CIRCUIT with the sidecar left in place so the human
+ *                  sees the failure and re-answers (matches the
+ *                  `requeue --reset` abort-on-failed-delete contract).
+ *
+ * Returns `undefined` when no answered `kind: 'stuck'` entry is present (the
+ * apply rung then proceeds to the existing path — an unrelated content
+ * question falls through to the normal `applyAnsweredQuestions` /
+ * agentic-decider path).
+ */
+async function maybeRunStuckAction(input, itemPath) {
+    const { item, context } = input;
+    const cwd = context.cwd;
+    const note = context.note ?? (() => { });
+    const detected = detectAnsweredStuckAction(cwd, item);
+    if (detected === undefined)
+        return undefined;
+    const handler = context.stuckAction ?? performStuckAction;
+    let result;
+    try {
+        result = await handler({
+            action: detected,
+            item,
+            slug: input.slug,
+            cwd,
+            arbiter: context.arbiter ?? DEFAULT_ARBITER,
+            note,
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        const message = `apply ${item}: answered stuck-question dispatch raised (${detail}); NOT ` +
+            `clearing needsAnswers; the sidecar stays surfaced.`;
+        note(message);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+    if (result.outcome === 'refused') {
+        // The arbiter delete FAILED (not `already-gone`); we MUST NOT clear
+        // needsAnswers, because that would leave the item claimable while still
+        // carrying the WIP branch we meant to discard — the very stale-continue
+        // trap the `requeue --reset` path guards against. Leave the sidecar in
+        // place for a re-answer.
+        note(result.message);
+        return { exitCode: 1, outcome: 'usage-error', message: result.message };
+    }
+    note(result.message);
+    const apply = context.applyPersist ?? applyAnsweredQuestions;
+    try {
+        const applyOptions = {
+            cwd,
+            item,
+            itemPath,
+            note,
+        };
+        if (result.outcome === 'cancel') {
+            // The human's answer text is the dispose reason (verbatim), so the
+            // terminal `tasks/cancelled/` body records WHY — the same reason
+            // contract the agentic `dispose` verdict uses.
+            applyOptions.dispose = { reason: detected.entry.answer.trim() };
+        }
+        const applied = apply(applyOptions);
+        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
@@ -706,15 +961,24 @@ function findItemPath(cwd, namespace, slug) {
  *
  *   - `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
+ *   - `task` / `spec` → {@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).
+ *   - `resolve` → {@link applyAnsweredQuestions}'s resolve-fully path (harvest the
+ *     answers into `## Applied answers`, strip the open-questions block, clear
+ *     `needsAnswers`, DELETE the sidecar — the note is RETAINED). The sibling of
+ *     `dispose` that KEEPS the note instead of moving/rm-ing it (task
+ *     `apply-decide-resolve-verdict-mint-nothing`);
+ *   - `dispose` → {@link applyAnsweredQuestions}'s regime-polymorphic disposal
+ *     (task `apply-disposition-delete-to-dispose-regime-polymorphic`): an
+ *     observation is `git rm`-ed in one revertible commit (reason in the
+ *     message); a task is `git mv`-ed to `tasks/cancelled/` (reason written into
+ *     the body); a spec is `git mv`-ed to `specs/dropped/`.
  *
- * The allowed set is `{task | prd | adr | delete | ask}`; a verdict outside it is
+ * The allowed set is `{task | spec | adr | dispose | resolve | ask}`; a verdict
+ * outside it is
  * rejected by the engine's allowed-outcome guard ({@link DisallowedOutcomeError})
  * and mapped onto a usage-error — never dispatched.
  */
@@ -812,11 +1076,13 @@ async function applyAgenticDecision(input, itemPath) {
                 exitCode: result.exitCode,
                 outcome: result.outcome === 'promoted'
                     ? 'advanced'
-                    : result.outcome === 'lost'
-                        ? 'lost'
-                        : result.outcome === 'contended'
-                            ? 'contended'
-                            : 'usage-error',
+                    : result.outcome === 'already-triaged'
+                        ? 'already-triaged'
+                        : result.outcome === 'lost'
+                            ? 'lost'
+                            : result.outcome === 'contended'
+                                ? 'contended'
+                                : 'usage-error',
                 message: result.message,
             };
         }
@@ -880,16 +1146,53 @@ async function applyAgenticDecision(input, itemPath) {
             };
         }
     }
-    // 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.
+    if (verdict.outcome === 'resolve') {
+        // resolve-no-mint → the EXISTING resolve-fully path (task
+        // `apply-decide-resolve-verdict-mint-nothing`). The answer SETTLES the item
+        // with NOTHING to mint and the note RETAINED: call `applyAnsweredQuestions`
+        // with NEITHER `appendQuestions` (re-pause) NOR `dispose` (drop/terminal), so it
+        // takes the default resolve-fully branch — harvest the answers into `##
+        // Applied answers`, strip the marker-fenced open-questions block, clear
+        // `needsAnswers`, and DELETE the sidecar in ONE atomic commit. Invariant-clean
+        // (`needsAnswers:false` ⟺ no active sidecar). The note file is KEPT (this is
+        // the sibling of `dispose`, which git-rm's it or moves it to a terminal). `resolveReason` is advisory
+        // context only; the durable disposition record is the harvested `## Applied
+        // answers` block the resolve-fully path writes (NOT a separate convention).
+        const apply = context.applyPersist ?? applyAnsweredQuestions;
+        try {
+            const result = apply({ cwd, item, itemPath, 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}`,
+            };
+        }
+    }
+    // dispose-source → regime-polymorphic disposal (DIRECT, no confirm — decision
+    // 12; task `apply-disposition-delete-to-dispose-regime-polymorphic`, spec
+    // `surface-stuck-as-questions-and-retire-stuck-lock-state` decision #5). The
+    // human's answer is the source of truth; the persist chooses the on-disk
+    // effect by the source's regime: an OBSERVATION is `git rm`-ed in one
+    // revertible commit (reason in the message, git history = archive); a TASK is
+    // `git mv`-ed to `tasks/cancelled/` (RETAINED, `reason:` written into the
+    // moved body); a SPEC is `git mv`-ed to `specs/dropped/` (RETAINED). A task
+    // cannot be hard-deleted by the apply rung — dispose is the only path off the
+    // board.
     const apply = context.applyPersist ?? applyAnsweredQuestions;
     try {
         const result = apply({
             cwd,
             item,
             itemPath,
-            discharge: { reason: verdict.deleteReason ?? '' },
+            dispose: { reason: verdict.disposeReason ?? '' },
             note,
         });
         return {
@@ -1069,6 +1372,10 @@ export async function performAdvance(options) {
                 verify: options.verify,
                 strictMergeApproval: options.strictMergeApproval,
                 mergeAction: options.mergeAction,
+                // The answered-stuck-question dispatch context (task
+                // `apply-resolve-reset-flag-discards-work-branch`): threaded into the
+                // apply rung's kind-check for a `kind: 'stuck'` runner-action.
+                stuckAction: options.stuckAction,
                 note,
             },
         });