dorfl 0.0.0 → 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,668 @@
+import { type Identity } from './identity.js';
+import { type SelectionOrderConfig } from './select-order.js';
+/**
+ * How a completed item is integrated back to the arbiter's `main`. `merge` lands
+ * it directly on `main` (ff/rebase + push); `propose` pushes a branch + requests
+ * review. (`propose` is provider-neutral; the old `pr` name was GitHub jargon.
+ * See ADR §6.)
+ */
+export type IntegrationMode = 'propose' | 'merge';
+/**
+ * **Per-repo TASK-PLACEMENT default** (prd
+ * `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
+ * 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
+ * value was renamed `'backlog'` → `'todo'` → `'ready'` (ADR
+ * `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
+ * a `'ready'` repo (the positional analogue of the existing
+ * `untrusted-origin-forces-build-propose` rule).
+ */
+export type TasksLandIn = 'pre-backlog' | 'ready';
+/**
+ * **Per-repo PRD-PLACEMENT default** (prd
+ * `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 —
+ * `'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
+ * auto-tasking POOL — the trusted fast-path landing, on-disk
+ * `work/prds/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
+ * {@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.
+ */
+export type SpecsLandIn = 'pre-proposed' | 'ready';
+/**
+ * The observation-triage gate (ADR `ci-config-policy-and-gate-family` §2): a
+ * 3-state ENUM governing the observation INBOX (raw captured signal). It REPLACES
+ * the old `autoTriage` boolean, whose name read like "is triage on?" but only
+ * gated the auto-DISPOSITION exception (the resolved naming trap). The three
+ * states say what they gate:
+ *   - `off` (default): the triage rung is dropped from the auto-pick SELECTION —
+ *     observations are left untouched (the NEW state the boolean could not
+ *     express, "leave my observations alone entirely");
+ *   - `ask`: the observation pool IS selected; surface a promote/keep/delete
+ *     question for every untriaged observation (the old `autoTriage:false`);
+ *   - `auto`: the observation pool is selected; auto-dispose ONLY the no-question
+ *     cases (exact-duplicate ⇒ recommend delete; unambiguous map) and surface a
+ *     question for the rest (the old `autoTriage:true`). It still NEVER
+ *     auto-deletes a non-duplicate or auto-promotes a judgement call.
+ */
+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
+ * `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?"
+ * is materially more consequential than "is this observation worth promoting?",
+ * so a merge-question must NEVER ride `observationTriage` and must NOT default
+ * `off` (a silently-dropped merge-question means finished, pushed work never
+ * lands). The states:
+ *   - `off` ⇒ the merge-question surfacer is not invoked (only correct for a
+ *     repo that lands by some other means);
+ *   - `ask` (DEFAULT) ⇒ the surfacer enumerates unmerged `work/*` branches +
+ *     emits a merge-question sidecar; a human's plain `merge | hold | drop`
+ *     answer is required before the land. The conservative default that honours
+ *     propose semantics and never silently drops pushed work;
+ *   - `auto` ⇒ the runner self-supplies the `merge` answer without surfacing
+ *     and lands through the SAME deterministic answer-driven runner-action
+ *     dispatch + apply-time re-verify (the merge-mode-like fast path). Does NOT
+ *     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
+ * Q3.
+ */
+export type MergeQuestions = 'off' | 'ask' | 'auto';
+/**
+ * Which harness adapter (ADR §5) launches a job's agent and reports its
+ * liveness: `null` (shell out to `agentCmd`) or `pi` (the pi CLI). Selected via
+ * the `harness` config field; defaults to `null`.
+ */
+export type HarnessAdapter = 'null' | 'pi';
+/**
+ * The `propose`-mode review-request provider (ADR §6): `github` (`gh pr
+ * create`) or `none` (push-only). This names which provider the ARBITER URL
+ * RESOLVES to (`selectProvider`) — it is NOT a config OVERRIDE axis (there is
+ * none; the provider is purely arbiter-derived: a GitHub remote ⇒ `github`, else
+ * `none`). Whether `gh` can actually open the PR is the identity's
+ * `providers.github` / ambient `gh` auth; whether to open a PR at all is the
+ * separate `noPR` intent. `merge` mode is provider-agnostic and ignores all of
+ * this.
+ */
+export type ReviewProviderName = 'none' | 'github';
+/**
+ * The per-repo acceptance gate: a single shell command, or an ordered list of
+ * commands run in sequence (all must pass). See `verify.ts` / ADR §8.
+ */
+export type VerifyConfig = string | string[];
+/**
+ * **The `promptGuidance` NAMESPACE** — per-repo prompt-text NUDGES the runner
+ * folds into the worker's in-band prompt (`prompt.ts` + `CLAIM-PROTOCOL.md`).
+ * Categorically SEPARATE from the gate family (`verify`/`autoBuild`/`humanOnly`):
+ * a nudge changes the agent's DISPOSITION, never the acceptance bar (the `verify`
+ * gate is still the sole pass/fail). The namespace name is deliberate — it
+ * signals "guidance, not guarantee" — and is shaped to grow (`testFirst` is just
+ * the first member; later siblings, e.g. `preferSmallDiffs`, land here too).
+ */
+export interface PromptGuidance {
+    /**
+     * Strengthen the wrapper's existing soft "TDD where the task asks for it"
+     * line into an explicit TEST-FIRST nudge ("at the agreed seam, write the
+     * failing test BEFORE the production code; this is guidance, not a gate —
+     * the `verify` step still decides pass/fail"). The strengthened text lives
+     * in `CLAIM-PROTOCOL.md` (the single source of truth), gated by the
+     * `<!-- if promptGuidance.testFirst --> … <!-- else --> … <!-- /if -->`
+     * conditional-fragment convention the extractor in `prompt.ts` honours.
+     * Default `false` (omitted ⇒ false); the worker prompt is byte-identical
+     * to today when this is off. Resolved like the gate family: flag > env
+     * (`DORFL_PROMPT_GUIDANCE_TEST_FIRST`) > per-repo > global >
+     * default (`false`). NEVER an enforced acceptance criterion.
+     */
+    testFirst: boolean;
+}
+/**
+ * Resolve the `promptGuidance` namespace down to its concrete boolean fields
+ * with the documented defaults applied — so callers can read
+ * `resolvePromptGuidance(cfg).testFirst` without re-checking the namespace's
+ * presence (a per-repo file may legitimately omit `promptGuidance` entirely,
+ * or supply only a subset). Mirrors the gate family's defaults-resolved
+ * convention.
+ */
+export declare function resolvePromptGuidance(cfg: Config): PromptGuidance;
+/**
+ * Resolved runner configuration. There is NO `roots`/`remotes` field: discovery
+ * is the registered hub-mirror set under `<workspacesDir>/repos/` (the registry,
+ * ADR `command-surface-and-journeys` §1), NOT a config roots walk. `scan` reads
+ * the eligibility fields per repo; `run --once` additionally consumes the
+ * execution fields (maxParallel, perRepoMax, defaultArbiter, integration,
+ * agentCmd).
+ */
+export interface Config {
+    /**
+     * Per-repo policy: may agents auto-BUILD *undeclared* (not `humanOnly`) tasks
+     * in this repo? `false` (default, strict) ⇒ agents claim nothing automatically;
+     * `true` ⇒ agents may claim any task that is not `humanOnly: true`. Resolved
+     * like `integration`: flag (`--auto-build`/`--no-auto-build`) > `DORFL_AUTO_BUILD`
+     * env > per-repo > global > default. The build member of the per-action gate family
+     * (`autoBuild`/`autoTask` + the question-surfacing gates `observationTriage`/
+     * `surfaceBlockers`).
+     */
+    autoBuild: boolean;
+    /**
+     * **The `promptGuidance` NUDGE namespace** (see {@link PromptGuidance}). A
+     * NUDGE modifies the worker's IN-BAND PROMPT text (`prompt.ts` + the
+     * `CLAIM-PROTOCOL.md` wrapper); it is CATEGORICALLY SEPARATE from the gate
+     * family (`verify`/`autoBuild`/`humanOnly`) — guidance, never guarantee. The
+     * `verify` gate's semantics are unaffected regardless of any value here.
+     * Resolution mirrors the gate family per-member: flag > env > per-repo >
+     * global > default. Defaults to `{testFirst: false}` (worker prompt is
+     * byte-identical to today when every member is off). Designed to grow:
+     * later sibling nudges (e.g. `preferSmallDiffs`) land as new members.
+     */
+    promptGuidance: PromptGuidance;
+    /**
+     * 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
+     * `autoBuild`: flag > `DORFL_AUTO_TASK` env > per-repo > global >
+     * default. The two-axis tasking gate (`work/prds/auto-task.md`), one level up
+     * from the build gate's `autoBuild`.
+     */
+    autoTask: boolean;
+    /**
+     * Per-repo policy governing the OBSERVATION INBOX (raw captured signal) — the
+     * 3-state member of the question-surfacing gate family (its sibling is
+     * `surfaceBlockers`, which governs DECLARED blocked work; the two are orthogonal
+     * peers, ADR `ci-config-policy-and-gate-family` §2). It REPLACES the old
+     * `autoTriage` boolean (cleanly, no alias — this repo has no external users yet,
+     * decided 2026-06-12). `off` (default) ⇒ the triage pool is dropped from the
+     * auto-pick SELECTION (observations untouched); `ask` ⇒ surface a
+     * promote/keep/delete question for every untriaged observation; `auto` ⇒
+     * auto-dispose ONLY the no-question cases (duplicate ⇒ recommend delete /
+     * unambiguous map) and surface a question for the rest (still NEVER auto-deletes
+     * a non-duplicate or auto-promotes). Resolved like `integration`/`autoBuild`:
+     * flag (`--observation-triage`) > `DORFL_OBSERVATION_TRIAGE` env >
+     * per-repo > global > default `off`. Gates the CREATE phase only; APPLY (consume
+     * a committed answer) stays ALWAYS allowed.
+     */
+    observationTriage: ObservationTriage;
+    /**
+     * Per-repo policy governing the MERGE-QUESTION SURFACER — the 3-state member
+     * of the question-surfacing gate family (prd
+     * `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 —
+     * `observationTriage` defaults `off` (a dropped observation is safely
+     * ignorable), `mergeQuestions` defaults `ask` (a dropped merge-question means
+     * pushed work never lands). `off` ⇒ the surfacer is NOT invoked (only for a
+     * repo that lands by some other means); `ask` (default) ⇒ the surfacer
+     * enumerates unmerged `work/*` branches and emits a merge-question sidecar a
+     * human answers; `auto` ⇒ the runner self-supplies the `merge` answer without
+     * surfacing and lands via the SAME deterministic answer-driven runner-action
+     * dispatch + apply-time re-verify (the merge-mode-like fast path; NOT the
+     * agentic decider). Resolved like `observationTriage`/`integration`: flag
+     * (`--merge-questions`) > `DORFL_MERGE_QUESTIONS` env > per-repo > global >
+     * default `ask`. Gates the SURFACE phase of the merge-question loop only;
+     * APPLY (consume a committed merge-answer) stays ALWAYS allowed (the
+     * create-vs-consume invariant the gate family obeys, ADR
+     * `ci-config-policy-and-gate-family` §4).
+     */
+    mergeQuestions: MergeQuestions;
+    /**
+     * 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
+     * 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
+     * surface a declared blocker; `true` ⇒ the blocked pool IS enumerated and
+     * `advance`'s surface rung renders the declared blocker into a sidecar the human
+     * can answer + unblock in-repo. This is a DIFFERENT job from `observationTriage`:
+     * it is about committed work items, not the raw inbox (so
+     * `observationTriage: ask|auto` + `surfaceBlockers: off` — "groom my inbox, leave
+     * my blocked work alone" — is expressible). Resolved like `autoBuild`: flag
+     * (`--surface-blockers`/`--no-surface-blockers`) > `DORFL_SURFACE_BLOCKERS`
+     * env > per-repo > global > default `false`. Gates the CREATE (surface) phase
+     * only; APPLY (consume a committed answer) stays ALWAYS allowed, and
+     * `needs-attention` (a stuck build) is a SEPARATE always-on mechanism this gate
+     * does NOT touch.
+     */
+    surfaceBlockers: boolean;
+    /**
+     * 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
+     * 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
+     * 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`:
+     * flag > `DORFL_SURFACE_STAGING` env > per-repo > global > default
+     * `true`. Surfacing is read-only-ish (writes a question sidecar; touches only
+     * the item's per-item lock), so widening it into staging does NOT loosen the
+     * BUILD trust gate — it only stops the surface polarity from being
+     * gratuitously trust-gated identically to it.
+     */
+    surfaceStaging: boolean;
+    /**
+     * Per-repo SELECTION ORDER across the four ORDERABLE auto-pick pools (`build` =
+     * eligible tasks, `task` = taskable prds, `surface` = `needsAnswers`
+     * blockers, `triage` = untriaged observations). `apply` (consume a committed
+     * answer) is PINNED FIRST and is NOT orderable (consume-always-wins). The value
+     * is EITHER a PRESET keyword (`drain` (default) ⇒ `[build, task, surface,
+     * triage]`, drain ready work then create then ask; `groom` ⇒ `[surface, triage,
+     * build, task]`) OR an explicit ordered pool-name list (the env comma form
+     * `build,task,surface,triage`); the preset is sugar over the list. It only
+     * REORDERS pools; the gates decide what is PRESENT (a gated-off pool named in
+     * the order is a no-op). SUBSUMES the old `prdsFirst` boolean: `drain`
+     * reproduces its default, `[task, build, ...]` reproduces `prdsFirst: true`.
+     * Resolved per-repo like `autoBuild`/`autoTask`: flag
+     * (`--selection-order`) > `DORFL_SELECTION_ORDER` env (the `'list'`
+     * coercion) > per-repo > global > default (`drain`). An unknown name/keyword
+     * FAILS LOUDLY (`select-order.ts` `resolveSelectionOrder`).
+     */
+    selectionOrder: SelectionOrderConfig;
+    /** Global cap on how many items the runner claims+runs in one tick. */
+    maxParallel: number;
+    /** Per-repo cap on concurrent claims (≤ maxParallel in effect). */
+    perRepoMax: number;
+    /** Name of the git remote that serializes claims (the arbiter). */
+    defaultArbiter: string;
+    /**
+     * The execution working area: bare hub mirrors (`<dir>/repos/<key>.git`) and
+     * job worktrees (`<dir>/work/<work-id>/`). STATE, not cache (ADR §3) — lives
+     * under a single visible `~/.dorfl/`, NEVER `~/.cache`. Overridable so
+     * tests (and unusual setups) can relocate it.
+     */
+    workspacesDir: string;
+    /**
+     * Where local `--bare` arbiters (offline source of truth) are provisioned:
+     * `<dir>/<host>/<org>/<name>.git` (hierarchical, reusing the repo→key
+     * encoding). Arbiters are precious DATA, not state/cache (ADR §7): they live
+     * under a visible `~/git/` and MUST NEVER be placed under `~/.dorfl/`
+     * (a `gc`/cleanup mishap could nuke the only copy). Overridable so tests can
+     * relocate it.
+     */
+    arbitersDir: string;
+    /**
+     * Where the HUMAN `work-on` command checks out its parallel worktrees:
+     * `<dir>/<key>/<slug>/` on branch `work/<slug>`. This is a **human-only**,
+     * editor-facing area — deliberately NOT under `~/.dorfl/` (the agents'
+     * execution state, ADR §3), so a `work-on` worktree never carries the human's
+     * secrets into an agent context. It is intentionally OPTIONAL with **no silent
+     * default**: `work-on` prompts for it on first use and saves it here (offering a
+     * sensible suggestion that does NOT share a prefix with the user's code dirs, so
+     * shell tab-completion never collides). `undefined` ⇒ not yet configured.
+     */
+    humanWorktreesDir?: string;
+    /** 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
+     * 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
+     * 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
+     * per-LIFECYCLE-TRANSITION knob, inside the trust boundary, operator/config-only.
+     */
+    taskingIntegration?: IntegrationMode;
+    /**
+     * **Per-repo DEFAULT landing for the TASKER's emitted tasks** (prd
+     * `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
+     * 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
+     * runner OWNS placement from unforgeable inputs; the agent cannot
+     * influence it.
+     */
+    tasksLandIn: TasksLandIn;
+    /**
+     * **Per-repo DEFAULT landing for `intake`-authored spec files** (spec
+     * `staging-pool-position-gate-and-trust-model` US #2/#5/#6/#12). The SPEC twin
+     * of {@link tasksLandIn}: resolved per-repo EXACTLY like it (flag
+     * `--specs-land-in` > env `DORFL_SPECS_LAND_IN` > per-repo > global >
+     * built-in `'pre-proposed'`). `intake`'s spec dispatch 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.
+     * `intake` NEVER sets placement itself. Spec US #6 / the governing ADR: the
+     * runner OWNS placement from unforgeable inputs; the agent cannot
+     * 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
+     * `prd-to-spec-vocabulary-cutover-and-migration-command`): the legacy
+     * `prdsLandIn` config key + `--prds-land-in` flag are GONE (clean break).
+     */
+    specsLandIn: SpecsLandIn;
+    /**
+     * **The PR-INTENT axis** (ADR §6): on the `propose` path, do NOT open a review
+     * request even on a GitHub arbiter with auth — push the branch (the
+     * safety-bearing recovery point) but SKIP `openRequest`. `true` ⇒ deliberately
+     * no PR (the explicit, no-warning "suppress the PR" intent that re-homes the old
+     * `provider: none` use); `false`/unset (default) ⇒ "I want a PR", so propose
+     * opens it via the arbiter-derived provider as normal. This is NOT a provider
+     * choice — `selectProvider` stays purely arbiter-derived; `noPR` is an intent
+     * LAYERED on top. Its honest-failure twin: when `noPR` is unset + propose + a
+     * GitHub arbiter but a `gh` auth PROBE says `gh` cannot open a PR, the run FAILS
+     * UP FRONT (a pre-flight guard) instead of silently degrading. `merge` mode
+     * ignores it (it never opens a PR). Resolved per-repo like `review`: flag
+     * (`--no-pr`) > env > per-repo > global > default `false`.
+     */
+    noPR: boolean;
+    /**
+     * The command the runner shells out to for one task. The runner appends the
+     * built prompt on stdin; the command does NO git ops on the repo (the runner
+     * owns those). Empty string ⇒ no agent configured (run will refuse). Consumed
+     * by the **null** harness adapter (it shells out to this verbatim); the **pi**
+     * adapter ignores it (it invokes the pi CLI directly — see `harness`).
+     */
+    agentCmd: string;
+    /**
+     * The model a job's agent runs on (harness-agnostic ROUTING intent, ADR §13).
+     * dorfl decides WHICH model; it never touches auth/keys (those stay the
+     * harness's job). Optional with NO default so "unset" is meaningful: unset ⇒
+     * dorfl forces no model (the harness's own default / a model baked into
+     * `agentCmd` is used untouched). Carried through the harness seam
+     * (`LaunchInput.model`); the ADAPTER decides HOW it reaches its tool — the pi
+     * adapter passes `--model <model>` natively, the null/shell adapter substitutes
+     * a `{model}` placeholder in `agentCmd`. Resolved per-repo like `integration`:
+     * flag (`--model`) > env > per-repo > global > default (unset).
+     */
+    model?: string;
+    /**
+     * Which harness adapter launches + reports liveness for a job's agent (the
+     * harness seam, ADR §5): `null` (default — shells out to `agentCmd`,
+     * PID-only liveness) or `pi` (invokes the pi CLI with the work-agent prompt;
+     * liveness from PID + the pi session dir/log, never mtime). pi specifics stay
+     * behind the adapter; the core only sees the `Harness` interface.
+     */
+    harness?: HarnessAdapter;
+    /**
+     * The pi CLI binary the `pi` harness invokes (default `pi` on `PATH`).
+     * Overridable so an operator can pin a path; tests stub it. Ignored unless
+     * `harness` is `pi`.
+     */
+    piBin?: string;
+    /**
+     * The ROOT folder under which the runner generates a job's pi session FILE —
+     * the adapter passes `--session <sessionsDir>/<unique-id>.jsonl` (a literal
+     * file path pi creates + writes; never `--session-dir`). A **HOST-ONLY machine
+     * path** (same class as `piBin`/`workspacesDir`): resolved flag (`--sessions-
+     * dir`) > env (`DORFL_SESSIONS_DIR`) > global > default — there is NO
+     * per-repo layer (a committed repo file must not redirect where the host writes
+     * session logs), so it is in `REPO_REJECTED_KEYS`. Optional with a DYNAMIC
+     * default (NOT a `DEFAULT_CONFIG` entry): unset ⇒ the path generator derives
+     * pi's default per-cwd sessions folder at launch from the job cwd (a direct
+     * child of `~/.pi/agent/sessions/`, so the dashboard's non-recursive `listAll`
+     * scans it). Set ⇒ any folder (e.g. a dedicated `run` fleet folder).
+     */
+    sessionsDir?: string;
+    /**
+     * The per-repo ENV-PREP step (install deps, fetch submodules, run codegen) —
+     * the SIBLING of `verify`, NOT part of it. `prepare` makes a freshly-
+     * materialised worktree's environment READY; `verify` checks the tree is
+     * GREEN. The runner sequences `prepare` THEN `verify`: `prepare` runs ONCE,
+     * before the FIRST `verify`, on a worktree that needs deps but does not have
+     * them (a fresh job worktree off the hub mirror). Install MUST NOT be baked
+     * into `verify` — that would make `verify` stop being a pure, cheaply-re-
+     * runnable acceptance check and make every gate run pay the install cost.
+     * `prepare` is where install belongs. A deterministic shell command (or an
+     * ordered list, all must pass); no model in the loop. Same shape and the SAME
+     * resolution/precedence as `verify` (flag > env > per-repo > global > default).
+     * The ONE difference from `verify`: unset (omitted) ⇒ NO prepare step (a
+     * no-op) — there is NO default install (a repo with no deps needs none; we
+     * never invent a default that would run `pnpm install` in a repo that has no
+     * lockfile). See `prepare.ts`.
+     */
+    prepare?: VerifyConfig;
+    /**
+     * The per-repo acceptance gate run by `dorfl verify` (a deterministic
+     * shell command, or an ordered list of commands). NOT per-task and NOT model-
+     * interpreted — it is declared, auditable config (ADR §8). Unset (omitted) ⇒
+     * a sensible `pnpm -r build && test && format:check` default; the field is
+     * intentionally optional so "unset" is distinguishable from "empty". Install
+     * must NOT be baked into `verify` — env-prep belongs in the sibling `prepare`
+     * field, which the runner runs ONCE before the first `verify` on a fresh
+     * worktree (the prepare=env-ready / verify=tree-green split).
+     */
+    verify?: VerifyConfig;
+    /**
+     * **Gate 2 — the PR/code review gate** (GATES prd `work/prds/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 —
+     * opt-in, ADR §8). Resolved per-repo like `integration`: flag
+     * (`--review`/`--no-review`) > env > per-repo > global > default false.
+     * `verify` is never replaced — review is layered, never a substitute.
+     */
+    review: boolean;
+    /**
+     * The model the REVIEW agent runs on (de-correlation from the builder's
+     * `model`). Optional with NO default so "unset" means "no forced review model"
+     * (the harness's own default). Carried to the review-agent launch through the
+     * EXISTING harness seam (`LaunchInput.model` / `substituteModel`) — NOT a new
+     * mechanism. Resolved like `model`: flag (`--review-model`) > env > per-repo >
+     * global > default (unset). Distinct from the builder's `model`.
+     */
+    reviewModel?: string;
+    /**
+     * How many CORROBORATING review rounds Gate 2 runs on the SAME tip. Semantics are
+     * UNANIMOUS-APPROVAL, not retry-until-pass: the gate approves ONLY if EVERY round
+     * approves, and a `block` is TERMINAL (it short-circuits the loop and is never
+     * 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
+     * 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
+     * is not implemented yet.) Resolved like `integration`: flag
+     * (`--review-max-rounds`) > env > per-repo > global > default.
+     */
+    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
+     * 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
+     * (`--tasker-loop`/`--no-tasker-loop`) > env > per-repo > global > default (on).
+     * DISTINCT from the acceptance gate's `review` toggle.
+     */
+    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
+     * 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
+     * loop can never run forever; on hitting it WITH unresolved blockers the loop
+     * REJECTS via the needsAnswers / needs-attention sink. It lives on the LOOP,
+     * never on a gate (the orphaned `reviewMaxRounds` belongs to the Gate-2 path —
+     * separate cleanup). A cheap default (3). Resolved per-repo like `integration`:
+     * flag (`--tasker-loop-max`) > env > per-repo > global > default. Distinct from
+     * Gate-2's `reviewMaxRounds`.
+     */
+    taskerLoopMax: number;
+    /**
+     * The model the tasker IMPROVER loop's review agent runs on (de-correlation
+     * from the tasker). Optional with NO default so "unset" means "no forced model"
+     * (the harness's own default). Carried to the review-agent launch through the
+     * EXISTING harness seam (`LaunchInput.model` / `substituteModel`). Resolved like
+     * `model`: flag (`--tasker-loop-model`) > env > per-repo > global > default
+     * (unset). DISTINCT from the acceptance gate's `reviewModel` (build
+     * `--review-model`).
+     */
+    taskerLoopModel?: string;
+    /**
+     * **The fresh-worktree acceptance-gate toggle** (`--fresh-worktree-gate` /
+     * `--no-fresh-worktree-gate`). When ON (the default), the acceptance gate
+     * (`prepare` then `verify`) runs in a CLEAN throwaway worktree cut from the
+     * work branch REBASED onto the latest `<arbiter>/main` — i.e. the exact tree
+     * the arbiter will integrate — rather than the agent's pre-rebase working
+     * checkout. So a green gate provably describes the merged artifact: a
+     * gitignored/uncommitted file the checkout has but the committed/pushed tree
+     * does NOT cannot leak into a falsely-green gate, and a change introduced only
+     * by the integration rebase IS gated. When OFF (`freshWorktreeGate: false` /
+     * `--no-fresh-worktree-gate`), `verify` runs in the agent's build worktree
+     * exactly as before (the PRE-rebase gate) — the opt-out for when the per-gate
+     * install cost is too high. The throwaway gate worktree is fresh (no deps), so
+     * `prepare` runs in it before `verify` (the per-gate install cost the opt-out
+     * exists for). Modelled EXACTLY on `taskerLoop`: a POSITIVE boolean, default
+     * ON, `--no-` negation. Resolved per-repo like `integration`: flag
+     * (`--fresh-worktree-gate`/`--no-fresh-worktree-gate`) > env > per-repo >
+     * global > default (on). DISTINCT from `review`/`taskerLoop` (a separate
+     * concern: WHICH tree the gate runs against, not whether a review runs).
+     *
+     * The shared gate→integrate band (`performIntegration`) simply HONOURS the
+     * boolean it is handed (caller-agnostic). The `run` FLEET caller passes
+     * `(resolvedFlag && perRepoMax === 1)` so the fresh gate is used only when
+     * same-repo concurrency is OFF (two pre-existing run-fleet races would
+     * otherwise fire at `perRepoMax > 1`; they are their own task). Single-job
+     * callers (`do` in-place / `--isolated` / `--remote` / `complete`) pass the
+     * resolved flag UNCONDITIONALLY.
+     */
+    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`,
+     * 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
+     * needs-attention. The in-process `integrateLock` only serialises sibling
+     * INTEGRATES in ONE process; across separate CI jobs the CAS loop IS the queue,
+     * and this cap is what determines how wide a matrix burst converges before any
+     * spurious bounce. A wide-matrix CI raises it; the default stays modest. Race-1
+     * safety is unchanged (a lost CAS costs only a re-rebase + re-gate retry, never a
+     * `--force`, never a both-land-broken) — scaling the cap only changes WHEN a
+     * genuinely-stuck loser gives up. Resolved per-repo like `freshWorktreeGate`:
+     * flag (`--merge-retries`) > env (`DORFL_MERGE_RETRIES`) > per-repo > global >
+     * default. The default matches `integration-core.ts`'s built-in fallback (1000 —
+     * the C2 rebase-until-real-conflict liveness ceiling, not a small Race-1 budget),
+     * so resolving it through this layer is byte-for-byte today's behaviour when no
+     * source sets it. Forwarded into `performIntegration`'s `mergeRetries` (resolved
+     * ONCE per `performIntegration` call, fixed across that call's CAS-retry loop —
+     * the same per-item resolution `freshWorktreeGate` / `review` use).
+     */
+    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
+     * `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
+     * when the rebased tip re-verifies GREEN — a green re-verify is trusted as
+     * sufficient (the cheap fast-path). `true` re-surfaces the merge-question
+     * (clears the answer back to no-answer and re-authors the question on
+     * `main`/runner under the `advancing` lock — no branch-side mutation)
+     * instead of auto-landing on a merge-base change, even on a green re-verify
+     * — the host-agnostic analogue of GitHub's "dismiss stale approvals when
+     * the base changes". Story #16's RED-re-verify refusal is UNCHANGED and
+     * independent of this flag.
+     *
+     * This module ONLY resolves the boolean; the re-surface vs. land branch
+     * lives in `apply-rung-merge-disposition`'s consumer. Resolved per-repo
+     * through the SAME gate-family precedence chain as the sibling gates
+     * (flag `--strict-merge-approval` > env `DORFL_STRICT_MERGE_APPROVAL` >
+     * per-repo > global > default `false`). DOES NOT alter `mergeQuestions` /
+     * `observationTriage` default or shape — a SEPARATE, independent axis.
+     */
+    strictMergeApproval: boolean;
+    /**
+     * The optional runner **identity** (a bot): run the runner's git + provider
+     * operations as a configured entity via process-scoped env overrides, without
+     * mutating the user's global git/`gh` config (see `identity.ts`). HOST-ONLY
+     * (it carries secrets and is per-machine) ⇒ rejected in a per-repo file
+     * (`REPO_REJECTED_KEYS`); it lives only in the global config. Optional with NO
+     * default: unset ⇒ fully ambient (today's behaviour, byte-for-byte) — the CI
+     * path relies on `actions/checkout`'s ambient HTTPS+`GITHUB_TOKEN`. When set,
+     * `auth` is mandatory and validated at load time ({@link validateIdentity}).
+     */
+    identity?: Identity;
+}
+/** A partial config, e.g. loaded from a JSON file or built from CLI flags. */
+export type PartialConfig = Partial<Config>;
+/**
+ * The DEPRECATED config/env keys: present in an OLD config keeps working but is
+ * IGNORED with a one-line warning (never a hard error), so an existing setup is
+ * not broken by a removal. Each maps to the human-facing replacement hint. Mirrors
+ * the `allowAgents`→`autoBuild` removal-with-warning precedent.
+ *
+ * `provider` (the review-request provider OVERRIDE + `--provider` flag) was
+ * removed: the provider is purely ARBITER-derived now (a GitHub remote ⇒ the
+ * GitHub provider, else `none`), so an override could only contradict the arbiter.
+ * The legitimate `provider: none` use ("suppress the PR") is re-homed to the
+ * `noPR` intent axis.
+ */
+export declare const DEPRECATED_CONFIG_KEYS: Readonly<Record<string, string>>;
+/**
+ * Warn (once per offending key) for any DEPRECATED key present in a parsed config
+ * object, then DELETE it from the object so it never lingers in the resolved
+ * config. A stale key is IGNORED, not an error — an existing config keeps working.
+ * For `provider`, the warning points specifically at the `noPR` replacement when
+ * the stale value was the old `none` ("suppress the PR") use.
+ */
+export declare function warnDeprecatedConfigKeys(parsed: Record<string, unknown>, source: string, warn?: (message: string) => void): void;
+/**
+ * Built-in defaults. Chosen so that zero-config is useful: stay strict about the
+ * autonomy gate (agents claim nothing unless a repo opts in via `autoBuild`).
+ * Discovery has no default `roots` — it is the registered hub-mirror set (empty
+ * until `remote add`/`remote find` registers a target).
+ */
+export declare const DEFAULT_CONFIG: Config;
+/** The conventional config location (`~/.config/dorfl/config.json`). */
+export declare function defaultConfigPath(): string;
+/** Merge a partial config over the built-in defaults; arrays are replaced. */
+export declare function mergeConfig(overrides: PartialConfig): Config;
+/**
+ * Persist `config` to `path` as pretty JSON (creating the parent dir). Used by
+ * `work-on` to SAVE the prompted `humanWorktreesDir` on first use so the human is
+ * never asked again. Only the keys present in `config` are written — we round-trip
+ * whatever the loader produced (defaults + file + the new key), which keeps the
+ * on-disk file explicit and stable.
+ */
+export declare function saveConfig(config: PartialConfig, path: string): void;
+/**
+ * Load config from `path`, merged over defaults. A missing file is not an error
+ * (defaults make the tool work out of the box); invalid JSON is.
+ */
+export declare function loadConfig(path?: string): Config;
+//# sourceMappingURL=config.d.ts.map