@thebattlearena/corner 0.10.1-beta.78 → 0.10.1-beta.80

package/ring/scripts/review-blocks.mjs

@@ -0,0 +1,232 @@
+// The human review by blocks with PR Review Lab: each point of the technical plan is a block (B<n>
+// is point n), with its priority, estimate, author and range in plan.jsonl; every `humanReviewEvery`
+// blocks waiting on the judge, brief.mjs briefs no wrestler until the human reviews that cut in
+// PR Review Lab and signs a verdict with a Tape. PR Review Lab appends the verdicts to
+// `<bout dir>/review-verdicts.jsonl`; the ring reads them: a pass moves the blocks to «hecho», a
+// fail sends them back with the feedback and the Tape as a rebound for the next wrestler.
+// Zero-dependency.
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { readState, writeState } from './config.mjs';
+import { parsePlan, parsePlanLog, PLAN, PLAN_LOG } from './tech-plan.mjs';
+
+export const VERDICTS = 'review-verdicts.jsonl';
+const WAITING = 'espera al juez';
+const TAPE = /^https:\/\/(?:[\w-]+\.)?battlearena\.dev\/t\/[\w-]+$/;
+
+/** What PR Review Lab reads of a block, as its last line of plan.jsonl carries it. */
+const FACTS = [
+  'priority',
+  'estimateMin',
+  'email',
+  'range',
+  'startSha',
+  'startedAt',
+  'endedAt',
+];
+
+/** The facts of point `n` so far: each field from the last plan.jsonl line that has it. PURE. */
+export function blockFacts(log, n) {
+  return log
+    .filter((line) => line.n === n)
+    .reduce(
+      (facts, line) => ({
+        ...facts,
+        ...Object.fromEntries(
+          FACTS.filter((key) => line[key] != null).map((key) => [
+            key,
+            line[key],
+          ]),
+        ),
+      }),
+      {},
+    );
+}
+
+/**
+ * The facts a state change adds: entering «en curso» stamps the start (the first time: a block sent
+ * back keeps its start, so its next review shows the whole block), and «espera al juez» the end and
+ * the range from that start to the worktree's head. PURE.
+ */
+export function factsForState(previous, to, { at, head, email, range }) {
+  if (to === 'en curso')
+    return {
+      startedAt: previous.startedAt ?? at,
+      startSha: previous.startSha ?? head,
+      email: previous.email ?? email,
+      // Back at work: no end and no range until it waits on the judge again.
+      endedAt: null,
+      range: null,
+    };
+  if (to === WAITING) {
+    const from = previous.startSha;
+    return {
+      endedAt: at,
+      range: range ?? (from && head ? `${from}..${head}` : null),
+    };
+  }
+  return {};
+}
+
+/** Checks an estimate: priority 1–4 and whole minutes. PURE. */
+export function estimateFacts({ priority, minutes }) {
+  const facts = {};
+  if (priority != null) {
+    if (![1, 2, 3, 4].includes(Number(priority)))
+      throw new Error('--priority is 1 (first) to 4 (last)');
+    facts.priority = Number(priority);
+  }
+  if (minutes != null) {
+    if (!/^\d+$/.test(String(minutes)) || Number(minutes) < 1)
+      throw new Error('--minutes is a whole number of minutes');
+    facts.estimateMin = Number(minutes);
+  }
+  if (!Object.keys(facts).length)
+    throw new Error(
+      'usage: plan <pr> estimate <n> --minutes <m> [--priority 1-4]',
+    );
+  return facts;
+}
+
+/** The verdicts PR Review Lab signed, in order; a torn line is skipped. PURE. */
+export function parseVerdicts(text) {
+  return parsePlanLog(text).filter(
+    (verdict) =>
+      ['pass', 'fail'].includes(verdict.verdict) &&
+      Array.isArray(verdict.blocks) &&
+      verdict.at,
+  );
+}
+
+/** `["B3", "B4"]` (or numbers) as point numbers. PURE. */
+export const blockNumbers = (blocks) =>
+  blocks.map((block) => Number(/\d+/.exec(String(block))?.[0])).filter(Boolean);
+
+/**
+ * The blocks waiting for the human: in «espera al juez», with a range to review, and no verdict
+ * signed after the block's last change. PURE.
+ */
+export function blocksAwaitingReview(plan, log, verdicts) {
+  return parsePlan(plan)
+    .groups.flatMap((group) => group.items)
+    .filter((item) => item.state === WAITING)
+    .filter((item) => blockFacts(log, item.n).range)
+    .filter((item) => {
+      const last = log.filter((line) => line.n === item.n).at(-1)?.at ?? '';
+      return !verdicts.some(
+        (verdict) =>
+          blockNumbers(verdict.blocks).includes(item.n) && verdict.at > last,
+      );
+    });
+}
+
+/** Why the next wrestler waits for the human's review, or null. PURE. */
+export function reviewDue(waiting, every) {
+  if (!every || waiting.length < every) return null;
+  return `the human review is due: ${waiting.map((item) => `B${item.n} «${item.title}»`).join(', ')} wait on the judge (humanReviewEvery ${every}). The bell rang in PR Review Lab (bout mode): the human reviews that cut in one diff and signs a verdict with a Tape; brief.mjs reads it and goes on`;
+}
+
+/**
+ * What a verdict does to the bout: the plan state of each block, the decisions line (the judge's
+ * verdict, which Engram learns) and, for a fail, the rebound with the feedback and the Tape. PURE.
+ */
+export function verdictEffects(verdict) {
+  const blocks = blockNumbers(verdict.blocks);
+  const names = blocks.map((n) => `B${n}`).join(' + ');
+  const pass = verdict.verdict === 'pass';
+  if (!TAPE.test(String(verdict.tape ?? '')) || !verdict.feedback?.trim())
+    throw new Error(
+      `the verdict of ${names} at ${verdict.at} has no Tape or no feedback: PR Review Lab must not write it without both`,
+    );
+  const who = verdict.reviewer ? ` (${verdict.reviewer})` : '';
+  return {
+    blocks,
+    state: pass ? 'hecho' : 'en curso',
+    decision: `revisión humana de ${names}${who}: ${pass ? 'pasa' : 'no pasa'} · ${verdict.feedback.trim()} · Tape ${verdict.tape} · ${verdict.range ?? ''}`,
+    rebound: pass
+      ? null
+      : `Revisión humana de ${names}${who} no pasa (Tape ${verdict.tape}, rango ${verdict.range ?? 'del corte'}): ${verdict.feedback.trim()}`,
+  };
+}
+
+const read = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : '');
+
+/** The author of a block: the git user of the worktree that writes it. */
+export function authorEmail(worktree) {
+  try {
+    return (
+      execFileSync('git', ['-C', worktree, 'config', 'user.email'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim() || null
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** A bout's plan, its log and PR Review Lab's verdicts, as read now. */
+export function reviewInputs(dir) {
+  return {
+    plan: read(join(dir, PLAN)),
+    log: parsePlanLog(read(join(dir, PLAN_LOG))),
+    verdicts: parseVerdicts(read(join(dir, VERDICTS))),
+  };
+}
+
+/**
+ * Applies the verdicts the bout has not handled yet (state.handledVerdicts holds their `at`):
+ * `setState(n, state, ref)` moves each block, and the decision and the rebound are appended.
+ * Returns the state to write and what was applied.
+ */
+export function applyVerdicts(dir, state, setState) {
+  const handled = new Set(state.handledVerdicts ?? []);
+  const fresh = reviewInputs(dir).verdicts.filter(
+    (verdict) => !handled.has(verdict.at),
+  );
+  const nextId = () =>
+    Math.max(
+      0,
+      ...[...read(join(dir, 'decisions.md')).matchAll(/ · D(\d+) · /g)].map(
+        (match) => Number(match[1]),
+      ),
+    ) + 1;
+  const applied = fresh.map((verdict) => {
+    const effects = verdictEffects(verdict);
+    for (const n of effects.blocks)
+      setState(n, effects.state, `review ${verdict.tape}`);
+    appendFileSync(
+      join(dir, 'decisions.md'),
+      `- ${new Date().toISOString()} · D${nextId()} · judge · ${effects.decision}\n`,
+    );
+    if (effects.rebound)
+      appendFileSync(
+        join(dir, 'rebounds.md'),
+        `- [ ] ${new Date().toISOString()} · ${effects.rebound}\n`,
+      );
+    handled.add(verdict.at);
+    return `${verdict.verdict} ${effects.blocks.map((n) => `B${n}`).join('+')} (${verdict.at})`;
+  });
+  return {
+    state: applied.length ? { ...state, handledVerdicts: [...handled] } : state,
+    applied,
+  };
+}
+
+/**
+ * The review turn of a bout, before a wrestler is briefed or the referee resumes: applies the new
+ * 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) {
+  const before = readState(dir);
+  const { state, applied } = applyVerdicts(dir, before, setState);
+  const next = { ...state, pauseEvery: every ?? null };
+  if (applied.length || before.pauseEvery !== next.pauseEvery)
+    writeState(dir, next);
+  const { plan, log, verdicts } = reviewInputs(dir);
+  const waiting = blocksAwaitingReview(plan, log, verdicts);
+  return { applied, waiting, due: reviewDue(waiting, every) };
+}

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

@@ -1,6 +1,7 @@
 // Reads and writes a bout's technical plan (tech-plan.mjs): `judges-card.mjs plan` changes a
 // point's state or adds one, `page-verdicts` adds each judge's «se mejora», and `play-by-play.mjs
 // embed --plan` puts the plan into the chronicle. Zero-dependency.
+import { execFileSync } from 'node:child_process';
 import {
   appendFileSync,
   existsSync,
@@ -11,6 +12,7 @@ import { join } from 'node:path';
 
 import { readState } from './config.mjs';
 import { scriptJson } from './contract-endpoints.mjs';
+import { authorEmail, blockFacts, factsForState } from './review-blocks.mjs';
 import {
   parsePlan,
   parsePlanLog,
@@ -32,18 +34,48 @@ export function setPlanState(
   state,
   ref = null,
   at = new Date().toISOString(),
+  { range = null, estimate = null } = {},
 ) {
   const file = join(dir, PLAN);
   const markdown = read(file);
   if (markdown === null) throw new Error(`no ${PLAN} in ${dir}`);
   const item = planItem(parsePlan(markdown), target);
   const next = planState(state);
+  // Each line carries every fact of the block so far (PR Review Lab reads the last one): the
+  // priority and estimate, and the start, end, author and range a state change stamps.
+  const previous = blockFacts(parsePlanLog(read(join(dir, PLAN_LOG))), item.n);
+  const { worktree } = readState(dir);
+  const facts = {
+    ...previous,
+    ...(estimate ?? {}),
+    // Only a change of state stamps a start or an end: an estimate keeps the block's range.
+    ...(next === item.state && !range
+      ? {}
+      : factsForState(previous, next, {
+          at,
+          head: worktreeHead(worktree),
+          email: authorEmail(worktree),
+          range,
+        })),
+  };
   writeFileSync(file, withPlanState(markdown, item, next));
   appendFileSync(
     join(dir, PLAN_LOG),
-    `${JSON.stringify({ at, n: item.n, title: item.title, from: item.state, to: next, ref })}\n`,
+    `${JSON.stringify({ at, n: item.n, title: item.title, from: item.state, to: next, ref, ...Object.fromEntries(Object.entries(facts).filter(([, value]) => value != null)) })}\n`,
   );
-  return { ...item, from: item.state, to: next };
+  return { ...item, from: item.state, to: next, facts };
+}
+
+/** The worktree's head, or null when it is gone. */
+function worktreeHead(worktree) {
+  try {
+    return execFileSync('git', ['-C', worktree, 'rev-parse', 'HEAD'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
 }
 
 /** Adds a point to the plan (creating the file when it does not exist); returns whether it was new. */

package/ring/skills/no-surrender/SKILL.md

@@ -43,6 +43,11 @@ theirs may be decided by you. It runs on top of an active bout: without one, say
 - **Keep the cycle**: every range reviewed by a cornerman at effort high, filtered against the
   base, one rebound package, round-bells opened as concepts close (they wait for the human; that
   is fine).
+- **A fresh wrestler per concept, and a relay every few**: a long night is where a wrestler's and a
+  referee's context grow stale. Close each approved concept with `judges-card.mjs concept`, brief
+  the next one to a new wrestler (`--mode resume`), and when `brief.mjs` says a relay is due,
+  rewrite the card's «How to resume» and run `judges-card.mjs relay` before going on. When the
+  session compacts, the SessionStart hook puts that section back: it is all you keep.
 - **Red gates are classified**, not silenced: code (rebound to the wrestler), environment (note it
   and retry once), harness (note it). A coverage gap is fixed with real tests, never with a test
   that only imports a file (T8). A flag decision and a PR over the host's size ceiling (how to

package/ring/skills/referee/SKILL.md

@@ -201,6 +201,23 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
      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
+   `judges-card.mjs concept <pr> "<concept>" --range <first>..<last>`: it records the concept and
+   retires the wrestlers that carried it (a long-lived wrestler drags the earlier concepts'
+   context and repeats their mistakes). The next concept goes to a fresh wrestler:
+   `brief.mjs wrestler <pr> --mode resume --vars <file>` with `nextConcept`; brief-guard warns
+   (or, under `briefGuard: "block"`, refuses) a SendMessage to a retired one. Every `relayEvery`
+   concepts (4 by default) you relay first: rewrite the card's «How to resume» (where the bout is,
+   what is next, what waits on the human) and run `judges-card.mjs relay <pr>`; until then
+   `brief.mjs` briefs no wrestler. That is what a compaction or a new session resumes from.
+   **Human review by blocks**: each point of the technical plan is a block. Give each its estimate
+   and priority when the plan is made (`judges-card.mjs plan <pr> estimate <n> --minutes <m>
+   --priority <1-4>`), move it to «en curso» when its wrestler starts and to «espera al juez» when
+   its review passes (that stamps the author, the times and the range PR Review Lab reviews). Every
+   `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.
    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
@@ -504,8 +521,10 @@ and runs the fixes through this same cycle (§2).
    who, when), validation (SHA, command, result), what is not verified yet. Show it to the human;
    apply it with `gh pr edit <pr> --body-file …` only when they say so, then check it with
    `gh pr view <pr> --json title,body`.
-8. **Precedents**: show the human the proposals in "For the rulebook / precedents". For the ones
-   they accept, offer a small separate PR that appends them to the host precedents file
+8. **Precedents**: show the human the proposals in "For the rulebook / precedents" (the `X0`
+   findings land there too) and record each answer with
+   `judges-card.mjs proposal <pr> <n> accept|reject --why "<what they said>"`: `judges-card.mjs
+   close` refuses while one has no decision. For the ones they accept, offer a small separate PR that appends them to the host precedents file
    (`config.precedentsPath`, or a new `.claude/ring-precedents.md`) with the next HPn ids. Never
    commit that file on your own.
 9. **List, never close**: `node "$RING/scripts/round-bell.mjs" list <pr>`, `git worktree list`
@@ -522,7 +541,9 @@ and runs the fixes through this same cycle (§2).
 
 1. Without `<pr>`: `node "$RING/scripts/judges-card.mjs" list`; take the only active bout or ask.
 2. `node "$RING/scripts/judges-card.mjs" summary <pr>`: state (with the bout's venue),
-   unreviewed commits, open rebounds, decisions and the judges card. Read the rulebook and both precedent files in full again (§0.4).
+   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;
+   they are context, never rules). Read the rulebook and both precedent files in full again (§0.4).
 3. Review the unreviewed commits first (§2.1–2.4).
 4. A new session cannot talk to the old wrestler: its agent id does not survive. Relaunch it
    **without `isolation`**, on the existing worktree, with