@dev-loops/core 1.0.0-rc.6 → 1.0.0

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."),
@@ -315,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 —
@@ -731,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);
 
@@ -743,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(),
@@ -783,6 +905,7 @@ export const DevLoopConfigSchema = z.strictObject({
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.optional(),
   uiReview: UiReviewConfig.optional(),
+  postMerge: PostMergeConfig.optional(),
 });
 
 // ============================================================================
@@ -858,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,
@@ -901,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";
@@ -1037,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);
 }
 
 /**
@@ -1818,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.
  *
@@ -1838,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
@@ -1854,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.
@@ -2448,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;
@@ -2461,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,
@@ -2736,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
@@ -2771,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

package/src/github/comment-id-guard.mjs

@@ -21,27 +21,113 @@
  * helpers cannot emit an issue/PR id without an explicit allowlist entry.
  *
  * Deliberate cross-reference mechanism: pass the id(s) to allow as
- * `allowedRefs: ["1670"]`. This is the ONLY sanctioned way a generated comment
- * body may reference an issue/PR id. Keep the allowlist small and deliberate.
+ * `allowedRefs: ["1670"]`. Aside from a genuine HTML numeric character
+ * reference (`&#<digits>;`, e.g. `&#91;` for `[`) — each such OCCURRENCE is
+ * skipped; the same digit run appearing elsewhere as a bare token still
+ * refuses — this is the ONLY sanctioned way a generated comment body may
+ * carry a `#<digits>` token. Extraction is decode-aware on BOTH sides of the
+ * token: the body is also scanned after a single left-to-right decode of the
+ * entity forms GitHub's renderer resolves (numeric character references,
+ * zero-padding and hex included at cmark-gfm's 8-digit bound, plus the named
+ * hash entity),
+ * so a hash or any digit of the id smuggled as an entity — `&#35;123`,
+ * `&num;123`, `#&#49;23`, any mix — still refuses. The decode is single-pass
+ * like the renderer's: a double-encoded form (`&amp;#35;123`) renders as
+ * inert literal text and the decode pass never manufactures a refusal of its
+ * INNER id — though the raw scan still refuses the outer digit run of the
+ * numeric form as a pre-existing fail-closed near-miss (the outer entity's
+ * semicolon sits before the hash, so the well-formed-entity exclusion does
+ * not apply). Case-variants of the named hash entity are decoded too even
+ * where GitHub would not (`&NUM;`): deliberate over-refusal, keeping the
+ * guard fail-closed. Keep the allowlist small and deliberate.
  */
 
 // Matches a bare GitHub auto-link issue/PR reference: `#<digits>`. Bound to
 // 1..9 digits to avoid absurd ids while covering the full GitHub id space.
+// A match is excluded only when it forms a well-formed HTML numeric character
+// reference — preceded by `&` AND immediately followed by `;` (e.g. `&#91;`,
+// the entity-encoded form of `[`). Any other shape (a bare `#123`, an
+// `&`-preceded run with no terminating `;`, or a `;`-followed run with no
+// preceding `&`) is not a well-formed entity and still refuses as a genuine
+// auto-link candidate.
 const ISSUE_PR_ID_RE = /#(\d{1,9})/g;
 
