@thebattlearena/corner 0.10.0 → 0.10.1-beta.79

package/ring/scripts/brief-guard.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// Hook on PreToolUse (Agent|Task|SendMessage). In a session registered in a bout, a wrestler or a cornerman is
+// launched with a brief brief.mjs generated, never one written by hand. Zero-dependency.
+//
+// - The referee launches with `prompt: "ring-brief: <path>"`: the guard reads the file, checks its
+//   seal (generated, unedited, on today's rules, of this bout and of this role) and replaces the
+//   prompt with the file's text, with the model and effort `.claude/ring.json` sets for the role.
+// - A prompt that is the brief itself is checked the same way and only gets the model and effort.
+// - A brief that does not hold: `briefGuard: "warn"` (the default) lets the launch through and tells
+//   the referee why; `"block"` refuses it with the command that generates one; `"off"` does nothing.
+// Every decision goes to `<bout dir>/brief-guard.jsonl`. A SendMessage to a wrestler that
+// `judges-card.mjs concept` retired is warned (or blocked) the same way: the next concept goes to a
+// fresh wrestler.
+//
+// Sessions that are not the bout's, agents that are not the ring's and the rudo are left alone.
+// It never fails a tool call by accident: any error of its own ends in exit 0 with no output.
+import { appendFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { checkBrief } from './brief.mjs';
+import { isMain, loadConfig, projectDir, readState } from './config.mjs';
+import { classifyAgent } from './live-hook.mjs';
+import { findBout, sessionRegistered } from './live.mjs';
+
+export const GUARD_LOG = 'brief-guard.jsonl';
+const AGENT_TOOLS = ['Agent', 'Task'];
+const ROLE = { luchador: 'wrestler', esquinero: 'cornerman' };
+const REFERENCE = /^ring-brief:\s*(\S+)$/;
+
+/** The brief a prompt carries: the file of a `ring-brief: <path>` reference, or the prompt itself. */
+export function briefOf(
+  prompt,
+  readFile = (path) => readFileSync(path, 'utf8'),
+) {
+  const text = String(prompt ?? '').trim();
+  const path = REFERENCE.exec(text)?.[1] ?? null;
+  if (!path) return { text, path: null };
+  try {
+    return { text: readFile(path), path };
+  } catch {
+    return { text: null, path };
+  }
+}
+
+/** Why a brief does not hold for this launch, or null when it holds. PURE given `check`. */
+export function problemOf({ text, path, check, role, pr }) {
+  if (text === null) return `there is no brief at ${path}`;
+  if (!check.ok) return check.reason;
+  if (check.meta.kind !== role)
+    return `it is a ${check.meta.kind} brief, launched as the ${role}`;
+  if (String(check.meta.pr) !== String(pr))
+    return `it is the brief of #${check.meta.pr}, not of this bout (#${pr})`;
+  return null;
+}
+
+const howToFix = (role, pr) =>
+  `generate it with \`node <ring>/scripts/brief.mjs ${role} ${pr} --mode <mode> --vars <file.json>\` and launch with \`prompt: "ring-brief: <the path it prints>"\``;
+
+/**
+ * The hook's answer for one launch: the JSON to print, or null to print nothing. PURE.
+ * `brief` is briefOf's result, `problem` problemOf's, `launch` the role's {model, effort}.
+ */
+export function answer({ input, brief, problem, mode, role, pr, launch }) {
+  if (problem && mode === 'block')
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: `brief-guard: the ${role} brief does not hold (${problem}); ${howToFix(role, pr)}.`,
+      },
+    };
+  if (problem)
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: `brief-guard (warn): this ${role} was launched with a brief that does not hold (${problem}). It runs without the rules and decisions brief.mjs embeds; next time ${howToFix(role, pr)}.`,
+      },
+    };
+  const updated = {
+    ...input,
+    prompt: brief.text,
+    ...(launch?.model ? { model: launch.model } : {}),
+    ...(launch?.effort ? { effort: launch.effort } : {}),
+  };
+  const same = ['prompt', 'model', 'effort'].every(
+    (key) => updated[key] === input[key],
+  );
+  if (same) return null;
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      permissionDecisionReason: `brief-guard: ${brief.path ? `brief ${brief.path} expanded` : 'brief holds'}, ${role} on ${launch?.model ?? input.model} / ${launch?.effort ?? input.effort}`,
+      updatedInput: updated,
+    },
+  };
+}
+
+/**
+ * The answer to a SendMessage to a wrestler a concept close retired: it carries the old concept's
+ * context, and the next concept belongs to a fresh one. PURE.
+ */
+export function retiredAnswer({ to, retired, mode, pr }) {
+  if (!to || !(retired ?? []).includes(to)) return null;
+  const why = `wrestler ${to} closed its concept and was retired; the next concept goes to a fresh wrestler: brief.mjs wrestler ${pr} --mode resume --vars <file with nextConcept>`;
+  return mode === 'block'
+    ? {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: `brief-guard: ${why}.`,
+        },
+      }
+    : {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext: `brief-guard (warn): ${why}.`,
+        },
+      };
+}
+
+function guardMessage(input) {
+  const bout = findBout({ cwd: input.cwd, hint: input.tool_input?.summary });
+  if (!bout || !sessionRegistered(bout, input.session_id)) return null;
+  const state = readState(bout);
+  const { config } = loadConfig(projectDir(process.env, input.cwd), {
+    contract: false,
+    venue: state.venue ?? 'backend',
+  });
+  const mode = config.briefGuard ?? 'warn';
+  if (mode === 'off') return null;
+  return retiredAnswer({
+    to: input.tool_input?.to,
+    retired: state.retiredWrestlers,
+    mode,
+    pr: state.pr,
+  });
+}
+
+/** The guard on one hook input; returns what to print (null for nothing). */
+export function guard(input) {
+  if (input?.hook_event_name !== 'PreToolUse') return null;
+  if (input.tool_name === 'SendMessage') return guardMessage(input);
+  if (!AGENT_TOOLS.includes(input.tool_name)) return null;
+  const role = ROLE[classifyAgent(input.tool_input)];
+  if (!role) return null;
+  const bout = findBout({
+    cwd: input.cwd,
+    hint: input.tool_input?.description,
+  });
+  if (!bout || !sessionRegistered(bout, input.session_id)) return null;
+  const state = readState(bout);
+  const { config } = loadConfig(projectDir(process.env, input.cwd), {
+    contract: false,
+    venue: state.venue ?? 'backend',
+  });
+  const mode = config.briefGuard ?? 'warn';
+  if (mode === 'off') return null;
+  const brief = briefOf(input.tool_input?.prompt);
+  let check = { ok: false, reason: 'no seal', meta: null };
+  if (brief.text !== null) {
+    try {
+      check = checkBrief(brief.text);
+    } catch (error) {
+      check = { ok: false, reason: error.message, meta: null };
+    }
+  }
+  const problem = problemOf({ ...brief, check, role, pr: state.pr });
+  appendFileSync(
+    join(bout, GUARD_LOG),
+    `${JSON.stringify({ at: new Date().toISOString(), role, mode, path: brief.path, ok: !problem, problem })}\n`,
+  );
+  return answer({
+    input: input.tool_input,
+    brief,
+    problem,
+    mode,
+    role,
+    pr: state.pr,
+    launch: config.agents?.[role],
+  });
+}
+
+if (isMain(import.meta.url)) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => (raw += chunk));
+  process.stdin.on('end', () => {
+    let out = null;
+    try {
+      out = guard(JSON.parse(raw));
+    } catch {
+      out = null;
+    }
+    if (out) process.stdout.write(JSON.stringify(out));
+    process.exit(0);
+  });
+}

