@thebattlearena/corner 0.9.1-beta.70 → 0.10.1-beta.78

package/ring/scripts/brief.mjs

@@ -0,0 +1,272 @@
+#!/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 { 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);
+
+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);
+  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);
+  // 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}\`.`,
+    ...(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>',
+      );
+    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,17 @@ 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 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 +345,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 +367,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] ?? {}) },
+      ]),
+    ),
   };
 }
 
@@ -712,7 +736,7 @@ function listDirs(dir) {
 
 /** The bout records the chronicle narrates; play-by-play.html and state.json are not records. */
 const CHRONICLED =
-  /^(decisions|rebounds|title-defense|judges-card)\.md$|^round-.*\.md$/;
+  /^(decisions|rebounds|title-defense|judges-card)\.md$|^round-.*\.md$|^(interview|verdicts|plan)\.jsonl$|^plan-tecnico\.md$/;
 
 /**
  * Is the bout's play-by-play behind its records? Only once it has a link (`playByPlayUrl`): a

package/ring/scripts/contract-endpoints.mjs

@@ -0,0 +1,163 @@
+// «Endpoints del contrato» for the chronicle's weigh-in: what the judge has to see to sign the API
+// contract, inside the one Artifact page and without a server. The plugin is zero-dependency and
+// cannot parse YAML in Node, so this side only gathers the spec files (every file a changed spec
+// root reaches through `$ref`, as the base has it and as the worktree proposes it, the same
+// proposal contract-preview.mjs serves) and writes them into the page as JSON; the page parses and
+// renders them in the browser (templates/endpoints-view.js, js-yaml from the CDN), operation by
+// operation, with the schemas expanded. Regenerating replaces the block, never duplicates it.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { loadConfig, readState } from './config.mjs';
+import { globToRegExp } from './contract.mjs';
+import { isSpecRoot, reachable, specRoots } from './contract-preview.mjs';
+
+const show = (worktree, ref, path) => {
+  try {
+    return execFileSync('git', ['-C', worktree, 'show', `${ref}:${path}`], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return null;
+  }
+};
+
+const refExists = (worktree, ref) => {
+  try {
+    execFileSync('git', ['-C', worktree, 'rev-parse', '--verify', '-q', ref], {
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The spec roots whose reachable files differ between `read.base` and `read.head`, each with those
+ * files: `{ path: { base, head } }`, a side null when the file does not exist there and `head`
+ * omitted (`same: true`) when it did not change, so an untouched fragment travels once. PURE apart
+ * from `read`.
+ */
+export function specSources(roots, read) {
+  return roots
+    .map((root) => {
+      const paths = new Set([
+        ...reachable([root], read.head),
+        ...reachable([root], read.base),
+      ]);
+      const files = Object.fromEntries(
+        [...paths].sort().map((path) => {
+          const base = read.base(path);
+          const head = read.head(path);
+          return [path, base === head ? { base, same: true } : { base, head }];
+        }),
+      );
+      const changed = Object.values(files).some((file) => !file.same);
+      return changed ? { root, files } : null;
+    })
+    .filter(Boolean);
+}
+
+/**
+ * The spec roots the PR deletes: files gone from the worktree that the config's `apiSpec` names
+ * and that were an OpenAPI root at the base. `specRoots` only sees the worktree, so without these
+ * a deleted root never reaches the judge. PURE apart from `baseHead`.
+ */
+export function deletedSpecRoots(deleted, apiSpec, baseHead) {
+  const named = (path) =>
+    apiSpec.some((entry) => {
+      const spec = entry.replace(/^\.\//, '');
+      return /[*?]/.test(spec) ? globToRegExp(spec).test(path) : spec === path;
+    });
+  return deleted.filter(
+    (path) => named(path) && isSpecRoot(path, baseHead(path) ?? ''),
+  );
+}
+
+/** The bout's changed spec roots against its stack base, read from its worktree. */
+export function collectContractSources(boutDir) {
+  const state = readState(boutDir);
+  const { worktree, base } = state;
+  if (!worktree || !existsSync(worktree))
+    throw new Error(`the worktree of #${state.pr} is gone (${worktree})`);
+  const ref = refExists(worktree, `origin/${base}`) ? `origin/${base}` : base;
+  const { config } = loadConfig(worktree);
+  const head = (path) => {
+    const file = join(worktree, path);
+    return existsSync(file) ? readFileSync(file, 'utf8') : null;
+  };
+  const atBase = (path) => show(worktree, ref, path);
+  const deleted = execFileSync(
+    'git',
+    [
+      '-C',
+      worktree,
+      'diff',
+      '--name-only',
+      '--no-renames',
+      '--diff-filter=D',
+      ref,
+    ],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+    .split('\n')
+    .filter(Boolean);
+  const roots = [
+    ...new Set([
+      ...specRoots(worktree, config),
+      ...deletedSpecRoots(deleted, config.apiSpec, (path) =>
+        atBase(path)?.slice(0, 2048),
+      ),
+    ]),
+  ];
+  return {
+    pr: state.pr,
+    base: ref,
+    roots: specSources(roots, { head, base: atBase }),
+  };
+}
+
+/** JSON safe inside a `<script>` element. PURE. */
+const LINE_SEPARATOR = String.fromCharCode(0x2028);
+const PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029);
+export const scriptJson = (value) =>
+  JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .split(LINE_SEPARATOR)
+    .join('\\u2028')
+    .split(PARAGRAPH_SEPARATOR)
+    .join('\\u2029');
+
+/**
+ * The block that goes after `<!-- ring:api-contract #<pr> -->`: the container the page renders
+ * into, a line for a reader without scripts, and the sources as JSON. PURE.
+ */
+export function endpointsBlock(sources) {
+  const roots = sources.roots.map((entry) => entry.root).join(', ');
+  const fallback = sources.roots.length
+    ? `Los endpoints del contrato se dibujan al abrir la página (${roots} contra ${sources.base}).`
+    : `Ningún spec cambia contra ${sources.base}.`;
+  return [
+    `<div class="endpoints" data-ring-spec="${sources.pr}"><p class="endpoints-wait">${fallback}</p></div>`,
+    `<script type="application/json" id="ring-spec-${sources.pr}">${scriptJson(sources)}</script>`,
+  ].join('\n');
+}
+
+/**
+ * The fingerprint of the spec files a page embeds for this bout (SHA-256 of the JSON exactly as
+ * written into the page, which the page hashes too), or null when they cannot be read.
+ */
+export function contractSourcesHash(boutDir) {
+  try {
+    return createHash('sha256')
+      .update(scriptJson(collectContractSources(boutDir)))
+      .digest('hex');
+  } catch {
+    return null;
+  }
+}