+function isNumericCharacterReference(body, match) {
+  // The digit bound mirrors cmark-gfm's 8-digit entity parser: a 9-digit
+  // ampersand-wrapped run is NOT decoded by the renderer, so it renders
+  // literally and must not be excluded as a spent entity.
+  return match[1].length <= 8
+    && body[match.index - 1] === "&"
+    && body[match.index + match[0].length] === ";";
+}
+
+// Entity forms the renderer resolves that can participate in assembling a
+// rendered `#<digits>` auto-link: numeric character references (any code
+// point — the hash AND the digits themselves are smuggleable) plus the named
+// hash entity. The digit bounds match cmark-gfm's numeric-entity parser
+// (up to 8 digits, decimal or hex) so nothing GitHub decodes escapes the
+// pass. Single non-rescanning replace = one decode, like the renderer, so a
+// double-encoded form's output is never re-read as a fresh entity.
+const DECODABLE_ENTITY_RE = /&(?:#(?:\d{1,8}|x[0-9a-f]{1,8})|num);/gi;
+
+function decodeRenderedText(body) {
+  return body.replace(DECODABLE_ENTITY_RE, (entity) => {
+    const inner = entity.slice(1, -1).toLowerCase();
+    if (inner === "num") return "#";
+    const code = inner[1] === "x" ? Number.parseInt(inner.slice(2), 16) : Number.parseInt(inner.slice(1), 10);
+    try {
+      return String.fromCodePoint(code);
+    } catch {
+      // cmark substitutes the replacement character for a reference it cannot
+      // decode; mirroring that keeps decodable-shaped text from lingering in
+      // the decoded scan, where it could masquerade as a spent entity.
+      return "�";
+    }
+  });
+}
+
+function collectBareIds(text, found, { excludeEntities }) {
+  for (const m of text.matchAll(ISSUE_PR_ID_RE)) {
+    if (excludeEntities && isNumericCharacterReference(text, m)) continue;
+    found.add(m[1]);
+  }
+}
+
 /**
  * Extract the raw issue/PR id tokens found in a body (as strings, deduped).
- * Returns [] for non-string input (and for a body with no `#<digits>`).
+ * Scans the body as written AND after a single renderer-like entity decode,
+ * so an id assembled from entity-encoded pieces is still found. The entity
+ * exclusion applies only to the RAW scan: in decoded text the renderer's one
+ * decode is already spent, so an ampersand-then-digits-then-semicolon shape
+ * there is plain text a wrapper cannot re-protect (an ampersand-wrapped
+ * encoded hash plus digits must refuse, not hide). Returns [] for non-string
+ * input (and for a body with no `#<digits>`).
  */
 export function extractIssuePrIds(body) {
   if (typeof body !== "string" || body.length === 0) return [];
   const found = new Set();
-  for (const m of body.matchAll(ISSUE_PR_ID_RE)) {
-    found.add(m[1]);
-  }
+  collectBareIds(body, found, { excludeEntities: true });
+  const decoded = decodeRenderedText(body);
+  if (decoded !== body) collectBareIds(decoded, found, { excludeEntities: false });
   return [...found];
 }
 
+// A caller-supplied allowlist is normally already an array (or other
+// iterable) of ids. Guard the one mis-shaped input that would otherwise
+// silently produce the wrong set: a plain CSV string. `Array.from` over a
+// string character-splits it ("1670" -> ["1","6","7","0"]), which would
+// spuriously allowlist single-digit refs while still refusing the id the
+// caller meant to allow. Mirrors parseAllowedRefsCsv's comma-split (trim,
+// drop empties) — deliberately without its numeric validation, since this is
+// a permissive low-level guard, not the CLI arg parser.
+function normalizeAllowedRefs(allowedRefs) {
+  if (allowedRefs == null) return [];
+  if (typeof allowedRefs === "string") {
+    return allowedRefs.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  }
+  return Array.from(allowedRefs, (id) => String(id));
+}
+
 /**
  * Fail-closed guard: returns `body` unchanged when it contains no raw
  * issue/PR id (or every id it contains is explicitly allowlisted). Throws
@@ -50,13 +136,15 @@ export function extractIssuePrIds(body) {
  * @param {string} body - the generated comment body to guard.
  * @param {object} [opts]
  * @param {string} [opts.ref] - human label for the guarded surface (error context).
- * @param {Iterable<number|string>} [opts.allowedRefs] - explicit allowlist of
- *   deliberate cross-reference ids permitted to appear in the body.
+ * @param {Iterable<number|string>|string} [opts.allowedRefs] - explicit
+ *   allowlist of deliberate cross-reference ids permitted to appear in the
+ *   body. A plain string is treated as a comma-separated list (like a CLI
+ *   `--allowed-refs` value), never character-split.
  * @returns {string} the (unchanged, since no stripping) body.
  */
 export function guardCommentBodyNoIssuePrIds(body, { ref = "generated comment body", allowedRefs = [] } = {}) {
   if (typeof body !== "string") return body;
-  const allow = new Set(Array.from(allowedRefs ?? [], (id) => String(id)));
+  const allow = new Set(normalizeAllowedRefs(allowedRefs));
   const offending = extractIssuePrIds(body).filter((id) => !allow.has(id));
   if (offending.length > 0) {
     throw new Error(