@thebattlearena/corner 0.10.1-beta.82 → 0.10.1-beta.84

package/ring/scripts/lanes.mjs

@@ -0,0 +1,146 @@
+// Several blocks at once in ONE worktree: each block «en curso» holds the files it declared
+// (`--files "<globs>"` at estimate or start), and only that block's wrestler commits them. The
+// referee grants them all when the block starts (the start is refused when another running block
+// holds one of them, or when `parallelBlocks` are already running); a wrestler that needs a file of
+// another block stops and asks the referee, never the other wrestler. mask-guard refuses a commit
+// that stages a file another running block holds. Files the host regenerates (`generatedPaths`,
+// e.g. docs a pre-commit writes) are nobody's: the referee regenerates them when the wave closes.
+// Closing a concept with `--block <n>` retires only that block's wrestlers. Zero-dependency.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { globToRegExp } from './contract.mjs';
+import { wrestlerLines } from './relay.mjs';
+import { parsePlan, parsePlanLog, PLAN, PLAN_LOG } from './tech-plan.mjs';
+
+/** `"a/**, b/*.ts"` as globs. PURE. */
+export const parseGlobs = (text) =>
+  String(text ?? '')
+    .split(',')
+    .map((glob) => glob.trim())
+    .filter(Boolean);
+
+const matcher = (globs) => {
+  const patterns = (globs ?? []).map((glob) => globToRegExp(glob));
+  return (file) => patterns.some((pattern) => pattern.test(file));
+};
+
+/** The blocks «en curso» with the files each holds (its last `files` in plan.jsonl). PURE. */
+export function runningLeases(plan, log) {
+  return parsePlan(plan)
+    .groups.flatMap((group) => group.items)
+    .filter((item) => item.state === 'en curso')
+    .map((item) => ({
+      n: item.n,
+      title: item.title,
+      files:
+        log.filter((line) => line.n === item.n && line.files).at(-1)?.files ??
+        [],
+    }));
+}
+
+/**
+ * Why block `n` may not start next to the blocks already running, or null. With `parallel` 1 (the
+ * default) nothing changes. Otherwise it needs its files, a free slot, and no tracked file that a
+ * running block holds too (generated files are nobody's). PURE.
+ */
+export function startLaneRefusal({
+  n,
+  files,
+  running,
+  parallel,
+  tracked,
+  generated,
+  waiting = [],
+}) {
+  const others = running.filter((lease) => lease.n !== n);
+  if (!parallel || parallel <= 1 || !others.length) return null;
+  // The human's queue first: with a block waiting on review, one block runs at a time.
+  if (waiting.length)
+    return `${waiting.map((item) => `B${item.n}`).join(', ')} wait${waiting.length === 1 ? 's' : ''} on the human's review and ${others.map((lease) => `B${lease.n}`).join(', ')} is running: a second block starts only while nothing waits on review. Start B${n} when one of them clears`;
+  if (others.length >= parallel)
+    return `${others.length} blocks are already running (parallelBlocks ${parallel}): ${others.map((lease) => `B${lease.n}`).join(', ')}. Start B${n} when one closes`;
+  const undeclared = others.filter((lease) => !lease.files.length);
+  if (undeclared.length)
+    return `${undeclared.map((lease) => `B${lease.n}`).join(', ')} runs without declared files, so nothing proves B${n} would not touch them: declare them first (judges-card.mjs plan <pr> estimate ${undeclared[0].n} --files "<globs>")`;
+  if (!files?.length)
+    return `B${n} starts next to ${others.map((lease) => `B${lease.n}`).join(', ')}: declare the files it will touch with --files "<glob>,<glob>" so no two wrestlers edit the same file`;
+  const isGenerated = matcher(generated);
+  const mine = matcher(files);
+  const clashes = others.flatMap((lease) => {
+    const theirs = matcher(lease.files);
+    return tracked
+      .filter((file) => !isGenerated(file) && mine(file) && theirs(file))
+      .map((file) => `${file} (B${lease.n})`);
+  });
+  if (clashes.length)
+    return `B${n} would share files with a running block: ${clashes.slice(0, 8).join(', ')}${clashes.length > 8 ? ', …' : ''}. Narrow its --files, or start another block`;
+  return null;
+}
+
+/**
+ * Why a commit may not go in, or null: a staged file held by a running block other than the one
+ * whose wrestler commits. Unknown committer: a commit may not mix files of two blocks. PURE.
+ */
+export function commitLeaseRefusal({ staged, running, block, generated }) {
+  if (running.length < 2) return null;
+  const isGenerated = matcher(generated);
+  const owners = staged
+    .filter((file) => !isGenerated(file))
+    .flatMap((file) =>
+      running
+        .filter((lease) => matcher(lease.files)(file))
+        .map((lease) => ({ file, n: lease.n })),
+    );
+  const foreign = block
+    ? owners.filter((owner) => owner.n !== block)
+    : owners.filter((owner) => owner.n !== owners[0]?.n);
+  if (!foreign.length) return null;
+  return `this commit stages files another running block holds: ${foreign.map((owner) => `${owner.file} (B${owner.n})`).join(', ')}. Unstage them (git restore --staged <path>); if your block needs one, stop and ask the referee, who moves it between blocks. Never edit or commit another wrestler's files.`;
+}
+
+const jsonl = (path) =>
+  existsSync(path) ? parsePlanLog(readFileSync(path, 'utf8')) : [];
+
+/**
+ * The block each wrestler works on: its agent id (live.jsonl) → the Agent launch (tool_use_id) →
+ * the brief brief-guard saw → that brief's `block` in briefs/index.jsonl. PURE apart from reads.
+ */
+export function wrestlerBlocks(dir) {
+  const briefs = new Map(
+    jsonl(join(dir, 'briefs', 'index.jsonl'))
+      .filter((brief) => brief.kind === 'wrestler' && brief.block)
+      .map((brief) => [
+        `wrestler-${brief.mode}-${brief.n}.md`,
+        Number(brief.block),
+      ]),
+  );
+  const launches = new Map(
+    jsonl(join(dir, 'brief-guard.jsonl'))
+      .filter((entry) => entry.toolUseId && entry.path)
+      .map((entry) => [
+        entry.toolUseId,
+        briefs.get(entry.path.split('/').at(-1)),
+      ]),
+  );
+  const blocks = new Map();
+  for (const line of wrestlerLines(dir)) {
+    try {
+      const event = JSON.parse(line);
+      const agent = /^agent (\S+)$/.exec(event.note ?? '')?.[1];
+      const block = launches.get(event.id);
+      if (event.actor === 'luchador' && agent && block)
+        blocks.set(agent, block);
+    } catch {
+      // A torn line is skipped.
+    }
+  }
+  return blocks;
+}
+
+/** The running blocks of a bout dir, read now. */
+export function boutLeases(dir) {
+  const read = (name) =>
+    existsSync(join(dir, name)) ? readFileSync(join(dir, name), 'utf8') : '';
+  return runningLeases(read(PLAN), parsePlanLog(read(PLAN_LOG)));
+}

