@dev-loops/core 1.0.0-rc.5 → 1.0.0-rc.7

package/src/config/config.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { classifyFile } from "../analysis/diff-analyzer.mjs";
 import { isDevLoopConfigSourcePath } from "../loop/gate-carry-forward.mjs";
+import { trimmedOrNull } from "../loop/normalize.mjs";
 
 // ============================================================================
 // Sub-schemas
@@ -219,6 +220,47 @@ const GateDynamicConfig = z.strictObject({
 // accepted but INERT for spike (a findings-doc deliverable has no "clean
 // verdict" escalation path and no additive dynamic pool) rather than being
 // split into a second schema.
+// Single source for the blockCleanOnFindingSeverities vocabulary: the schema
+// enum below consumes these spellings verbatim, and resolveGateConfig's
+// fail-closed guard exact-matches raw entries against the same list, so the
+// guard's accept set is byte-identical to the schema's (no trim/normalize
+// superset) and widening the enum can never leave the runtime guard behind.
+// Exported (not just module-internal) so the vocabulary contract test
+// (test/contracts/gate-severity-vocabulary-contract.test.mjs) can pin this
+// list against SEVERITY_ORDER + LEGACY_SEVERITY_ALIASES
+// (@dev-loops/core/loop/gate-fanin) — a DEFECT severity added to
+// SEVERITY_ORDER (one not also added to NON_DEFECT_SEVERITIES) without
+// updating this canonical defect trio plus its legacy alias spellings (or a
+// new defect-targeting legacy alias added without a matching entry here)
+// must fail that test rather than leaving this enum silently stale.
+export const BLOCKING_SEVERITY_SPELLINGS = Object.freeze(["high", "medium", "low", "must-fix", "worth-fixing-now", "nice-to-have", "defer"]);
+const BLOCKING_SEVERITY_SPELLING_SET = new Set(BLOCKING_SEVERITY_SPELLINGS);
+
+// Render an offending config value for a refusal message without letting the
+// renderer itself throw: JSON.stringify raises on BigInt and circular
+// structures and returns undefined for undefined/symbol/function (those fall
+// back to String()), and String() itself can throw for exotic values (a
+// null-prototype cycle, a throwing Symbol.toPrimitive) — those get a literal
+// placeholder so the refusal always surfaces as the refusal.
+function formatConfigValue(value) {
+  try {
+    const rendered = JSON.stringify(value);
+    return rendered === undefined ? String(value) : rendered;
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return "<unrenderable value>";
+    }
+  }
+}
+
+// The three GatesConfig keys whose value is a GateConfig (i.e. carries its
+// own blockCleanOnFindingSeverities) — kept in sync with the `gates:
+// { draft, preApproval, spike }` keys below by construction (both list the
+// same three names; a fourth GateConfig-typed gate would need both updated).
+const GATE_KEYS_WITH_BLOCKING_SEVERITIES = /** @type {const} */ (["draft", "preApproval", "spike"]);
+
 const GateConfig = z.strictObject({
   angles: z.array(GateAngleEntry).optional().describe("Review lenses this gate fans out to. A bare string is sugar for { name }; an object may set mandatory/enabled/persona/prompt/model/tier."),
   dynamic: GateDynamicConfig.optional().describe("Diff-driven dynamic angle selection policy for this gate."),
@@ -231,7 +273,7 @@ const GateConfig = z.strictObject({
   // admitting either here would let a config block on a severity the
   // disposition pass simultaneously auto-resolves.
   blockCleanOnFindingSeverities: z
-    .array(z.enum(["high", "medium", "low", "must-fix", "worth-fixing-now", "nice-to-have", "defer"]))
+    .array(z.enum(/** @type {[string, ...string[]]} */ (BLOCKING_SEVERITY_SPELLINGS)))
     .min(1)
     .default(["high"])
     .describe("Defect finding severities that block a clean gate verdict (high/medium/low only — \"question\"/\"nit\" are non-defect categories and never block by severity). \"must-fix\" is the deprecated legacy spelling of \"high\", \"worth-fixing-now\" of \"medium\", and \"nice-to-have\"/\"defer\" of \"low\"; consumers normalize them."),
@@ -286,7 +328,8 @@ const FanoutConfig = z.strictObject({
   mode: z.enum(["grouped", "per-angle"]).default("grouped").describe("Angle dispatch mode: grouped batches related angles onto one reviewer each (default); per-angle bypasses the configured-groups table and emits one singleton unit per angle (the original full-scrutiny shape). per-angle is equivalent to maxAnglesPerGroup: 1 in dispatch unit size ONLY when no configured multi-angle group matches a resolved angle; otherwise per-angle bypasses configured groups while maxAnglesPerGroup: 1 honors them (matched first, never split)."),
   groups: z.array(FanoutGroup).optional().describe("Static named angle groups consulted in grouped mode. An angle absent from every group joins the auto-chunked leftover pool (chunked into units of ≤maxAnglesPerGroup)."),
   maxAnglesPerGroup: z.number().int().min(1).default(3).describe("Max angles per auto-chunked dispatch unit for leftover ungrouped angles (default 3, min 1). Configured groups are matched first and never split by this knob; mode: per-angle bypasses the table entirely (one singleton per angle)."),
-  maxConcurrent: z.number().int().min(1).default(4).describe("Max dispatch units (groups) the conductor dispatches concurrently per wave (default 4, min 1). The wave plan is emitted by write-gate-context.mjs via scheduleFanoutWaves (scheduleParallelWaves)."),
+  maxConcurrent: z.number().int().min(1).default(4).describe("Max dispatch units (groups) the conductor dispatches concurrently per wave (default 4, min 1). The wave plan is emitted by write-gate-context.mjs via scheduleFanoutWaves (scheduleParallelWaves). Ignored when sequential is true (which forces one unit per wave)."),
+  sequential: z.boolean().default(false).describe("Dispatch heavy reviewers one at a time (serial) instead of wave-by-wave parallel (issue #1726). When true, effective fan-out concurrency is one dispatch unit per wave regardless of maxConcurrent, so each heavy reviewer completes and writes its evidence artifact before the next starts. Distinct reviewers, real fan-in/ledger, and provenance are unchanged — this only bounds dispatch concurrency. Default false keeps shipped behaviour unchanged for other harnesses/repos (cross-harness non-regression #1086); a repo sets it in .devloops to bound concurrency for all its PRs."),
 });
 
 /**
@@ -314,8 +357,45 @@ function rejectDuplicateFanoutGroupNames(val, ctx) {
   }
 }
 
+// Fail-closed PR size budget (Phase 1 of the escalate-don't-chop size gate:
+// this schema plus check-size-budget.mjs's pure computation only — no
+// enforcement wiring yet). `patterns` classifies a changed file into t1/t3
+// by path glob; the default tier is implicit for every file matching
+// neither, so it carries no `patterns` field of its own. `sliceHardLoc`
+// (t1 only) caps the T1-slice LOC, not the whole-PR LOC.
+//
+// Per-tier `softLoc`/`waiverLoc` on t1/t3, and `sliceHardLoc` on t3, are a
+// later phase's escalation surface (e.g. a t3 "relaxed" tier with its own
+// softLoc, or a t1 slice with its own waiver ceiling) — not honored by
+// computeSizeBudget yet, so they are parked out of the schema for Phase 1
+// rather than shipped as inert accepted-but-ignored knobs. Only the
+// default tier's softLoc/waiverLoc and t1's sliceHardLoc drive Phase 1's
+// outcome; see check-size-budget.mjs.
+const SizeTierConfig = z.strictObject({
+  patterns: z.array(z.string().trim().min(1)).optional().describe("Glob-style path patterns; a changed file matching one resolves to this tier."),
+  softLoc: z.number().int().positive().nullable().optional().describe("Escalate above this many logic LOC; null disables the soft threshold for this tier."),
+  waiverLoc: z.number().int().positive().nullable().optional().describe("Block (waiver required) above this many logic LOC, up to absoluteHardLoc; null disables the waiver threshold for this tier."),
+  sliceHardLoc: z.number().int().positive().optional().describe("T1 only: block above this many T1-slice logic LOC unless waived by a named human approver."),
+});
+
+const SizeTiersConfig = z.strictObject({
+  default: SizeTierConfig.omit({ patterns: true, sliceHardLoc: true }).default({ softLoc: 400, waiverLoc: 1500 }).describe("Fallback tier applied to every changed file that matches no t1/t3 pattern."),
+  t1: SizeTierConfig.omit({ softLoc: true, waiverLoc: true }).optional().describe("Risk-slice tier (money/auth/shared/ungated paths). Empty by default — a repo defines its own patterns; the T1 slice is computed separately from whole-PR LOC."),
+  t3: SizeTierConfig.pick({ patterns: true }).optional().describe("Relaxed tier (e.g. scaffold/template clones). Empty by default — a repo defines its own patterns; the absolute ceiling still applies. Per-tier soft/waiver thresholds are not yet honored (Phase 1)."),
+});
+
+const SizeConfig = z.strictObject({
+  testDiscount: z.number().min(0).max(1).default(0.25).describe("Weight applied to test LOC when computing logicLoc = code + testDiscount * test."),
+  absoluteHardLoc: z.number().int().positive().default(2000).describe("Whole-PR logic-LOC ceiling; blocks with no waiver possible above this, for any tier."),
+  tiers: SizeTiersConfig.default({}).describe("Per-tier soft/waiver/slice thresholds and path patterns."),
+});
+
 const GatesConfig = z.strictObject({
   draft: GateConfig.optional(),
+  // Fail-closed PR size/tier budget (active by default). Computation lives in
+  // scripts/loop/check-size-budget.mjs; this config carries only the
+  // thresholds and tier patterns it reads.
+  size: SizeConfig.optional(),
   // `requireCi` is honored on both gates: default true keeps CI a precondition,
   // false is an opt-out escape hatch so a repo with no CI is not held at the
   // gate. The pre-approval gate mirrors the draft gate's `requireCi` semantics —
@@ -427,6 +507,17 @@ const WorkflowConfig = z.strictObject({
   requireRetrospective: z.boolean().describe("Require a retrospective checkpoint for the previous qualifying async completion before the next dev-loop start/resume."),
   requireDraftFirst: z.boolean().describe("Open pull requests as drafts and promote via the draft gate."),
   devModeDefault: z.boolean().describe("Default new loops to dev mode."),
+  // Agent-level stall detection (#1669): when a dev-loop child shows no turn
+  // progress for `thresholdMinutes` with no pending request, the parent bails
+  // to a fresh-context recovery dispatch instead of waiting through a manual
+  // interrupt+resume. `enabled: false` disables the auto-bail and restores
+  // the old wait behavior.
+  stallDetection: z
+    .strictObject({
+      enabled: z.boolean().default(true).describe("Enable agent-level stall -> auto-fresh-dispatch."),
+      thresholdMinutes: z.number().int().min(1).default(5).describe("No-turn-progress window in minutes before a child is treated as stalled."),
+    })
+    .optional(),
   // No default here and absent from BUILT_IN_DEFAULTS — unset means "keep
   // auto-detecting the default branch" (see resolveBaseBranch), never a static
   // "main". Bare branch name; consumers add the `origin/` remote-ref prefix
@@ -719,6 +810,48 @@ const UiReviewConfig = z.strictObject({
     .optional(),
 });
 
+// Default/ceiling bounds for a post-merge action's run/verify timing (#1457).
+// The default keeps a config-declared action from hanging a harness hook
+// forever when the author leaves timeoutMs unset; the ceiling caps how far a
+// config CAN push it — a config can only tighten these, never loosen past the
+// ceiling.
+export const POST_MERGE_ACTION_DEFAULT_TIMEOUT_MS = 120000;
+export const POST_MERGE_ACTION_TIMEOUT_CEILING_MS = 600000;
+export const POST_MERGE_VERIFY_DEFAULT_TIMEOUT_MS = 60000;
+export const POST_MERGE_VERIFY_TIMEOUT_CEILING_MS = 600000;
+export const POST_MERGE_VERIFY_DEFAULT_INTERVAL_MS = 2000;
+export const POST_MERGE_VERIFY_INTERVAL_CEILING_MS = 60000;
+
+/**
+ * One post-merge action (Stage: local consumer hook). `run` and `verify` are
+ * executed VERBATIM as the operator wrote them — same trust level as
+ * `uiReview.run.command` (this repo's own committed `.devloops`) — so callers
+ * must never build these strings by interpolating untrusted runtime data
+ * (PR titles, branch names, verify output) into them. `onlyIfChanged` is
+ * matched as DATA (plain substrings against changed file paths), never
+ * shelled out.
+ */
+const PostMergeActionConfig = z.strictObject({
+  name: z.string().trim().min(1),
+  run: z.string().trim().min(1),
+  onlyIfChanged: z.array(z.string().trim().min(1)).optional(),
+  verify: z.string().trim().min(1).optional(),
+  timeoutMs: z.number().int().min(1).max(POST_MERGE_ACTION_TIMEOUT_CEILING_MS).default(POST_MERGE_ACTION_DEFAULT_TIMEOUT_MS),
+  verifyTimeoutMs: z.number().int().min(1).max(POST_MERGE_VERIFY_TIMEOUT_CEILING_MS).default(POST_MERGE_VERIFY_DEFAULT_TIMEOUT_MS),
+  verifyIntervalMs: z.number().int().min(1).max(POST_MERGE_VERIFY_INTERVAL_CEILING_MS).default(POST_MERGE_VERIFY_DEFAULT_INTERVAL_MS),
+});
+
+/**
+ * `postMerge.actions`: consumer-declared local actions (sync checkout, restart
+ * a local service, smoke check) run sequentially, in declared order, after the
+ * dev-loop's merge succeeds. Mirrors `uiReview.run` as the config-shape,
+ * validation, and command-execution precedent. Absent (the default) means no
+ * action is declared — a repo without this family gets zero new hook commands.
+ */
+const PostMergeConfig = z.strictObject({
+  actions: z.array(PostMergeActionConfig).optional(),
+});
+
 /** Internal path whitelist for internal-only PR detection — flat array of regex strings */
 const InternalPatternsConfig = z.array(z.string().trim().min(1)).min(1);
 
@@ -731,6 +864,7 @@ const FileGatesConfig = z.strictObject({
   draft: GateConfig.partial().describe("Draft gate config (runs before a PR leaves draft).").optional(),
   preApproval: GateConfig.partial().describe("Pre-approval gate config (final re-review before the merge handoff).").optional(),
   spike: GateConfig.partial().describe("Relaxed spike gate profile; applies only to spike-mode work.").optional(),
+  size: SizeConfig.partial().describe("Fail-closed PR size/tier budget: testDiscount, absoluteHardLoc, and per-tier soft/waiver/slice thresholds + patterns.").optional(),
   requireFanoutEvidence: z.boolean().describe("Require fan-out/fan-in review evidence on gate verdicts; inline single-agent verdicts are rejected except under the strict light-mode exception (under-threshold scope, no gate:full label, recorded inline reason).").optional(),
   requireFanoutProvenance: z.boolean().describe("Additionally require recorded, internally-consistent fan-out provenance (distinct reviewer count + per-angle dispatch).").optional(),
   maxFanoutReviewers: z.number().int().min(1).max(64).describe("SUPERSEDED by gates.fanout.maxConcurrent (#1601, ADR 0048): no longer governs fan-out dispatch — the conductor dispatches wave-by-wave at most gates.fanout.maxConcurrent (M) dispatch units per wave via scheduleFanoutWaves (the wave plan emitted by write-gate-context.mjs). Kept for back-compat; setting it has no dispatch effect.").optional(),
@@ -771,6 +905,7 @@ export const DevLoopConfigSchema = z.strictObject({
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.optional(),
   uiReview: UiReviewConfig.optional(),
+  postMerge: PostMergeConfig.optional(),
 });
 
 // ============================================================================
@@ -795,6 +930,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     requireRetrospective: false,
     requireDraftFirst: false,
     devModeDefault: false,
+    stallDetection: Object.freeze({ enabled: true, thresholdMinutes: 5 }),
   }),
   localImplementation: Object.freeze({
     lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200, maxCopilotRounds: 1 }),
@@ -845,6 +981,7 @@ export const FileConfigSchema = z.strictObject({
   internalPathPatterns: InternalPatternsConfig.describe("Regex whitelist for internal-only PR detection.").optional(),
   worktree: WorktreeConfig.partial().describe("Worktree provisioning: gitignored files/dirs copied or symlinked into fresh worktrees.").optional(),
   uiReview: UiReviewConfig.partial().describe("UI-review route recipes: per-project run/boot, dev-login, driven flows, and caps.").optional(),
+  postMerge: PostMergeConfig.partial().describe("Post-merge local hook actions (postMerge.actions): consumer-declared commands run sequentially, in order, after a merge succeeds — optionally scoped to changed-file substrings (onlyIfChanged) and polled for readiness (verify).").optional(),
   // 1.0 hard break (no dual-form): the deprecated `localPlanning` key (removed
   // behavior in #1088, tolerated-but-unread since) is dropped from the 1.0
   // schema entirely — an unknown key now fails closed like any other typo,
@@ -888,6 +1025,7 @@ const BUILTIN_PERSONAS = Object.freeze({
   determinism:          { persona: "review", defaultModel: null },
   "acceptance-criteria": { persona: "review", defaultModel: null },
   "ac-dod":              { persona: "review", defaultModel: null },
+  deslop:                { persona: "review", defaultModel: null },
 });
 
 const DEFAULT_REVIEWER_PERSONA = "default-reviewer";
@@ -1024,7 +1162,7 @@ function resolveTierMapping(config, tierAlias, harness) {
   if (!builtinMapping && !configMapping) return null;
   const mapping = { ...builtinMapping, ...configMapping };
   const model = mapping[harness];
-  return typeof model === "string" && model.trim().length > 0 ? model.trim() : null;
+  return trimmedOrNull(model);
 }
 
 /**
@@ -1805,6 +1943,51 @@ export function resolveRefinement(config) {
   return { fanOut, mode, roles, maxCopilotRounds, stopOnLowSignal, lowSignalRoundThreshold, lowSignalMaxComments, preApprovalRequireCi };
 }
 
+/**
+ * Resolve and validate ONE gate's raw `blockCleanOnFindingSeverities` value
+ * against the schema's severity vocabulary, returning the normalized/deduped
+ * list (or the ["high"] default when the key is absent). Shared by
+ * resolveGateConfig, which calls this for every GateConfig-typed gate on
+ * every invocation (see that function's @throws doc) so an invalid list on
+ * any gate refuses eagerly, not only when that specific gate is requested.
+ *
+ * @param {DevLoopConfig} config
+ * @param {"draft"|"preApproval"|"spike"} gate
+ * @returns {string[]}
+ * @throws {Error} when `gate`'s PRESENT `blockCleanOnFindingSeverities` key
+ *   is schema-invalid (non-array, empty, or containing an out-of-vocabulary
+ *   entry).
+ */
+function resolveBlockingSeverities(config, gate) {
+  const rawBlocking = config?.gates?.[gate]?.blockCleanOnFindingSeverities;
+  if (rawBlocking === undefined) return ["high"];
+  if (!Array.isArray(rawBlocking)) {
+    throw new Error(
+      `Config validation failed: gates.${gate}.blockCleanOnFindingSeverities must be an array ` +
+      `of defect severities, got ${formatConfigValue(rawBlocking)}. ` +
+      `Fix the config before gate operations can proceed.`
+    );
+  }
+  if (rawBlocking.length === 0) {
+    throw new Error(
+      `Config validation failed: gates.${gate}.blockCleanOnFindingSeverities is empty; ` +
+      `the schema requires at least one blocking severity, and an empty list would make the gate block on nothing. ` +
+      `Fix the config before gate operations can proceed.`
+    );
+  }
+  const invalid = rawBlocking.filter((s) => typeof s !== "string" || !BLOCKING_SEVERITY_SPELLING_SET.has(s));
+  if (invalid.length > 0) {
+    throw new Error(
+      `Config validation failed: gates.${gate}.blockCleanOnFindingSeverities contains ` +
+      `value(s) outside the schema's severity vocabulary: ${invalid.map((s) => formatConfigValue(s)).join(", ")}. ` +
+      `Allowed (exact spellings): ${BLOCKING_SEVERITY_SPELLINGS.join(", ")} ` +
+      `(the legacy spellings normalize to high/medium/low). ` +
+      `Fix the config before gate operations can proceed.`
+    );
+  }
+  return [...new Set(rawBlocking.map((s) => normalizeSeverity(s)))];
+}
+
 /**
  * Resolve one gate configuration object from the merged dev-loop config.
  *
@@ -1825,9 +2008,42 @@ export function resolveRefinement(config) {
  * @param {DevLoopConfig} config
  * @param {"draft"|"preApproval"|"spike"} gate
  * @returns {{ angles: string[]|null, excludeAngles: string[], mandatoryAngles: string[], required: boolean, requireCi: boolean, blockCleanOnFindingSeverities: string[], dynamicAngles: boolean, additiveAngles: boolean, mediumFixWindow: number, tiers: Array<{name: string, match: object, angles: string[]}> }}
+ * @throws {Error} when ANY gate's (draft, preApproval, or spike — not only
+ *   the requested `gate`'s) PRESENT `blockCleanOnFindingSeverities` key is
+ *   any schema-invalid shape: a non-array value, an empty array, or an entry
+ *   that is not one of the schema enum's exact spellings. Every such shape
+ *   can only arrive through a config that failed schema validation (the
+ *   schema requires a min-1 array of the enum spellings; the guard
+ *   exact-matches raw entries against the same spelling list, so its accept
+ *   set is byte-identical to the schema's), and passing it through would make
+ *   the affected gate block on the wrong severities or on nothing at all.
+ *   Validated EAGERLY across all three gates on every call — not lazily,
+ *   only for the requested `gate` — so that a single-gate consumer (e.g. a
+ *   draft-only fan-in consolidation) can never proceed and produce a
+ *   side-effect (write a ledger artifact, flip ready-for-review) while a
+ *   DIFFERENT gate's severity list is invalid; that invalid gate would only
+ *   have surfaced later, lazily, at a dual-gate call site (e.g. verdict
+ *   posting), after the single-gate side effect already happened. This is
+ *   the stated boundary with the module's degrade-quietly convention for
+ *   dispatch-ergonomics keys (resolveMaxAnglesPerGroup substitutes its
+ *   default, resolveFanoutGroups drops malformed entries): those keys only
+ *   shape dispatch, so they degrade; the key that decides what blocks a
+ *   clean verdict refuses, fail-closed, before any gate proceeds. An ABSENT
+ *   key still falls back to the default unchanged.
  */
 export function resolveGateConfig(config, gate) {
   const gateConfig = config?.gates?.[gate];
+  // Eagerly validate every gate's blockCleanOnFindingSeverities together
+  // (not just the requested `gate`'s) so an invalid list on ANY gate refuses
+  // up front, before this call's single-gate result can be used for a
+  // side effect that a later, different-gate call would otherwise still be
+  // able to reach lazily. See the @throws doc above for the reachability
+  // this closes.
+  let blockCleanOnFindingSeverities = ["high"];
+  for (const g of GATE_KEYS_WITH_BLOCKING_SEVERITIES) {
+    const resolved = resolveBlockingSeverities(config, g);
+    if (g === gate) blockCleanOnFindingSeverities = resolved;
+  }
   const entries = normalizeAngleEntries(gateConfig?.angles);
   // An explicitly-empty (or all-garbage/malformed) array is a real configured
   // "no angles" — distinct from the key being absent entirely, which callers
@@ -1841,12 +2057,11 @@ export function resolveGateConfig(config, gate) {
     requireCi: gateConfig?.requireCi ?? true,
     dynamicAngles: gateConfig?.dynamic?.subtractive ?? true,
     additiveAngles: gateConfig?.dynamic?.additive ?? false,
-    // Normalized + deduped at the resolve boundary so every consumer (envelope,
-    // verdict poster, fan-in, viewer) sees canonical spellings only; a
-    // half-migrated ["must-fix","low","defer"] collapses to two entries.
-    blockCleanOnFindingSeverities: gateConfig?.blockCleanOnFindingSeverities && Array.isArray(gateConfig.blockCleanOnFindingSeverities)
-      ? [...new Set(gateConfig.blockCleanOnFindingSeverities.map((s) => normalizeSeverity(s)))]
-      : ["high"],
+    // Normalized + deduped at the resolve boundary (above) so every consumer
+    // (envelope, verdict poster, fan-in, viewer) sees canonical spellings
+    // only; a half-migrated ["must-fix","low","defer"] collapses to two
+    // entries, and anything outside the vocabulary has already thrown.
+    blockCleanOnFindingSeverities,
     // `mediumFixWindow` wins; `worthFixingNowFixWindow` is the deprecated
     // pre-rename key, still honored so an unmigrated config keeps its
     // configured window rather than silently reverting to the default.
@@ -2059,6 +2274,36 @@ export const DEFAULT_MAX_ANGLES_PER_GROUP = 3;
  * `scheduleFanoutWaves` (@dev-loops/core/loop/gate-fanin).
  */
 export const DEFAULT_FANOUT_MAX_CONCURRENT = 4;
+export const DEFAULT_FANOUT_SEQUENTIAL = false;
+
+/**
+ * Resolve `gates.fanout.sequential` (issue #1726, default false). Serial
+ * (one-at-a-time) dispatch of heavy reviewers so each completes and writes its
+ * evidence before the next starts — the concurrency bound that keeps genuine
+ * fan-out from SIGTERMing under child-safe parallel overload. Separate from
+ * `maxConcurrent` so a repo may choose either serial (sequential: true) or a
+ * small parallel cap (maxConcurrent: 1-2, sequential: false); the shipped
+ * default stays false for cross-harness non-regression (#1086).
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveFanoutSequential(config) {
+  const s = config?.gates?.fanout?.sequential;
+  return s === true;
+}
+
+/**
+ * Resolve the effective fan-out concurrency (dispatch units per wave) for a
+ * round: 1 when `gates.fanout.sequential` is set (serial dispatch forces one
+ * unit per wave), else `resolveFanoutMaxConcurrent`. The conductor builds the
+ * wave plan from this effective value (issue #1726).
+ * @param {DevLoopConfig} config
+ * @returns {number}
+ */
+export function resolveFanoutEffectiveConcurrency(config) {
+  if (resolveFanoutSequential(config)) return 1;
+  return resolveFanoutMaxConcurrent(config);
+}
 
 /**
  * Resolve `gates.fanout.maxAnglesPerGroup` (issue #1601, default 3, min 1).
@@ -2405,11 +2650,13 @@ export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabe
   let changedFiles;
   let filesChanged;
   let linesChanged;
+  let prosePresent = false;
   if (diff) {
     const { analyzeT0, analyzeT1 } = await import("../analysis/diff-analyzer.mjs");
     const t0 = analyzeT0(diff.nameStatusOutput);
     changedFiles = t0.files;
     filesChanged = changedFiles.length;
+    prosePresent = t0.prosePresent; // #1442: gate deslop on the prose surface
     if (diff.diffOutput) {
       const lineStats = analyzeT1(diff.diffOutput, t0).lineStats;
       linesChanged = lineStats.added + lineStats.deleted;
@@ -2418,10 +2665,18 @@ export async function resolveGateAnglesDynamic(config, gate, { diff, hasFullLabe
   const tierResult = resolveGateTier(config, gate, { changedFiles, filesChanged, linesChanged, hasFullLabel });
   if (tierResult.tier) {
     const configuredAngles = resolveGateAngles(config, gate) ?? [];
-    const tierAngleSet = new Set(tierResult.angles);
-    const skippedAngles = configuredAngles.filter((a) => !tierAngleSet.has(a));
+    let recommendedAngles = tierResult.angles;
+    // #1442 (ADR 0041 prose half): deslop is a prose-only angle. A docs-kind
+    // tier (e.g. this repo's docs-only/small-non-code) names it so prose diffs
+    // keep it, but that same kind matches exempt normative contracts
+    // (skills/docs/**). Strip deslop when the diff touches no prose surface so
+    // exemption holds even through the tier path.
+    if (recommendedAngles.includes("deslop") && prosePresent === false) {
+      recommendedAngles = recommendedAngles.filter((a) => a !== "deslop");
+    }
+    const skippedAngles = configuredAngles.filter((a) => !recommendedAngles.includes(a));
     return {
-      recommendedAngles: tierResult.angles,
+      recommendedAngles,
       skippedAngles,
       reasons: Object.fromEntries(skippedAngles.map((a) => [a, `tier:${tierResult.tier}`])),
       fallbackToAll: false,
@@ -2531,6 +2786,15 @@ export function resolveWorkflowConfig(config, key) {
     return config?.workflow?.devModeDefault ?? DEFAULT_WORKFLOW_CONFIG.devModeDefault;
   }
 
+  if (key === "stallDetection") {
+    const configured = config?.workflow?.stallDetection;
+    const def = DEFAULT_WORKFLOW_CONFIG.stallDetection;
+    return {
+      enabled: configured?.enabled ?? def.enabled,
+      thresholdMinutes: configured?.thresholdMinutes ?? def.thresholdMinutes,
+    };
+  }
+
   throw new Error(`Unknown workflow config key: ${key}`);
 }
 
@@ -2684,12 +2948,41 @@ export function resolveUiReviewRunRecipe(config) {
     readyUrl: run.readyUrl.trim(),
     readyTimeoutMs: Number.isInteger(run.readyTimeoutMs) ? run.readyTimeoutMs : 60000,
     readyIntervalMs: Number.isInteger(run.readyIntervalMs) ? run.readyIntervalMs : 1000,
-    cwd: typeof run.cwd === "string" && run.cwd.trim().length > 0 ? run.cwd.trim() : null,
+    cwd: trimmedOrNull(run.cwd),
     migrate,
     rowTeardown,
   };
 }
 
+/**
+ * Resolve `postMerge.actions` from the merged config into normalized, runner-ready
+ * action objects. `run`/`verify` are trimmed but otherwise passed through
+ * VERBATIM (never rebuilt by concatenation) — the runner executes them exactly
+ * as declared. Returns `[]` when `postMerge` is absent — a `.devloops` without
+ * this family produces zero actions (and so zero hook commands).
+ *
+ * @param {DevLoopConfig} config
+ * @returns {{ name: string, run: string, onlyIfChanged: string[]|null, verify: string|null,
+ *   timeoutMs: number, verifyTimeoutMs: number, verifyIntervalMs: number }[]}
+ */
+export function resolvePostMergeActions(config) {
+  const actions = config?.postMerge?.actions;
+  if (!Array.isArray(actions)) return [];
+  return actions
+    .filter((a) => a && typeof a.name === "string" && a.name.trim().length > 0 && typeof a.run === "string" && a.run.trim().length > 0)
+    .map((a) => ({
+      name: a.name.trim(),
+      run: a.run.trim(),
+      onlyIfChanged: Array.isArray(a.onlyIfChanged)
+        ? a.onlyIfChanged.filter((p) => typeof p === "string" && p.trim().length > 0).map((p) => p.trim())
+        : null,
+      verify: trimmedOrNull(a.verify),
+      timeoutMs: Number.isInteger(a.timeoutMs) ? a.timeoutMs : POST_MERGE_ACTION_DEFAULT_TIMEOUT_MS,
+      verifyTimeoutMs: Number.isInteger(a.verifyTimeoutMs) ? a.verifyTimeoutMs : POST_MERGE_VERIFY_DEFAULT_TIMEOUT_MS,
+      verifyIntervalMs: Number.isInteger(a.verifyIntervalMs) ? a.verifyIntervalMs : POST_MERGE_VERIFY_DEFAULT_INTERVAL_MS,
+    }));
+}
+
 /**
  * Default server-log exception signal for the drive stage's log tail. Matched
  * (case-insensitive, per line) against the tailed server-log text. This is a
@@ -2719,7 +3012,7 @@ export function resolveUiReviewDriveRecipe(config) {
   if (!login || typeof login.loginUrl !== "string" || login.loginUrl.trim().length === 0) return null;
   if (typeof login.submitSelector !== "string" || login.submitSelector.trim().length === 0) return null;
   if (typeof login.successSelector !== "string" || login.successSelector.trim().length === 0) return null;
-  const serverLogPath = typeof ui.serverLogPath === "string" && ui.serverLogPath.trim().length > 0 ? ui.serverLogPath.trim() : null;
+  const serverLogPath = trimmedOrNull(ui.serverLogPath);
   return {
     login: {
       loginUrl: login.loginUrl.trim(),

package/src/config/extension-defaults.yaml

@@ -106,7 +106,7 @@ gates:
         prompt: Review this change for input-validation drift. Check repo slug, issue number, host, SHA, whitespace, and sentinel normalization. Prefer shared parsers/helpers over ad hoc validation. Flag malformed inputs that slip through, confusing errors, path traversal-like segments, and inconsistent trimming/normalization across CLI/API entrypoints. Recommend minimal tests for accepted and rejected forms.
       - name: threat-model
         persona: review
-        prompt: "Adversarially threat-model this change end to end — you are an attacker with control over every caller-/plan-influenced input (descriptors, paths, URLs, flags, env, fixture data). Do NOT spot-check; return a trust-boundary CHECKLIST and a verdict per item. Enumerate exhaustively for every seam the diff touches: (1) INPUT ALLOWLISTS — are actions/commands/schemes/hosts allowlisted (not denylisted), and enforced BEFORE any dangerous use (browser launch, exec, read)? (2) NAVIGATION/ORIGIN CONFINEMENT — same-origin/scheme enforced both pre-launch AND at runtime after every redirect / click / server-response (a pre-check the runtime can defeat is a hole). (3) RESOURCE/LOOP BOUNDS — step/size/time/recursion caps on attacker-influenced counts. (4) DATA-AT-REST + CLEANUP — sensitive intermediate artifacts minimized and removed on EVERY fail-closed path (not just the happy path); no off-origin/partial artifact left on disk on error. (5) EXPORTED/ENTRY-POINT TRUST — does every exported function / alternate entry self-validate, or can it bypass the parse-time validation the CLI does? (6) ERROR/TEARDOWN SAFETY — a throw in rm/close/teardown must not break the fail-closed envelope or leak state. (7) PATH TRAVERSAL / DESERIALIZATION — reject absolute/`..`/escape-base paths before read; no unsafe deserialization of untrusted data. (8) SHELL/PROCESS — no unescaped interpolation into a shell; prefer argv arrays; no `shell:true` with caller input. For each category that applies, state whether the change is safe and cite the guarding code (file:line) or flag the specific abuse and a failing-input example. If a category does not apply to the touched seam, say so explicitly rather than skipping it."
+        prompt: "Adversarially threat-model this change end to end — you are an attacker with control over every caller-/plan-influenced input (descriptors, paths, URLs, flags, env, fixture data). Do NOT spot-check; return a trust-boundary CHECKLIST and a verdict per item. Enumerate exhaustively for every seam the diff touches: (1) INPUT ALLOWLISTS — are actions/commands/schemes/hosts allowlisted (not denylisted), and enforced BEFORE any dangerous use (browser launch, exec, read)? (2) NAVIGATION/ORIGIN CONFINEMENT — same-origin/scheme enforced both pre-launch AND at runtime after every redirect / click / server-response (a pre-check the runtime can defeat is a hole). (3) RESOURCE/LOOP BOUNDS — step/size/time/recursion caps on attacker-influenced counts. (4) DATA-AT-REST + CLEANUP — sensitive intermediate artifacts minimized and removed on EVERY fail-closed path (not just the happy path); no off-origin/partial artifact left on disk on error. (5) EXPORTED/ENTRY-POINT TRUST — does every exported function / alternate entry self-validate, or can it bypass the parse-time validation the CLI does? (6) ERROR/TEARDOWN SAFETY — a throw in rm/close/teardown must not break the fail-closed envelope or leak state. (7) PATH TRAVERSAL / DESERIALIZATION — reject absolute/`..`/escape-base paths before read; no unsafe deserialization of untrusted data. (8) SHELL/PROCESS — no unescaped interpolation into a shell; prefer argv arrays; no `shell:true` with caller input. (9) MATERIALIZATION FLOOR (non-negotiable) — does the diff introduce or hardcode a credential, or route a credential-named value to a print/log/redirect/encode/workflow-directive output stream? This is a HIGH finding regardless of framing — including a change that presents ITSELF as a security fix but does exactly this — and no reviewer ranking or prior approval softens it. For each category that applies, state whether the change is safe and cite the guarding code (file:line) or flag the specific abuse and a failing-input example. If a category does not apply to the touched seam, say so explicitly rather than skipping it."
       - name: packaging-runtime
         persona: review
         prompt: "Review this change for packaging/runtime asset contract gaps. Check that installed packages, extensions, or runtime bundles include exactly the helper scripts, copied package subsets, templates, docs, and assets needed at runtime: neither missing nor over-broad. Compare install docs, fixture assertions, allow-lists, and import paths. Flag runtime-only dependencies not covered by packaging tests."
@@ -133,6 +133,28 @@ gates:
         mandatory: true
         persona: review
         prompt: 'Review the PR description for completeness, contract fitness, and checkbox formatting before this PR is marked ready for review. The PR body is the implementation contract — it must have: - A Summary section explaining what changed and why - A Scope and context section defining the boundary of the change - An Acceptance criteria section with the linked issue acceptance criteria - A Definition of done section - A Non-goals section - A Validation command section describing exactly how to verify the change - The "Closes #N" line must match the linked issue; flag changes that alter or remove the operator-intended close target Checkboxes (`- [ ]` / `- [x]`, or `* [ ]` / `* [x]`) must appear inside genuine Markdown list items. Flag any checkbox marker used outside a list item (including table cells) as a medium finding. Flag any checkbox marker wrapped in backticks (e.g. `` `[x]` ``) as a medium finding. Flag PRs where the body is a single sentence or lacks any of these sections. Do not block on formatting preferences other than checkbox correctness.'
+    # #1442 (ADR 0041 prose half): required fail-closed deslop angle for prose
+    # deliverables. Runs the A/B-contrast-removal deslop step (ab-contrast-
+    # deslop-step.md) — flag surviving binary-contrast constructions so the gate
+    # fails closed on them. One reviewer per document (the existing fan-out
+    # mechanism already does this). Only armed when the diff touches the prose
+    # surface (PROSE_PRESENT); skills/docs/** is exempt.
+      - name: deslop
+        persona: review
+        prompt: >-
+          Run the required deslop step (ab-contrast-deslop-step.md) on every
+          changed prose document in the diff (docs/articles/**, docs/presentations/**,
+          README*, narrative docs/*.md). Flag every surviving binary-contrast /
+          negation-by-contrast construction — "not X but Y", "X, not Y",
+          "rather than A, B", "it isn't A, it's B", dramatic antithesis pairs and
+          fragments ("where X, Y", "less A, more B", "not just A but B") — in
+          either ordering (A-then-B or B-then-A). For each instance report a line
+          ref, the exact quote, the pattern name, and a proposed rewrite that cuts
+          the scaffolding while keeping any load-bearing factual distinction stated
+          plainly. Do NOT flag genuine conditionals, real either/or behavior, or
+          RFC-2119 modality (MUST/SHOULD) in normative contracts; and do NOT touch
+          skills/docs/** (exempt). Be exhaustive — a missed instance is the failure
+          mode, and fail closed when any survives.
     required: true
     requireCi: true
     # Diff-class angle tiers (opt-in, ordered, first match wins). A matching tier
@@ -143,6 +165,17 @@ gates:
     #     - name: docs-only
     #       match: { kinds: [docs] }
     #       angles: [pr-description, link-check, gate-evidence]
+  # Fail-closed PR size/tier budget (Phase 1: computation only, via
+  # scripts/loop/check-size-budget.mjs — not yet wired into any gate). Empty
+  # t1/t3 — no shipped tier patterns; a repo defines its own risk-slice
+  # (money/auth/shared) and relaxed (scaffold/template) globs in .devloops.
+  size:
+    testDiscount: 0.25
+    absoluteHardLoc: 2000
+    tiers:
+      default:
+        softLoc: 400
+        waiverLoc: 1500
   # The gate round's verdict review already carries every finding, so the
   # consolidated findings comment is opt-in duplication — keep it off.
   postFindingsComments: false
@@ -278,6 +311,11 @@ workflow:
   # it on consumers' product phases (#846). Matches the code default; the dev-loops repo opts in
   # via its own repo-root .devloops (which takes precedence over these extension defaults).
   devModeDefault: false
+  # Agent-level stall detection (#1669): auto-bail to fresh-context dispatch
+  # when a dev-loop child shows no turn progress for the window.
+  stallDetection:
+    enabled: true
+    thresholdMinutes: 5
 
 # Light-mode threshold for small local changes.
 localImplementation: