dorfl 0.0.0 → 0.1.0

package/src/drop-source.ts

@@ -0,0 +1,194 @@
+import {existsSync} from 'node:fs';
+import {join} from 'node:path';
+import {run, type RunResult} from './git.js';
+import {resolveSidecarIdentity, sidecarPathFor} from './sidecar.js';
+import {resolveItemPathByIdentity} from './item-path.js';
+
+/**
+ * The DIRECT-DELETE helper (prd
+ * `agentic-question-resolution-retire-disposition-vocabulary`, US #5/#11; task
+ * `direct-delete-question-cli-helper`) — the "I just want to throw this away"
+ * path that `git rm`s a source item AND its question sidecar (when present) in
+ * ONE revertible commit, the human's reason recorded in the commit MESSAGE (git
+ * history is the archive).
+ *
+ * It is the DIRECT human/skill/CLI action of decision 7: the human, the
+ * `answer-questions` skill, or the `dorfl drop` verb deletes a signal STRAIGHT —
+ * it does NOT round-trip through the decision engine or spawn any agent. (The
+ * AGENT reaching `delete-source` as a verdict is the SEPARATE engine path in
+ * `apply-persist.ts`'s `dischargeByDeletion`; this module is its no-engine twin.)
+ *
+ * The shape deliberately MIRRORS `apply-persist.ts`'s `dischargeByDeletion` (same
+ * one-commit `git rm`, same reason-in-the-message archive) but reaches it WITHOUT
+ * the answered-sidecar precondition, the apply rung, or any verdict: the human
+ * has already decided. Both the source path and the sidecar path are resolved by
+ * the item's namespaced IDENTITY (the single source of truth) via the SHARED
+ * `resolveItemPathByIdentity` / `sidecarPathFor` resolvers — NOT a captured path.
+ *
+ * Git-recoverable by construction: a single revertible commit, so a wrong delete
+ * is never catastrophic (US #11).
+ */
+
+export interface DropSourceOptions {
+	/** Working clone/worktree the deletion commits in. */
+	cwd: string;
+	/**
+	 * The namespaced item identity to delete (`task:foo` / `prd:bar` /
+	 * `observation:baz` / `obs:baz` / a bare `<slug>` = task). Resolved to its
+	 * on-disk path by identity, folder-agnostic.
+	 */
+	item: string;
+	/**
+	 * The human's reason for the deletion, recorded in the commit MESSAGE (git
+	 * history is the archive). Empty/whitespace is recorded as "(no reason given)"
+	 * rather than refused — the human asked to delete; the reason is documentation,
+	 * not a gate.
+	 */
+	reason?: string;
+	/** Advisory committer id for the commit subject. Defaults to git user.name. */
+	by?: string;
+	/** Environment for child git processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for human-readable progress notes. */
+	note?: (message: string) => void;
+}
+
+/** The terminal a drop reached. */
+export type DropTerminal =
+	/** The source (+ its sidecar when present) were `git rm`-ed in one commit. */
+	| 'deleted'
+	/**
+	 * No source resolved by identity in any lifecycle folder — nothing to delete.
+	 * A clean no-op (no commit), NOT an error: the human asked to throw away
+	 * something that is already gone, and the sidecar (if any) is the orphan-gc
+	 * sweep's concern, not this direct verb's.
+	 */
+	| 'not-found';
+
+export interface DropSourceResult {
+	/** The terminal the drop reached. */
+	outcome: DropTerminal;
+	/** The canonical namespaced identity the drop acted on. */
+	item: string;
+	/** The commit sha the drop produced (only on `deleted`). */
+	commit?: string;
+	/** The source path (relative to `cwd`) that was removed (only on `deleted`). */
+	itemPath?: string;
+	/**
+	 * The sidecar path (relative to `cwd`) that was removed, or `undefined` when
+	 * no sidecar was present (a source with no open-question conversation).
+	 */
+	sidecarPath?: string;
+	/** A human-readable summary. */
+	message: string;
+}
+
+/** Raised for usage errors (a missing repo). */
+export class DropSourceError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'DropSourceError';
+	}
+}
+
+function gitSoft(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): RunResult {
+	return run('git', args, cwd, {env});
+}
+
+function gitHard(
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+): RunResult {
+	const result = run('git', args, cwd, {env});
+	if (result.status !== 0) {
+		throw new DropSourceError(
+			`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`,
+		);
+	}
+	return result;
+}
+
+function resolveBy(cwd: string, env: NodeJS.ProcessEnv | undefined): string {
+	const name = gitSoft(['config', 'user.name'], cwd, env);
+	if (name.status === 0 && name.stdout.trim() !== '') {
+		return name.stdout.trim();
+	}
+	const e = env ?? process.env;
+	return e.USER ?? e.USERNAME ?? '';
+}
+
+/**
+ * DELETE a source item + its question sidecar DIRECTLY (US #5/#11): `git rm` the
+ * source AND its sidecar (when present) in ONE revertible commit, the human's
+ * `reason` recorded in the commit MESSAGE. No decision engine, no agent — the
+ * direct human/skill/CLI throw-it-away path.
+ *
+ *   - Resolves the source by IDENTITY (`resolveItemPathByIdentity`); when it is
+ *     already gone, returns `not-found` as a clean no-op (no commit) — deleting
+ *     something already absent is "nothing to throw away", not a failure.
+ *   - `git rm`s the sidecar TOO when one is present (`sidecarPathFor` →
+ *     `existsSync`); a source with no open-question conversation simply has no
+ *     sidecar to remove.
+ *   - Both ride ONE commit, so the deletion is a single revertible unit (a wrong
+ *     delete is recoverable via `git revert`).
+ */
+export function dropSource(options: DropSourceOptions): DropSourceResult {
+	const {cwd, env} = options;
+	const note = options.note ?? (() => {});
+
+	if (gitSoft(['rev-parse', '--git-dir'], cwd, env).status !== 0) {
+		throw new DropSourceError('not inside a git repository');
+	}
+
+	// Canonicalise the identity (bare slug → task, `obs:` → observation, …) so the
+	// commit message + result speak the one namespaced form.
+	const {item} = resolveSidecarIdentity(options.item);
+
+	const itemPath = resolveItemPathByIdentity(cwd, item);
+	if (itemPath === undefined) {
+		const message =
+			`drop ${item}: no source item resolves by identity in any lifecycle ` +
+			`folder — nothing to throw away (clean no-op, no commit).`;
+		note(message);
+		return {outcome: 'not-found', item, message};
+	}
+
+	// `git rm` the source. The sidecar may or may not exist (only items with an
+	// open-question conversation have one); rm it too when present, so the drop
+	// leaves no orphaned sidecar. Both ride ONE commit.
+	const sidecarPath = sidecarPathFor(item);
+	const sidecarPresent = existsSync(join(cwd, sidecarPath));
+	const rmPaths = sidecarPresent ? [itemPath, sidecarPath] : [itemPath];
+	gitHard(['rm', '--quiet', '--', ...rmPaths], cwd, env);
+
+	const by = options.by || resolveBy(cwd, env);
+	const reasonLine =
+		(options.reason ?? '').trim() === ''
+			? '(no reason given)'
+			: (options.reason ?? '').trim();
+	const subject = `drop: ${item} → deleted (by ${by})`;
+	const messageBody =
+		`Direct delete (the human threw it away; no engine round-trip; git ` +
+		`history is the archive). This is a single revertible commit.\n\n` +
+		`reason: ${reasonLine}`;
+	gitHard(['commit', '--quiet', '-m', subject, '-m', messageBody], cwd, env);
+	const commit = gitHard(['rev-parse', 'HEAD'], cwd, env).stdout.trim();
+
+	const message =
+		`dropped ${item} → deleted (source${sidecarPresent ? ' + sidecar' : ''} ` +
+		`git rm-ed in one revertible commit; reason in the commit message).`;
+	note(message);
+	return {
+		outcome: 'deleted',
+		item,
+		commit,
+		itemPath,
+		...(sidecarPresent ? {sidecarPath} : {}),
+		message,
+	};
+}