package/ring/scripts/live.mjs

@@ -255,9 +255,17 @@ export function appendLive(file, event, keep = KEEP) {
 export function record(dir, raw) {
   if (!dir) return false;
   const { event } = validateEvent(raw);
-  return event ? appendLive(join(dir, LIVE_LOG), event) : false;
+  if (!event) return false;
+  // live.jsonl is trimmed to its last lines; who each wrestler is must outlive the trim (a concept
+  // close retires them by these ids, and lanes map them to their block).
+  if (event.actor === 'luchador' && /^agent \S+$/.test(event.note ?? ''))
+    appendFileSync(join(dir, WRESTLERS), `${JSON.stringify(event)}\n`);
+  return appendLive(join(dir, LIVE_LOG), event);
 }
 
+/** The launches of the bout's wrestlers (agent ids), kept whole. */
+export const WRESTLERS = 'wrestlers.jsonl';
+
 const within = (dir, path) => {
   const inside = relative(resolve(dir), resolve(path));
   return !inside.startsWith('..') && !isAbsolute(inside);

package/ring/scripts/lookout.mjs

@@ -9,7 +9,8 @@
 //                                                             formatted; see format-gate.mjs)
 //   node lookout.mjs backup <boutDir>                         push the worktree HEAD to the backup branch
 //
-// `watch` polls the wrestler's worktree and EXITS as soon as its HEAD differs from the last
+// `watch` polls the wrestler's worktree and EXITS as soon as the human signs a verdict in PR Review
+// Lab that the bout has not applied, or as soon as its HEAD differs from the last
 // reviewed commit in state.json, printing the new commits. Launched with run_in_background, its
 // exit wakes the referee; nothing expires and nothing has to be re-armed by hand. A pidfile makes a
 // new watcher kill the previous one, and both ends of the comparison are FULL hashes: comparing an
@@ -19,13 +20,16 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import {
+  boutDir,
   DEFAULTS,
   isMain,
   loadConfig,
   projectDir,
   readState,
+  repoSlug,
   writeState,
 } from './config.mjs';
+import { reviewInputs } from './review-blocks.mjs';
 import { counts, readLedger, reviewDeclared } from './findings.mjs';
 import { acceptUnverified, boutFormatGate } from './format-gate.mjs';
 
@@ -187,6 +191,14 @@ function backupQuietly(state, template) {
   }
 }
 
+/** The verdicts PR Review Lab wrote that the bout has not applied yet. */
+export function unhandledVerdicts(dir, state) {
+  const handled = new Set(state.handledVerdicts ?? []);
+  return reviewInputs(dir).verdicts.filter(
+    (verdict) => !handled.has(verdict.at),
+  );
+}
+
 const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
 
 async function watch(dir, intervalSeconds) {
@@ -203,6 +215,12 @@ async function watch(dir, intervalSeconds) {
     const state = readState(dir);
     if (state.active !== true)
       return console.log('lookout: the bout is closed.');
+    // The human's verdict wakes the referee too: until the next brief applies it, the bout waits.
+    const fresh = unhandledVerdicts(dir, state);
+    if (fresh.length)
+      return console.log(
+        `lookout: the human signed ${fresh.map((verdict) => `${verdict.verdict} ${verdict.blocks.join('+')} (Tape ${verdict.tape})`).join(' · ')} in PR Review Lab: run judges-card.mjs summary ${state.pr} (or brief the next wrestler) to apply it, then go on.`,
+      );
     const head = git(state.worktree, ['rev-parse', 'HEAD']);
     if (compareHeads(state.lastReviewed, head).changed) {
       const settings = hostSettings();
@@ -332,7 +350,11 @@ function approve(dir, ref, { formatUnverified = null } = {}) {
 }
 
 if (isMain(import.meta.url)) {
-  const [command, dir, ...rest] = process.argv.slice(2);
+  const [command, target, ...rest] = process.argv.slice(2);
+  // A bout dir, or the PR number every other ring script takes.
+  const dir = /^\d+$/.test(target ?? '')
+    ? boutDir(repoSlug(projectDir()), target)
+    : target;
   const intervalIndex = rest.indexOf('--interval');
   const interval = intervalIndex === -1 ? 60 : Number(rest[intervalIndex + 1]);
   const fail = (error) => {

package/ring/scripts/mask-guard.mjs

@@ -12,6 +12,7 @@
 // it blocks too: a guard that cannot evaluate must not let the command through.
 import { boutArchGate } from './arch-gate.mjs';
 import { boutFormatGate } from './format-gate.mjs';
+import { boutLeases, commitLeaseRefusal, wrestlerBlocks } from './lanes.mjs';
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -803,6 +804,11 @@ const gitRules = [
     reason: (git, ctx) =>
       `This commit changes the API contract, database models or native surface (${ctx.unapprovedContractFiles(git).join(', ')}) without the judge's approval of exactly this content. Serve the preview (contract-preview.mjs), get the judge's yes, record it with judges-card.mjs approve-contract <pr> --files <paths>, then commit. Any edit after approval needs a new one.`,
   },
+  {
+    // Blocks running side by side in one worktree: a wrestler commits only its block's files.
+    when: (git, ctx) => git.sub === 'commit' && ctx.leaseRefusal(git) !== null,
+    reason: (git, ctx) => ctx.leaseRefusal(git),
+  },
   {
     // An amend adds no commit; everything else waits once the unreviewed range hits the cap.
     when: (git, ctx) =>
@@ -1067,7 +1073,7 @@ const ghRules = [
       gh.action === 'create' &&
       !hasFlag(gh.args, '--draft', '-d'),
     reason: () =>
-      'Every PR ring opens is a draft; only the human marks it ready. Add --draft to gh pr create.',
+      'Every PR opened while a bout is active is a draft, even one the human asked for outside the bout: add --draft to gh pr create, and tell the human the link; they mark it ready (gh pr ready <n>, or «Ready for review» on GitHub).',
   },
   {
     when: (gh) =>
@@ -1290,6 +1296,10 @@ function judgeSegment(segment, words, cwd, ctx) {
       hasAiTrailer(commitMessage(commit, segment, context)),
     commitBoutIds: (commit) => boutIds(commitMessage(commit, segment, context)),
     reviewDebt: (commit) => ctx.reviewDebtAt(context.path(commit.dir)),
+    leaseRefusal: (commit) =>
+      ctx.leaseRefusalAt(context.path(commit.dir), () =>
+        ctx.committedFiles(commit, commitsWorkingTree(commit)),
+      ),
     pushBeyondApproval: (push, refspecs) =>
       ctx.pushBeyondApprovalAt(context.path(push.dir), refspecs),
     findingsBeforePush: (push, refspecs) =>
@@ -1410,7 +1420,7 @@ function insideGitRepo(dir) {
  * The real context of one hook invocation. The host config is loaded lazily, only when a rule
  * reads it: a broken .claude/ring.json must not cost every command a parse, nor fail it.
  */
-function realContext(cwd) {
+function realContext(cwd, agentId = null) {
   const bouts = new Map();
   const slugs = new Map();
   let config = null;
@@ -1506,6 +1516,18 @@ function realContext(cwd) {
       contract ??= loadConfig(projectDir(process.env, cwd)).config;
       return contract;
     },
+    // A commit staging files another running block holds (parallelBlocks > 1), or null.
+    leaseRefusalAt: (dir, staged) => {
+      if ((loaded().parallelBlocks ?? 1) <= 1) return null;
+      const bout = boutOfDir(dir);
+      if (!bout) return null;
+      return commitLeaseRefusal({
+        staged: staged(),
+        running: boutLeases(bout.dir),
+        block: agentId ? (wrestlerBlocks(bout.dir).get(agentId) ?? null) : null,
+        generated: loaded().generatedPaths,
+      });
+    },
     // The unreviewed range of the bout whose worktree holds `dir`, when it is at or over the cap.
     reviewDebtAt: (dir) => {
       const bout = boutOfDir(dir);
@@ -1771,7 +1793,10 @@ function block(reason) {
 function evaluate(payload) {
   if (payload?.tool_name !== 'Bash') return;
   const command = payload?.tool_input?.command ?? '';
-  const verdict = decide(command, realContext(payload?.cwd || process.cwd()));
+  const verdict = decide(
+    command,
+    realContext(payload?.cwd || process.cwd(), payload?.agent_id ?? null),
+  );
   if (verdict.block) return block(verdict.reason);
   if (verdict.warnings.length)
     process.stdout.write(

package/ring/scripts/one-at-a-time.mjs

@@ -211,9 +211,20 @@ function reportInvisible(feed, command) {
   if (!feed.dir || feed.visible) return () => undefined;
   const id = `invisible:${process.pid}`;
   let shown = false;
-  console.error(
-    `one-at-a-time: no declared monitor shows "${commandLabel(command)}" on the Scorecard; a long run needs one: rerun with --monitor <id>, or declare a monitor whose match.command matches it`,
-  );
+  // Once per bout every few hours, not on every tsc or jest.
+  const marker = join(feed.dir, '.no-monitor-warned');
+  const fresh = (() => {
+    try {
+      return Date.now() - statSync(marker).mtimeMs < 6 * 3600_000;
+    } catch {
+      return false;
+    }
+  })();
+  if (!fresh) writeFileSync(marker, '');
+  if (!fresh)
+    console.error(
+      `one-at-a-time: no declared monitor shows "${commandLabel(command)}" on the Scorecard; a long run needs one: rerun with --monitor <id>, or declare a monitor whose match.command matches it`,
+    );
   const timer = setTimeout(() => {
     shown = true;
     record(feed.dir, {

package/ring/scripts/relay.mjs

@@ -11,7 +11,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { LIVE_LOG } from './live.mjs';
+import { LIVE_LOG, WRESTLERS } from './live.mjs';
 
 export const PROPOSALS = 'For the rulebook / precedents';
 const DECIDED = /→\s*(accepted|rejected)\b/;
@@ -115,6 +115,18 @@ export function withConceptClosed(state, { name, range, at, wrestlers }) {
   };
 }
 
+/** The wrestlers' launch lines (wrestlers.jsonl, never trimmed) and the live lines after them. */
+export function wrestlerLines(dir) {
+  try {
+    return [
+      ...readFileSync(join(dir, WRESTLERS), 'utf8').split('\n').filter(Boolean),
+      ...liveLines(dir),
+    ];
+  } catch {
+    return liveLines(dir);
+  }
+}
+
 /** The live lines of a bout, or none. */
 export function liveLines(dir) {
   try {

package/ring/scripts/review-blocks.mjs

@@ -10,6 +10,7 @@ import { appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { readState, writeState } from './config.mjs';
+import { globToRegExp } from './contract.mjs';
 import { parsePlan, parsePlanLog, PLAN, PLAN_LOG } from './tech-plan.mjs';
 
 export const VERDICTS = 'review-verdicts.jsonl';
@@ -25,6 +26,7 @@ const FACTS = [
   'startSha',
   'startedAt',
   'endedAt',
+  'files',
 ];
 
 /** The facts of point `n` so far: each field from the last plan.jsonl line that has it. PURE. */
@@ -86,8 +88,9 @@ export function startRefusal(facts, to, n) {
 }
 
 /** Checks an estimate: priority 1–4 and whole minutes. PURE. */
-export function estimateFacts({ priority, minutes }) {
+export function estimateFacts({ priority, minutes, files }) {
   const facts = {};
+  if (files?.length) facts.files = files;
   if (priority != null) {
     if (![1, 2, 3, 4].includes(Number(priority)))
       throw new Error('--priority is 1 (first) to 4 (last)');
@@ -168,6 +171,20 @@ export function verdictEffects(verdict) {
 
 const read = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : '');
 
+/**
+ * The human's «no pasa» still open as rebounds: until the blocks wait on the judge again, every
+ * resume (summary, compaction) shows them first, with their Tape. PURE apart from the read.
+ */
+export function openHumanReturns(dir) {
+  return read(join(dir, 'rebounds.md'))
+    .split('\n')
+    .filter((line) => /^- \[ \] .*Revisión humana/.test(line));
+}
+
+/** What the referee does with a returned cut: read its Tape before writing the rebound. */
+export const TAPE_HINT =
+  'Read each Tape before writing the rebound (Battle Arena connector: mcp__claude_ai_Battle_Arena__qa_session_overview, then qa_session_timeline on the chapter) and cite its minutes in the rebound. If those tools are not in this session, say so to the human in one line and connect them (/mcp, the claude.ai Battle Arena connector); never design the rebound from the feedback line alone.';
+
 /** The author of a block: the git user of the worktree that writes it. */
 export function authorEmail(worktree) {
   try {
@@ -235,13 +252,43 @@ export function applyVerdicts(dir, state, setState) {
  * verdicts, keeps `pauseEvery` in state.json for PR Review Lab, and says whether the human's review
  * is due. `setState(n, state, ref)` moves a block of the plan.
  */
-export function reviewTurn(dir, every, setState) {
+export function reviewTurn(dir, every, setState, parallel = null) {
   const before = readState(dir);
   const { state, applied } = applyVerdicts(dir, before, setState);
-  const next = { ...state, pauseEvery: every ?? null };
-  if (applied.length || before.pauseEvery !== next.pauseEvery)
+  // PR Review Lab reads both from state.json: when the bell rings and how many blocks may run.
+  const next = { ...state, pauseEvery: every ?? null, parallel };
+  if (
+    applied.length ||
+    before.pauseEvery !== next.pauseEvery ||
+    before.parallel !== next.parallel
+  )
     writeState(dir, next);
   const { plan, log, verdicts } = reviewInputs(dir);
   const waiting = blocksAwaitingReview(plan, log, verdicts);
   return { applied, waiting, due: reviewDue(waiting, every) };
 }
+
+/**
+ * Why a wrestler may not work ahead while the human reviews a cut, or null. Ahead means one block
+ * at a time (nothing else «en curso») on files declared up front that the cut under review does
+ * not touch, so the human's verdict on the cut never lands on code that moved. PURE.
+ */
+export function lookaheadRefusal({ globs, waitingFiles, running }) {
+  if (!globs.length)
+    return 'a block ahead of the review declares its files: --lookahead "<glob>,<glob>"';
+  if (running.length)
+    return `only one block works ahead of the review: B${running[0].n} «${running[0].title}» is already «en curso» (if that is the block of this brief, pass --block ${running[0].n})`;
+  const matchers = globs.map((glob) => globToRegExp(glob));
+  const overlap = waitingFiles.filter((file) =>
+    matchers.some((matcher) => matcher.test(file)),
+  );
+  if (overlap.length)
+    return `the block ahead would touch files of the cut under review: ${overlap.join(', ')}. Pick a block that does not, or wait for the verdict`;
+  return null;
+}
+
+/** The blocks «en curso» right now. PURE. */
+export const runningBlocks = (plan) =>
+  parsePlan(plan)
+    .groups.flatMap((group) => group.items)
+    .filter((item) => item.state === 'en curso');

package/ring/scripts/tech-plan-log.mjs

@@ -12,11 +12,15 @@ import { join } from 'node:path';
 
 import { readState } from './config.mjs';
 import { scriptJson } from './contract-endpoints.mjs';
+import { runningLeases, startLaneRefusal } from './lanes.mjs';
 import {
   authorEmail,
   blockFacts,
   factsForState,
+  blocksAwaitingReview,
+  parseVerdicts,
   startRefusal,
+  VERDICTS,
 } from './review-blocks.mjs';
 import {
   parsePlan,
@@ -39,7 +43,7 @@ export function setPlanState(
   state,
   ref = null,
   at = new Date().toISOString(),
-  { range = null, estimate = null, requireEstimate = false } = {},
+  { range = null, estimate = null, requireEstimate = false, lanes = null } = {},
 ) {
   const file = join(dir, PLAN);
   const markdown = read(file);
@@ -68,6 +72,26 @@ export function setPlanState(
       ? startRefusal(facts, next, item.n)
       : null;
   if (refusal) throw new Error(refusal);
+  const laneRefusal =
+    lanes && next === 'en curso' && next !== item.state
+      ? startLaneRefusal({
+          n: item.n,
+          files: facts.files,
+          running: runningLeases(
+            markdown,
+            parsePlanLog(read(join(dir, PLAN_LOG))),
+          ),
+          parallel: lanes.parallel,
+          tracked: trackedFiles(worktree),
+          generated: lanes.generated,
+          waiting: blocksAwaitingReview(
+            markdown,
+            parsePlanLog(read(join(dir, PLAN_LOG))),
+            parseVerdicts(read(join(dir, VERDICTS)) ?? ''),
+          ),
+        })
+      : null;
+  if (laneRefusal) throw new Error(laneRefusal);
   writeFileSync(file, withPlanState(markdown, item, next));
   appendFileSync(
     join(dir, PLAN_LOG),
@@ -76,6 +100,21 @@ export function setPlanState(
   return { ...item, from: item.state, to: next, facts };
 }
 
+/** The files git tracks in the worktree (none when it is gone). */
+function trackedFiles(worktree) {
+  try {
+    return execFileSync('git', ['-C', worktree, 'ls-files'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    })
+      .split('\n')
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 /** The worktree's head, or null when it is gone. */
 function worktreeHead(worktree) {
   try {

package/ring/skills/referee/SKILL.md

@@ -199,7 +199,8 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    - each new range: `brief.mjs cornerman <pr> --mode range --vars <file>` (≤15 lines; the range
      is `lastReviewed..HEAD` unless you pass `--range`; your value: `claims`);
    - when the wrestler closes a concept: `--mode concept` (your values: `invariants`, numbered,
-     and `claims`; `designReference` at a UI venue), over ranges already reviewed one by one. It
+     always including «no question is asked again downstream for the same reason» (PR31), and
+     `claims`; `designReference` at a UI venue), over ranges already reviewed one by one. It
      also reads the concept as one piece through the venue's lenses: what no single range shows;
    - a design review: `--mode batch --files <f1,f2,…>`.
    **A concept ends its wrestler.** When the concept review approves it, run
@@ -219,7 +220,26 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    `humanReviewEvery` blocks waiting, brief.mjs stops: the human reviews that cut in PR Review Lab
    (bout mode) and signs a verdict with a Tape. The next brief applies it: a pass closes the
    blocks, a fail comes back as a rebound the next wrestler fixes first. Do not work around the
-   pause.
+   pause. **Work ahead while the human reviews:** one wrestler may take ONE more block whose files
+   the cut does not touch: `brief.mjs wrestler <pr> --mode resume --vars <file> --lookahead
+   "<glob>,<glob>"` (the files that block will touch). brief.mjs refuses it when those globs match a
+   file of the cut, or when another block is already «en curso». Its brief says which files it may
+   touch; a rebound from the verdict still goes first.
+   **Blocks side by side (`parallelBlocks`, 2 by default)**: when a block is running and NOTHING
+   waits on the human's review, start one more INDEPENDENT block next to it, in the SAME worktree,
+   one wrestler each (a long block should not leave the human's queue empty). While any block waits
+   on review, one block at a time: the script refuses the second start. Pick blocks that neither depend on each
+   other nor share a contract (props, a hook's return, i18n keys, a helper): a file lock does not
+   see that, you do. Start each with its files: `judges-card.mjs plan <pr> <n> "en curso"
+   --minutes <m> --priority <p> --files "<glob>,<glob>"`; the script refuses a start whose files a
+   running block holds. Brief each with `--block <n>` (its brief lists its files and the other
+   wrestler's). mask-guard refuses a commit that stages another block's file; a wrestler that needs
+   one stops and asks you: decide who keeps it (narrow one block's `--files` with `plan <pr>
+   estimate <n> --files …`). Close each with `judges-card.mjs concept <pr> "<name>" --range <A>..<B>
+   --block <n>`: only that block's wrestler retires. The review cap counts both wrestlers' commits:
+   review the shared range as usual. **When the wave closes** (both blocks wait on the judge),
+   regenerate the `generatedPaths` files once and commit them yourself, then run the typecheck and
+   the tests of both blocks on the shared tip before the human's cut.
    If the wrestler claimed something ("does not change counter X"), hand the claim to the
    cornerman to verify against the base. The cornerman always checks the format of the range
    (`format-gate.mjs check`); an unclean file is a finding like any other, fixed by the wrestler
@@ -491,6 +511,8 @@ logs there; whichever session regenerates the page passes every bout dir of the
 
 ## 4 · `close`
 
+**Close comes after title-defense.** The order is: plan complete → the judge tests it in the sandbox → the human marks the PR ready → `/ring:title-defense` → `judges-card.mjs close`. A plan whose blocks the judge all passed is not the end. `close` refuses a bout that never defended its title unless the judge waives it (`--without-title-defense "<what they said>"`). A bout closed too early goes back with `judges-card.mjs reopen <pr> --why "<what the judge said>"`; `resume` on a closed bout asks the judge whether to reopen it.
+
 When the PR gets an automated review (GitHub Copilot), converge it with
 `/ring:title-defense <pr> [--max-rounds N]` before or during `close`: it catalogues the findings
 and runs the fixes through this same cycle (§2).
@@ -541,7 +563,7 @@ and runs the fixes through this same cycle (§2).
 
 ## 5 · `resume [<pr>]`
 
-1. Without `<pr>`: `node "$RING/scripts/judges-card.mjs" list`; take the only active bout or ask.
+1. Without `<pr>`: `node "$RING/scripts/judges-card.mjs" list`; take the only active bout or ask. A bout listed as closed is reopened only with the judge's yes: `judges-card.mjs reopen <pr> --why "<what they said>"`.
 2. `node "$RING/scripts/judges-card.mjs" summary <pr>`: state (with the bout's venue),
    unreviewed commits, open rebounds, decisions and the judges card, and, when Engram answers,
    the repo's latest fouls, verdicts and precedents from earlier bouts (do not repeat those fouls;

package/ring/skills/referee/references/precedents.md

@@ -47,6 +47,12 @@ _Why: after the first approved slice was cited as the reference, the next one dr
 **PR11. Under doubt between two reasonable options, keep current behavior and wire contracts; ticket
 the rest.** _Why: a refactor that also "improves" behavior cannot be validated against the base._
 
+**PR31. A null or an undefined that crosses more than one function is settled where it is born.**
+With a default, a value that cannot be missing, or a Null Object; never asked again downstream for
+the same reason. Count how many times the range asks the same question: three or more is a finding.
+_Why: in agents-studio-fe#606 «did the call connect?» was asked six times downstream; each range
+review approved its piece, the human rejected the cut, and the first rebound only moved the cascade._
+
 ## Process
 
 **PR12. Small reviewed slices first, polish later.** No automated review loops or convergence before

package/ring/skills/referee/templates/wrestler-brief.md

@@ -32,7 +32,9 @@ WAITING ON THE HUMAN (hard list; do not touch): {{waitingOnHuman}}.
 Design doubts go to me, never to the human: I decide them (or escalate them) and tell you.
 
 Gates (from `.claude/ring.json`, each through one-at-a-time; a long run such as a battery adds
-`--monitor <id>` when its command does not match a declared monitor, so it shows on the Scorecard):
+`--monitor <id>` when its command does not match a declared monitor, so it shows on the Scorecard).
+Run them when the block's work is done, before you report it, on the files you touched; not after
+every edit (a half-written block fails for no reason and holds the machine):
 
 - typecheck: `{{gateTypecheck}}`
 - tests of what you touched: `{{gateTest}}`

package/ring/skills/title-defense/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: title-defense
 description: Converges a PR after an external automated reviewer (GitHub Copilot) has commented. Each Copilot review is a challenger's round; the PR defends its belt until a round brings nothing actionable and CI is green, or the round limit is hit. A thin layer over the referee: it gathers, classifies and catalogues the findings, hands the fixes to the referee's normal cycle, then replies to fixed threads, resolves them and re-requests Copilot. Invoke with `/ring:title-defense <pr> [--max-rounds N]`, "defend the PR against Copilot", "converge the Copilot review".
-argument-hint: "<pr> [--max-rounds N]"
+argument-hint: "<pr> [--max-rounds N] [--keep-draft]"
 ---
 
 # title-defense
@@ -20,10 +20,13 @@ list, judges card, `decisions.md` and `rebounds.md`, and the same `mask-guard` r
 
 ## 0 · Before the first round
 
-1. **Only once the human took the PR out of draft.** `gh pr view <pr> --json isDraft`: if it is
-   still a draft, answer with one line, "PR #<n> is still a draft; title-defense starts when you
-   mark it ready for review", and do nothing else (no flag, no Copilot request).
-   `judges-card.mjs title-defense` refuses on a draft too, and when gh cannot tell.
+1. **Invoking title-defense is the human's yes to take the PR out of draft.** Never run
+   `gh pr ready` yourself (mask-guard refuses it): `judges-card.mjs title-defense <pr>
+   --until-round <k>` marks a draft PR ready, logs «the judge invoked title-defense» in
+   decisions.md and sets the flag. If the human said to keep it a draft (`--keep-draft` in the
+   invocation), pass `--keep-draft`: then a draft refuses as before, "PR #<n> is still a draft;
+   title-defense starts when you mark it ready for review", and you do nothing else. When gh cannot
+   tell whether it is a draft, it refuses too.
 2. `--max-rounds` defaults to 3 (the owner often uses up to 6).
 3. **A bout for this PR**: `node "$RING/scripts/judges-card.mjs" summary <pr>`. If there is none,
    open one with the referee's `start` flow (§1); if it exists, reuse it as in `resume` (§5),