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

package/README.md

@@ -374,7 +374,7 @@ rama. El contrato para el proyecto está en `ring/skills/sparring/references/hos
 **Config del repo** (`.claude/ring.json`, opcional): `gates` (typecheck, tests por ruta con
 `{paths}`, lint), `validateCommand`, `rulebook` (por defecto el genérico del plugin),
 `protectedBranches`, `forbidAiTrailers` (por defecto `true`), `heavyCommands`, `delegation`,
-`precedents`, `monitors` (ver «Monitores del repo»), `briefGuard` (`warn`, `block` u `off`), `layers`, `layersIgnore`, `layersRequired` y `findingsNeedJudge` (ver «Gate de arquitectura»), `relayEvery`, `engramUrl` y `engramProject` (ver «Memoria entre peleas»), y `agents` (modelo y esfuerzo por rol; por
+`precedents`, `monitors` (ver «Monitores del repo»), `briefGuard` (`warn`, `block` u `off`), `layers`, `layersIgnore`, `layersRequired` y `findingsNeedJudge` (ver «Gate de arquitectura»), `relayEvery`, `humanReviewEvery` (ver «Revisión humana por bloques»), `engramUrl` y `engramProject` (ver «Memoria entre peleas»), y `agents` (modelo y esfuerzo por rol; por
 defecto el luchador y el rudo en `sonnet` con esfuerzo `high` y el esquinero en `opus` con `high`,
 p. ej. `"agents": { "wrestler": { "model": "opus" } }`). Sin el archivo, `ring` usa los gates que
 detecta en `package.json`, `pyproject.toml`, `go.mod` y el `Makefile`.
@@ -437,6 +437,18 @@ compactarse. Y `judges-card.mjs close` no cierra mientras una propuesta de «For
 precedents» (los `X0` incluidos) no tenga decisión: `judges-card.mjs proposal <pr> <n>
 accept|reject --why "<lo que dijo el humano>"`.
 
+**Revisión humana por bloques (PR Review Lab)**: cada punto del plan técnico es un bloque (`B<n>` es
+el punto n). `judges-card.mjs plan <pr> estimate <n> --minutes <m> [--priority 1-4]` le pone estimado y
+prioridad. Al pasar a «en curso» se anotan el inicio y el autor (el `user.email` de git del worktree),
+y al pasar a «espera al juez» el fin y el rango (`--range A..B` lo fija a mano); todo va en
+`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. PR Review Lab lo escribe en `<combate>/review-verdicts.jsonl`
+y el ring lo lee en el siguiente brief o `summary`: si pasa, los bloques quedan en «hecho»; si no
+pasa, vuelven a «en curso» con el feedback y el Tape como rebote, que el brief del siguiente luchador
+trae al principio. Cada veredicto queda en `decisions.md` como decisión del juez (y en Engram).
+
 **Memoria entre peleas (Engram, opcional)**: si en `engramUrl` (por default
 `http://127.0.0.1:7437`) contesta un [Engram](https://github.com/Gentleman-Programming/engram)
 (`engram serve`), los scripts le mandan lo que cada pelea aprendió: las faltas, las respuestas y

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebattlearena/corner",
-  "version": "0.10.1-beta.79",
+  "version": "0.10.1-beta.80",
   "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

@@ -44,6 +44,8 @@ import {
 } from './config.mjs';
 import { recallSection } from './engram.mjs';
 import { conceptsSinceRelay, relayDue } from './relay.mjs';
+import { reviewTurn } from './review-blocks.mjs';
+import { setPlanState } from './tech-plan-log.mjs';
 import { loadRules } from './rule-ids.mjs';
 
 const TEMPLATES = join(RING_ROOT, 'skills', 'referee', 'templates');
@@ -164,6 +166,20 @@ function boutVars({ dir, state, config }, values) {
   };
 }
 
