@event4u/agent-config 9.17.0 → 9.18.0

package/src/scripts/lint_trigger_collisions.ts

@@ -0,0 +1,257 @@
+#!/usr/bin/env tsx
+/**
+ * lint_trigger_collisions — every shared trigger carries a written-down
+ * disposition, or the build is red.
+ *
+ * Defect measured: a trigger string shared by ≥2 routed rules makes both fire
+ * on the same prompt. Many collisions are correct (`refactor` firing both the
+ * analyze-first and the diff-shape floor is complementary), but before this
+ * gate nothing forced that argument to be WRITTEN DOWN — so accidental
+ * co-firing (the brand pair, secret/password, valuation/DCF) accumulated
+ * silently. This gate makes every collision either dispositioned or an error.
+ *
+ * Why this gate shape: the existing `tests/scripts/rule_trigger_collisions.test.ts`
+ * is a pair-level Jaccard SIMILARITY ratchet (near-duplicate trigger sets);
+ * it is kept untouched. This lint is per-trigger-VALUE disposition coverage —
+ * a different axis: one shared value between otherwise-different rules never
+ * moves Jaccard past 0.4, but still needs an argument.
+ *
+ * Disposition, in the sharing rule's frontmatter (both optional keys are in
+ * `schemas/rule.schema.json`):
+ *
+ *   collision_ok:
+ *     "refactor": "one-line reason why this rule also firing here is correct"
+ *   precedence:
+ *     "refactor": 1        # all sharers declare pairwise-distinct integers
+ *
+ * A collision is clean when EVERY sharer has `collision_ok[<value>]`, OR all
+ * sharers carry pairwise-distinct `precedence[<value>]` integers.
+ *
+ * Scope: `src/rules/*.md`, `type: manual` excluded (reference-only, no router
+ * emission — ADR-004), rules without `triggers:` excluded (kernel).
+ * Same-value-different-kind never collides (a `keyword` and a `path_prefix`
+ * match different surfaces).
+ *
+ * Modes: default lint (exit 0 clean, 2 findings/dead-scope, 1 internal error;
+ * emits one machine-readable `scanned: <N>` line for gate-coverage), plus
+ * `--report <path>` writing the collision-census markdown, `--json`, `--quiet`.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const RULES_ROOT = 'src/rules';
+const TRIGGER_KINDS = ['keyword', 'phrase', 'command', 'path_prefix', 'file_pattern'] as const;
+
+export interface RuleTriggers {
+    id: string;
+    type: string;
+    triggers: { kind: string; value: string }[];
+    collision_ok: Record<string, string>;
+    precedence: Record<string, number>;
+}
+
+export interface Collision {
+    kind: string;
+    value: string; // case-folded
+    sharers: string[]; // rule ids, sorted
+    undispositioned: string[]; // rule ids missing a valid disposition
+}
+
+function _parse_frontmatter(text: string): Record<string, unknown> {
+    if (!text.startsWith('---\n')) return {};
+    const end = text.indexOf('\n---', 4);
+    if (end < 0) return {};
+    const data = parseYaml(text.slice(4, end), { version: '1.1' }) ?? {};
+    return data !== null && typeof data === 'object' && !Array.isArray(data)
+        ? (data as Record<string, unknown>)
+        : {};
+}
+
+function _as_string_map(v: unknown): Record<string, string> {
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) return {};
+    const out: Record<string, string> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+        out[k.toLowerCase()] = String(val);
+    }
+    return out;
+}
+
+function _as_int_map(v: unknown): Record<string, number> {
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) return {};
+    const out: Record<string, number> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+        const n = Number(val);
+        if (Number.isInteger(n)) out[k.toLowerCase()] = n;
+    }
+    return out;
+}
+
+export function load_rules(rules_dir: string): RuleTriggers[] {
+    const out: RuleTriggers[] = [];
+    let files: string[] = [];
+    try {
+        files = fs.readdirSync(rules_dir).filter((f) => f.endsWith('.md')).sort();
+    } catch {
+        return [];
+    }
+    for (const f of files) {
+        const fm = _parse_frontmatter(fs.readFileSync(path.join(rules_dir, f), 'utf-8'));
+        if (Object.keys(fm).length === 0) continue;
+        const type = String(fm['type'] ?? 'auto');
+        const rawTriggers = Array.isArray(fm['triggers']) ? (fm['triggers'] as unknown[]) : [];
+        const triggers: { kind: string; value: string }[] = [];
+        for (const t of rawTriggers) {
+            if (t === null || typeof t !== 'object' || Array.isArray(t)) continue;
+            for (const kind of TRIGGER_KINDS) {
+                if (kind in (t as Record<string, unknown>)) {
+                    triggers.push({ kind, value: String((t as Record<string, unknown>)[kind]).toLowerCase() });
+                    break;
+                }
+            }
+        }
+        out.push({
+            id: f.replace(/\.md$/, ''),
+            type,
+            triggers,
+            collision_ok: _as_string_map(fm['collision_ok']),
+            precedence: _as_int_map(fm['precedence']),
+        });
+    }
+    return out;
+}
+
+export function find_collisions(rules: RuleTriggers[]): Collision[] {
+    const routed = rules.filter((r) => r.type !== 'manual' && r.triggers.length > 0);
+    const byKey = new Map<string, Set<string>>();
+    const ruleById = new Map(routed.map((r) => [r.id, r]));
+    for (const r of routed) {
+        for (const t of r.triggers) {
+            const key = `${t.kind}\u0000${t.value}`;
+            const set = byKey.get(key) ?? new Set<string>();
+            set.add(r.id);
+            byKey.set(key, set);
+        }
+    }
+    const collisions: Collision[] = [];
+    for (const [key, sharerSet] of byKey) {
+        if (sharerSet.size < 2) continue;
+        const [kind, value] = key.split('\u0000') as [string, string];
+        const sharers = [...sharerSet].sort();
+        const withOk = sharers.filter((id) => value in (ruleById.get(id)?.collision_ok ?? {}));
+        const precedences = sharers
+            .map((id) => (ruleById.get(id)?.precedence ?? {})[value])
+            .filter((n): n is number => n !== undefined);
+        const precedence_ok =
+            precedences.length === sharers.length && new Set(precedences).size === sharers.length;
+        const undispositioned = precedence_ok ? [] : sharers.filter((id) => !withOk.includes(id));
+        collisions.push({ kind, value, sharers, undispositioned });
+    }
+    collisions.sort(
+        (a, b) => b.sharers.length - a.sharers.length || (a.value < b.value ? -1 : a.value > b.value ? 1 : 0),
+    );
+    return collisions;
+}
+
+export function render_report(rules: RuleTriggers[], collisions: Collision[], sha: string): string {
+    const routed = rules.filter((r) => r.type !== 'manual' && r.triggers.length > 0);
+    const totalTriggers = routed.reduce((s, r) => s + r.triggers.length, 0);
+    const distinct = new Set(routed.flatMap((r) => r.triggers.map((t) => `${t.kind}\u0000${t.value}`))).size;
+    const undisp = collisions.filter((c) => c.undispositioned.length > 0);
+    const lines: string[] = [
+        '# Trigger-collision census',
+        '',
+        `> Generated by \`./scripts-run src/scripts/lint_trigger_collisions --report agents/evidence/reports/trigger-collision-census.md\` on 2026-08-04 at ${sha}.`,
+        '> Do not hand-edit — re-run the command.',
+        '',
+        `- Routed rules with triggers: ${routed.length} (of ${rules.length} rule files; \`type: manual\` and trigger-less kernel rules excluded)`,
+        `- Trigger entries: ${totalTriggers} · distinct (kind, value) pairs: ${distinct}`,
+        `- Colliding values (shared by ≥2 rules): ${collisions.length}`,
+        `- Undispositioned collisions: ${undisp.length} (the lint is red unless this is 0)`,
+        '',
+        '| # | Kind | Trigger | Rules | Disposition |',
+        '|---|------|---------|-------|-------------|',
+    ];
+    collisions.forEach((c, i) => {
+        const status = c.undispositioned.length === 0 ? 'dispositioned' : `MISSING: ${c.undispositioned.join(', ')}`;
+        lines.push(`| ${i + 1} | ${c.kind} | \`${c.value}\` | ${c.sharers.join(', ')} | ${status} |`);
+    });
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function main(argv: string[]): number {
+    const quiet = argv.includes('--quiet');
+    const as_json = argv.includes('--json');
+    let reportPath: string | null = null;
+    const ri = argv.indexOf('--report');
+    if (ri >= 0) reportPath = argv[ri + 1] ?? null;
+
+    const rulesDir = path.join(REPO_ROOT, RULES_ROOT);
+    const rules = load_rules(rulesDir);
+    try {
+        assertScanned({
+            gate: 'lint_trigger_collisions',
+            scanned: rules.length,
+            units: 'rule file(s)',
+            roots: [RULES_ROOT],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) throw exc;
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
+    process.stdout.write(`scanned: ${rules.length}\n`);
+
+    const collisions = find_collisions(rules);
+    const findings = collisions.filter((c) => c.undispositioned.length > 0);
+
+    if (reportPath) {
+        let sha = 'HEAD';
+        try {
+            sha = fs.readFileSync(path.join(REPO_ROOT, '.git', 'HEAD'), 'utf-8').trim().slice(0, 9);
+        } catch {
+            // detached info unavailable — keep the placeholder
+        }
+        const target = path.isAbsolute(reportPath) ? reportPath : path.join(REPO_ROOT, reportPath);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, render_report(rules, collisions, sha));
+        if (!quiet) process.stdout.write(`report → ${reportPath}\n`);
+    }
+
+    if (as_json) {
+        process.stdout.write(JSON.stringify({ collisions, findings: findings.length }, null, 2) + '\n');
+    }
+
+    if (findings.length > 0) {
+        process.stderr.write(
+            `❌  ${findings.length} trigger collision(s) without a written disposition:\n`,
+        );
+        for (const c of findings) {
+            process.stderr.write(
+                `    ${c.kind} "${c.value}" shared by [${c.sharers.join(', ')}] — missing collision_ok/precedence on: ${c.undispositioned.join(', ')}\n`,
+            );
+        }
+        process.stderr.write(
+            '    Remedy: add `collision_ok: {"<value>": "<one-line reason>"}` (or pairwise-distinct\n' +
+                '    `precedence: {"<value>": <int>}`) to EVERY sharer’s frontmatter, or disjoin the trigger sets.\n',
+        );
+        return 2;
+    }
+    if (!quiet) {
+        process.stdout.write(
+            `✅  ${collisions.length} trigger collision(s), all dispositioned (${rules.length} rules scanned)\n`,
+        );
+    }
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+if (process.argv[1] && (import.meta.url === pathToFileURL(process.argv[1]).href || path.resolve(process.argv[1]) === _HERE)) {
+    process.exitCode = main(process.argv.slice(2));
+}

package/src/scripts/router_telemetry.ts

@@ -17,15 +17,10 @@
  * - tier_1 + tier_2 rules: active iff any trigger matches the prompt
  *   text (plus optional open-files / command context).
  *
- * Trigger semantics implemented:
- *
- *   | Type           | Match rule                                                       |
- *   |----------------|------------------------------------------------------------------|
- *   | `keyword`      | case-insensitive substring inside the prompt text                |
- *   | `phrase`       | case-insensitive substring (multi-word) inside the prompt text   |
- *   | `command`      | case-sensitive prefix on `command:` field (optional context)     |
- *   | `path_prefix`  | prefix match against any path in `open_files` (optional context) |
- *   | `file_pattern` | fnmatch against any path in `open_files` (optional context)      |
+ * Trigger semantics live in `_lib/router_match.ts` — the single matcher
+ * implementation (anchored `keyword`, unanchored `phrase`, `command`
+ * prefix, `path_prefix` / `file_pattern` over `open_files`); this module
+ * re-exports its names for existing importers.
  *
  * Reports go to `internal/bench/reports/router-telemetry/<UTC>.json`.
  *
@@ -36,6 +31,18 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml, YAMLError } from "yaml";
 
+import {
+  _asRuleList,
+  keyword_matches_anchored,
+  match_prompt,
+  trigger_matches,
+} from "./_lib/router_match.js";
+import type { JsonValue, Router } from "./_lib/router_match.js";
+
+// The matcher lives in `_lib/router_match.ts` (the single implementation —
+// see its header). Re-exported here so existing importers keep working.
+export { keyword_matches_anchored, match_prompt, trigger_matches };
+
 // src/scripts/router_telemetry.ts → two levels up is the repo root
 // (mirrors the Python module's parent.parent.parent resolution from
 // src/scripts/router_telemetry.py).
@@ -58,29 +65,6 @@ const DEFAULT_SAMPLE_CAP = 200;
 // tasks are the attribution map and become the untouchable set.
 const TRACK_B_CORPUS_REL = "internal/bench/corpora/ab-trackb.yaml";
 
-type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | { [key: string]: JsonValue };
-
-type Trigger = Record<string, JsonValue>;
-
-interface Rule {
-  id?: JsonValue;
-  triggers?: JsonValue;
-  [key: string]: JsonValue;
-}
-
-interface Router {
-  kernel?: JsonValue;
-  tier_1?: JsonValue;
-  tier_2?: JsonValue;
-  [key: string]: JsonValue;
-}
-
 function _log(msg: string, quiet: boolean, err = false): void {
   if (err) {
     process.stderr.write(`${msg}\n`);
@@ -101,264 +85,6 @@ function _utc_iso(): string {
   return iso.slice(0, 19) + "+00:00";
 }
 
-// ── fnmatch (Python fnmatch.fnmatch) ─────────────────────────────────────
-
-/**
- * Translate a Unix shell pattern into a RegExp, matching CPython's
- * `fnmatch.translate`. `*` → `.*`, `?` → `.`, `[...]` char classes
- * preserved (with `!` → `^` negation), everything else escaped.
- * Matching is case-sensitive on POSIX (the corpus paths are POSIX).
- */
-function _fnmatchToRegExp(pat: string): RegExp {
-  let res = "";
-  let i = 0;
-  const n = pat.length;
-  while (i < n) {
-    const c = pat[i] as string;
-    i += 1;
-    if (c === "*") {
-      res += ".*";
-    } else if (c === "?") {
-      res += ".";
-    } else if (c === "[") {
-      let j = i;
-      if (j < n && pat[j] === "!") {
-        j += 1;
-      }
-      if (j < n && pat[j] === "]") {
-        j += 1;
-      }
-      while (j < n && pat[j] !== "]") {
-        j += 1;
-      }
-      if (j >= n) {
-        res += "\\[";
-      } else {
-        let stuff = pat.slice(i, j);
-        if (!stuff.includes("-")) {
-          stuff = stuff.replace(/\\/g, "\\\\");
-        } else {
-          // Faithful port of CPython's dash-handling in fnmatch.translate:
-          // split the class body on `-` (bounded to [i, j)), escaping each
-          // chunk, then re-join with `-` so ranges survive.
-          const chunks: string[] = [];
-          let k = pat[i] === "!" ? i + 2 : i + 1;
-          let start = i;
-          while (true) {
-            const rel = pat.slice(k, j).indexOf("-");
-            if (rel < 0) {
-              break;
-            }
-            const idx = k + rel;
-            chunks.push(pat.slice(start, idx));
-            start = idx + 1;
-            k = idx + 3;
-          }
-          chunks.push(pat.slice(start, j));
-          stuff = chunks
-            .map((s) => s.replace(/\\/g, "\\\\").replace(/-/g, "\\-"))
-            .join("-");
-        }
-        // Escape regex set-meta chars except backslash/dash already handled.
-        stuff = stuff.replace(/([&~|])/g, "\\$1");
-        i = j + 1;
-        if (stuff.startsWith("!")) {
-          stuff = "^" + stuff.slice(1);
-        } else if (stuff.startsWith("^") || stuff.startsWith("[")) {
-          stuff = "\\" + stuff;
-        }
-        res += `[${stuff}]`;
-      }
-    } else {
-      res += c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    }
-  }
-  return new RegExp(`^(?:${res})$`, "s");
-}
-
-function _fnmatch(name: string, pat: string): boolean {
-  return _fnmatchToRegExp(pat).test(name);
-}
-
-// ── Trigger matching ─────────────────────────────────────────────────────
-
-/** Apply one trigger to a prompt + context; return True on match. */
-/** Unicode word character — letters, digits, underscore (incl. umlauts). */
-const _WORD_CHAR = /[\p{L}\p{N}_]/u;
-
-function _isWordChar(c: string | undefined): boolean {
-  return c !== undefined && _WORD_CHAR.test(c);
-}
-
-/**
- * Word-boundary-anchored keyword match (road-to-tested-routing Phase 3).
- *
- * A `keyword` occurrence counts only when its word-character edges sit on
- * word boundaries: `ac` no longer fires inside "black", `plan` no longer
- * fires inside "planet". Two deliberate reliefs:
- *
- * - An edge that is itself a NON-word character (e.g. `__()`, `/image:`,
- *   `trans(`, an emoji) carries no boundary requirement on that side —
- *   punctuation-shaped keywords keep their exact substring semantics.
- * - The right boundary accepts one optional plural `s` ("icons", "options",
- *   "secrets" still fire their singular keyword). Richer inflection (German
- *   verb endings: "implementiere", "committen") is a DOCUMENTED accepted
- *   recall cost of anchoring — the matrices carry standalone-token phrasings
- *   for those languages instead.
- *
- * `phrase` deliberately stays unanchored substring; since this change the
- * two trigger kinds genuinely differ.
- */
-export function keyword_matches_anchored(prompt_lower: string, kw_lower: string): boolean {
-  if (kw_lower === "") {
-    return false;
-  }
-  const needLeft = _isWordChar(kw_lower[0]);
-  const needRight = _isWordChar(kw_lower[kw_lower.length - 1]);
-  let idx = prompt_lower.indexOf(kw_lower);
-  while (idx !== -1) {
-    const leftOk = !needLeft || !_isWordChar(prompt_lower[idx - 1]);
-    let rightOk = true;
-    if (needRight) {
-      let end = idx + kw_lower.length;
-      if (prompt_lower[end] === "s") {
-        end += 1; // optional plural `s`
-      }
-      rightOk = !_isWordChar(prompt_lower[end]);
-    }
-    if (leftOk && rightOk) {
-      return true;
-    }
-    idx = prompt_lower.indexOf(kw_lower, idx + 1);
-  }
-  return false;
-}
-
-export function trigger_matches(
-  trigger: Trigger,
-  prompt: string,
-  open_files?: Iterable<string> | null,
-  command?: string | null,
-): boolean {
-  const prompt_lower = prompt.toLowerCase();
-  if ("keyword" in trigger) {
-    return keyword_matches_anchored(prompt_lower, String(trigger["keyword"]).toLowerCase());
-  }
-  if ("phrase" in trigger) {
-    return prompt_lower.includes(String(trigger["phrase"]).toLowerCase());
-  }
-  if ("command" in trigger) {
-    if (!command) {
-      return false;
-    }
-    return command.startsWith(String(trigger["command"]));
-  }
-  if ("path_prefix" in trigger) {
-    if (!open_files) {
-      return false;
-    }
-    const pref = String(trigger["path_prefix"]);
-    for (const p of open_files) {
-      if (String(p).startsWith(pref)) {
-        return true;
-      }
-    }
-    return false;
-  }
-  if ("file_pattern" in trigger) {
-    if (!open_files) {
-      return false;
-    }
-    const pat = String(trigger["file_pattern"]);
-    for (const p of open_files) {
-      if (_fnmatch(String(p), pat)) {
-        return true;
-      }
-    }
-    return false;
-  }
-  return false;
-}
-
-interface MatchedTrigger {
-  tier: string;
-  rule: JsonValue | undefined;
-  trigger: Trigger;
-}
-
-interface ActivatedRule {
-  tier: string;
-  rule: JsonValue | undefined;
-}
-
-interface MatchResult {
-  matched_triggers: MatchedTrigger[];
-  activated_rules: ActivatedRule[];
-}
-
-function _asRuleList(value: JsonValue | undefined): Rule[] {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-  return value as unknown as Rule[];
-}
-
-function _asTriggerList(value: JsonValue | undefined): Trigger[] {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-  return value as unknown as Trigger[];
-}
-
-/**
- * Return the matched-triggers + activated-rules for one prompt.
- *
- * Kernel rules are always active. tier_1 always considered. tier_2
- * only considered when `profile == 'full'`.
- */
-export function match_prompt(
-  router: Router,
-  prompt: string,
-  profile = "full",
-  open_files?: Iterable<string> | null,
-  command?: string | null,
-): MatchResult {
-  const tiers: Array<[string, Rule[]]> = [
-    ["tier_1", _asRuleList(router["tier_1"])],
-  ];
-  if (profile === "full") {
-    tiers.push(["tier_2", _asRuleList(router["tier_2"])]);
-  }
-
-  const matched_triggers: MatchedTrigger[] = [];
-  const activated_rules: ActivatedRule[] = [];
-
-  for (const [tier_name, rules] of tiers) {
-    for (const rule of rules) {
-      const rule_id = rule["id"];
-      const rule_triggers = _asTriggerList(rule["triggers"]);
-      let rule_hit = false;
-      for (const trig of rule_triggers) {
-        if (trigger_matches(trig, prompt, open_files, command)) {
-          matched_triggers.push({ tier: tier_name, rule: rule_id, trigger: trig });
-          rule_hit = true;
-        }
-      }
-      if (rule_hit) {
-        activated_rules.push({ tier: tier_name, rule: rule_id });
-      }
-    }
-  }
-
-  // Kernel rules are always active.
-  const kernel = Array.isArray(router["kernel"]) ? router["kernel"] : [];
-  for (const kid of kernel) {
-    activated_rules.push({ tier: "kernel", rule: kid });
-  }
-
-  return { matched_triggers, activated_rules };
-}
-
 // ── JSON serialization (Python-faithful) ─────────────────────────────────
 
 /**

package/src/scripts/schemas/rule.schema.json

@@ -155,6 +155,16 @@
       },
       "description": "ADR-013 trust block. Vocabulary mirrored by scripts/lint_artefact_frontmatter.py."
     },
+    "collision_ok": {
+      "type": "object",
+      "additionalProperties": {"type": "string", "minLength": 8},
+      "description": "Per-trigger collision disposition: maps a trigger VALUE (case-insensitive) shared with >=1 other rule to a one-line reason why this rule also firing on it is correct. Enforced by scripts/lint_trigger_collisions.ts."
+    },
+    "precedence": {
+      "type": "object",
+      "additionalProperties": {"type": "integer"},
+      "description": "Alternative collision disposition: maps a shared trigger VALUE to an integer ordering; a collision is clean when ALL sharers declare pairwise-distinct integers for it. Enforced by scripts/lint_trigger_collisions.ts."
+    },
     "install": {
       "type": "object",
       "additionalProperties": false,

package/src/server/schemas/settings.ts

@@ -205,6 +205,24 @@ export const settingsSchema = z.object({
             'Optional planning horizon (weeks) the agent shows in roadmap framing ("next 4 weeks"). Set 0 to omit the horizon — most teams prefer to ship without a hardcoded window.',
         ),
     }),
+    planning: z.object({
+        challenge_on_create: z.boolean().default(true).describe(
+            'Gate C — plan-confidence gate before authoring. true (default) = a plan-artifact ask (/roadmap:create, roadmap-writing, /feature:plan, /feature:roadmap) first checks the four 95%-confidence conditions from /challenge-me vision; any gap routes into the interview (or the inline degrade protocol) before authoring, and a confident pass emits exactly one marker line. false = inert, plan asks author directly. An explicit user bypass always wins for that turn and is counted.',
+        ),
+        risk_review: z.boolean().default(true).describe(
+            'Gate R1 — plan-risk review. true (default) = every ready (non-draft) plan must carry a schema-valid "## Risk Register" section (ranked risks, mitigation + anchor per row, freshness marker, exact honest-null grammar), enforced by lint_plan_risk_register at pre-push + CI. false = escape hatch, the validator skips.',
+        ),
+        completion_review: z.boolean().default(true).describe(
+            'Gate R2 — completion review at 100% roadmap completion / pre-PR. true (default) = a findings-before-fixes review by a fresh reviewer context must exist for the current diff hash (or an exact honest-null / skip declaration) before fix commits and PR creation, enforced by check_completion_review at pre-push + CI (CI authoritative; a crashed validator warns and allows). false = escape hatch, the validator skips.',
+        ),
+    })
+        // `.default({})` is load-bearing, not cosmetic: without it the SECTION is
+        // required, so any settings payload that omits `planning` fails with
+        // `ZodError: planning Required` — which contradicts this gate family's own
+        // contract ("missing key = true" for all three) and reds every server
+        // test whose fixture predates the section. With the default, an absent
+        // section materialises as the three `true` leaves the contract promises.
+        .default({}),
     quality: z.object({
         local_auto_run: z.boolean().default(false).describe(
             'Run quality tools (linters, type-checks, formatters) and the local test suite autonomously after edits. Off by default — the agent never runs quality tools proactively and does not ask; the user runs them manually (e.g. /quality-fix) and remote CI is the authoritative gate. The agent only runs a quality tool on an explicit ask, a concrete CI failure, or the new-gate carve-out. Turn on to restore autonomous pipeline runs.',