dorfl 0.1.1 → 0.2.0

package/src/advance.ts

@@ -66,13 +66,19 @@ import {
 	type MergeActionHandler,
 	type MergeActionResult,
 } from './apply-merge-action.js';
+import {
+	detectAnsweredStuckAction,
+	performStuckAction,
+	type StuckActionHandler,
+	type StuckActionResult,
+} from './apply-stuck-action.js';
 import type {VerifyConfig} from './verify.js';
 import type {NewQuestion} from './sidecar.js';
 
 /**
- * The **`advance` verb SKELETON** (prd `advance-loop`, task
+ * The **`advance` verb SKELETON** (spec `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
+ * (NOT a `do` subcommand — `do` subcommands are REJECTED in the spec) 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}).
@@ -96,7 +102,7 @@ import type {NewQuestion} from './sidecar.js';
  * (`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):
+ * `do`/`do spec:`. 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`.
@@ -131,11 +137,34 @@ export type AdvanceOutcome =
 	| 'advanced'
 	| 'no-op'
 	| 'vanished'
+	/**
+	 * The triage/apply promote leg found the task it would mint ALREADY EXISTS on
+	 * the arbiter AND was PROVABLY minted from THIS observation in a prior run (its
+	 * `promotedFrom:` back-reference matches) — an idempotency fact, so the source was
+	 * already triaged. `exitCode: 0` (the matrix tolerates it, so it does NOT red CI),
+	 * DISTINGUISHABLE from `vanished` (item file gone) and `no-op` (calm classify) so
+	 * reviewers can grep it. The LOUD `lost` (exit 2) is reserved for a genuine
+	 * concurrent-create race with an UNRELATED same-path item, where a retry helps.
+	 * (task `observation-triage-already-triaged-benign-skip`; sibling of the
+	 * stale-snapshot / held-lock CI-noise fixes.)
+	 */
+	| 'already-triaged'
 	| 'usage-error'
 	| 'lost'
 	| 'contended'
 	| 'not-implemented'
-	| 'invariant-violation';
+	| 'invariant-violation'
+	/**
+	 * The answered-merge dispatcher REFUSED the land on the rebased tip (RED
+	 * re-verify, rebase conflict, or a pre-checkout failure). Distinct from
+	 * `usage-error` (which is reserved for genuine caller-usage errors — e.g.
+	 * the workspacesDir-unset guard below). `performIntegration` has already
+	 * routed the item to needs-attention via its shared seam, so `main` never
+	 * received a failing tree; the sidecar is LEFT IN PLACE so the open answer
+	 * stays surfaced for a human follow-up. `exitCode: 1`.
+	 * (task `merge-action-nits-followup` nit 2.)
+	 */
+	| 'merge-refused';
 
 /** Maps onto the claim-CAS exit codes (identical semantics). */
 export type AdvanceExitCode = 0 | 1 | 2 | 3;
@@ -144,7 +173,7 @@ export type AdvanceExitCode = 0 | 1 | 2 | 3;
  * The injectable rung-executor SEAM — WHAT happens once the tick has classified a
  * rung AND won the `advancing` lock. It is the boundary between the skeleton (this
  * task) and the rung bodies (later tasks): the surface/apply/triage rungs are
- * filled by their own tasks; the build/task rungs ORCHESTRATE `do`/`do prd:`.
+ * filled by their own tasks; the build/task rungs ORCHESTRATE `do`/`do spec:`.
  *
  * Production wires {@link defaultRungExecutor}; tests inject a spy to assert the
  * classify→lock→dispatch ORDER (and that a CAS loser never reaches the executor).
