dorfl 0.1.2 → 0.2.0

package/src/orphan-sidecar.ts

@@ -3,8 +3,44 @@ import {join} from 'node:path';
 import {run} from './git.js';
 import {resolveSidecarIdentity} from './sidecar.js';
 import {resolveItemPathByIdentity} from './item-path.js';
+import {terminalMainPaths} from './item-lock.js';
 import {workFolderPath, workFolderRel} from './work-layout.js';
 
+/**
+ * Resolve the source item's CURRENT on-disk path INCLUDING its TERMINAL resting
+ * records — the orphan-sweep existence predicate.
+ *
+ * This deliberately WIDENS {@link resolveItemPathByIdentity} (which scans the
+ * ACTIVE lifecycle folders + staging, and EXCLUDES terminals on purpose: for the
+ * apply rung a terminal-reached item is `vanished`). The orphan sweep asks a
+ * DIFFERENT question — "does a source item for this sidecar exist AT ALL?" — and a
+ * task/spec that reached its terminal (`tasks/cancelled/`, `specs/dropped/`) is a
+ * durable RESTING record that still EXISTS, so its sidecar is NOT an orphan.
+ * Treating "reached a terminal" as "gone" would let a routine `gc` delete a live
+ * sidecar (and any human answer it carries) — the 2026-07-12 false-positive.
+ *
+ * Reuses the shared {@link terminalMainPaths} (`item-lock.ts`, the SAME per-type
+ * terminal set the lock/branch reapers key off) so the "where do terminals live?"
+ * knowledge stays single-sourced. Returns the ACTIVE path when present, else the
+ * first existing TERMINAL path, else `undefined` (a genuine orphan).
+ */
+function resolveSourceForOrphanSweep(
+	cwd: string,
+	item: string,
+): string | undefined {
+	const active = resolveItemPathByIdentity(cwd, item);
+	if (active !== undefined) {
+		return active;
+	}
+	const {type, slug} = resolveSidecarIdentity(item);
+	for (const rel of terminalMainPaths(type, slug)) {
+		if (existsSync(join(cwd, rel))) {
+			return rel;
+		}
+	}
+	return undefined;
+}
+
 /**
  * The **orphan-sidecar reaper** — the WORKING-TREE counterpart of the job-worktree
  * and remote-branch reapers (`gc.ts` / `reap-branches.ts`), folded into `dorfl gc`
@@ -26,10 +62,14 @@ import {workFolderPath, workFolderRel} from './work-layout.js';
  *
  * The existence check REUSES the keystone's extracted `resolveItemPathByIdentity`
  * (`item-path.ts`, the neutral re-exported seam) — the same working-tree,
- * by-identity "does the source item exist?" resolver the apply rung uses — never a
- * forked second resolver. A sidecar whose source EXISTS is left untouched; a
- * sidecar whose source is ABSENT is `git rm`'d (deletion, not a `git mv`: the
- * sidecar leaves by deletion, recoverable from git history).
+ * by-identity "does the source item exist?" resolver the apply rung uses — WIDENED
+ * to also count a source that has reached a TERMINAL folder (`tasks/cancelled/`,
+ * `specs/dropped/`, via the shared `terminalMainPaths`) as EXISTING: a terminal is
+ * a durable resting record, not "gone", so its sidecar is NOT an orphan (see
+ * `resolveSourceForOrphanSweep`). A sidecar whose source EXISTS anywhere is left
+ * untouched; a sidecar whose source is ABSENT from every active AND terminal
+ * folder is `git rm`'d (deletion, not a `git mv`: the sidecar leaves by deletion,
+ * recoverable from git history).
  */
 
 /** A sidecar the orphan sweep reaped (its source item was absent). */
