dorfl 0.1.1 → 0.2.0

package/src/config.ts

@@ -17,12 +17,12 @@ import {
 export type IntegrationMode = 'propose' | 'merge';
 
 /**
- * **Per-repo TASK-PLACEMENT default** (prd
+ * **Per-repo TASK-PLACEMENT default** (spec
  * `staging-pool-position-gate-and-trust-model`, task
  * `runner-deterministic-slice-placement-policy-and-precedence`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). Which
  * folder the runner lands the tasker's emitted task files in BY DEFAULT —
- * `'pre-backlog'` (staging — durable + readable but NOT in the agent-eligible
+ * `'backlog'` (staging — durable + readable but NOT in the agent-eligible
  * POOL; a runner/human promotion is needed to make an item claimable; the on-disk
  * folder for this value is `work/tasks/backlog/`) or `'ready'` (the agent-eligible
  * POOL — the trusted fast-path landing, on-disk `work/tasks/ready/`). The pool
@@ -30,32 +30,33 @@ export type IntegrationMode = 'propose' | 'merge';
  * `rename-task-pool-folder-todo-to-ready`, a CLEAN BREAK matching the on-disk
  * folder `tasks/ready/` and the spec-side `'ready'` pool spelling). The runner-deterministic
  * placement RESOLVER (`src/placement.ts`) layers on top: `explicit operator flag
- * > untrusted-origin ⇒ pre-backlog > tasksLandIn default > built-in
- * (pre-backlog)`. An untrusted-origin tasker output is FORCED to staging even in
+ * > untrusted-origin ⇒ backlog > tasksLandIn default > built-in
+ * (backlog)`. The staging value was renamed `'pre-backlog'` → `'backlog'`
+ * (matching the on-disk folder `tasks/backlog/`). An untrusted-origin tasker output is FORCED to staging even in
  * a `'ready'` repo (the positional analogue of the existing
  * `untrusted-origin-forces-build-propose` rule).
  */
-export type TasksLandIn = 'pre-backlog' | 'ready';
+export type TasksLandIn = 'backlog' | 'ready';
 
 /**
- * **Per-repo PRD-PLACEMENT default** (prd
+ * **Per-repo SPEC-PLACEMENT default** (spec
  * `staging-pool-position-gate-and-trust-model`, task
  * `pre-prd-staging-pool-split-and-untrusted-prd-placement`, governing ADR
  * `placement-is-runner-deterministic-humanonly-is-agent-judgement`). Which
- * folder the runner lands `intake`-authored prd files in BY DEFAULT —
+ * folder the runner lands `intake`-authored spec files in BY DEFAULT —
  * `'pre-proposed'` (staging — durable + readable but NOT in the auto-tasking
- * POOL; a runner/human promotion is needed to make the prd auto-taskable; the
- * on-disk folder for this value is `work/prds/proposed/`) or `'ready'` (the
+ * POOL; a runner/human promotion is needed to make the spec auto-taskable; the
+ * on-disk folder for this value is `work/specs/proposed/`) or `'ready'` (the
  * auto-tasking POOL — the trusted fast-path landing, on-disk
- * `work/prds/ready/`). The same runner-deterministic placement RESOLVER
+ * `work/specs/ready/`). The same runner-deterministic placement RESOLVER
  * (`src/placement.ts`) layers on top:
  * `explicit operator flag > untrusted-origin ⇒ pre-proposed > specsLandIn
  * default > built-in (pre-proposed)`. An untrusted-origin intake spec is FORCED
  * to staging even in a `'ready'` repo (the positional analogue of the existing
- * `untrusted-origin-forces-build-propose` rule). The PRD twin of
+ * `untrusted-origin-forces-build-propose` rule). The SPEC twin of
  * {@link TasksLandIn}; the SAME shape, the SAME precedence chain. The value
- * spellings mirror the live prd folders (`prds/proposed/` staging,
- * `prds/ready/` pool), exactly as {@link TasksLandIn} mirrors the task folders.
+ * spellings mirror the live spec folders (`specs/proposed/` staging,
+ * `specs/ready/` pool), exactly as {@link TasksLandIn} mirrors the task folders.
  */
 export type SpecsLandIn = 'pre-proposed' | 'ready';
 
@@ -79,7 +80,7 @@ export type ObservationTriage = 'off' | 'ask' | 'auto';
 
 /**
  * **The `mergeQuestions` gate axis** — the 3-state member of the question-
- * surfacing gate family that governs the MERGE-QUESTION surfacer (prd
+ * surfacing gate family that governs the MERGE-QUESTION surfacer (spec
  * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
  * `merge-questions-gate-axis`). MIRRORS `observationTriage`'s shape
  * (`off | ask | auto`) but is a SEPARATE axis — "should this built work merge?"
@@ -99,7 +100,7 @@ export type ObservationTriage = 'off' | 'ask' | 'auto';
  *     invoke the agentic decider — a merge-land is never an agent decision.
  * Resolved through the SAME precedence chain as the other gates (flag > env >
  * per-repo > global > default `ask`). The exact name + default + shape were
- * answered in this task's Applied answers 2026-06-26 (q1/q2/q3) + PRD sidecar
+ * answered in this task's Applied answers 2026-06-26 (q1/q2/q3) + SPEC sidecar
  * Q3.
  */
 export type MergeQuestions = 'off' | 'ask' | 'auto';
@@ -201,10 +202,10 @@ export interface Config {
 	/**
 	 * Per-repo policy: may an agent auto-task *undeclared* (not `humanOnly`,
 	 * no open questions) prds in this repo? `false` (default, strict, human-first)
-	 * ⇒ a human must drive every prd's tasking; `true` ⇒ an agent may auto-task
-	 * any prd that is not `humanOnly: true` and has no `needsAnswers`. Resolved like
+	 * ⇒ a human must drive every spec's tasking; `true` ⇒ an agent may auto-task
+	 * any spec that is not `humanOnly: true` and has no `needsAnswers`. Resolved like
 	 * `autoBuild`: flag > `DORFL_AUTO_TASK` env > per-repo > global >
-	 * default. The two-axis tasking gate (`work/prds/auto-task.md`), one level up
+	 * default. The two-axis tasking gate (`work/specs/auto-task.md`), one level up
 	 * from the build gate's `autoBuild`.
 	 */
 	autoTask: boolean;
@@ -227,7 +228,7 @@ export interface Config {
 	observationTriage: ObservationTriage;
 	/**
 	 * Per-repo policy governing the MERGE-QUESTION SURFACER — the 3-state member
-	 * of the question-surfacing gate family (prd
+	 * of the question-surfacing gate family (spec
 	 * `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
 	 * `merge-questions-gate-axis`). MIRRORS `observationTriage`'s SHAPE
 	 * (`off | ask | auto`) but is a SEPARATE axis with a DIFFERENT default —
@@ -251,7 +252,7 @@ export interface Config {
 	 * Per-repo policy governing DECLARED blocked work — the BOOLEAN member of the
 	 * question-surfacing gate family (its orthogonal PEER is `observationTriage`,
 	 * which governs the raw observation INBOX; ADR `ci-config-policy-and-gate-family`
-	 * §2). It gates whether a task/prd carrying `needsAnswers: true` is rendered
+	 * §2). It gates whether a task/spec carrying `needsAnswers: true` is rendered
 	 * into an answerable question sidecar (`on`) or left silently blocked in the
 	 * backlog (`off`). `false` (default, calm) ⇒ the `needsAnswers`-blocked pool is
 	 * dropped from the auto-pick SELECTION, so a bare `advance` does NOT proactively
@@ -271,11 +272,11 @@ export interface Config {
 	/**
 	 * Per-repo policy governing whether SURFACING (the question-minting polarity)
 	 * inspects STAGING in addition to the agent pool — the BOOLEAN gate-family
-	 * member added by prd `staging-surface-and-apply-promote-safety` (F2). The
+	 * member added by spec `staging-surface-and-apply-promote-safety` (F2). The
 	 * BUILD polarity is UNCHANGED in either mode: staging items stay non-claimable,
 	 * the trust model is untouched. `true` (default) ⇒ the SURFACE candidate set
-	 * draws from STAGING (`tasks/backlog/`, `prds/proposed/`) PLUS the pool, so
-	 * a `needsAnswers` task/prd in staging surfaces its questions BEFORE a human
+	 * draws from STAGING (`tasks/backlog/`, `specs/proposed/`) PLUS the pool, so
+	 * a `needsAnswers` task/spec in staging surfaces its questions BEFORE a human
 	 * promotes it (you promote an already-clarified item, not blind and then get
 	 * asked after); `false` ⇒ the legacy POOL-ONLY behaviour (staging is not
 	 * inspected for questions). Resolved like `surfaceBlockers`/`autoBuild`:
@@ -340,33 +341,33 @@ export interface Config {
 	/** Integration mode for completed items: `propose` (default) or `merge`. */
 	integration: IntegrationMode;
 	/**
-	 * **Per-TRANSITION override for the prd→tasks (TASKING) transition only.** When
-	 * set, the tasking transition (a `do prd:<slug>` run: emit `work/tasks/backlog/*.md` +
-	 * the `work/prds/ready/ → work/prds/tasked/` lifecycle move) integrates with THIS
+	 * **Per-TRANSITION override for the spec→tasks (TASKING) transition only.** When
+	 * set, the tasking transition (a `do spec:<slug>` run: emit `work/tasks/backlog/*.md` +
+	 * the `work/specs/ready/ → work/specs/tasked/` lifecycle move) integrates with THIS
 	 * mode instead of the flat {@link integration}; the task-BUILD transition is
 	 * unaffected (it always reads {@link integration}). UNSET (the default) ⇒ tasking
 	 * falls back to {@link integration} — byte-for-byte today's behaviour for any repo
 	 * that does not set it. The maintainer's target is `integration: 'propose'` +
-	 * `taskingIntegration: 'merge'`: task a prd straight onto `main` (the task FILES
+	 * `taskingIntegration: 'merge'`: task a spec straight onto `main` (the task FILES
 	 * land, no PR) but build each task as a reviewable PR. Resolved per-repo like
 	 * {@link integration}: flag (`--merge`/`--propose`) > env
 	 * (`DORFL_TASKING_INTEGRATION`) > per-repo > global > (fall back to)
 	 * `integration` > default `propose`. DISTINCT from intake's per-EMITTED-TYPE
-	 * `{task, prd}` resolver (front door, author-trust-resolved): this is a
+	 * `{task, spec}` resolver (front door, author-trust-resolved): this is a
 	 * per-LIFECYCLE-TRANSITION knob, inside the trust boundary, operator/config-only.
 	 */
 	taskingIntegration?: IntegrationMode;
 	/**
-	 * **Per-repo DEFAULT landing for the TASKER's emitted tasks** (prd
+	 * **Per-repo DEFAULT landing for the TASKER's emitted tasks** (spec
 	 * `staging-pool-position-gate-and-trust-model` US #5, task
 	 * `runner-deterministic-slice-placement-policy-and-precedence`). Resolved
 	 * per-repo EXACTLY like {@link taskingIntegration} (flag `--tasks-land-in`
 	 * > env `DORFL_TASKS_LAND_IN` > per-repo > global > built-in
-	 * `'pre-backlog'`). The tasking path reads it and passes it as the
+	 * `'backlog'`). The tasking path reads it and passes it as the
 	 * CONFIGURED-DEFAULT rung into the shared placement resolver
 	 * (`src/placement.ts`); the resolver overlays an EXPLICIT operator flag
 	 * (top) and the UNTRUSTED-ORIGIN force (staging) on top, in that order. The
-	 * tasker NEVER sets placement itself. Prd US #6 / the governing ADR: the
+	 * tasker NEVER sets placement itself. Spec US #6 / the governing ADR: the
 	 * runner OWNS placement from unforgeable inputs; the agent cannot
 	 * influence it.
 	 */
@@ -385,7 +386,7 @@ export interface Config {
 	 * influence it. KEY-LEVEL SYMMETRY with `tasksLandIn` — one resolver, two
 	 * lifecycles, one precedence change touches ONE place.
 	 *
-	 * The sole spec-placement key after the prd → spec HARD CUTOVER (spec
+	 * The sole spec-placement key after the ''prd'' → `spec` HARD CUTOVER (spec
 	 * `prd-to-spec-vocabulary-cutover-and-migration-command`): the legacy
 	 * `prdsLandIn` config key + `--prds-land-in` flag are GONE (clean break).
 	 */
@@ -483,7 +484,7 @@ export interface Config {
 	 */
 	verify?: VerifyConfig;
 	/**
-	 * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/tasked/review.md`): run the
+	 * **Gate 2 — the PR/code review gate** (GATES spec `work/specs/tasked/review.md`): run the
 	 * `review` SKILL as a fresh-context judgement gate ON TOP of the deterministic
 	 * `verify` floor, AFTER `verify` passes and BEFORE the done-move, on the
 	 * `do`/`complete` path. Default **OFF** (it puts a model on the merge path —
@@ -508,8 +509,8 @@ export interface Config {
 	 * re-rolled — re-reviewing an unchanged tip after a block would just be a
 	 * stochastic dice re-roll that could launder a real reject into a pass). So a
 	 * value > 1 makes a FALSE APPROVE harder to slip through (each extra round is a
-	 * veto), it does NOT give blocked work a second chance. A non-approve forces
-	 * `needs-attention/` (never silently merges or loops), per the maintainer
+	 * veto), it does NOT give blocked work a second chance. A non-approve forces the
+	 * item stuck (the lock `state: stuck`; never silently merges or loops), per the maintainer
 	 * decision. Default a small N (2): two independent approvals required. (A future
 	 * builder-REVISE step that MUTATES the tree between rounds is the only thing that
 	 * should make a block retryable, because it changes the artifact under review; it
@@ -519,7 +520,7 @@ export interface Config {
 	reviewMaxRounds: number;
 	/**
 	 * **The tasker IMPROVER loop on/off toggle** (`--tasker-loop` /
-	 * `--no-tasker-loop`). On the `do prd:<slug>` tasking path the improver loop is
+	 * `--no-tasker-loop`). On the `do spec:<slug>` tasking path the improver loop is
 	 * the task path's quality engine (auto-tasking has no `verify` floor), so it is
 	 * ON by default; setting this false gates wiring the loop seam (the candidate
 	 * tasks land as-is). Resolved per-repo like `integration`: flag
@@ -529,8 +530,8 @@ export interface Config {
 	taskerLoop: boolean;
 	/**
 	 * **The tasker IMPROVER loop's convergence cap** (`slicer-review-edit-loop`,
-	 * GATES prd `work/prds/tasked/review.md` RESOLVED DESIGN — Shape 2 / insertion point
-	 * A). On the `do prd:<slug>` tasking path, AFTER the agent produces candidate
+	 * GATES spec `work/specs/tasked/review.md` RESOLVED DESIGN — Shape 2 / insertion point
+	 * A). On the `do spec:<slug>` tasking path, AFTER the agent produces candidate
 	 * tasks the loop runs the `review` SKILL, APPLIES its edits, and re-reviews
 	 * until a pass finds no NEW blocking issue (the natural terminator).
 	 * `taskerLoopMax` is the HARD CAP on the in-context review passes (N) so the
@@ -583,7 +584,7 @@ export interface Config {
 	freshWorktreeGate: boolean;
 	/**
 	 * **The cross-job merge serialiser's CAS-retry cap** — the git-alone FLOOR of the
-	 * land-time cross-job queue (prd `land-time-reverify-and-parallel-merge-ceiling`,
+	 * land-time cross-job queue (spec `land-time-reverify-and-parallel-merge-ceiling`,
 	 * Story 5 + Applied Answer q1 (a)). The merge-mode `${branch}:main` push retries
 	 * a non-fast-forward rejection by re-rebasing onto the moved `<arbiter>/main` and
 	 * pushing again, up to this cap; only after exhaustion does a loser bounce to
@@ -605,7 +606,7 @@ export interface Config {
 	mergeRetries: number;
 	/**
 	 * **Per-repo OPT-IN strictness layered on the OQ6 stale-approval default**
-	 * (prd `land-time-reverify-and-parallel-merge-ceiling`, sidecar OQ6 / task
+	 * (spec `land-time-reverify-and-parallel-merge-ceiling`, sidecar OQ6 / task
 	 * `strict-merge-approval-gate`). Controls how the apply rung treats a prior
 	 * merge-answer when the merge-base CHANGED between the human's answer and
 	 * the apply step. The default (`false`) honours the prior answer and lands
@@ -626,6 +627,40 @@ export interface Config {
 	 * `observationTriage` default or shape — a SEPARATE, independent axis.
 	 */
 	strictMergeApproval: boolean;
+	/**
+	 * **The dorfl-INTERNAL agent deadline** (minutes). The agent session self-stops
+	 * at this budget; dorfl then SAVES the WIP (commit + push `work/<slug>`) and
+	 * routes it per the progress+ceiling decision (auto-continue, or surface). This
+	 * is the PRIMARY stop (see spec `graceful-pre-timeout-wip-checkpoint`); the
+	 * GitHub `timeout-minutes` cap is a BACKSTOP set above it as
+	 * `agentDeadlineMinutes + checkpointHeadroomMinutes`. Default 60; MAX 240 (4h).
+	 * FAIL-LOUD: values outside `[1, 240]` throw at config load (never silently
+	 * clamped). Resolved per-repo through the SAME chain as `integration` (flag >
+	 * env `DORFL_AGENT_DEADLINE_MINUTES` > per-repo > global > default).
+	 */
+	agentDeadlineMinutes: number;
+	/**
+	 * **The GitHub-backstop head-room above the internal deadline** (minutes). The
+	 * enumerate job's dynamic `githubTimeout` output is
+	 * `agentDeadlineMinutes + checkpointHeadroomMinutes`; the MIN 10 guarantees the
+	 * GitHub cap is always at least 10 minutes above the internal deadline so the
+	 * graceful save always has room to commit + push before the hard kill. Default
+	 * 30; MIN 10; MAX 60 (1h). FAIL-LOUD: out-of-range throws at load. Resolved
+	 * per-repo through the SAME chain as `agentDeadlineMinutes`.
+	 */
+	checkpointHeadroomMinutes: number;
+	/**
+	 * **The auto-continue ceiling** for the deadline-checkpoint anti-loop guard
+	 * (spec `graceful-pre-timeout-wip-checkpoint`). Counts CONSECUTIVE deadline
+	 * auto-continues; on hitting this cap the next deadline checkpoint SURFACES a
+	 * `needsAnswers:true` question ("this task has hit the deadline N times — it
+	 * may be too big for one CI leg; split it or run it locally?") instead of
+	 * auto-continuing. The counter naturally resets when the item completes (the
+	 * work branch is discarded on integration). Default 5. Must be a positive
+	 * integer (fail-loud). Resolved per-repo through the SAME chain as its
+	 * siblings.
+	 */
+	maxAutoCheckpoints: number;
 	/**
 	 * The optional runner **identity** (a bot): run the runner's git + provider
 	 * operations as a configured entity via process-scoped env overrides, without
@@ -711,7 +746,7 @@ export const DEFAULT_CONFIG: Config = {
 	// auto-dispose the no-question cases). ADR `ci-config-policy-and-gate-family` §3.
 	observationTriage: 'off',
 	// The merge-question SURFACER defaults to `ask` — the conservative default
-	// (prd `land-time-reverify-and-parallel-merge-ceiling` Applied answer q2 /
+	// (spec `land-time-reverify-and-parallel-merge-ceiling` Applied answer q2 /
 	// task `merge-questions-gate-axis` Applied answer q2). NEVER `off` by default:
 	// a silently-dropped merge-question means finished, pushed work never lands —
 	// strictly more consequential than a dropped observation-promote prompt, so
@@ -728,9 +763,9 @@ export const DEFAULT_CONFIG: Config = {
 	// (a stuck build) is separate + always-on. ADR `ci-config-policy-and-gate-family` §3.
 	surfaceBlockers: false,
 	// SURFACING widens to STAGING by default (`true`) — a `needsAnswers` task in
-	// `tasks/backlog/` or a `needsAnswers` prd in `prds/proposed/` surfaces
+	// `tasks/backlog/` or a `needsAnswers` spec in `specs/proposed/` surfaces
 	// its questions BEFORE promotion, so a human promotes an already-clarified
-	// item. Prd `staging-surface-and-apply-promote-safety` (F2). BUILD/claim
+	// item. Spec `staging-surface-and-apply-promote-safety` (F2). BUILD/claim
 	// stays pool-only + trust-gated regardless: this widens ONLY the surface
 	// polarity, not the build polarity. Set `false` to restore the legacy
 	// pool-only surface behaviour.
@@ -741,7 +776,7 @@ export const DEFAULT_CONFIG: Config = {
 	// always first. Reproduces today's tasks-first two-pool default. Subsumes the
 	// removed `prdsFirst` boolean (`[task, build, ...]` reproduces `prdsFirst: true`).
 	selectionOrder: DEFAULT_SELECTION_ORDER,
-	maxParallel: 4,
+	maxParallel: 2,
 	perRepoMax: 2,
 	defaultArbiter: 'origin',
 	workspacesDir: join(homedir(), brand.workdirName),
@@ -752,14 +787,14 @@ export const DEFAULT_CONFIG: Config = {
 	// branch but deliberately skip the PR (the explicit suppress-PR intent that
 	// re-homes the old `provider: none` use). NOT a provider choice.
 	noPR: false,
-	// The tasker's emitted tasks land STAGED (`pre-backlog/`) by default — the
+	// The tasker's emitted tasks land STAGED (`tasks/backlog/`) by default — the
 	// conservative landing that preserves the tracer task's behaviour: an item is
 	// durable + readable but NOT in the agent-eligible pool until a human/runner
 	// promotes it. A repo opts into the trusted fast-path with `tasksLandIn:
 	// 'ready'` (or `--tasks-land-in ready` / `DORFL_TASKS_LAND_IN=ready`).
 	// The runner-deterministic resolver overlays explicit-flag + untrusted-origin
 	// force on top of this default (`src/placement.ts`).
-	tasksLandIn: 'pre-backlog',
+	tasksLandIn: 'backlog',
 	// `intake`-authored specs land STAGED (`pre-proposed/`) by default — the
 	// conservative landing that mirrors `tasksLandIn`'s built-in floor: a spec is
 	// durable + readable but NOT in the auto-tasking POOL until a human/runner
@@ -791,7 +826,7 @@ export const DEFAULT_CONFIG: Config = {
 	// (positive name, default-on).
 	freshWorktreeGate: true,
 	// The cross-job merge serialiser's CAS-retry cap — the git-alone FLOOR of the
-	// land-time cross-job queue (prd `land-time-reverify-and-parallel-merge-ceiling`,
+	// land-time cross-job queue (spec `land-time-reverify-and-parallel-merge-ceiling`,
 	// Story 5 + Applied Answer q1 (a)). Matches `integration-core.ts`'s built-in
 	// `DEFAULT_MERGE_RETRIES` fallback (1000 — the C2 large liveness ceiling, NOT a
 	// small Race-1 budget) so resolving it through this layer is byte-for-byte
@@ -800,14 +835,71 @@ export const DEFAULT_CONFIG: Config = {
 	mergeRetries: 1000,
 	// The strict-merge-approval gate defaults OFF (sidecar OQ6 / task
 	// `strict-merge-approval-gate`): the cheap "green re-verify is enough" path
-	// is the default; the OQ6 PRD answer pins this. A repo opts in to the
+	// is the default; the OQ6 SPEC answer pins this. A repo opts in to the
 	// host-agnostic "dismiss stale approvals on base change" discipline with
 	// `strictMergeApproval: true` (or `--strict-merge-approval` /
 	// `DORFL_STRICT_MERGE_APPROVAL=true`). The re-surface vs. land branch is
 	// `apply-rung-merge-disposition`'s consumer, NOT here.
 	strictMergeApproval: false,
+	// The dorfl-INTERNAL agent deadline defaults to 60 minutes (spec
+	// `graceful-pre-timeout-wip-checkpoint`). A legitimately-long task that runs
+	// past this checkpoints its WIP + auto-continues on the next tick (rather than
+	// losing everything to a 6h GitHub SIGKILL). MAX 240 (4h); fail-loud outside.
+	agentDeadlineMinutes: 60,
+	// The GitHub-backstop head-room above the internal deadline defaults to 30
+	// minutes: the enumerate job's dynamic `githubTimeout` output is
+	// deadline + headroom, so the default GitHub cap is 60 + 30 = 90 (1h30). MIN 10
+	// (guarantees the graceful save has room); MAX 60; fail-loud outside.
+	checkpointHeadroomMinutes: 30,
+	// The auto-continue ceiling defaults to 5 CONSECUTIVE deadline checkpoints;
+	// past that the next checkpoint SURFACES to a human (spec
+	// `graceful-pre-timeout-wip-checkpoint` anti-loop guard).
+	maxAutoCheckpoints: 5,
 };
 
+/**
+ * Fail-loud range validation for the deadline / backstop / ceiling triple
+ * (spec `graceful-pre-timeout-wip-checkpoint`). Called at the two resolution
+ * FINAL points (`loadConfig` for the global chain; `resolveRepoConfigFromLoaded`
+ * for the per-repo chain), so an out-of-range value from ANY layer (flag / env /
+ * per-repo / global) surfaces as a clean throw naming the field + the valid
+ * range. Never clamps — the task's decision is fail-loud, since a silently
+ * clamped 400-minute deadline would look correct in `dorfl config --json` and
+ * quietly break the invariant that GitHub cap > internal deadline.
+ */
+export function validateDeadlineConfig(config: Config): void {
+	const adm = config.agentDeadlineMinutes;
+	if (!Number.isInteger(adm) || adm < 1 || adm > 240) {
+		throw new Error(
+			`agentDeadlineMinutes must be a positive integer in [1, 240] ` +
+				`(got ${adm}). The dorfl-internal agent deadline caps a single ` +
+				`agent session; 240 minutes (4h) is the hard ceiling so the ` +
+				`GitHub backstop (deadline + headroom) still fits under GitHub's ` +
+				`6h job limit.`,
+		);
+	}
+	const chm = config.checkpointHeadroomMinutes;
+	if (!Number.isInteger(chm) || chm < 10 || chm > 60) {
+		throw new Error(
+			`checkpointHeadroomMinutes must be an integer in [10, 60] ` +
+				`(got ${chm}). This is the head-room the GitHub 'timeout-minutes' ` +
+				`backstop sits above the internal deadline (rendered dynamically ` +
+				`as agentDeadlineMinutes + checkpointHeadroomMinutes by the ` +
+				`advance-lifecycle 'enumerate' job); MIN 10 guarantees the ` +
+				`graceful save always has room to commit + push before the hard kill.`,
+		);
+	}
+	const cap = config.maxAutoCheckpoints;
+	if (!Number.isInteger(cap) || cap < 1) {
+		throw new Error(
+			`maxAutoCheckpoints must be a positive integer (got ${cap}). ` +
+				`It caps CONSECUTIVE deadline auto-continues; past this the ` +
+				`next checkpoint surfaces a needs-answers question to a human ` +
+				`(the anti-loop guard for the graceful pre-timeout checkpoint).`,
+		);
+	}
+}
+
 /** The conventional config location (`~/.config/dorfl/config.json`). */
 export function defaultConfigPath(): string {
 	return join(homedir(), '.config', brand.configDirName, 'config.json');
@@ -879,5 +971,7 @@ export function loadConfig(path: string = defaultConfigPath()): Config {
 			);
 		}
 	}
-	return mergeConfig(parsed);
+	const merged = mergeConfig(parsed);
+	validateDeadlineConfig(merged);
+	return merged;
 }

package/src/continue-branch.ts

@@ -1,6 +1,28 @@
 import {run, type RunResult} from './git.js';
 
 /**
+ * BROADENED SCOPE NOTE (follow-up task
+ * `complete-propose-honour-already-landed-and-rename-continue-branch-module`):
+ * this module's name still reads as "continue-branch" (its ORIGINAL role: the
+ * continue-detection + rebase-onto-fresh-main helpers used by the onboarding
+ * paths, documented below), BUT it now ALSO hosts the shared
+ * **stale-lease work-branch push** helpers used by MULTIPLE callers:
+ *
+ *   - {@link pushContinuedBranchWithStaleLeaseRetry} — the original
+ *     continue/onboard caller (the mirror hub → arbiter reconcile push).
+ *   - {@link pushProposeBranchWithStaleLeaseRetry} — the propose-mode
+ *     integrator's push (task `propose-push-survives-stale-lease-on-reaped-work-
+ *     ref`), which adds the BENIGN already-landed predicate (gone remote ref +
+ *     work reachable from `<arbiter>/main`) on top of the shared `stale info`
+ *     retry.
+ *
+ * A rename to something like `stale-lease-work-push.ts` was considered; the
+ * scope-note is preferred here because a rename would churn many imports
+ * across `src/` + `test/` for no behavioural gain, and the module already reads
+ * as a single conceptual bucket ("the work-branch push + continue-detection
+ * helpers"). Add new stale-lease work-ref push helpers here rather than
+ * spawning a sibling module.
+ *
  * The **continue-detection** shared by BOTH onboarding paths (the keystone of
  * the `requeue-continue-and-reset` task). `requeue` keeps the `work/<slug>`
  * branch so the NEXT claim CONTINUES from its tip instead of force-cutting a
@@ -156,7 +178,7 @@ export interface ContinueRebaseResult {
  * (ADR §10: rebase, NOT merge — linear history; the prior attempt's commits were
  * based on an OLD main that moved while the item sat in backlog).
  *
- * This is a PLAIN rebase. After the per-item-lock cut-over (prd
+ * This is a PLAIN rebase. After the per-item-lock cut-over (spec
  * `ledger-status-per-item-lock-refs`, tasks 9a–9d) NO transient status lands on
  * a work branch: claim does not move the body (it rests in `backlog/`),
  * needs-attention is the lock `state: stuck` (not a `git mv`), and the

package/src/cwd-section.ts

@@ -268,7 +268,7 @@ export async function resolveCwdSection(
 	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
+	// 3b. The PER-ITEM LOCK in-flight SURFACE for the cwd (spec
 	//     `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

package/src/decision-engine.ts

@@ -1,7 +1,7 @@
 import {extractJsonObjectSpan} from './verdict-json.js';
 
 /**
- * **The SHARED decision engine** (prd
+ * **The SHARED decision engine** (spec
  * `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
@@ -20,7 +20,7 @@ import {extractJsonObjectSpan} from './verdict-json.js';
  *   "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 |
+ *   `{task | spec | adr | dispose | ask}`, intake keeps its own `{task | spec | 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
@@ -43,26 +43,47 @@ import {extractJsonObjectSpan} from './verdict-json.js';
  * - **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).
+ * - **dispose** — DISPOSE the SOURCE the input is about, POLYMORPHIC on the
+ *   source's regime (spec `surface-stuck-as-questions-and-retire-stuck-lock-state`
+ *   resolved decision #5; task
+ *   `apply-disposition-delete-to-dispose-regime-polymorphic`): an OBSERVATION is
+ *   `git rm`-ed (notes leave by deletion, decision 12); a TASK is `git mv`-ed to
+ *   its regime's won't-proceed terminal `tasks/cancelled/` (RETAINED — a task
+ *   cannot be hard-deleted by the apply rung, only disposed to its terminal); a
+ *   SPEC is `git mv`-ed to `specs/dropped/` (RETAINED). Making the token
+ *   polymorphic (rather than adding a second `cancel` beside a literal `delete`)
+ *   makes "a task cannot be deleted, only disposed to its terminal" true BY
+ *   CONSTRUCTION.
+ * - **resolve** — the answer SETTLES the item with NO artifact to mint and the
+ *   note RETAINED: route to the apply persist's resolve-fully path (harvest the
+ *   answers into the body, clear `needsAnswers`, delete the sidecar) so the
+ *   already-answered question stops re-surfacing. The SIBLING of `dispose` (both
+ *   end the question-loop minting nothing), but `resolve` KEEPS the note whereas
+ *   `dispose` drops-or-terminals it (task `apply-decide-resolve-verdict-mint-nothing`).
  * - **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
+// MIGRATE step (spec `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';
+// (nothing ''prd''-valued is persisted), so the rename needs no on-disk alias.
+export type DecisionOutcome =
+	| 'task'
+	| 'spec'
+	| 'adr'
+	| 'dispose'
+	| 'resolve'
+	| '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
+ * `question`, a `dispose` 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).
@@ -93,11 +114,24 @@ export interface DecisionVerdict {
 	/** 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).
+	 * The reason the source should be DISPOSED (`dispose` outcome) — carried by
+	 * the caller into the regime-polymorphic disposal: an OBSERVATION's reason
+	 * rides the revertible git-rm commit message (decision 12: notes leave by
+	 * deletion, git history = archive); a TASK/SPEC's reason is written into the
+	 * moved item's `reason:` frontmatter so the durable body records why the
+	 * item won't proceed (the file is RETAINED at the regime's terminal —
+	 * `tasks/cancelled/` or `specs/dropped/`).
 	 */
-	deleteReason?: string;
+	disposeReason?: string;
+	/**
+	 * Why the item is settled with NOTHING to mint (`resolve` outcome) — the
+	 * SIBLING of {@link disposeReason}, but the note is RETAINED (the apply rung
+	 * routes this to the resolve-fully path, which harvests the answers into the
+	 * body rather than deleting the note). The reason is advisory context for the
+	 * human/reviewer; the durable disposition record is the `## Applied answers`
+	 * block the resolve-fully path writes.
+	 */
+	resolveReason?: string;
 	/**
 	 * The drafted follow-up question(s) (`ask` outcome) — the caller appends them
 	 * to the conversation and re-pauses (decision 5: reuse the existing
@@ -200,7 +234,7 @@ export async function decide<TInput>(
  * 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}`.
+ * `outcome ∈ {task,spec,adr,dispose,resolve,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
@@ -235,12 +269,13 @@ export function parseDecisionVerdict(output: string): DecisionVerdict {
 		outcome !== 'task' &&
 		outcome !== 'spec' &&
 		outcome !== 'adr' &&
-		outcome !== 'delete' &&
+		outcome !== 'dispose' &&
+		outcome !== 'resolve' &&
 		outcome !== 'ask'
 	) {
 		throw new Error(
-			`decision verdict 'outcome' was not one of task|spec|adr|delete|ask (got ` +
-				`${JSON.stringify(outcome)}).`,
+			`decision verdict 'outcome' was not one of task|spec|adr|dispose|resolve|ask ` +
+				`(got ${JSON.stringify(outcome)}).`,
 		);
 	}
 	// Map the per-outcome fields onto the verdict shape, keeping ONLY the strings
@@ -264,8 +299,11 @@ export function parseDecisionVerdict(output: string): DecisionVerdict {
 		...(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.disposeReason) !== undefined
+			? {disposeReason: str(obj.disposeReason)}
+			: {}),
+		...(str(obj.resolveReason) !== undefined
+			? {resolveReason: str(obj.resolveReason)}
 			: {}),
 		...(str(obj.question) !== undefined ? {question: str(obj.question)} : {}),
 	};