+/** The open rebounds the human's review sent back, as a section of the brief (none: nothing). */
+function humanReview(dir) {
+  const path = join(dir, 'rebounds.md');
+  const open = (existsSync(path) ? readFileSync(path, 'utf8') : '')
+    .split('\n')
+    .filter((line) => /^- \[ \] .*Revisión humana/.test(line));
+  return open.length
+    ? [
+        '## Sent back by the human review (PR Review Lab; fix these first, the Tape shows what failed)',
+        open.join('\n'),
+      ]
+    : [];
+}
+
 const real = (path) => (existsSync(path) ? realpathSync(path) : path);
 
 async function generate(kind, [pr, ...argv]) {
@@ -178,6 +194,17 @@ async function generate(kind, [pr, ...argv]) {
     throw new Error(
       `a relay is due (${conceptsSinceRelay(bout.state)} concepts since the last one): rewrite the card's «How to resume», run judges-card.mjs relay ${pr}, then brief the next wrestler`,
     );
+  if (kind === 'wrestler') {
+    // The human's verdicts from PR Review Lab first: a fail comes back as a rebound for this brief.
+    const turn = reviewTurn(
+      bout.dir,
+      bout.config.humanReviewEvery,
+      (n, to, ref) => setPlanState(bout.dir, n, to, ref),
+    );
+    if (turn.applied.length)
+      console.error(`human review applied: ${turn.applied.join(' · ')}`);
+    if (turn.due) throw new Error(turn.due);
+  }
   const own = values.vars ? JSON.parse(readFileSync(values.vars, 'utf8')) : {};
   const roots = [
     projectDir(),
@@ -220,6 +247,7 @@ async function generate(kind, [pr, ...argv]) {
     '## Decisions already taken (excerpt: every foul, the ones on these files, the last 20)',
     decisions,
     `The whole ledger: \`${decisionsPath}\`.`,
+    ...humanReview(bout.dir),
     ...(learned ? [learned] : []),
     ...(shape.rules ? ['---', rules.block] : []),
   ].join('\n\n');

package/ring/scripts/config.mjs

@@ -156,6 +156,10 @@ export const DEFAULTS = Object.freeze({
   // Concepts after which the referee relays (rewrites the card's «How to resume» and runs
   // judges-card.mjs relay) before brief.mjs briefs the next wrestler. null: never.
   relayEvery: 4,
+  // The human review by blocks (review-blocks.mjs, PR Review Lab's bout mode): once this many
+  // blocks of the plan (points with a reviewed range) wait on the judge, brief.mjs briefs no
+  // wrestler until the human signs a verdict on that cut. null: no pause.
+  humanReviewEvery: 2,
   // Engram (github.com/Gentleman-Programming/engram), the memory of what earlier bouts learned:
   // fouls, the judge's verdicts, accepted precedents, X0 findings and each bout's status. Never the
   // rules. The scripts sync and read it when something answers at this URL (null: off). The

package/ring/scripts/judges-card.mjs

@@ -115,7 +115,8 @@ import {
 } from './preparation.mjs';
 import { handOffWarning, withChronicleUrl } from './sparring-chronicle.mjs';
 import { refereeRecall, syncAfter } from './engram.mjs';
-import { parsePlan, PLAN } from './tech-plan.mjs';
+import { estimateFacts, reviewTurn } from './review-blocks.mjs';
+import { parsePlan, PLAN, planItem } from './tech-plan.mjs';
 import { addPlanItem, setPlanState } from './tech-plan-log.mjs';
 import { logPageVerdicts } from './verdicts-log.mjs';
 import { DEFAULT_VENUE } from './venues.mjs';
@@ -313,6 +314,22 @@ 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),
+  );
+  console.log(
+    [
+      '',
+      '## Human review by blocks (PR Review Lab, bout mode)',
+      review.applied.length
+        ? `verdicts applied now: ${review.applied.join(' · ')}`
+        : 'no new verdicts',
+      review.waiting.length
+        ? `waiting on the judge: ${review.waiting.map((item) => `B${item.n} «${item.title}»`).join(', ')}`
+        : 'no block waits on the judge',
+      review.due ?? '',
+    ].join('\n'),
+  );
   const learned = await refereeRecall(config, {
     slug: repoSlug(projectDir()),
     pr,
@@ -577,14 +594,29 @@ function plan([pr, target, ...rest]) {
         : 'a point with that origin is already in the plan',
     );
   }
+  if (target === 'estimate') {
+    const [n] = rest;
+    const point = planItem(parsePlan(readFileSync(join(dir, PLAN), 'utf8')), n);
+    const estimated = setPlanState(dir, point.n, point.state, null, undefined, {
+      estimate: estimateFacts({
+        priority: value('--priority'),
+        minutes: value('--minutes'),
+      }),
+    });
+    return void console.log(
+      `B${estimated.n} «${estimated.title}»: priority ${estimated.facts.priority ?? '—'} · ${estimated.facts.estimateMin ?? '—'} min`,
+    );
+  }
   const [state] = rest;
   if (!target || !state)
     throw new Error(
-      'usage: plan <pr> <n|title> <pendiente|espera al juez|en curso|hecho> [--ref <sha|round-bell>] | add … | list',
+      'usage: plan <pr> <n|title> <pendiente|espera al juez|en curso|hecho> [--ref <sha|round-bell>] [--range A..B] | estimate <n> --minutes <m> [--priority 1-4] | add … | list',
     );
-  const changed = setPlanState(dir, target, state, value('--ref'));
+  const changed = setPlanState(dir, target, state, value('--ref'), undefined, {
+    range: value('--range'),
+  });
   console.log(
-    `${changed.n}. ${changed.title}: ${changed.from} → ${changed.to} at ${localStamp(new Date())}`,
+    `${changed.n}. ${changed.title}: ${changed.from} → ${changed.to} at ${localStamp(new Date())}${changed.facts.range && changed.to === 'espera al juez' ? ` · range ${changed.facts.range}` : ''}`,
   );
 }
 

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/referee/SKILL.md

@@ -210,6 +210,14 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    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