@@ -164,15 +193,15 @@ export interface RungExecutor {
 
 /** What a rung executor is handed: the resolved identity + the run context. */
 export interface RungExecInput {
-	/** The canonical namespaced identity (`task:<slug>` / `prd:<slug>` / `observation:<slug>`). */
+	/** The canonical namespaced identity (`task:<slug>` / `spec:<slug>` / `observation:<slug>`). */
 	item: string;
-	/** The resolved namespace (`task` / `prd` / `observation`). */
+	/** The resolved namespace (`task` / `spec` / `observation`). */
 	namespace: SlugNamespace;
 	/** The bare slug. */
 	slug: string;
 	/** The classification that selected this rung (the two signals are visible). */
 	classification: TickClassification;
-	/** The tick's run context (cwd, arbiter, …) — threaded to `do`/`do prd:`. */
+	/** The tick's run context (cwd, arbiter, …) — threaded to `do`/`do spec:`. */
 	context: AdvanceContext;
 }
 
@@ -250,14 +279,14 @@ export interface AdvanceContext {
 	 * The AGENTIC apply DECISION seam (task
 	 * `agentic-apply-retire-disposition-vocabulary`): the fresh-context decision
 	 * agent the apply rung runs on a fully-answered OBSERVATION to choose what to DO
-	 * with the signal (`mint-task | mint-prd | mint-adr | delete-source |
-	 * ask-follow-up`),
+	 * with the signal (`mint-task | mint-spec | mint-adr | dispose-source |
+	 * resolve-no-mint | ask-follow-up`),
 	 * grounded in the source's full context. It is the injected
 	 * {@link ApplyDecider} the shared `decide(input, allowedOutcomes)` engine runs;
 	 * tests inject a CANNED verdict (no model). `undefined` ⇒ the apply rung defaults
 	 * to {@link harnessApplyDecider} (a NullHarness, no real model) so the seam is
 	 * never a crash — but the CLI threads the real harness-backed decider. The
-	 * verdict's type SELECTION (task vs prd vs adr) replaces the retired `promote-*`
+	 * verdict's type SELECTION (task vs spec vs adr) replaces the retired `promote-*`
 	 * disposition token; `adr` is now WIRED (task `agentic-apply-mint-adr-route`).
 	 */
 	applyDecide?: ApplyDecider;
@@ -322,10 +351,14 @@ export interface AdvanceContext {
 	 * The execution working area (`workspacesDir`, default `~/.dorfl`) the
 	 * answered-merge LAND uses to cut a per-job worktree from the hub mirror
 	 * (via `workspace.ts` `createJob`). Unset ⇒ no `workspacesDir` is available
-	 * to the dispatcher, so an answered `kind: merge` entry is REFUSED (clean
-	 * surfacing); the answer stays for a follow-up. The registry-set advance
-	 * driver threads the resolved `workspacesDir` here.
-	 * (prd `land-time-reverify-and-parallel-merge-ceiling`, task
+	 * to the dispatcher, so an answered `kind: merge` entry is REFUSED as a
+	 * genuine caller-usage error (outcome `usage-error`, `exitCode: 1`) and the
+	 * answer stays surfaced for a follow-up — threading `workspacesDir` is the
+	 * caller's contract, and forgetting it gets this documented clean refusal
+	 * rather than a mysterious downstream failure (task
+	 * `merge-action-nits-followup` nit 3). The registry-set advance driver
+	 * threads the resolved `workspacesDir` here.
+	 * (spec `land-time-reverify-and-parallel-merge-ceiling`, task
 	 * `apply-rung-merge-disposition`)
 	 */
 	workspacesDir?: string;
@@ -353,7 +386,7 @@ export interface AdvanceContext {
 	/**
 	 * Resolved `strictMergeApproval` boolean (sibling task
 	 * `strict-merge-approval-gate`). Default OFF ⇒ honour the prior approval +
-	 * land on a green re-verify (cheap, the PRD-applied OQ6 default). ON ⇒
+	 * land on a green re-verify (cheap, the SPEC-applied OQ6 default). ON ⇒
 	 * re-surface the merge-question when the merge-base moved between the
 	 * surfacer's question and this apply (the host-agnostic analogue of
 	 * GitHub's "dismiss stale approvals when the base changes").
@@ -370,6 +403,20 @@ export interface AdvanceContext {
 	 * WITHOUT spinning up a hub mirror or running real verify.
 	 */
 	mergeAction?: MergeActionHandler;
+	/**
+	 * The stuck-action dispatch SEAM (task
+	 * `apply-resolve-reset-flag-discards-work-branch`, spec
+	 * `surface-stuck-as-questions-and-retire-stuck-lock-state`): the
+	 * deterministic answer-driven runner-action handler the apply rung invokes
+	 * BEFORE the fall-through persist when an answered `kind: 'stuck'` entry
+	 * (the shape the bounce-surface path stamps) is detected. Production wires
+	 * {@link performStuckAction} (drives the shared
+	 * `deleteRemoteWorkBranchIfPresent` primitive on `reset`); tests inject a
+	 * stub so they assert on the apply-rung's `keep | reset | refused | cancel`
+	 * routing WITHOUT touching a real arbiter. The deterministic sibling of
+	 * {@link mergeAction} for the `kind: 'stuck'` axis.
+	 */
+	stuckAction?: StuckActionHandler;
 	/** Sink for human-readable progress notes. */
 	note?: (message: string) => void;
 }
@@ -377,7 +424,7 @@ export interface AdvanceContext {
 /** The options one `advance` tick consumes. */
 export interface AdvanceOptions extends AdvanceContext {
 	/**
-	 * The raw CLI slug argument: bare (= task), `task:<slug>`, `prd:<slug>`, or
+	 * The raw CLI slug argument: bare (= task), `task:<slug>`, `spec:<slug>`, or
 	 * `obs:<slug>` / `observation:<slug>`. Omit/empty ⇒ the bare eligible-SET form,
 	 * which needs the driver task (a clear error here — see `## Decisions`).
 	 */
@@ -420,7 +467,7 @@ export interface ItemSignals {
 export interface ReadSignalsInput {
 	/** The repo working-tree root. */
 	repoPath: string;
-	/** The item type (task / prd / observation). */
+	/** The item type (task / spec / observation). */
 	type: SidecarType;
 	/** The bare slug. */
 	slug: string;
@@ -469,14 +516,14 @@ export function readItemSignals(input: ReadSignalsInput): ItemSignals {
  * 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
+ * `tasking/` folder is GONE — a spec rests in `specs/ready` (source) or
+ * `specs/tasked` (tasked); while it is being tasked the body STAYS in
+ * `specs/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
+ * `needsAnswers` items resting in STAGING as `task:`/`spec:` 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
@@ -512,11 +559,11 @@ function readNeedsAnswers(
 
 /**
  * The PRODUCTION rung executor: build/task rungs ORCHESTRATE the existing
- * `do`/`do prd:` machinery ({@link performDo}); the `surface`/`apply`/
+ * `do`/`do spec:` 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
+ * which spans both namespaces (the task path is the `do spec:` rung the spec's
  * 2026-06-09 UPDATE confirms routes through `performIntegration`).
  */
 export const defaultRungExecutor: RungExecutor = {
@@ -602,7 +649,10 @@ function mapDoOutcome(result: DoResult): AdvanceOutcome {
  * 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: RungExecInput): Promise<RungExecResult> {
+async function surfaceRung(
+	input: RungExecInput,
+	surfaceOpts: {baseQuestions?: NewQuestion[]} = {},
+): Promise<RungExecResult> {
 	const {item, context} = input;
 	const note = context.note ?? (() => {});
 	const cwd = context.cwd;
@@ -615,50 +665,84 @@ async function surfaceRung(input: RungExecInput): Promise<RungExecResult> {
 		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,
-		});
-	} 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}).`,
-		};
+	if (isNothingToSurfaceObservation(cwd, input, itemPath, sidecarExists)) {
+		note(
+			`surface ${item}: auto-triaged (no open questions, no sidecar) — skipped agent.`,
+		);
+		emit = {questions: []};
+	} 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',
@@ -675,40 +759,113 @@ async function surfaceRung(input: RungExecInput): Promise<RungExecResult> {
 }
 
 /**
- * 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: RungExecInput): string | undefined {
-	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: string,
+	input: RungExecInput,
+	itemPath: string,
+	sidecarExists: boolean,
+): boolean {
+	if (input.namespace !== 'observation') {
+		return false;
+	}
+	if (sidecarExists) {
+		return false;
+	}
+	let content: string;
+	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: string): boolean {
+	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(): NewQuestion {
+	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.',
+	};
 }
 
 /**
@@ -745,6 +902,28 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
 	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
@@ -795,7 +974,12 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
 	// 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()]});
 }
 
 /**
@@ -807,8 +991,9 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
  * 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
+ * `{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}
@@ -817,15 +1002,26 @@ async function triageRung(input: RungExecInput): Promise<RungExecResult> {
  *   - `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/PRD (answering its OWN open questions) or a caller-supplied follow-up
+ * For a TASK/SPEC (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
+ * re-pause) — the lifecycle path is untouched (a task/spec is dropped by its own
  * lifecycle, not by a question answer).
  *
  * Under the `advancing` CAS lock (held by {@link performAdvance} BEFORE this runs
@@ -844,7 +1040,7 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
 		return vanishedSkip({rung: 'apply', item});
 	}
 
-	// RUNNER-ACTION KIND-CHECK (task `apply-rung-merge-disposition`, prd
+	// RUNNER-ACTION KIND-CHECK (task `apply-rung-merge-disposition`, spec
 	// `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
@@ -859,10 +1055,30 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
 		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
-	// re-pauses directly (a test/driver hook). TASK/PRD items resolve in place
+	// re-pauses directly (a test/driver hook). TASK/SPEC items resolve in place
 	// (their own lifecycle), so they skip the decision and fall through to the
 	// persist below.
 	const runAgenticDecision =
@@ -910,7 +1126,7 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
  * 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
+ * The deterministic SIBLING of the agentic `decide()` content-decision (SPEC
  * `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
@@ -919,7 +1135,7 @@ async function applyRung(input: RungExecInput): Promise<RungExecResult> {
  *
  * 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).
+ * observations, normal `applyAnsweredQuestions` for task/spec content questions).
  * Returns a {@link RungExecResult} when the dispatcher handled the rung:
  *
  *   - `landed` / `already-integrated` ⇒ the kept commit landed on `main` (or
@@ -995,8 +1211,13 @@ async function maybeRunMergeAction(
 		// 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') {
@@ -1064,6 +1285,113 @@ async function maybeRunMergeAction(
 	}
 }
 
+/**
+ * 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: RungExecInput,
+	itemPath: string,
+): Promise<RungExecResult | undefined> {
+	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: StuckActionResult;
+	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: ApplyAnsweredQuestionsOptions = {
+			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: AdvanceOutcome =
+			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
@@ -1113,21 +1441,30 @@ function findItemPath(
  * 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
+ * the verdict. The artifact-type selection (task vs spec) 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
+ *   - `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.
  */
@@ -1234,11 +1571,13 @@ async function applyAgenticDecision(
 				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,
 			};
 		} catch (err) {
@@ -1303,16 +1642,53 @@ async function applyAgenticDecision(
 		}
 	}
 
-	// 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 {
@@ -1353,13 +1729,13 @@ export async function performAdvance(
 		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>`.';
+			'`advance <slug>` / `advance spec:<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.
+	//    spans task / spec / observation; a collision / bad arg is a loud usage error.
 	let resolved;
 	try {
 		resolved = resolveAdvanceArg({
@@ -1419,7 +1795,7 @@ export async function performAdvance(
 	// 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
+	//    UNIFIED PER-ITEM LOCK, TREE-LESS RUNGS ONLY (spec
 	//    `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
@@ -1428,7 +1804,7 @@ export async function performAdvance(
 	//    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
+	//    exclusion. For a BUILD-TASK / TASK-SPEC 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
@@ -1506,6 +1882,10 @@ export async function performAdvance(
 				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,
 			},
 		});