package/src/eligibility.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure eligibility resolution. No I/O — callers pass in the two autonomy axes
+ * (`humanOnly`, `needsAnswers`), the item's `blockedBy` slugs, and the set of
+ * slugs present in the same repo's `work/done/`. Dependencies are per-repo only
+ * and never cross repos.
+ */
+
+/**
+ * An autonomy gate axis. `true` ⇒ the item is gated on this axis (never
+ * auto-claim); `undefined`/`false` ⇒ not gated on it. Both `humanOnly` (DECIDED)
+ * and `needsAnswers` (DISCOVERED) share this shape and block orthogonally.
+ */
+export type HumanOnlyGate = boolean | undefined;
+
+export interface BlockedByResult {
+	/** True when every blocker is present in `work/done/`. */
+	satisfied: boolean;
+	/** Blocker slugs not yet in `work/done/`, in declaration order. */
+	missing: string[];
+}
+
+export interface EligibilityInput {
+	humanOnly: HumanOnlyGate;
+	needsAnswers: HumanOnlyGate;
+	blockedBy: string[];
+	/** Slugs present in this repo's `work/done/`. */
+	doneSlugs: Set<string>;
+	/** Per-repo policy: may agents auto-BUILD *undeclared* (not human-only) tasks? */
+	autoBuild: boolean;
+}
+
+export interface EligibilityResult {
+	/** Eligible now = gate passes AND all blockers satisfied. */
+	eligible: boolean;
+	/** Whether the autonomy gate alone passes (agent-claimable). */
+	gatePass: boolean;
+	blockedBy: BlockedByResult;
+}
+
+/**
+ * Resolve the autonomy gate: agent-claimable iff `needsAnswers` is not `true`
+ * AND `humanOnly` is not `true` AND the repo's `autoBuild` policy is on. Both
+ * axes block orthogonally and are never claimable by an agent regardless of
+ * policy; a human is never bound by either.
+ */
+export function resolveGate(
+	humanOnly: HumanOnlyGate,
+	needsAnswers: HumanOnlyGate,
+	autoBuild: boolean,
+): boolean {
+	if (needsAnswers === true || humanOnly === true) {
+		return false;
+	}
+	return autoBuild;
+}
+
+/** Resolve `blockedBy` against the slugs present in `work/done/`. */
+export function resolveBlockedBy(
+	blockedBy: string[],
+	doneSlugs: Set<string>,
+): BlockedByResult {
+	const missing = blockedBy.filter((slug) => !doneSlugs.has(slug));
+	return {satisfied: missing.length === 0, missing};
+}
+
+/** Combine the autonomy gate and `blockedBy` resolution into a verdict. */
+export function resolveEligibility(input: EligibilityInput): EligibilityResult {
+	const gatePass = resolveGate(
+		input.humanOnly,
+		input.needsAnswers,
+		input.autoBuild,
+	);
+	const blockedBy = resolveBlockedBy(input.blockedBy, input.doneSlugs);
+	return {
+		eligible: gatePass && blockedBy.satisfied,
+		gatePass,
+		blockedBy,
+	};
+}