@@ -111,9 +151,10 @@ export function sweepOrphanSidecars(
 		const {item} = resolveSidecarIdentity(stem.replace('-', ':'));
 		const path = `${workFolderRel('questions')}/${entry}`;
 
-		const sourcePath = resolveItemPathByIdentity(input.cwd, item);
+		const sourcePath = resolveSourceForOrphanSweep(input.cwd, item);
 		if (sourcePath !== undefined) {
-			// The source item still exists ⇒ a LIVE sidecar ⇒ leave it untouched.
+			// The source item still exists (active lifecycle OR a terminal resting
+			// record) ⇒ a LIVE sidecar ⇒ leave it untouched.
 			retained.push({path, item, sourcePath});
 			note(`Retained ${path}: source ${item} still exists (${sourcePath}).`);
 			continue;

package/src/pi-harness.ts

@@ -65,6 +65,15 @@ import type {HarnessAdapter} from './config.js';
 /** The default pi CLI binary name (resolved on `PATH`). */
 export const DEFAULT_PI_BIN = 'pi';
 
+/**
+ * The grace period between a deadline SIGTERM and the follow-up SIGKILL in
+ * {@link PiHarness.launchAsync} (spec `graceful-pre-timeout-wip-checkpoint`).
+ * Ten seconds gives pi enough time to flush its session `.jsonl` and exit
+ * cleanly; a wedged/frozen child that ignores SIGTERM still gets reaped in a
+ * bounded time so the promise settles and the caller's checkpoint routing runs.
+ */
+export const DEADLINE_SIGKILL_GRACE_MS = 10_000;
+
 export interface PiHarnessOptions {
 	/**
 	 * The pi CLI binary (default `pi` on `PATH`). Tests inject a stub script here
@@ -239,11 +248,60 @@ export class PiHarness implements Harness {
 			child.stdout?.on('data', () => {});
 			// Guard so `exit` and a late `error` never double-settle the promise.
 			let settled = false;
+			let timedOut = false;
+			// DEADLINE RACE (spec `graceful-pre-timeout-wip-checkpoint`): when the
+			// caller threads a `deadlineMs` (absolute wall-clock epoch-ms), arm a
+			// SOFT SIGTERM at that time, then a HARD SIGKILL after a ~10s grace. The
+			// child's own `exit` handler below still resolves the promise (with
+			// `timedOut: true`), so we preserve the settle-once + FD-release
+			// discipline and never double-settle. A run that finishes BEFORE the
+			// deadline clears both timers (see the `exit` handler) — byte-for-byte
+			// unchanged from the pre-task behaviour.
+			let softTimer: NodeJS.Timeout | undefined;
+			let hardTimer: NodeJS.Timeout | undefined;
+			const clearDeadlineTimers = (): void => {
+				if (softTimer !== undefined) {
+					clearTimeout(softTimer);
+					softTimer = undefined;
+				}
+				if (hardTimer !== undefined) {
+					clearTimeout(hardTimer);
+					hardTimer = undefined;
+				}
+			};
+			if (input.deadlineMs !== undefined) {
+				const softMs = Math.max(0, input.deadlineMs - Date.now());
+				softTimer = setTimeout(() => {
+					if (settled) {
+						return;
+					}
+					timedOut = true;
+					try {
+						child.kill('SIGTERM');
+					} catch {
+						// Best-effort: a already-exited child throws ESRCH; the `exit`
+						// handler will still settle the promise.
+					}
+					hardTimer = setTimeout(() => {
+						if (settled) {
+							return;
+						}
+						try {
+							child.kill('SIGKILL');
+						} catch {
+							// Best-effort: see above.
+						}
+					}, DEADLINE_SIGKILL_GRACE_MS);
+					hardTimer.unref?.();
+				}, softMs);
+				softTimer.unref?.();
+			}
 			child.on('error', (err) => {
 				if (settled) {
 					return;
 				}
 				settled = true;
+				clearDeadlineTimers();
 				reject(new Error(`failed to spawn pi (${this.piBin}): ${err.message}`));
 			});
 			// Resolve on `exit` (pi itself terminated), NOT `close`: `close` waits for
@@ -255,6 +313,7 @@ export class PiHarness implements Harness {
 					return;
 				}
 				settled = true;
+				clearDeadlineTimers();
 				// Release our end of the stdio pipes so a leaked grandchild's inherited
 				// FDs stop keeping our streams referenced; `unref` the child handle too.
 				child.stdout?.destroy();
@@ -263,9 +322,11 @@ export class PiHarness implements Harness {
 				child.unref?.();
 				const status = code ?? -1;
 				resolve({
-					ok: status === 0,
+					ok: status === 0 && !timedOut,
 					record,
-					detail: status === 0 ? undefined : stderr.trim(),
+					detail:
+						status === 0 && !timedOut ? undefined : stderr.trim() || undefined,
+					timedOut: timedOut ? true : undefined,
 					// Read the agent's ANSWER from the `.jsonl` at `exit` — the same
 					// last-assistant-text read `launch` does at return (task
 					// `harness-agent-output`); the process has exited so the log is final.
@@ -354,6 +415,14 @@ export class PiHarness implements Harness {
  * pointer with an `existsSync` check. This is the pi-native "is there an audit
  * trail to look at?" signal — distinct from PID liveness, and STILL not mtime
  * (we check existence, never modification time).
+ *
+ * Studied (task `pi-harness-polish`, finding
+ * `work/notes/findings/pi-harness-channels.md`): the recorded `--session <path>`
+ * file remains the right audit pointer even against pi's other output surfaces
+ * (`--mode json` stdout stream, `--mode rpc`, in-process SDK) — those are
+ * transient stdio channels that do not survive the process, whereas the session
+ * file is the versioned, dashboard-visible activity trail pi itself treats as
+ * the audit artefact. PID stays the liveness anchor alongside it.
  */
 export function piSessionExists(record: HarnessRecord): boolean {
 	return record.session !== undefined && existsSync(record.session);
@@ -368,6 +437,17 @@ export function piSessionExists(record: HarnessRecord): boolean {
  * It REUSES `watch-session.ts`'s {@link lastAssistantText} (one `.jsonl` parser,
  * not two). An absent file (pi never wrote it) yields `undefined`, as does a log
  * with no assistant text — a read error is never thrown back into the launch.
+ *
+ * Studied (task `pi-harness-polish`, finding
+ * `work/notes/findings/pi-harness-channels.md`, pinned against pi 0.73.1 +
+ * session format v3): the session `.jsonl` is the right channel for output
+ * because it is the only one that is BOTH post-mortem readable AND explicitly
+ * versioned + migrated (`docs/session-format.md`). The `--mode json` STDOUT
+ * event stream is not versioned and is transient; `--mode rpc` and the
+ * in-process SDK cost more without solving anything the file does not. The
+ * cross-harness `LaunchResult.output` seam (Option C) is a bare `string | undefined`,
+ * so a future stream/HTTP-shaped harness (opencode-style) still fits: the file
+ * shape lives BEHIND this reader and is not observable through the seam.
  */
 function readLastAssistantText(sessionFile: string): string | undefined {
 	let jsonl: string;

package/src/placement.ts

@@ -19,7 +19,7 @@
  *
  * LIFECYCLE-GENERIC. The folder names + the configured-default value are
  * PARAMETERS (`slots`, `configuredDefault`), so the same resolver serves the
- * TASK lifecycle (`tasksLandIn`: `pre-backlog`/`ready` — the POOL value was
+ * TASK lifecycle (`tasksLandIn`: `backlog`/`ready` — the POOL value was
  * renamed `'backlog'` → `'todo'` → `'ready'`, ADR
  * `rename-task-pool-folder-todo-to-ready`) AND the SPEC-
  * placement lifecycle (`specsLandIn`: `pre-proposed`/`ready`) without forking. A future
@@ -31,7 +31,7 @@
  * Which side of the staging/pool split the runner chose. The CALLER maps this
  * onto the lifecycle's concrete folder name via {@link PlacementSlots}.
  *
- * - `'staging'` — land in the staging area (tasks: `pre-backlog/`; prds:
+ * - `'staging'` — land in the staging area (tasks: `tasks/backlog/`; prds:
  *   `specs/proposed/`). Not in the agent pool; a human/runner promotion is needed to make
  *   the item eligible. Review-without-PR review surface.
  * - `'pool'` — land directly in the agent-eligible pool (tasks: `tasks/ready/`;
@@ -42,7 +42,7 @@ export type PlacementSide = 'staging' | 'pool';
 /**
  * The two folder names a lifecycle uses for its staging/pool split. Supplied by
  * the caller so this resolver stays lifecycle-generic (the TASK caller passes
- * `{staging: 'pre-backlog', pool: 'tasks/ready'}`; the SPEC-placement caller passes
+ * `{staging: 'tasks/backlog', pool: 'tasks/ready'}`; the SPEC-placement caller passes
  * `{staging: 'specs/proposed', pool: 'specs/ready'}`).
  */
 export interface PlacementSlots {

package/src/prd-to-spec.ts

@@ -8,10 +8,11 @@ import {
 	mkdirSync,
 	rmdirSync,
 } from 'node:fs';
-import {join, relative, dirname} from 'node:path';
+import {join, relative, dirname, basename} from 'node:path';
 import {run, git, gitMv} from './git.js';
 import {resolveProtocolDoc} from './prompt.js';
 import {WORK_ROOT} from './work-layout.js';
+import {repoConfigPath} from './repo-config.js';
 
 /**
  * The **`dorfl prd-to-spec` migration ENGINE** (spec
@@ -675,7 +676,9 @@ export function migrateConfig(
 	migration: VocabularyMigration = MIGRATION,
 	options: {dryRun?: boolean} = {},
 ): ConfigRewrite[] {
-	const configAbs = join(repoPath, '.dorfl.json');
+	// Resolve the repo's actual config file (prefers `dorfl.json`, falls back to
+	// the legacy `.dorfl.json`), so the key rewrite finds it under either name.
+	const configAbs = repoConfigPath(repoPath);
 	if (!existsSync(configAbs)) {
 		return [];
 	}
@@ -922,10 +925,15 @@ export function scanForLeaks(
 			scanText(rel, readFileSync(join(repoPath, rel), 'utf8'), []);
 		}
 	}
-	// The config file (the key layer).
-	const configAbs = join(repoPath, '.dorfl.json');
+	// The config file (the key layer) — under either the preferred `dorfl.json`
+	// or the legacy `.dorfl.json`.
+	const configAbs = repoConfigPath(repoPath);
 	if (existsSync(configAbs)) {
-		scanText('.dorfl.json', readFileSync(configAbs, 'utf8'), configKeyPatterns);
+		scanText(
+			basename(configAbs),
+			readFileSync(configAbs, 'utf8'),
+			configKeyPatterns,
+		);
 	}
 	// The FOLDER TREE itself: a surviving `work/prds/` directory (empty ⇒ no
 	// file, but the folder still leaks). Report it structurally.

package/src/reap-branches.ts

@@ -1,6 +1,7 @@
 import {run} from './git.js';
-import {isAncestor} from './gc.js';
+import {isProvablyMergedForReap} from './gc.js';
 import {parseWorkBranchRef} from './slug-namespace.js';
+import type {SidecarType} from './sidecar.js';
 
 /**
  * The **remote merged-work-branch reaper** — the cross-machine COUNTERPART of the
@@ -9,13 +10,15 @@ import {parseWorkBranchRef} from './slug-namespace.js';
  * the arbiter after their propose-mode PR has MERGED.
  *
  * The safety lynchpin is the SAME provably-merged predicate the worktree reaper
- * uses (`gc.ts` `isAncestor`, REUSED here, never a second one): a remote
- * `work/<slug>` branch is reapable **iff** its tip is
- * `git merge-base --is-ancestor <tip> <arbiter>/main` — provably on `main`. A
- * merely-pushed-but-unmerged branch (an in-flight, kept-for-continue recovery
- * point) is NOT an ancestor of `main`, so the predicate AUTOMATICALLY excludes it
- * — the never-delete-the-in-flight-branch invariant (ADR §4 deletion-safety)
- * stays absolute. Deletion of a fully-merged ref needs NO force, so this NEVER
+ * uses (`gc.ts` `isProvablyMergedForReap`, REUSED here, never a second one): a
+ * remote `work/<slug>` branch is reapable **iff** it is provably on
+ * `<arbiter>/main` — EITHER `git merge-base --is-ancestor <tip> <arbiter>/main`
+ * (fast path) OR the squash-aware fallback (durable done/dropped record on main
+ * AND branch carries nothing main lacks). A merely-pushed-but-unmerged branch
+ * (an in-flight, kept-for-continue recovery point) has no terminal record on
+ * main AND is not an ancestor, so the predicate AUTOMATICALLY excludes it — the
+ * never-delete-the-in-flight-branch invariant (ADR §4 deletion-safety) stays
+ * absolute. Deletion of a fully-merged ref needs NO force, so this NEVER
  * `--force`s.
  *
  * It is provider-AGNOSTIC plain git (`git ls-remote` to enumerate, `git push
@@ -101,8 +104,9 @@ export interface SweepRemoteBranchesResult {
  *   2. Fetch `<arbiter>/main` into a local tracking ref so the ancestor check
  *      resolves the descendant LOCALLY; fetch each candidate tip object too (so
  *      `merge-base` can read it) — best-effort, into a scratch ref.
- *   3. For each branch whose tip `--is-ancestor` of the fetched main ⇒ delete via
- *      `git push <arbiter> --delete <branch>`; else retain with a reason.
+ *   3. For each branch that is provably merged for reap (fast-path ancestor
+ *      OR squash-aware fallback — {@link isProvablyMergedForReap}) ⇒ delete
+ *      via `git push <arbiter> --delete <branch>`; else retain with a reason.
  */
 export function sweepRemoteMergedBranches(
 	input: SweepRemoteBranchesInput,
@@ -126,12 +130,32 @@ export function sweepRemoteMergedBranches(
 			retain(retained, note, branch, tip, 'main-unresolved');
 			continue;
 		}
-		// Make the candidate tip OBJECT readable locally so `merge-base` can use it
-		// (ls-remote gave us the sha, but the object may not be in the local repo).
+		// Make the candidate tip OBJECT readable locally so `merge-base` /
+		// `diff` / `cherry` can read it (ls-remote gave us the sha, but the
+		// object may not be in the local repo).
 		fetchScratch(input.cwd, input.arbiter, branch, env);
 
-		if (!isAncestor(input.cwd, tip, mainRef, env)) {
-			// NOT an ancestor of main ⇒ still in-flight ⇒ NEVER delete (the invariant).
+		const parsed = parseWorkBranchRef(branch);
+		if (parsed === undefined) {
+			// Guarded above by `listRemoteWorkBranches` (which only enumerates
+			// parseable heads), but keep a defensive belt: without a slug the
+			// squash-aware fallback has no anchor ⇒ retain.
+			retain(retained, note, branch, tip, 'not-merged');
+			continue;
+		}
+
+		if (
+			!isProvablyMergedForReap({
+				cwd: input.cwd,
+				tip,
+				arbiterMain: mainRef,
+				namespace: parsed.namespace as SidecarType,
+				slug: parsed.slug,
+				env,
+			})
+		) {
+			// NOT provably merged (neither ancestor nor squash-aware equivalent)
+			// ⇒ still in-flight ⇒ NEVER delete (the invariant).
 			retain(retained, note, branch, tip, 'not-merged');
 			continue;
 		}

package/src/recover-isolated.ts

@@ -57,6 +57,18 @@ export interface RecoverIsolatedOptions {
 	integration?: IntegrationMode;
 	/** Suppress the PR on the propose path (push the branch, open no review request). */
 	noPR?: boolean;
+	/**
+	 * **The cross-job merge-serialiser CAS-retry cap** (config `mergeRetries`, spec
+	 * `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1
+	 * (a)). Threaded VERBATIM into {@link performIntegration} so a wide-matrix CI's
+	 * raised cap actually reaches the cross-job land queue on the isolated-recovery
+	 * path too (task `thread-merge-retries-cross-task-and-ratify-default`). Resolved
+	 * ONCE at the CLI (the `complete --isolated` command) through the SAME
+	 * gate-family precedence chain the plain `complete` path uses (flag > env >
+	 * per-repo > global > default). Unset ⇒ the engine's `DEFAULT_MERGE_RETRIES =
+	 * 1000` (byte-for-byte unchanged).
+	 */
+	mergeRetries?: number;
 	/** Optional fully-formed provider used verbatim (test/embedding seam). */
 	providerInstance?: ReviewProvider;
 	/** Optional injectable PR opener (legacy bridge); used in `propose` mode. */
@@ -177,6 +189,11 @@ export async function performRecoverIsolated(
 		recovering: false,
 		committedRecovery: true,
 		mode: options.integration ?? 'propose',
+		// The cross-job merge-serialiser CAS-retry cap (config `mergeRetries`) — the
+		// git-alone floor of the cross-job land queue, resolved through the gate-
+		// family precedence chain in the CLI and threaded here so the isolated-
+		// recovery land tail respects the per-repo cap.
+		mergeRetries: options.mergeRetries,
 		noPR: options.noPR,
 		providerInstance: options.providerInstance,
 		openPr: options.openPr,

package/src/repo-config.ts

@@ -2,6 +2,7 @@ import {readFileSync, existsSync} from 'node:fs';
 import {join} from 'node:path';
 import {
 	mergeConfig,
+	validateDeadlineConfig,
 	warnDeprecatedConfigKeys,
 	type Config,
 	type PartialConfig,
@@ -67,17 +68,17 @@ export const REPO_ALLOWED_KEYS = [
 	// still BUILDS each task as a reviewable PR is agreed by all collaborators +
 	// travels with the repo. Resolved per-repo through the SAME chain as
 	// `integration`, then falls back to `integration` when unset. DISTINCT from
-	// intake's per-EMITTED-TYPE `{task, prd}` resolver (front door, author-trust):
+	// intake's per-EMITTED-TYPE `{task, spec}` resolver (front door, author-trust):
 	// this is a per-lifecycle-transition knob, inside the boundary, config-resolved.
 	'taskingIntegration',
 	// `tasksLandIn` (the per-repo TASK-PLACEMENT default — staging vs pool, spec
 	// `staging-pool-position-gate-and-trust-model` US #5) is a genuine repo property
 	// exactly like `taskingIntegration`/`integration`: whether THIS repo's tasker
-	// output lands STAGED (`pre-backlog/`, review-without-PR human-promote path) or
+	// output lands STAGED (`tasks/backlog/`, review-without-PR human-promote path) or
 	// straight in the agent-eligible POOL (`ready/`, trusted fast-path) is agreed
 	// by all collaborators + travels with the repo. Resolved per-repo through the
 	// SAME chain as `taskingIntegration` (flag > env > per-repo > global > built-in
-	// `pre-backlog`). DISTINCT from intake's per-emitted-type stamps (front door):
+	// `backlog`). DISTINCT from intake's per-emitted-type stamps (front door):
 	// this is a per-lifecycle PLACEMENT knob, inside the trust boundary,
 	// config-resolved. Fed into the shared placement resolver as the
 	// configured-default rung (`src/placement.ts`).
@@ -91,7 +92,7 @@ export const REPO_ALLOWED_KEYS = [
 	// through the SAME chain as `tasksLandIn` (flag `--specs-land-in` > env
 	// `DORFL_SPECS_LAND_IN` > per-repo > global > built-in). Fed into the shared
 	// placement resolver as the configured-default rung for the spec lifecycle
-	// (`src/placement.ts`). The sole spec-placement key after the `prd` → `spec` HARD
+	// (`src/placement.ts`). The sole spec-placement key after the ''prd'' → `spec` HARD
 	// CUTOVER (the legacy `prdsLandIn` key is GONE — clean break, no accepted alias).
 	'specsLandIn',
 	// `noPR` (the PR-INTENT axis — push the branch but deliberately skip the PR) is
@@ -207,6 +208,16 @@ export const REPO_ALLOWED_KEYS = [
 	// default or shape. The re-surface vs. land branch is
 	// `apply-rung-merge-disposition`'s consumer, never here.
 	'strictMergeApproval',
+	// `agentDeadlineMinutes` / `checkpointHeadroomMinutes` / `maxAutoCheckpoints`
+	// (spec `graceful-pre-timeout-wip-checkpoint`) are genuine repo properties:
+	// how long an agent session runs before checkpointing, and how much head-room
+	// the GitHub backstop leaves above it, are agreed by all collaborators + travel
+	// with the repo. The dynamic GitHub `timeout-minutes` cap is rendered by the
+	// `enumerate` job at run time FROM this committed config, so an edit reflects
+	// EVERYWHERE (internal deadline AND GitHub cap) with no install-ci re-run.
+	'agentDeadlineMinutes',
+	'checkpointHeadroomMinutes',
+	'maxAutoCheckpoints',
 	// `promptGuidance` (the NUDGE namespace — prompt-text knobs that strengthen
 	// the worker's in-band wrapper line, e.g. `testFirst`) is a genuine repo
 	// property: "is this repo nudged toward test-first?" travels with the repo
@@ -257,9 +268,42 @@ export type RepoRejectedKey = (typeof REPO_REJECTED_KEYS)[number];
 
 const ALLOWED_SET = new Set<string>(REPO_ALLOWED_KEYS);
 
-/** The path to a repo's `.dorfl.json` (repo root + filename). */
+/**
+ * The LEGACY per-repo config filename (`.dorfl.json`, the original dotfile form)
+ * still honoured on READ for backward compatibility. Reads prefer
+ * {@link REPO_CONFIG_FILENAME} (`dorfl.json`) and fall back to this; writes /
+ * `setup` use the preferred name. Derived from the single brand identity so a
+ * rename flips it in lockstep (see `brand.ts`).
+ */
+export const REPO_CONFIG_FILENAME_LEGACY = brand.repoConfigFilenameLegacy;
+
+/**
+ * Resolve which per-repo config file a repo USES: the PREFERRED
+ * `dorfl.json` if present, else the LEGACY `.dorfl.json` if present, else the
+ * preferred path (the location a missing file WOULD live / be created at). So a
+ * repo that already committed the legacy dotfile keeps working, while a fresh
+ * repo (and every write) uses the plain name. If BOTH exist, the preferred
+ * `dorfl.json` wins (a deliberate, documented precedence, not a merge).
+ */
+export function resolveRepoConfigPath(repoPath: string): string {
+	const preferred = join(repoPath, REPO_CONFIG_FILENAME);
+	if (existsSync(preferred)) {
+		return preferred;
+	}
+	const legacy = join(repoPath, REPO_CONFIG_FILENAME_LEGACY);
+	if (existsSync(legacy)) {
+		return legacy;
+	}
+	return preferred;
+}
+
+/**
+ * The path to a repo's config file. Prefers the plain `dorfl.json`, falls back
+ * to the legacy `.dorfl.json` when only that exists (see
+ * {@link resolveRepoConfigPath}).
+ */
 export function repoConfigPath(repoPath: string): string {
-	return join(repoPath, REPO_CONFIG_FILENAME);
+	return resolveRepoConfigPath(repoPath);
 }
 
 /** The result of reading (and filtering) a repo's `.dorfl.json`. */
@@ -542,6 +586,11 @@ export function resolveRepoConfigFromLoaded(
 		...envOverrides(env),
 		...(flags ?? {}),
 	});
+	// Fail-loud range validation for the deadline / backstop / ceiling triple
+	// (spec `graceful-pre-timeout-wip-checkpoint`): a bad value from ANY layer
+	// (flag / env / per-repo / global) throws with a clear message naming the
+	// field + range — NEVER silently clamped.
+	validateDeadlineConfig(config);
 	return {
 		config,
 		rejected: repo.rejected,

package/src/repo-mirror.ts

@@ -5,6 +5,7 @@ import type {Config, PartialConfig} from './config.js';
 import type {ConfigOverrideMap} from './config-override.js';
 import {
 	REPO_CONFIG_FILENAME,
+	REPO_CONFIG_FILENAME_LEGACY,
 	loadRepoConfigFromContent,
 	resolveRepoConfigFromLoaded,
 	type LoadedRepoConfig,
@@ -247,7 +248,28 @@ export function readRepoConfigFromMirrorMain(
 	mirrorDir: string,
 	env?: NodeJS.ProcessEnv,
 ): string | undefined {
-	const spec = `main:${REPO_CONFIG_FILENAME}`;
+	// Prefer the plain `dorfl.json`; fall back to the legacy `.dorfl.json` when the
+	// preferred name is absent on `main` (a repo that committed the dotfile before
+	// dual-support). A genuine read fault on the FIRST attempt propagates; a
+	// path-missing on the first falls through to the legacy attempt.
+	const preferred = showConfigOnMain(mirrorDir, REPO_CONFIG_FILENAME, env);
+	if (preferred !== undefined) {
+		return preferred;
+	}
+	return showConfigOnMain(mirrorDir, REPO_CONFIG_FILENAME_LEGACY, env);
+}
+
+/**
+ * `git show main:<filename>` in a mirror, returning the bytes, or `undefined`
+ * when the PATH is absent on `main` (the expected config-less / wrong-name case).
+ * A genuine fault (unresolvable `main` / bad object) throws.
+ */
+function showConfigOnMain(
+	mirrorDir: string,
+	filename: string,
+	env?: NodeJS.ProcessEnv,
+): string | undefined {
+	const spec = `main:${filename}`;
 	const res = run('git', ['show', spec], mirrorDir, {env});
 	if (res.status === 0) {
 		return res.stdout;

package/src/review-verdict.ts

@@ -397,7 +397,7 @@ export function reviewDisciplinePrompt(): string {
 		'(the in-band, protocol-native review protocol every set-up repo carries;',
 		'the human-facing pointer is `skills/review/SKILL.md`). Apply its lenses',
 		'IN ORDER, ENDING in the destination check ("if this is built/merged',
-		'exactly as written, do we end up with the system the prd/task',
+		'exactly as written, do we end up with the system the spec/task',
 		'goal describes?"). Be ADVERSARIAL; verify against what ACTUALLY LANDED',
 		'(the bytes on disk), not intent. Weight findings by REAL impact \u2014 the',
 		'lenses find candidates, impact decides severity (a technically-true nit',