dorfl 0.0.0 → 0.1.0

package/src/cwd-section.ts

@@ -0,0 +1,392 @@
+import {run, runAsync, localMainDivergence} from './git.js';
+import {isParticipatingRepo} from './detect.js';
+import {scanRepoPaths, type RepoReport} from './scan.js';
+import {arbiterStatus} from './arbiter.js';
+import {listMirrors} from './registry.js';
+import {encodeRepoKey, mirrorPath} from './repo-mirror.js';
+import {heldTaskSlugsStrict, listItemLockEntries} from './item-lock.js';
+import type {Config} from './config.js';
+import type {ConfigOverrideMap} from './config-override.js';
+
+/**
+ * The CWD-LOCAL section of `scan`/`status` (the `scan-status-read-cwd-repo`
+ * task). When a command runs INSIDE a participating repo, it ALSO reports that
+ * CURRENT repo as a clearly-labelled, separately-counted LOCAL section, in
+ * addition to (NEVER merged into) the cross-repo REGISTRY view.
+ *
+ * The consistency rule this module enforces (do not violate):
+ *
+ *   - The local section reads the LOCAL WORKING TREE (`scanRepoPaths([cwd])`) —
+ *     your possibly-uncommitted / unpushed / diverged state — NOT the bare
+ *     mirror-ref the registry reads. The two reads have DIFFERENT freshness +
+ *     storage models, so they are kept VISUALLY + SEMANTICALLY distinct, each
+ *     with its OWN count. A merged grand total would be true in NEITHER model.
+ *   - **The SELECTION pool is REMOTE-AUTHORITATIVE + FAILS CLOSED offline.** The
+ *     held-lock set (`refs/dorfl/lock/*`) lives ONLY on the arbiter, and it is the
+ *     LOAD-BEARING signal that keeps a claimed / in-flight item out of the
+ *     eligible pool (the body no longer moves on claim). So the cwd pool reads the
+ *     held set from the arbiter (`heldTaskSlugsStrict`) and SUBTRACTS it before
+ *     reporting eligibility — exactly as the registry `scan()` does. When the cwd
+ *     repo has a configured arbiter but that read cannot reach it, eligibility is
+ *     UNKNOWN and the section THROWS rather than emit a confident-but-wrong pool
+ *     (the
+ *     `scan-cwd-selection-pool-read-local-skips-held-lock-subtraction-offline-must-fail`
+ *     decision: offline selection fails; there is NO `--local` fallback). This is
+ *     the SELECTION concern; the divergence line is the SURFACE concern and keeps
+ *     its graceful warn+last-known behaviour.
+ *   - **Fetch-first ALSO for the cwd** (the maintainer's explicit ask): the cwd
+ *     repo's arbiter is fetched BEFORE the divergence is computed (the local
+ *     working tree is the LEAST authoritative view), reusing the
+ *     `scan-status-fetch-first` fetch+warn+fallback discipline — a failed fetch
+ *     WARNS and falls back to last-known, NEVER errors out (a read-only command
+ *     must degrade, ADR §5/§6).
+ *   - The divergence-vs-arbiter is shown with the `main-divergence-guard` framing
+ *     (`local main is N commits ahead of <arbiter>/main` = unpushed).
+ *   - **De-dup:** if the cwd repo is ALSO registered, it is shown ONCE in the
+ *     local section marked "(also registered)" and its registry row is dropped
+ *     from the registry list — so the same repo never appears as two mystery
+ *     rows with possibly-disagreeing states.
+ *
+ * The registry model is UNCHANGED by this: `scan`/`status` are read-only DISPLAY
+ * surfaces; the daemon (`run`) + the arbiter CAS still claim against the REGISTRY
+ * only. Showing the cwd changes nothing about where claims happen.
+ */
+
+/** The cwd repo's arbiter, as resolved for the local section's divergence line. */
+export interface CwdArbiter {
+	/** The arbiter remote name inspected (e.g. `arbiter` / `origin`). */
+	remote: string;
+	/** True iff the cwd repo has a remote with that name. */
+	configured: boolean;
+	/** The arbiter's URL, when configured. */
+	url?: string;
+	/**
+	 * True iff the cwd repo's arbiter `main` was FRESHLY FETCHED before the
+	 * divergence was computed. False ⇒ the fetch failed (offline / no arbiter) and
+	 * the divergence reflects the last-known arbiter ref (a warning was emitted).
+	 */
+	fetched: boolean;
+	/** Commits local `main` is AHEAD of `<arbiter>/main` (unpushed). */
+	ahead: number;
+	/** Commits local `main` is BEHIND `<arbiter>/main` (needs a pull/rebase). */
+	behind: number;
+}
+
+/** The cwd-local section report (one repo: the current working tree). */
+export interface CwdSection {
+	/** Absolute path to the cwd repo. */
+	path: string;
+	/**
+	 * True iff the cwd is a participating repo (a `work/` tree with lifecycle
+	 * content in any pool — see {@link isParticipatingRepo}, NOT `tasks/ready/`
+	 * alone). When false, every other field is absent — there is NO local section.
+	 */
+	participating: boolean;
+	/** The cwd repo's `work/` lifecycle, read from the LOCAL WORKING TREE. */
+	repo?: RepoReport;
+	/** Total backlog item count for the cwd (its OWN count, never merged). */
+	totalItems?: number;
+	/** Eligible item count for the cwd (its OWN count). */
+	totalEligible?: number;
+	/**
+	 * True iff the cwd repo is ALSO in the registry (its arbiter URL keys to a
+	 * registered hub mirror). When true the cwd is de-duped: shown once here,
+	 * marked "(also registered)", and its registry row is dropped.
+	 */
+	alsoRegistered?: boolean;
+	/**
+	 * The registered hub-mirror PATH the cwd de-dups against (so the registry view
+	 * can drop that row). Present only when {@link alsoRegistered} is true.
+	 */
+	registeredMirrorPath?: string;
+	/** The cwd repo's arbiter + divergence (fetch-first). Absent when no arbiter. */
+	arbiter?: CwdArbiter;
+}
+
+/** True iff the working repo has a git remote with name `remote`. The held-lock
+ * read targets the COORDINATION arbiter (default `origin`); we only attempt it
+ * when that remote actually exists, so a repo with no coordination remote keeps
+ * the empty held set rather than failing on a `git remote get-url` miss. */
+function remoteExists(
+	cwd: string,
+	remote: string,
+	env: NodeJS.ProcessEnv | undefined,
+): boolean {
+	return run('git', ['remote', 'get-url', remote], cwd, {env}).status === 0;
+}
+
+/** The verdict of the FETCH-FREE cwd pre-check {@link cwdSectionDisposition}. */
+export interface CwdDisposition {
+	/** True iff the cwd is a participating repo (a `work/` tree with lifecycle
+	 * content in any pool — see {@link isParticipatingRepo}, NOT `tasks/ready/`
+	 * alone). */
+	participating: boolean;
+	/**
+	 * True iff the cwd's arbiter URL keys to a registered hub mirror. When true the
+	 * registry view ALREADY covers this repo, so a default `scan`/`status` should
+	 * SKIP resolving the (expensive, fetch-first) cwd section entirely — the registry
+	 * row represents it, and re-reading the cwd would just re-fetch the SAME arbiter
+	 * `main` + lock refs the registry loop already fetched (the redundant-fetch the
+	 * `scan-here-and-skip-redundant-cwd` decision eliminates). Meaningful only when
+	 * {@link participating}.
+	 */
+	alsoRegistered: boolean;
+}
+
+/**
+ * The FETCH-FREE pre-check that decides whether a DEFAULT `scan`/`status` should
+ * pay for the cwd section at all. It does NO network I/O: it reads whether the cwd
+ * participates (local `readdirSync`) and resolves the cwd's arbiter URL via the
+ * fetch-free {@link arbiterStatus} (a local `git remote get-url`), then asks the
+ * fetch-free {@link resolveRegistration} (local {@link listMirrors} key match)
+ * whether that URL is already a registered mirror.
+ *
+ * The CLI gates on this BEFORE calling {@link resolveCwdSection}: a participating
+ * cwd that is ALSO registered is skipped (the registry already covers it, and the
+ * cwd read would only re-fetch the same arbiter), while a participating cwd with
+ * NO mirror is resolved + shown standalone so a mirror-less repo you are standing
+ * in is never invisible. `--here` bypasses this gate (it ALWAYS resolves the cwd,
+ * and only the cwd).
+ */
+export function cwdSectionDisposition(input: {
+	cwd: string;
+	config: Config;
+	/** The DIVERGENCE/arbiter remote whose URL keys the registration check. */
+	arbiterRemote?: string;
+	env?: NodeJS.ProcessEnv;
+}): CwdDisposition {
+	if (!isParticipatingRepo(input.cwd)) {
+		return {participating: false, alsoRegistered: false};
+	}
+	// Fetch-free: arbiterStatus reads the local remote config only (no fetch).
+	const status = arbiterStatus({
+		cwd: input.cwd,
+		remote: input.arbiterRemote,
+		env: input.env,
+	});
+	const {alsoRegistered} = resolveRegistration({
+		arbiterUrl: status.url,
+		config: input.config,
+		env: input.env,
+	});
+	return {participating: true, alsoRegistered};
+}
+
+/** Inputs to {@link resolveCwdSection}. */
+export interface ResolveCwdSectionOptions {
+	/** The current working directory to inspect (the candidate cwd repo). */
+	cwd: string;
+	/** Resolved global config (for `workspacesDir` + per-repo `autoBuild`). */
+	config: Config;
+	/**
+	 * The per-machine {@link ConfigOverrideMap}. Threaded into the local
+	 * working-tree scan so the cwd section's eligibility reflects the per-machine
+	 * override (consistent with the autopick / advance paths). Default: none.
+	 */
+	override?: ConfigOverrideMap;
+	/**
+	 * The arbiter remote name to fetch + diff against (the SURFACE/divergence
+	 * remote). Defaults to the same remote `status`'s arbiter section resolves
+	 * (`arbiter`); the CLI passes the configured value.
+	 */
+	arbiterRemote?: string;
+	/**
+	 * The COORDINATION arbiter remote where the per-item lock refs
+	 * (`refs/dorfl/lock/*`) live — the remote the held-lock SUBTRACTION reads. This
+	 * is the SAME remote `claim`/`do`/`complete` push locks to, which defaults to
+	 * `origin` (NOT the `arbiter`-named DIVERGENCE remote above — a repo can use
+	 * `origin` as its arbiter and have no `arbiter` remote at all, exactly this
+	 * repo's shape). Decoupled so the held-lock read targets the real coordination
+	 * arbiter even when the divergence remote is absent. Default `origin`.
+	 */
+	lockArbiterRemote?: string;
+	/** Sink for the fetch-first fall-back warning (warn + last-known, never error). */
+	warn?: (message: string) => void;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Resolve the cwd-local section for `scan`/`status`. Returns
+ * `{participating: false}` when the cwd is NOT a participating repo (the callers
+ * then render only the registry view, unchanged). When participating it:
+ *
+ *   1. FETCHES the cwd repo's arbiter first (warn + fall back to last-known on
+ *      failure — never errors), then computes the divergence vs `<arbiter>/main`;
+ *   2. reads the COORDINATION arbiter's HELD-LOCK set (the remote where
+ *      `refs/dorfl/lock/*` live, default `origin`; fail-closed: throws when that
+ *      remote exists but is unreachable) to SUBTRACT in-flight items from the pool;
+ *   3. reads the cwd's `work/` lifecycle from the LOCAL WORKING TREE
+ *      (`scanRepoPaths([cwd])`) with that held set subtracted;
+ *   4. de-dups against the registry (is the cwd's arbiter URL a registered
+ *      mirror?).
+ *
+ * It MUTATES nothing but the arbiter fetch (a read refresh, same as the registry
+ * fetch-first); it never claims/moves/integrates.
+ */
+export async function resolveCwdSection(
+	options: ResolveCwdSectionOptions,
+): Promise<CwdSection> {
+	const {cwd, config, warn, env} = options;
+
+	if (!isParticipatingRepo(cwd)) {
+		return {path: cwd, participating: false};
+	}
+
+	// 1. The cwd repo's arbiter + fetch-first divergence. We resolve the arbiter
+	//    via the SAME `arbiterStatus` the dashboard's arbiter section uses; if it
+	//    is configured we fetch it BEFORE diffing (the local tree is the least
+	//    authoritative view) — warn + fall back to last-known on failure. Resolved
+	//    FIRST (before the pool read) so the held-lock subtraction below reads that
+	//    same arbiter's lock refs.
+	const arbiter = await resolveCwdArbiter({
+		cwd,
+		remote: options.arbiterRemote,
+		warn,
+		env,
+	});
+
+	// 2. The held-lock set to SUBTRACT from the cwd pool (the SELECTION fix). The
+	//    lock refs live on the COORDINATION arbiter (`refs/dorfl/lock/*`) — the SAME
+	//    remote `claim`/`do` use, default `origin` — NOT the `arbiter`-named
+	//    DIVERGENCE remote resolved above (this repo has no `arbiter` remote; its
+	//    arbiter IS `origin`). So we read the held set from the coordination remote
+	//    and FAIL CLOSED on a read fault (`heldTaskSlugsStrict` throws): an offline /
+	//    unreachable arbiter makes the eligible pool UNKNOWN, and we must NOT emit a
+	//    confident-but-wrong pool (which CI would enumerate into doomed claim legs).
+	//    A repo with NO coordination remote configured has nothing to subtract and
+	//    nothing to fail against — it keeps the empty set.
+	const lockRemote = options.lockArbiterRemote ?? 'origin';
+	const hasLockRemote = remoteExists(cwd, lockRemote, env);
+	const heldSlugs = hasLockRemote
+		? await heldTaskSlugsStrict(cwd, lockRemote, env)
+		: new Set<string>();
+
+	// 3. The cwd's `work/` lifecycle from the LOCAL WORKING TREE (not a mirror ref),
+	//    with the arbiter-read held set SUBTRACTED so in-flight (lock-held) items are
+	//    not reported eligible. Thread the per-machine override so the cwd section's
+	//    eligibility matches what `do`/`advance` autopick will actually select.
+	const localReport = scanRepoPaths([cwd], config, heldSlugs, options.override);
+	const repo = localReport.repos[0];
+
+	// 3b. The PER-ITEM LOCK in-flight SURFACE for the cwd (prd
+	//     `ledger-status-per-item-lock-refs` US #8). The subtraction above removes a
+	//     held slug from the eligible `items[]` pool; on its OWN that leaves a
+	//     held/stuck cwd item in a BLIND SPOT — gone from every bucket with nothing
+	//     explaining why (the regression this fixes). The registry/mirror `scan`
+	//     attaches `lockHeld` to each `RepoReport` so a held item still shows up
+	//     in-progress/stuck; the cwd `RepoReport` from `scanRepoPaths` did not. So we
+	//     read the SAME held lock entries (action × state + reason/questions) via the
+	//     SAME `listItemLockEntries` primitive the mirror path uses (NOT a second
+	//     reader) and attach them, making `.cwd.repo.lockHeld` symmetric with
+	//     `.repos[].lockHeld`.
+	//
+	//     This is a SURFACE only, and it is INTENTIONALLY graceful (best-effort,
+	//     empty on any fault — exactly as `listItemLockEntries` is on the mirror
+	//     side): a read fault degrades to "no in-flight locks shown", it must NOT
+	//     fail the section. The SELECTION subtraction above stays STRICT
+	//     (`heldTaskSlugsStrict`, fail-closed) — the two reads have deliberately
+	//     different fault models (selection fails closed; the surface degrades).
+	//     Read from the SAME coordination remote the subtraction used. A repo with no
+	//     coordination remote has no lock refs to read — empty surface.
+	if (repo !== undefined && hasLockRemote) {
+		const lockHeld = await listItemLockEntries(cwd, lockRemote, env);
+		if (lockHeld.length > 0) {
+			repo.lockHeld = lockHeld;
+		}
+	}
+
+	// 4. De-dup: is the cwd's arbiter URL a registered hub mirror? Compare the
+	//    cwd's mirror KEY (from its arbiter URL) against the registry's keys.
+	const {alsoRegistered, registeredMirrorPath} = resolveRegistration({
+		arbiterUrl: arbiter?.url,
+		config,
+		env,
+	});
+
+	return {
+		path: cwd,
+		participating: true,
+		repo,
+		totalItems: localReport.totalItems,
+		totalEligible: localReport.totalEligible,
+		alsoRegistered,
+		...(registeredMirrorPath !== undefined ? {registeredMirrorPath} : {}),
+		...(arbiter !== undefined ? {arbiter} : {}),
+	};
+}
+
+/**
+ * Resolve the cwd repo's arbiter + divergence. Reuses `arbiterStatus` to find
+ * the arbiter remote/URL, FETCHES its `main` first (warn + fall back to
+ * last-known on failure — NEVER errors, ADR §5/§6), then reads the divergence of
+ * local `main` vs `<arbiter>/main` in both directions. Returns `undefined` when
+ * no arbiter remote is configured (no divergence line to show).
+ */
+async function resolveCwdArbiter(input: {
+	cwd: string;
+	remote?: string;
+	warn?: (message: string) => void;
+	env?: NodeJS.ProcessEnv;
+}): Promise<CwdArbiter | undefined> {
+	const {cwd, env} = input;
+	const status = arbiterStatus({cwd, remote: input.remote, env});
+	if (!status.configured) {
+		return undefined;
+	}
+	const remote = status.remote;
+
+	// Fetch-first ALSO for the cwd (the maintainer's explicit ask): refresh the
+	// arbiter's `main` before diffing, reusing scan-status-fetch-first's
+	// fetch+warn+fallback. A failed fetch is NOT fatal — warn + last-known.
+	let fetched = false;
+	const fetch = await runAsync('git', ['fetch', '--quiet', remote], cwd, {env});
+	if (fetch.status === 0) {
+		fetched = true;
+	} else {
+		input.warn?.(
+			`could not fetch the cwd repo's arbiter '${remote}'; ` +
+				'computing local divergence from last-known (offline). ' +
+				fetch.stderr.trim(),
+		);
+	}
+
+	const {ahead, behind} = await localMainDivergence(cwd, remote, env);
+	return {
+		remote,
+		configured: true,
+		url: status.url,
+		fetched,
+		ahead,
+		behind,
+	};
+}
+
+/**
+ * De-dup helper: is the cwd repo (identified by its arbiter URL) ALSO registered
+ * in the registry? The registry keys a mirror off its arbiter URL via
+ * `encodeRepoKey`/`mirrorPath`, so we encode the cwd's arbiter URL the same way
+ * and look for a matching registered mirror (by key, robust to the lossy URL).
+ * Returns whether it is registered + the matching mirror path (so the registry
+ * view can drop that row). With no arbiter URL there is nothing to match.
+ */
+function resolveRegistration(input: {
+	arbiterUrl: string | undefined;
+	config: Config;
+	env?: NodeJS.ProcessEnv;
+}): {alsoRegistered: boolean; registeredMirrorPath?: string} {
+	const {arbiterUrl, config, env} = input;
+	if (arbiterUrl === undefined || arbiterUrl.trim() === '') {
+		return {alsoRegistered: false};
+	}
+	const cwdKey = encodeRepoKey(arbiterUrl);
+	const cwdMirrorPath = mirrorPath(config.workspacesDir, arbiterUrl);
+	for (const mirror of listMirrors({
+		workspacesDir: config.workspacesDir,
+		env,
+	})) {
+		if (mirror.key === cwdKey || mirror.path === cwdMirrorPath) {
+			return {alsoRegistered: true, registeredMirrorPath: mirror.path};
+		}
+	}
+	return {alsoRegistered: false};
+}