package/src/env-config.ts

@@ -0,0 +1,305 @@
+import type {Config, PartialConfig} from './config.js';
+import {brand, constantCase} from './brand.js';
+
+/**
+ * The environment-variable config layer.
+ *
+ * A per-machine context (a CI job, a developer's shell) can set ANY {@link Config}
+ * key via an `DORFL_*` environment variable WITHOUT committing a file —
+ * including the host-only keys (`piBin`, `agentCmd`, …) that the per-repo
+ * `.dorfl.json` deliberately rejects.
+ *
+ * Env is a legitimate *per-machine source* — exactly like a CLI flag or the
+ * global `~/.config/dorfl/config.json` — so it is NOT subject to the
+ * per-repo allow/reject split (that split only governs the *committed repo
+ * file*). This is the sharpened host-only principle (ADR §13): host-only keys
+ * must come from a per-machine source (flag, env, or global file), never the
+ * committed repo file; env is simply the per-machine source CI actually has
+ * without writing a file.
+ *
+ * Resolution chain (highest wins):
+ *
+ *   flag > ENV (DORFL_*) > per-repo > global > built-in default
+ *
+ * Naming: `DORFL_<SCREAMING_SNAKE(key)>` (mechanical camelCase →
+ * SCREAMING_SNAKE, prefixed with `DORFL_` to match the binary). E.g.
+ * `DORFL_AGENT_CMD`, `DORFL_PI_BIN`, `DORFL_DEFAULT_ARBITER`,
+ * `DORFL_PER_REPO_MAX`.
+ *
+ * Each value is coerced per the key's type and a typo/invalid value FAILS LOUDLY
+ * (never silently ignored) with a message naming the offending variable.
+ */
+
+/**
+ * The shared `DORFL_` prefix on every env config variable. Derived from
+ * the single brand identity (`constantCase(base) + '_'`) so a rename flips the
+ * prefix in lockstep with the binary name (see `brand.ts`).
+ */
+export const ENV_PREFIX = brand.envPrefix;
+
+/** How a key's env value is coerced from its raw string. */
+type Coercion =
+	| 'string'
+	| 'boolean'
+	| 'number'
+	| 'list'
+	| {enum: readonly string[]};
+
+/**
+ * The coercion to apply per env-settable {@link Config} key. The source of truth
+ * for which env vars exist and how their raw strings become typed values. EVERY
+ * SCALAR `Config` key appears here (host-only included) — env is a per-machine
+ * source, so no scalar key is off-limits. Keys not listed have no env var.
+ *
+ * The lone EXCLUSION is `identity`: it is a NESTED structured object (with its
+ * own `auth`/`providers` sub-objects), not a scalar a single env string can
+ * carry. A `tokenEnv` indirection already covers the one secret a CI/per-machine
+ * context legitimately injects via env (the `gh` token), so there is no JSON-in-
+ * env hack here. The mapped type is `Partial` precisely to ALLOW this exclusion.
+ */
+const KEY_COERCIONS: {[K in keyof Config]?: Coercion} = {
+	autoBuild: 'boolean',
+	autoTask: 'boolean',
+	// The observation-triage gate is a 3-state ENUM coercion (like `integration`),
+	// so `DORFL_OBSERVATION_TRIAGE=off|ask|auto` works and a typo FAILS
+	// LOUDLY naming the variable + the valid options.
+	observationTriage: {enum: ['off', 'ask', 'auto']},
+	// The merge-question SURFACER gate is a 3-state ENUM coercion (mirrors
+	// `observationTriage`'s shape; SEPARATE axis with a HIGHER default, prd
+	// `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
+	// `merge-questions-gate-axis`), so `DORFL_MERGE_QUESTIONS=off|ask|auto`
+	// works and a typo FAILS LOUDLY naming the variable + the valid options.
+	mergeQuestions: {enum: ['off', 'ask', 'auto']},
+	// The surface-blockers gate is a BOOLEAN coercion (like `autoBuild`), so
+	// `DORFL_SURFACE_BLOCKERS=true|false` works and a typo FAILS LOUDLY.
+	surfaceBlockers: 'boolean',
+	// `surfaceStaging` (the BOOLEAN gate-family member that widens the SURFACE
+	// candidate set to include STAGING — `tasks/backlog/` + `prds/proposed/` —
+	// not only the agent pool; prd
+	// `staging-surface-and-apply-promote-safety` F2) coerces as a BOOLEAN like
+	// `autoBuild`/`surfaceBlockers`, so `DORFL_SURFACE_STAGING=true|false`
+	// works and a typo FAILS LOUDLY. Resolution chain identical to the other
+	// gate-family members (flag > env > per-repo > global > built-in `true`).
+	surfaceStaging: 'boolean',
+	// `selectionOrder` coerces as a `'list'` (comma form
+	// `DORFL_SELECTION_ORDER=build,task,surface,triage`); a single-element
+	// list whose one entry is a preset keyword (`=drain`) is expanded by the
+	// resolver (`select-order.ts`). Subsumes the removed `prdsFirst` boolean.
+	selectionOrder: 'list',
+	maxParallel: 'number',
+	perRepoMax: 'number',
+	defaultArbiter: 'string',
+	workspacesDir: 'string',
+	arbitersDir: 'string',
+	humanWorktreesDir: 'string',
+	integration: {enum: ['propose', 'merge']},
+	// `taskingIntegration` (the per-TRANSITION TASKING override) coerces as the SAME
+	// `propose`/`merge` enum as `integration`, so `DORFL_TASKING_INTEGRATION`
+	// works and a typo FAILS LOUDLY. Unset ⇒ the tasking transition falls back to
+	// `integration` (the flat value). It NEVER touches the build transition or intake.
+	taskingIntegration: {enum: ['propose', 'merge']},
+	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — prd
+	// `staging-pool-position-gate-and-trust-model` US #5) coerces as the
+	// `pre-backlog`/`ready` enum, so `DORFL_TASKS_LAND_IN=ready` works and a
+	// typo FAILS LOUDLY. Same
+	// precedence chain as `taskingIntegration` (flag > env > per-repo > global >
+	// built-in `pre-backlog`); fed into the runner-deterministic placement
+	// resolver (`src/placement.ts`) as the configured-default rung.
+	tasksLandIn: {enum: ['pre-backlog', 'ready']},
+	// `specsLandIn` (the per-repo SPEC-PLACEMENT default — spec
+	// `staging-pool-position-gate-and-trust-model` US #2/#5) coerces as the
+	// `pre-proposed`/`ready` enum, so `DORFL_SPECS_LAND_IN=ready` works and a typo
+	// FAILS LOUDLY. Same precedence chain as `tasksLandIn` (flag > env > per-repo
+	// > global > built-in `pre-proposed`); fed into the shared placement resolver
+	// (`src/placement.ts`) as the configured-default rung for the spec lifecycle.
+	// The legacy `prdsLandIn` key / `DORFL_PRDS_LAND_IN` env are GONE after the
+	// prd → spec hard cutover (clean break).
+	specsLandIn: {enum: ['pre-proposed', 'ready']},
+	// `noPR` (the PR-INTENT axis) is a BOOLEAN coercion (like `review`), so
+	// `DORFL_NO_PR=true|false` works and a typo FAILS LOUDLY. The removed
+	// `provider` override has NO env var (a stale `DORFL_PROVIDER` is ignored
+	// with a deprecation warning — see `envOverrides`).
+	noPR: 'boolean',
+	agentCmd: 'string',
+	model: 'string',
+	harness: {enum: ['null', 'pi']},
+	piBin: 'string',
+	sessionsDir: 'string',
+	// `prepare` coerces as a `'list'` (comma form
+	// `DORFL_PREPARE=pnpm install,git submodule update --init`), exactly
+	// like `verify` — the SAME precedence chain, the sibling env-prep step.
+	prepare: 'list',
+	verify: 'list',
+	review: 'boolean',
+	reviewModel: 'string',
+	reviewMaxRounds: 'number',
+	taskerLoop: 'boolean',
+	taskerLoopMax: 'number',
+	taskerLoopModel: 'string',
+	// `freshWorktreeGate` is a BOOLEAN coercion (like `taskerLoop`), so
+	// `DORFL_FRESH_WORKTREE_GATE=true|false` works and a typo FAILS LOUDLY.
+	freshWorktreeGate: 'boolean',
+	// `mergeRetries` (the cross-job merge serialiser's CAS-retry cap — prd
+	// `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a))
+	// coerces as a NUMBER (like `reviewMaxRounds`), so `DORFL_MERGE_RETRIES=20`
+	// works and a typo FAILS LOUDLY. A wide-matrix CI raises it; the default
+	// (1000 — the C2 large liveness ceiling) stays in place when unset.
+	mergeRetries: 'number',
+	// `strictMergeApproval` (the OPT-IN strictness layered on the OQ6
+	// stale-approval default — prd `land-time-reverify-and-parallel-merge-ceiling`
+	// sidecar OQ6 / task `strict-merge-approval-gate`) coerces as a BOOLEAN
+	// (like `freshWorktreeGate`), so `DORFL_STRICT_MERGE_APPROVAL=true|false`
+	// works and a typo FAILS LOUDLY. Default OFF; ON re-surfaces the
+	// merge-question on a merge-base change instead of auto-landing.
+	strictMergeApproval: 'boolean',
+	// `promptGuidance` is a STRUCTURED (nested) namespace, so it has no scalar env
+	// var of its own — each MEMBER carries its own env var (the nested-key form
+	// `DORFL_PROMPT_GUIDANCE_<MEMBER>`), handled out-of-band in
+	// `envOverrides` below. Listing the namespace here would imply a single scalar
+	// `DORFL_PROMPT_GUIDANCE` env var, which is NOT how the namespace is
+	// shaped (each nudge member is independently resolvable).
+};
+
+/**
+ * The env vars for the nested members of the `promptGuidance` namespace. The
+ * key is the env var name (`DORFL_PROMPT_GUIDANCE_<MEMBER>`, the nested
+ * naming the prd specifies); the value is the (boolean) coercion. Each member
+ * present in env contributes `{<member>: bool}` into a single
+ * `promptGuidance` partial — mergeConfig replaces the whole namespace per the
+ * layered precedence, which is correct because EVERY member is included (env
+ * supplies a complete inner object whenever ANY member is set).
+ */
+const PROMPT_GUIDANCE_ENV: Readonly<Record<string, 'boolean'>> = {
+	[ENV_PREFIX + 'PROMPT_GUIDANCE_TEST_FIRST']: 'boolean',
+};
+
+/** The `DORFL_*` env var name for a config key (`perRepoMax` →
+ * `DORFL_PER_REPO_MAX`): the brand prefix + the key in `constantCase`. */
+export function envVarName(key: keyof Config): string {
+	return ENV_PREFIX + constantCase(key);
+}
+
+/** A raw env map (defaults to `process.env`). */
+export type EnvMap = Record<string, string | undefined>;
+
+/**
+ * Coerce a raw env string for one key, FAILING LOUDLY (with the offending var
+ * name) on invalid input: booleans accept only `true`/`false`; numbers reject
+ * NaN; enums must be in their union; list keys split on comma; strings verbatim.
+ */
+function coerceValue(
+	varName: string,
+	raw: string,
+	coercion: Coercion,
+): unknown {
+	if (typeof coercion === 'object') {
+		// Enum: validate against the union.
+		if (!coercion.enum.includes(raw)) {
+			throw new Error(
+				`Invalid value for ${varName}: '${raw}'. ` +
+					`Expected one of: ${coercion.enum.join(', ')}.`,
+			);
+		}
+		return raw;
+	}
+	switch (coercion) {
+		case 'string':
+			return raw;
+		case 'boolean':
+			if (raw === 'true') {
+				return true;
+			}
+			if (raw === 'false') {
+				return false;
+			}
+			throw new Error(
+				`Invalid boolean for ${varName}: '${raw}'. Expected 'true' or 'false'.`,
+			);
+		case 'number': {
+			const n = Number(raw);
+			if (raw.trim() === '' || Number.isNaN(n)) {
+				throw new Error(
+					`Invalid number for ${varName}: '${raw}'. Expected a numeric value.`,
+				);
+			}
+			return n;
+		}
+		case 'list':
+			// Split on comma (cross-platform; not `:`), trimming each entry. An empty
+			// string ⇒ an empty list (an explicit "clear" of a list key).
+			return raw
+				.split(',')
+				.map((s) => s.trim())
+				.filter((s) => s !== '');
+	}
+}
+
+/**
+ * Read the `DORFL_*` env layer into a {@link PartialConfig}. Only vars
+ * actually present (and non-`undefined`) contribute, so absent env ⇒ `{}` and
+ * built-in floors/defaults are untouched. Each present var is coerced per its
+ * key's type; an invalid value throws LOUDLY naming the variable.
+ *
+ * Env may set ANY key — host-only included — because env is a per-machine
+ * source, NOT the committed repo file (see this module's doc + ADR §13).
+ */
+export function envOverrides(
+	env: EnvMap = process.env,
+	warn: (message: string) => void = (m) => console.error(`>> ${m}`),
+): PartialConfig {
+	// A stale `DORFL_PROVIDER` (the removed provider OVERRIDE) is IGNORED with
+	// a one-line deprecation warning, never an error — the provider is now purely
+	// arbiter-derived; "suppress the PR" re-homes to `noPR` (`DORFL_NO_PR`).
+	const staleProvider = env[ENV_PREFIX + 'PROVIDER'];
+	if (staleProvider !== undefined) {
+		warn(
+			`Ignoring deprecated env var ${ENV_PREFIX}PROVIDER: the provider is now ` +
+				'purely arbiter-derived (a GitHub remote ⇒ the GitHub provider, else ' +
+				'none). To suppress the PR (the old `none` use), set ' +
+				`${ENV_PREFIX}NO_PR=true (or pass --no-pr).` +
+				(staleProvider === 'none'
+					? ' (your `none` maps directly to NO_PR=true.)'
+					: ''),
+		);
+	}
+	const overrides: PartialConfig = {};
+	// Per-member env layer for the `promptGuidance` NUDGE namespace. Each member
+	// is INDEPENDENTLY resolvable (`DORFL_PROMPT_GUIDANCE_<MEMBER>`); a
+	// present env var sets that member in the partial. We merge ALL set members
+	// into a single inner object, then assign once — the outer mergeConfig
+	// REPLACES the namespace per layer, so we send a coherent partial-inner per
+	// env override (a missing member there reads its default from the lower
+	// layer's namespace, which works because env is precisely a per-machine
+	// SETTER, not a gate).
+	const promptGuidancePartial: Partial<{testFirst: boolean}> = {};
+	for (const [varName, coercion] of Object.entries(PROMPT_GUIDANCE_ENV)) {
+		const raw = env[varName];
+		if (raw === undefined) {
+			continue;
+		}
+		const value = coerceValue(varName, raw, coercion) as boolean;
+		if (varName === ENV_PREFIX + 'PROMPT_GUIDANCE_TEST_FIRST') {
+			promptGuidancePartial.testFirst = value;
+		}
+	}
+	if (Object.keys(promptGuidancePartial).length > 0) {
+		overrides.promptGuidance = {
+			testFirst: promptGuidancePartial.testFirst ?? false,
+		};
+	}
+	for (const key of Object.keys(KEY_COERCIONS) as (keyof Config)[]) {
+		const coercion = KEY_COERCIONS[key];
+		if (coercion === undefined) {
+			continue;
+		}
+		const varName = envVarName(key);
+		const raw = env[varName];
+		if (raw === undefined) {
+			continue;
+		}
+		const coerced = coerceValue(varName, raw, coercion);
+		// Type matches by construction: each coercion yields the key's value type.
+		(overrides as Record<string, unknown>)[key] = coerced;
+	}
+	return overrides;
+}