package/ring/scripts/brief.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+// The briefs of the ring's agents, generated from the templates with the rules embedded in full, so
+// what a wrestler or a cornerman knows does not depend on what the referee still remembers.
+// Zero-dependency; the rules are brief-build.mjs.
+//
+//   node brief.mjs wrestler  <pr> --mode start|resume|cutoff --vars <file.json>
+//   node brief.mjs cornerman <pr> --mode range|concept|batch --vars <file.json>
+//                            [--range <A>..<B>] [--files <f1,f2,…>]
+//   node brief.mjs verify <brief.md>      exit 0 while it holds, 1 when it does not
+//
+// The referee writes only its own values (the assignment, the invariants…) to the --vars JSON; the
+// script fills the rest from the bout, writes `<bout dir>/briefs/<kind>-<mode>-<n>.md`, logs it in
+// `briefs/index.jsonl` and prints the path and the Agent call. The referee passes the file as it is.
+import { execFileSync } from 'node:child_process';
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  briefStatus,
+  decisionsExcerpt,
+  fill,
+  readSeal,
+  rulesBlock,
+  seal,
+  sha256,
+  strayPaths,
+} from './brief-build.mjs';
+import {
+  boutDir,
+  isMain,
+  loadConfig,
+  projectDir,
+  readState,
+  repoSlug,
+  ringHome,
+  RING_ROOT,
+} from './config.mjs';
+import { recallSection } from './engram.mjs';
+import { conceptsSinceRelay, relayDue } from './relay.mjs';
+import { loadRules } from './rule-ids.mjs';
+
+const TEMPLATES = join(RING_ROOT, 'skills', 'referee', 'templates');
+
+/** Per kind and mode: the templates in order, and whether the rules go in (a cut-off resumes the same agent). */
+const SHAPES = {
+  wrestler: {
+    start: { templates: ['wrestler-brief.md'], rules: true },
+    resume: {
+      templates: ['wrestler-resume.md', 'wrestler-brief.md'],
+      rules: true,
+    },
+    cutoff: { templates: ['wrestler-cutoff.md'], rules: false },
+  },
+  cornerman: {
+    range: { templates: ['cornerman-range.md'], rules: true },
+    concept: { templates: ['cornerman-concept.md'], rules: true },
+    batch: { templates: ['cornerman-batch.md'], rules: true },
+  },
+};
+
+/** What the referee may leave out, and what stands in for it. */
+const OPTIONAL = {
+  claims: 'none',
+  comments: 'none',
+  referencePattern: 'none yet: no round-bell approved so far',
+  designReference: 'not applicable: this concept draws no screen',
+};
+
+const git = (dir, args) =>
+  execFileSync('git', ['-C', dir, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+
+function flags(argv) {
+  const values = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (!argv[i].startsWith('--')) {
+      rest.push(argv[i]);
+      continue;
+    }
+    values[argv[i].slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return { values, rest };
+}
+
+/** The bout of `pr` in this repo: its dir, its state and its venue's config. */
+function boutOf(pr) {
+  const dir = boutDir(repoSlug(projectDir()), pr);
+  if (!existsSync(join(dir, 'state.json')))
+    throw new Error(`no bout #${pr} in this repo (${dir})`);
+  const state = readState(dir);
+  const { config } = loadConfig(projectDir(), {
+    contract: false,
+    venue: state.venue ?? 'backend',
+  });
+  return { dir, state, config };
+}
+
+/** The rules block of a bout and its hash: what a brief embeds and what a seal is checked against. */
+function rulesOf(config) {
+  const block = rulesBlock(loadRules(config));
+  return { block, hash: sha256(block) };
+}
+
+/** What the script knows about the bout and its worktree. */
+function boutVars({ dir, state, config }, values) {
+  const { worktree } = state;
+  const head = git(worktree, ['rev-parse', 'HEAD']);
+  const range =
+    values.range ??
+    (state.lastReviewed ? `${state.lastReviewed}..${head}` : null);
+  const commits = range
+    ? git(worktree, ['log', '--reverse', '--format=- `%h` %s', range]) ||
+      '(none)'
+    : '(no range)';
+  const files = values.files
+    ? values.files
+        .split(',')
+        .map((file) => file.trim())
+        .filter(Boolean)
+    : range
+      ? git(worktree, ['diff', '--name-only', range])
+          .split('\n')
+          .filter(Boolean)
+      : [];
+  const gate = (name) => config.gates?.[name] ?? 'none configured';
+  return {
+    files,
+    vars: {
+      pr: state.pr,
+      branch: state.branch,
+      base: `origin/${state.base}`,
+      worktree,
+      boutDir: dir,
+      ring: RING_ROOT,
+      venue: config.venue,
+      range: range ?? '',
+      commits,
+      headSha: head.slice(0, 12),
+      lastSubject: git(worktree, ['log', '-1', '--format=%s']),
+      gateTypecheck: gate('typecheck'),
+      gateTest: gate('test'),
+      gateLint: gate('lint'),
+      forbidAiTrailers: String(config.forbidAiTrailers),
+      diskFloor: String(config.diskFloorGb ?? 5),
+      backupBranch: String(config.backupBranch ?? 'none').replace(
+        '{pr}',
+        state.pr,
+      ),
+      lenses: (config.lenses ?? []).join('; '),
+      leftoverPaths: files.join(', ') || 'the files of the range',
+      files: files.map((file) => `- ${file}`).join('\n'),
+    },
+  };
+}
+
+const real = (path) => (existsSync(path) ? realpathSync(path) : path);
+
+async function generate(kind, [pr, ...argv]) {
+  const { values } = flags(argv);
+  const shape = SHAPES[kind]?.[values.mode];
+  if (!pr || !shape)
+    throw new Error(
+      `usage: ${kind} <pr> --mode ${Object.keys(SHAPES[kind]).join('|')} --vars <file.json>`,
+    );
+  const bout = boutOf(pr);
+  if (kind === 'wrestler' && relayDue(bout.state, bout.config.relayEvery))
+    throw new Error(
+      `a relay is due (${conceptsSinceRelay(bout.state)} concepts since the last one): rewrite the card's «How to resume», run judges-card.mjs relay ${pr}, then brief the next wrestler`,
+    );
+  const own = values.vars ? JSON.parse(readFileSync(values.vars, 'utf8')) : {};
+  const roots = [
+    projectDir(),
+    bout.state.worktree,
+    bout.dir,
+    RING_ROOT,
+    ringHome(),
+  ].map(real);
+  const stray = strayPaths(own, roots);
+  if (stray.length)
+    throw new Error(
+      `paths outside the repo, the worktree, the bout dir and the ring (a session scratchpad is wiped on restart; what the human asked for goes to decisions.md or the technical plan):\n${stray.map(({ name, path }) => `  ${name}: ${path}`).join('\n')}`,
+    );
+  const { vars, files } = boutVars(bout, values);
+  const text = fill(
+    shape.templates
+      .map((name) => readFileSync(join(TEMPLATES, name), 'utf8'))
+      .join('\n'),
+    { ...OPTIONAL, ...vars, ...own },
+  );
+  const decisionsPath = join(bout.dir, 'decisions.md');
+  const decisions = decisionsExcerpt(
+    existsSync(decisionsPath) ? readFileSync(decisionsPath, 'utf8') : '',
+    files,
+  );
+  const rules = rulesOf(bout.config);
+  // What earlier bouts of the repo learned on these files, from Engram when it answers: context
+  // after the decisions and before the rules, never in their place (a cut-off resumes as it was).
+  const learned = shape.rules
+    ? await recallSection(bout.config, {
+        slug: repoSlug(projectDir()),
+        pr,
+        files,
+      })
+    : null;
+  // The task goes first and the rules last, as the reference: a brief that opens with the rules
+  // reads as a checklist, and a 2026-11 lab on #1212 found fewer real problems that way.
+  const body = [
+    text.trim(),
+    '## Decisions already taken (excerpt: every foul, the ones on these files, the last 20)',
+    decisions,
+    `The whole ledger: \`${decisionsPath}\`.`,
+    ...(learned ? [learned] : []),
+    ...(shape.rules ? ['---', rules.block] : []),
+  ].join('\n\n');
+  const briefs = join(bout.dir, 'briefs');
+  mkdirSync(briefs, { recursive: true });
+  const index = join(briefs, 'index.jsonl');
+  const n = existsSync(index)
+    ? readFileSync(index, 'utf8').split('\n').filter(Boolean).length + 1
+    : 1;
+  const meta = {
+    kind,
+    mode: values.mode,
+    pr,
+    n,
+    rules: shape.rules ? rules.hash : 'none',
+  };
+  const file = join(briefs, `${kind}-${values.mode}-${n}.md`);
+  writeFileSync(file, seal(body, meta));
+  appendFileSync(
+    index,
+    `${JSON.stringify({ ...meta, range: vars.range || null, at: new Date().toISOString(), vars: Object.keys(own) })}\n`,
+  );
+  const launch = bout.config.agents?.[kind] ?? {};
+  console.log(file);
+  console.log(
+    `Agent{subagent_type: "ring:${kind}", model: "${launch.model}", effort: "${launch.effort}", prompt: "ring-brief: ${file}"}`,
+  );
+}
+
+/**
+ * Whether a brief's text still holds: sealed by brief.mjs, unedited, and on the rules in force
+ * today. Returns the seal's meta too (kind, mode, pr) so a caller can check it is the right brief.
+ */
+export function checkBrief(text) {
+  const sealed = readSeal(text);
+  const rulesNow = (meta) =>
+    meta.rules === 'none' ? 'none' : rulesOf(boutOf(meta.pr).config).hash;
+  return {
+    ...briefStatus(text, sealed ? rulesNow(sealed.meta) : null),
+    meta: sealed?.meta ?? null,
+  };
+}
+
+function verify([path]) {
+  if (!path) throw new Error('usage: verify <brief.md>');
+  const status = checkBrief(readFileSync(path, 'utf8'));
+  console.log(
+    status.ok ? 'brief holds' : `brief does not hold: ${status.reason}`,
+  );
+  return status.ok ? 0 : 1;
+}
+
+if (isMain(import.meta.url)) {
+  const [command, ...rest] = process.argv.slice(2);
+  try {
+    if (command === 'verify') process.exit(verify(rest));
+    if (!SHAPES[command])
+      throw new Error(
+        'usage: brief.mjs wrestler|cornerman <pr> --mode … | verify <brief.md>',
+      );
+    await generate(command, rest);
+  } catch (error) {
+    console.error(`brief: ${error.message}`);
+    process.exit(1);
+  }
+}

package/ring/scripts/compact-hook.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Hook on SessionStart (matcher `compact`): after a compaction the referee's context loses what it
+// knew of the bout. This puts back, in under 10,000 characters (Claude Code's cap for hook output),
+// what must not be lost: which bout it referees and where its card and ledger live, the
+// architecture checklist, the bout's fouls (what must not happen again), the card's latest «how to
+// resume», and the rule that every wrestler and cornerman is launched with a brief from brief.mjs.
+// Zero-dependency. Only a session registered in a bout gets it; any error ends in exit 0, silent.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  isMain,
+  loadConfig,
+  projectDir,
+  readState,
+  RING_ROOT,
+} from './config.mjs';
+import { findBout, sessionRegistered } from './live.mjs';
+import { checklistLines, loadRules } from './rule-ids.mjs';
+
+/** Claude Code's cap for SessionStart output, with room to spare. */
+export const BUDGET = 9500;
+const RESUME = /^##\s+(How to resume|Cómo reanudar)\b/i;
+
+/** The card's first «how to resume» section (the newest is on top), cut to `max` characters. PURE. */
+export function resumeSection(card, max = 2500) {
+  const lines = String(card ?? '').split('\n');
+  const start = lines.findIndex((line) => RESUME.test(line));
+  if (start < 0) return '';
+  const end = lines.findIndex((line, i) => i > start && /^##\s/.test(line));
+  const text = lines
+    .slice(start + 1, end < 0 ? undefined : end)
+    .join('\n')
+    .trim();
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/** The ledger's fouls, newest last, cut to `max` characters from the oldest. PURE. */
+export function foulLines(decisions, max = 3000) {
+  const fouls = String(decisions ?? '')
+    .split('\n')
+    .filter((line) => /\bFOUL\b/.test(line));
+  const kept = [];
+  let size = 0;
+  for (const line of fouls.reverse()) {
+    if (size + line.length + 1 > max) break;
+    kept.unshift(line);
+    size += line.length + 1;
+  }
+  const dropped = fouls.length - kept.length;
+  return [
+    ...(dropped ? [`(${dropped} older fouls in decisions.md)`] : []),
+    ...kept,
+  ].join('\n');
+}
+
+/** The text a compacted referee gets back. PURE. */
+export function compactContext({ pr, dir, checklist, fouls, resume }) {
+  const text = [
+    `# Ring: you referee bout #${pr} (context restored after a compaction)`,
+    '',
+    `Reread before acting: the judges card \`${join(dir, 'judges-card.md')}\` and the ledger \`${join(dir, 'decisions.md')}\`. Every wrestler and cornerman is launched with a brief from \`node ${RING_ROOT}/scripts/brief.mjs\` and \`prompt: "ring-brief: <path>"\`; never a brief written by hand. Every finding cites its rule id (or X0).`,
+    '',
+    '## Architecture checklist (the full rules go in every brief)',
+    checklist || '(none for this venue)',
+    '',
+    '## Fouls of this bout (never again)',
+    fouls || '(none)',
+    ...(resume ? ['', '## How to resume (from the card)', resume] : []),
+  ].join('\n');
+  return text.length > BUDGET ? `${text.slice(0, BUDGET)}…` : text;
+}
+
+const read = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : '');
+
+/** The hook on one input: the text to print, or null. */
+export function restore(input) {
+  if (input?.hook_event_name !== 'SessionStart') return null;
+  if (input.source && input.source !== 'compact') return null;
+  const dir = findBout({ cwd: input.cwd });
+  if (!dir || !sessionRegistered(dir, input.session_id)) return null;
+  const state = readState(dir);
+  const { config } = loadConfig(projectDir(process.env, input.cwd), {
+    contract: false,
+    venue: state.venue ?? 'backend',
+  });
+  return compactContext({
+    pr: state.pr,
+    dir,
+    checklist: checklistLines(loadRules(config).entries).join('\n'),
+    fouls: foulLines(read(join(dir, 'decisions.md'))),
+    resume: resumeSection(read(join(dir, 'judges-card.md'))),
+  });
+}
+
+if (isMain(import.meta.url)) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => (raw += chunk));
+  process.stdin.on('end', () => {
+    let out = null;
+    try {
+      out = restore(JSON.parse(raw));
+    } catch {
+      out = null;
+    }
+    if (out) process.stdout.write(out);
+    process.exit(0);
+  });
+}

package/ring/scripts/config.mjs

@@ -106,6 +106,9 @@ export const DEFAULT_HEAVY_COMMANDS = [
   'make test',
 ];
 
+/** What brief-guard does with a launch whose brief brief.mjs did not generate. */
+export const BRIEF_GUARD_MODES = ['warn', 'block', 'off'];
+
 export const DEFAULTS = Object.freeze({
   gates: { typecheck: null, test: null, lint: null },
   validateCommand: null,
@@ -136,6 +139,37 @@ export const DEFAULTS = Object.freeze({
     previewTimeoutMin: 20,
     staleDays: 7,
   }),
+  // brief-guard on every Agent launch of a wrestler or cornerman in a bout: 'warn' lets a brief
+  // that brief.mjs did not generate through and says so; 'block' refuses it; 'off' does nothing.
+  briefGuard: 'warn',
+  // The architecture gate (arch-gate.mjs): the repo's layers, each { name, paths (globs),
+  // mayImport (layer names), forbid (package regexes) }. Empty: only the repo's dependency-cruiser.
+  layers: [],
+  // Files the layer check leaves out (null: tests, `*.spec.*`, `*.test.*`, `__tests__/`, `test/`).
+  layersIgnore: null,
+  // Globs where every NEW code file must fall in a layer (arch-gate flags the ones that do not).
+  layersRequired: [],
+  // Findings that cite one of these rules are never sent to a ticket or discarded by the referee
+  // alone: `findings.mjs ticket|discard` asks for --judge "<what the human said>". A cleanup bout
+  // adds the architecture rules (["P14", "R6", "R11", "R12", "R19", "R22"]).
+  findingsNeedJudge: ['P14'],
+  // Concepts after which the referee relays (rewrites the card's «How to resume» and runs
+  // judges-card.mjs relay) before brief.mjs briefs the next wrestler. null: never.
+  relayEvery: 4,
+  // Engram (github.com/Gentleman-Programming/engram), the memory of what earlier bouts learned:
+  // fouls, the judge's verdicts, accepted precedents, X0 findings and each bout's status. Never the
+  // rules. The scripts sync and read it when something answers at this URL (null: off). The
+  // project defaults to the repo name, as Engram names it.
+  engramUrl: 'http://127.0.0.1:7437',
+  engramProject: null,
+  // The model and effort of each ring agent, passed on every launch. Who writes runs on the
+  // cheaper model at high effort; who reviews keeps the strongest one (what slipped in bout #1223
+  // slipped in review). A host overrides a role in `.claude/ring.json` (`agents.wrestler.model`).
+  agents: Object.freeze({
+    wrestler: Object.freeze({ model: 'sonnet', effort: 'high' }),
+    rudo: Object.freeze({ model: 'sonnet', effort: 'high' }),
+    cornerman: Object.freeze({ model: 'opus', effort: 'high' }),
+  }),
 });
 
 const GATES = ['typecheck', 'test', 'lint'];
@@ -331,6 +365,10 @@ export function mergeConfig(detected, host) {
     throw new Error(
       `.claude/ring.json: "delegation" must be one of ${DELEGATION_LEVELS.join(', ')}, not ${JSON.stringify(own.delegation)}`,
     );
+  if ('briefGuard' in own && !BRIEF_GUARD_MODES.includes(own.briefGuard))
+    throw new Error(
+      `.claude/ring.json: "briefGuard" must be one of ${BRIEF_GUARD_MODES.join(', ')}, not ${JSON.stringify(own.briefGuard)}`,
+    );
   validateVenues(own.venues, VENUE_NAMES);
   return {
     ...DEFAULTS,
@@ -349,6 +387,12 @@ export function mergeConfig(detected, host) {
         ? null
         : { ...DEFAULTS.findingsGate, ...(own.findingsGate ?? {}) },
     sparring: { ...DEFAULTS.sparring, ...(own.sparring ?? {}) },
+    agents: Object.fromEntries(
+      Object.entries(DEFAULTS.agents).map(([role, launch]) => [
+        role,
+        { ...launch, ...(own.agents?.[role] ?? {}) },
+      ]),
+    ),
   };
 }