package/src/decision-engine.ts

@@ -0,0 +1,272 @@
+import {extractJsonObjectSpan} from './verdict-json.js';
+
+/**
+ * **The SHARED decision engine** (prd
+ * `agentic-question-resolution-retire-disposition-vocabulary` US #9, decision 3 +
+ * 13/14; task `decision-engine-shared-decide-seam`): the GENERALISED
+ * `decide(input, allowedOutcomes) → verdict` core every question-resolution
+ * decision is built on. It is the same `prompt → VERDICT → dispatch` shape
+ * `intake` already has, lifted into ONE outcome-AGNOSTIC engine so intake and the
+ * advance-apply rung share the machinery WITHOUT being forced to identical
+ * verdicts or inputs.
+ *
+ * Two things are parameters, NOT hard-coded into the engine:
+ *
+ * - **the INPUT-ADAPTER** ({@link DecisionDecider}'s `TInput`): each caller's
+ *   front door reads a DIFFERENT thing (intake reads an issue + its comment
+ *   thread; advance-apply reads an answered sidecar + its source item). The engine
+ *   never knows that shape — it threads the caller's `input` opaquely to the
+ *   injected decider, so the adapter boundary sits OUTSIDE the engine (decision 3:
+ *   "the INPUT adapter differs per front door and is NOT forced to be shared").
+ * - **the ALLOWED-OUTCOME SET** ({@link decide}'s `allowedOutcomes`): each caller
+ *   passes the SUBSET of {@link DecisionOutcome} it permits — advance-apply allows
+ *   `{task | prd | adr | delete | ask}`, intake keeps its own `{task | prd | ask |
+ *   bounce}` (intake is NOT refactored onto this engine here — decision 13). The
+ *   engine never hard-codes which outcomes a caller permits; it only VALIDATES the
+ *   returned verdict against the set and rejects (loudly) one outside it
+ *   (decision 14: "the engine stays outcome-AGNOSTIC", so `adr` can be added to a
+ *   caller later WITHOUT re-architecting).
+ *
+ * This module is the PURE engine + its types ONLY — no fs, no git, no seam ops, no
+ * wiring into `sidecar.ts` / `apply-persist.ts` / `intake.ts`. The keystone apply
+ * task (`agentic-apply-retire-disposition-vocabulary`) consumes it next; intake
+ * adopting `adr` is a separate decision (the engine being agnostic means it CAN
+ * be added later).
+ */
+
+/**
+ * The SUPERSET of outcomes the engine knows — a "verdict" is what an agent
+ * decides to DO with an input (the analogue of intake's {@link IntakeOutcome}):
+ *
+ * - **task** — mint a self-contained task from the input.
+ * - **spec** — mint a spec from the input.
+ * - **adr** — mint an adr from the input (NO caller wires this yet; the keystone's
+ *   allowed set will, and `agentic-apply-mint-adr-route` adds the route — decision
+ *   14 keeps the engine agnostic so this is added without re-architecting).
+ * - **delete** — delete the SOURCE the input is about (a direct, git-recoverable
+ *   removal — decision 12).
+ * - **ask** — ask the operator a follow-up (re-pause; the conversation
+ *   accumulates — decision 5).
+ *
+ * No caller is forced to allow ALL of these: each passes its own SUBSET to
+ * {@link decide}. The engine is agnostic to which subset a caller permits.
+ */
+// MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`): the
+// parent-spec verdict outcome is `'spec'` (renamed from `'prd'`); the decider
+// prompt emits it and the parser accepts it. This is a fresh per-call LLM verdict
+// (nothing `'prd'`-valued is persisted), so the rename needs no on-disk alias.
+export type DecisionOutcome = 'task' | 'spec' | 'adr' | 'delete' | 'ask';
+
+/**
+ * The VERDICT the decider returns — the chosen {@link DecisionOutcome} plus the
+ * DRAFTED content for that outcome (the analogue of {@link IntakeVerdict}). Every
+ * content field is OPTIONAL on the shape: a given verdict only fills the channels
+ * its outcome consumes (a `task` fills the task channels, an `ask` fills
+ * `question`, a `delete` may carry only a `reason`). The dispatching CALLER
+ * decides which channels it requires for each outcome it allows — the engine only
+ * guards the `outcome` discriminator against the allowed set, never the content
+ * (it stays outcome-agnostic).
+ */
+export interface DecisionVerdict {
+	/** Which outcome the decider chose for the input. */
+	outcome: DecisionOutcome;
+	/** The drafted task's content-derived slug (`task` outcome). */
+	taskSlug?: string;
+	/** The drafted task's `title:` (`task` outcome). */
+	taskTitle?: string;
+	/**
+	 * The drafted task BODY (`task` outcome) — the markdown AFTER the frontmatter.
+	 * The dispatching caller writes the frontmatter; the agent never writes
+	 * git-visible files (the in-band boundary intake already follows).
+	 */
+	taskBody?: string;
+	/** The drafted spec's content-derived slug (`spec` outcome). */
+	specSlug?: string;
+	/** The drafted spec's `title:` (`spec` outcome). */
+	specTitle?: string;
+	/** The drafted spec BODY (`spec` outcome) — the markdown AFTER the frontmatter. */
+	specBody?: string;
+	/** The drafted adr's content-derived slug (`adr` outcome). */
+	adrSlug?: string;
+	/** The drafted adr's `title:` (`adr` outcome). */
+	adrTitle?: string;
+	/** The drafted adr BODY (`adr` outcome) — the markdown AFTER the frontmatter. */
+	adrBody?: string;
+	/**
+	 * The reason the source should be deleted (`delete` outcome) — the caller
+	 * carries it into the revertible deletion's commit message (decision 12: the
+	 * delete is git-recoverable, the reason in the commit message).
+	 */
+	deleteReason?: string;
+	/**
+	 * The drafted follow-up question(s) (`ask` outcome) — the caller appends them
+	 * to the conversation and re-pauses (decision 5: reuse the existing
+	 * append/re-pause loop).
+	 */
+	question?: string;
+}
+
+/**
+ * The DECISION step: given the caller's `input` (whatever its input-adapter
+ * shaped), return a {@link DecisionVerdict}. This is the INJECTED, STUBBABLE seam
+ * — exactly like intake's `IntakeDecider`: production wires a harness/agent; tests
+ * inject a CANNED verdict (no model, no network). The engine is generic over
+ * `TInput` so the adapter boundary sits in the CALLER, never in the engine.
+ */
+export type DecisionDecider<TInput> = (
+	input: TInput,
+) => Promise<DecisionVerdict>;
+
+/**
+ * Thrown when a returned verdict's `outcome` is OUTSIDE the caller's
+ * `allowedOutcomes`. The engine NEVER silently coerces an out-of-set verdict — a
+ * caller that does not allow `adr` can never receive an `adr` verdict; it gets
+ * this loud rejection instead (the allowed-outcome guard).
+ */
+export class DisallowedOutcomeError extends Error {
+	/** The outcome the decider returned that was not permitted. */
+	readonly outcome: DecisionOutcome;
+	/** The set the caller allowed (the SUBSET it passed to {@link decide}). */
+	readonly allowed: readonly DecisionOutcome[];
+	constructor(outcome: DecisionOutcome, allowed: readonly DecisionOutcome[]) {
+		super(
+			`decision verdict 'outcome' ${JSON.stringify(outcome)} is not in the ` +
+				`caller's allowed set {${allowed.join(' | ')}}; the engine rejects an ` +
+				`out-of-set verdict rather than coercing it.`,
+		);
+		this.name = 'DisallowedOutcomeError';
+		this.outcome = outcome;
+		this.allowed = allowed;
+	}
+}
+
+/**
+ * Thrown when `allowedOutcomes` itself is EMPTY — a caller that allows no outcome
+ * can never receive a valid verdict, so this is a programming error caught up
+ * front rather than surfaced as a confusing per-verdict rejection.
+ */
+export class EmptyAllowedOutcomesError extends Error {
+	constructor() {
+		super(
+			'decide() was called with an EMPTY allowedOutcomes set; a caller must ' +
+				'allow at least one outcome.',
+		);
+		this.name = 'EmptyAllowedOutcomesError';
+	}
+}
+
+/**
+ * **The engine core.** Run the injected `decide`r over the caller's `input`, then
+ * VALIDATE the returned verdict's `outcome` against `allowedOutcomes` — the
+ * caller's permitted SUBSET of {@link DecisionOutcome}. Returns the verdict
+ * verbatim when it is in the set; throws {@link DisallowedOutcomeError} (loudly)
+ * when it is not. Throws {@link EmptyAllowedOutcomesError} when the set is empty.
+ *
+ * The engine is outcome-AGNOSTIC: it hard-codes NO caller's outcomes and inspects
+ * ONLY the `outcome` discriminator (never the per-outcome content channels — those
+ * are the dispatching caller's concern). The INPUT-ADAPTER boundary sits in the
+ * caller: `input` is threaded opaquely to the decider, so the engine never knows
+ * its shape.
+ *
+ * @param input the caller's adapter-shaped input (issue thread, answered sidecar
+ *   + source item, …) — opaque to the engine.
+ * @param decide the INJECTED decision seam (tests pass a canned verdict; prod a
+ *   harness-backed one).
+ * @param allowedOutcomes the caller's permitted subset (an array or any
+ *   iterable). Order is preserved in the rejection message.
+ */
+export async function decide<TInput>(
+	input: TInput,
+	decide: DecisionDecider<TInput>,
+	allowedOutcomes: Iterable<DecisionOutcome>,
+): Promise<DecisionVerdict> {
+	const allowed = [...allowedOutcomes];
+	if (allowed.length === 0) {
+		throw new EmptyAllowedOutcomesError();
+	}
+	const allowedSet = new Set(allowed);
+	const verdict = await decide(input);
+	if (!allowedSet.has(verdict.outcome)) {
+		throw new DisallowedOutcomeError(verdict.outcome, allowed);
+	}
+	return verdict;
+}
+
+/**
+ * Parse a decider's emitted VERDICT out of its (possibly prose-wrapped / fenced)
+ * textual output into a {@link DecisionVerdict} — the PRODUCTION-WIRE helper a
+ * harness-backed {@link DecisionDecider} uses to recover the verdict an agent
+ * emitted, modeled 1:1 on intake's `parseIntakeVerdict`. It pulls the first JSON
+ * object carrying an `"outcome"` field via the SHARED {@link extractJsonObjectSpan}
+ * (the same extractor every prompt→verdict→dispatch seam in this package uses —
+ * NOT a forked copy), `JSON.parse`s it, and validates the shape:
+ * `outcome ∈ {task,spec,adr,delete,ask}`.
+ *
+ * This validates the verdict is a WELL-FORMED member of the SUPERSET; the
+ * caller-specific allowed-outcome guard ({@link decide}) then rejects one outside
+ * the caller's SUBSET. The two checks are distinct: shape here, policy there.
+ *
+ * THROWS a clear error on: no JSON object present, invalid JSON, or an `outcome`
+ * not in the superset. A harness-backed decider lets the throw propagate so the
+ * caller maps it onto its own agent-failed path (a malformed verdict degrades
+ * honestly, never a crash and never a silent dispatch).
+ */
+export function parseDecisionVerdict(output: string): DecisionVerdict {
+	const span = extractJsonObjectSpan(output, 'outcome');
+	if (span === undefined) {
+		throw new Error(
+			'decision agent produced no parseable {outcome, …} verdict.',
+		);
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(output.slice(span.start, span.end));
+	} catch (err) {
+		throw new Error(
+			`decision verdict was not valid JSON: ${(err as Error).message}`,
+		);
+	}
+	if (typeof parsed !== 'object' || parsed === null) {
+		throw new Error('decision verdict was not an object.');
+	}
+	const obj = parsed as Record<string, unknown>;
+	const outcome = obj.outcome;
+	if (
+		outcome !== 'task' &&
+		outcome !== 'spec' &&
+		outcome !== 'adr' &&
+		outcome !== 'delete' &&
+		outcome !== 'ask'
+	) {
+		throw new Error(
+			`decision verdict 'outcome' was not one of task|spec|adr|delete|ask (got ` +
+				`${JSON.stringify(outcome)}).`,
+		);
+	}
+	// Map the per-outcome fields onto the verdict shape, keeping ONLY the strings
+	// the dispatcher consumes (a missing optional stays absent). Every field is
+	// optional on the type, so each outcome's content is carried verbatim when
+	// present — the engine never demands a channel (it stays outcome-agnostic).
+	const str = (v: unknown): string | undefined =>
+		typeof v === 'string' ? v : undefined;
+	return {
+		outcome,
+		...(str(obj.taskSlug) !== undefined ? {taskSlug: str(obj.taskSlug)} : {}),
+		...(str(obj.taskTitle) !== undefined
+			? {taskTitle: str(obj.taskTitle)}
+			: {}),
+		...(str(obj.taskBody) !== undefined ? {taskBody: str(obj.taskBody)} : {}),
+		...(str(obj.specSlug) !== undefined ? {specSlug: str(obj.specSlug)} : {}),
+		...(str(obj.specTitle) !== undefined
+			? {specTitle: str(obj.specTitle)}
+			: {}),
+		...(str(obj.specBody) !== undefined ? {specBody: str(obj.specBody)} : {}),
+		...(str(obj.adrSlug) !== undefined ? {adrSlug: str(obj.adrSlug)} : {}),
+		...(str(obj.adrTitle) !== undefined ? {adrTitle: str(obj.adrTitle)} : {}),
+		...(str(obj.adrBody) !== undefined ? {adrBody: str(obj.adrBody)} : {}),
+		...(str(obj.deleteReason) !== undefined
+			? {deleteReason: str(obj.deleteReason)}
+			: {}),
+		...(str(obj.question) !== undefined ? {question: str(obj.question)} : {}),
+	};
+}