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

package/README.md

@@ -444,8 +444,8 @@ y al pasar a «espera al juez» el fin y el rango (`--range A..B` lo fija a mano
 `plan.jsonl`, que es lo que lee el modo «Pelea del ring» de PR Review Lab. Cuando `humanReviewEvery`
 bloques (2 por default, `null` lo apaga) esperan al juez, suena la campana en PR Review Lab y
 `brief.mjs` no le arma instrucciones al siguiente luchador hasta que el humano revise ese corte en un
-solo diff y firme un veredicto con Tape. Con `parallelBlocks: 2` dos bloques corren a la vez **en el mismo
-worktree**, cada luchador sobre los archivos que su bloque declaró (`--files "<globs>"` al estimar o
+solo diff y firme un veredicto con Tape. Con `parallelBlocks: 2` (el default) dos bloques corren a la vez **en el mismo
+worktree** mientras nada espere la revisión del humano (con algo esperando, uno a la vez), cada luchador sobre los archivos que su bloque declaró (`--files "<globs>"` al estimar o
 arrancar): el script no deja arrancar un bloque con archivos de otro en curso, `mask-guard` rechaza un
 commit con archivos de otro bloque (los de `generatedPaths`, como los docs que regenera un pre-commit,
 no son de nadie: el árbitro los regenera al cerrar la oleada), y `concept … --block <n>` retira solo al

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebattlearena/corner",
-  "version": "0.10.1-beta.83",
+  "version": "0.10.1-beta.84",
   "description": "Corner: tu esquina de Battle Arena en Claude Code (el plugin `battlearena`). Hooks de tracking, objetivo del turno, plan de batalla /battlearena:conquer, Ringside (el panel de tu día), el ring y la radio. Zero-dependency.",
   "type": "module",
   "bin": {

package/ring/scripts/brief.mjs

@@ -214,7 +214,7 @@ function laneSection(bout, block) {
  * cut does not touch (`--lookahead "<globs>"`). Without it, or when it overlaps or another block is
  * running, the pause holds. Returns the brief's section that bounds the work ahead.
  */
-function workAhead(bout, lookahead, turn) {
+function workAhead(bout, lookahead, turn, block) {
   if (!lookahead)
     throw new Error(
       `${turn.due}. Or work ahead on one block whose files the cut does not touch: --lookahead "<glob>,<glob>"`,
@@ -241,7 +241,8 @@ function workAhead(bout, lookahead, turn) {
   const refusal = lookaheadRefusal({
     globs,
     waitingFiles,
-    running: runningBlocks(plan),
+    // The block this brief is for may already be «en curso»: it is not another block ahead.
+    running: runningBlocks(plan).filter((item) => item.n !== Number(block)),
   });
   if (refusal) throw new Error(`${turn.due}. ${refusal}`);
   return [
@@ -299,10 +300,11 @@ async function generate(kind, [pr, ...argv]) {
       bout.dir,
       bout.config.humanReviewEvery,
       (n, to, ref) => setPlanState(bout.dir, n, to, ref),
+      bout.config.parallelBlocks ?? 1,
     );
     if (turn.applied.length)
       console.error(`human review applied: ${turn.applied.join(' · ')}`);
-    if (turn.due) ahead = workAhead(bout, values.lookahead, turn);
+    if (turn.due) ahead = workAhead(bout, values.lookahead, turn, values.block);
   }
   const own = values.vars ? JSON.parse(readFileSync(values.vars, 'utf8')) : {};
   const roots = [

package/ring/scripts/config.mjs

@@ -161,8 +161,9 @@ export const DEFAULTS = Object.freeze({
   // wrestler until the human signs a verdict on that cut. null: no pause.
   humanReviewEvery: 2,
   // Blocks that may run at once in the bout's worktree, each wrestler on the files its block
-  // declared (lanes.mjs). 1: one at a time, as always.
-  parallelBlocks: 1,
+  // declared (lanes.mjs). A second block starts only while nothing waits on the human's review and
+  // its files do not touch the running one's. 1: one at a time.
+  parallelBlocks: 2,
   // Files the host regenerates on its own (a pre-commit that writes docs): no block holds them, and
   // the referee regenerates them when a wave of parallel blocks closes. Globs.
   generatedPaths: [],

package/ring/scripts/findings.mjs

@@ -553,7 +553,7 @@ function settleAlone(pr, argv, kind) {
   for (const finding of settled)
     appendFileSync(
       join(dir, 'decisions.md'),
-      `- ${at} · ${values.id ?? finding.id} · ${judge ? 'judge' : 'referee'} · cornerman finding ${finding.id} ${verb}: ${reason}${judge ? ` (the human: ${judge})` : ''} · «${finding.text}»\n`,
+      `- ${at} · ${finding.id} · ${judge ? 'judge' : 'referee'} · cornerman finding ${finding.id} ${verb}${values.id ? ` per ${values.id}` : ''}: ${reason}${judge ? ` (the human: ${judge})` : ''} · «${finding.text}»\n`,
     );
   const cardPath = join(dir, 'judges-card.md');
   if (existsSync(cardPath)) {

package/ring/scripts/judges-card.mjs

@@ -321,8 +321,11 @@ async function summary([pr]) {
     contract: false,
     venue: state.venue ?? DEFAULT_VENUE,
   });
-  const review = reviewTurn(dir, config.humanReviewEvery, (n, to, ref) =>
-    setPlanState(dir, n, to, ref),
+  const review = reviewTurn(
+    dir,
+    config.humanReviewEvery,
+    (n, to, ref) => setPlanState(dir, n, to, ref),
+    config.parallelBlocks ?? 1,
   );
   const returned = openHumanReturns(dir);
   console.log(
@@ -345,6 +348,23 @@ async function summary([pr]) {
       review.due ?? '',
     ].join('\n'),
   );
+  const points = existsSync(join(dir, PLAN))
+    ? parsePlan(readFileSync(join(dir, PLAN), 'utf8')).groups.flatMap(
+        (group) => group.items,
+      )
+    : [];
+  if (
+    points.length &&
+    points.every((item) => item.state === 'hecho') &&
+    titleDefenseRefusal(readState(dir), null)
+  )
+    console.log(
+      [
+        '',
+        '## Next in the bout’s life (the plan is complete)',
+        'The judge tests it in the sandbox → the human marks the PR ready → /ring:title-defense → judges-card.mjs close. Do not close before the defense unless the judge waives it (--without-title-defense "<what they said>").',
+      ].join('\n'),
+    );
   const learned = await refereeRecall(config, {
     slug: repoSlug(projectDir()),
     pr,
@@ -658,7 +678,8 @@ function plan([pr, target, ...rest]) {
   );
 }
 
-function log([pr, kind, ...words]) {
+function log([pr, kind, ...rest]) {
+  let words = rest;
   if (
     ['escalation', 'escalation-context', 'answer'].includes(kind) &&
     words.length
@@ -672,6 +693,26 @@ function log([pr, kind, ...words]) {
   const stamp = new Date().toISOString();
   const box = kind === 'rebound' ? '[ ] ' : '';
   const dir = currentDir(pr);
+  if (kind === 'decision') {
+    const path = join(dir, 'decisions.md');
+    const taken = new Set(
+      [
+        ...(existsSync(path) ? readFileSync(path, 'utf8') : '').matchAll(
+          / · (D\d+) · /g,
+        ),
+      ].map((m) => m[1]),
+    );
+    const fixed = withFreeDecisionId(
+      words.join(' '),
+      taken,
+      nextDecisionId(dir),
+    );
+    if (fixed.renumbered)
+      console.error(
+        `${fixed.renumbered[0]} is taken in decisions.md: logged as ${fixed.renumbered[1]}`,
+      );
+    words = [fixed.text];
+  }
   appendFileSync(
     join(dir, files[kind]),
     `- ${box}${stamp} · ${words.join(' ')}\n`,
@@ -717,8 +758,20 @@ function list() {
   console.log(rows.join('\n') || 'no bouts for this repo');
 }
 
-function close([pr]) {
+/**
+ * Why a bout may not close for its title defense yet, or null: the bout ends after the human's tests
+ * in the sandbox, the PR marked ready and title-defense against Copilot, unless the judge waives it
+ * (`--without-title-defense "<what the human said>"`, which goes to decisions.md). PURE.
+ */
+export function titleDefenseRefusal(state, waiver) {
+  if (state.titleDefense || state.titleDefenseStarted || waiver?.trim())
+    return null;
+  return 'it never defended its title. The bout ends with: plan complete → the judge tests it in the sandbox → the human marks the PR ready → /ring:title-defense → close. If the judge does not want the defense, close with --without-title-defense "<what the human said>"';
+}
+
+function close([pr, ...argv]) {
   const dir = currentDir(pr);
+  const waiver = options(argv)['without-title-defense'];
   const blocked = auditBlocks(readLedger(dir), { closing: true });
   if (blocked) throw new Error(`bout #${pr} does not close yet: ${blocked}`);
   const proposals = undecidedProposals(
@@ -733,10 +786,56 @@ function close([pr]) {
     if (format.refusal)
       throw new Error(`bout #${pr} does not close yet: ${format.refusal}`);
   }
+  const defense = titleDefenseRefusal(state, waiver);
+  if (defense) throw new Error(`bout #${pr} does not close yet: ${defense}`);
+  if (waiver?.trim())
+    appendFileSync(
+      join(dir, 'decisions.md'),
+      `- ${new Date().toISOString()} · ${nextDecisionId(dir)} · judge · closed without title-defense: ${waiver.trim()}\n`,
+    );
   writeState(dir, { ...state, active: false });
   console.log(`bout #${pr} closed; its files stay in ${dir} as the record.`);
 }
 
+/** The next free D<n> of the bout's decisions.md. */
+function nextDecisionId(dir) {
+  const path = join(dir, 'decisions.md');
+  const ids = existsSync(path)
+    ? [...readFileSync(path, 'utf8').matchAll(/ · D(\d+) · /g)].map((m) =>
+        Number(m[1]),
+      )
+    : [];
+  return `D${Math.max(0, ...ids) + 1}`;
+}
+
+/**
+ * The decision line as the referee wrote it, with its D<n> made unique: a D<n> already taken in
+ * the ledger (a judge's verdict wrote it meanwhile) becomes the next free one. PURE.
+ */
+export function withFreeDecisionId(text, taken, next) {
+  const id = /^(D\d+)(\s*·)/.exec(text)?.[1];
+  if (!id || !taken.has(id)) return { text, renumbered: null };
+  return { text: text.replace(id, next), renumbered: [id, next] };
+}
+
+/** A closed bout back to work, with the judge's reason in decisions.md. */
+function reopen([pr, ...argv]) {
+  const { why } = options(argv);
+  if (!why?.trim())
+    throw new Error('usage: reopen <pr> --why "<what the human said>"');
+  const dir = currentDir(pr);
+  const state = readState(dir);
+  if (state.active) throw new Error(`bout #${pr} is already active`);
+  appendFileSync(
+    join(dir, 'decisions.md'),
+    `- ${new Date().toISOString()} · ${nextDecisionId(dir)} · judge · bout reopened: ${why.trim()}\n`,
+  );
+  writeState(dir, { ...state, active: true });
+  console.log(
+    `bout #${pr} reopened; resume it with /ring:referee resume ${pr}.`,
+  );
+}
+
 /**
  * The title-defense flag in a bout state, set or cleared. `setAt` starts its count: mask-guard
  * allows at most `untilRound` Copilot review requests after it. PURE.
@@ -750,7 +849,12 @@ export function withTitleDefense(
   if (untilRound === null) return rest;
   if (!Number.isInteger(untilRound) || untilRound < 1)
     throw new Error('--until-round must be a positive integer');
-  return { ...rest, titleDefense: { pr: state.pr, untilRound, setAt } };
+  // titleDefenseStarted outlives the flag: close asks whether the PR ever defended its title.
+  return {
+    ...rest,
+    titleDefense: { pr: state.pr, untilRound, setAt },
+    titleDefenseStarted: rest.titleDefenseStarted ?? setAt,
+  };
 }
 
 /**
@@ -772,6 +876,7 @@ export function readyForTitleDefense(pr, view) {
   if (answer?.isDraft === true)
     return {
       ok: false,
+      draft: true,
       reason: `PR #${pr} is still a draft; title-defense starts when you mark it ready for review`,
     };
   return { ok: false, reason: `gh did not say whether PR #${pr} is a draft` };
@@ -888,7 +993,9 @@ function titleDefense([pr, ...argv]) {
   const clear = argv.includes('--clear');
   const index = argv.indexOf('--until-round');
   if (!pr || (!clear && index === -1))
-    throw new Error('usage: title-defense <pr> --until-round <k> | --clear');
+    throw new Error(
+      'usage: title-defense <pr> --until-round <k> [--keep-draft] | --clear',
+    );
   const dir = currentDir(pr);
   const state = readState(dir);
   if (state.active !== true)
@@ -904,7 +1011,25 @@ function titleDefense([pr, ...argv]) {
           stdio: ['ignore', 'pipe', 'pipe'],
         }),
       );
-  if (!gate.ok) throw new Error(gate.reason);
+  // Invoking title-defense is the judge's yes to take the PR out of draft (--keep-draft: not yet).
+  // The script runs gh itself, so mask-guard still refuses `gh pr ready` anywhere else.
+  if (!gate.ok && gate.draft && !argv.includes('--keep-draft')) {
+    execFileSync('gh', ['pr', 'ready', String(pr)], {
+      cwd: state.worktree,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    appendFileSync(
+      join(dir, 'decisions.md'),
+      `- ${new Date().toISOString()} · ${nextDecisionId(dir)} · judge · the judge invoked title-defense: PR #${pr} is out of draft\n`,
+    );
+    console.log(
+      `PR #${pr} marked ready for review (the judge invoked title-defense)`,
+    );
+  } else if (!gate.ok)
+    throw new Error(
+      gate.draft ? `${gate.reason} (--keep-draft was passed)` : gate.reason,
+    );
   const next = withTitleDefense(state, clear ? null : Number(argv[index + 1]));
   writeState(dir, next);
   console.log(
@@ -1071,6 +1196,7 @@ function proposal([pr, n, verdict, ...argv]) {
 
 const COMMANDS = {
   open,
+  reopen,
   concept,
   relay,
   proposal,
@@ -1093,7 +1219,7 @@ if (isMain(import.meta.url)) {
   const run = COMMANDS[command];
   if (!run) {
     console.error(
-      'Usage: node judges-card.mjs open|summary|log|did|list|path|close|concept|relay|proposal|approve-contract|title-defense|play-by-play-url|page-answers|page-verdicts|plan …',
+      'Usage: node judges-card.mjs open|reopen|summary|log|did|list|path|close|concept|relay|proposal|approve-contract|title-defense|play-by-play-url|page-answers|page-verdicts|plan …',
     );
     process.exit(1);
   }

package/ring/scripts/lanes.mjs

@@ -51,11 +51,18 @@ export function startLaneRefusal({
   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);

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
@@ -28,6 +29,7 @@ import {
   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';
 
@@ -189,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) {
@@ -205,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();

package/ring/scripts/review-blocks.mjs

@@ -252,11 +252,16 @@ 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);
@@ -272,7 +277,7 @@ 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»`;
+    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)),

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

@@ -17,7 +17,10 @@ import {
   authorEmail,
   blockFacts,
   factsForState,
+  blocksAwaitingReview,
+  parseVerdicts,
   startRefusal,
+  VERDICTS,
 } from './review-blocks.mjs';
 import {
   parsePlan,
@@ -81,6 +84,11 @@ export function setPlanState(
           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);

package/ring/skills/referee/SKILL.md

@@ -225,8 +225,10 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    "<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` > 1 in `.claude/ring.json`)**: up to that many blocks
-   run at once in the SAME worktree, one wrestler each. Pick blocks that neither depend on each
+   **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
@@ -509,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).
@@ -559,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/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),