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

package/ring/scripts/findings.mjs

@@ -9,8 +9,9 @@
 //                         in its second field (`<file:line> — R11 — …`); X0 when none covers it.
 //   node findings.mjs clean <pr> --range <from>..<to>      the cornerman found nothing in that range
 //   node findings.mjs applied <pr> F<n>[,F<m>…] <sha>      the wrestler applied it in that commit
-//   node findings.mjs discard <pr> F<n>[,…] --id D<k> --reason "<why>"
-//   node findings.mjs ticket <pr> F<n>[,…] --ticket <id|"to file"> --reason "<why>"
+//   node findings.mjs discard <pr> F<n>[,…] --id D<k> --reason "<why>" [--judge "<what the human said>"]
+//   node findings.mjs ticket <pr> F<n>[,…] --ticket <id|"to file"> --reason "<why>" [--judge "…"]
+//     (--judge is required when a finding cites a rule of `findingsNeedJudge`, P14 by default)
 //   node findings.mjs escalate <pr> F<n>[,…]               sent to the human; waits on their answer
 //   node findings.mjs shown <pr> F<n>[,…] --in "<where the human saw it>"
 //   node findings.mjs audit <pr> [--full]                  counts; --full writes findings-audit.md
@@ -41,6 +42,7 @@ import {
   readState,
   repoSlug,
 } from './config.mjs';
+import { syncAfter } from './engram.mjs';
 import { record } from './live.mjs';
 import {
   citedRules,
@@ -499,6 +501,21 @@ function applied([pr, ...argv]) {
   console.log(`${ids.join(', ')} applied in ${full.slice(0, 9)}`);
 }
 
+/**
+ * The findings among `ids` that cite a rule the referee may not settle alone (`findingsNeedJudge`):
+ * by the rule the referee recorded or by the rule field of the line. PURE.
+ */
+export function needJudge(findings, ids, rules) {
+  const guarded = new Set(rules ?? []);
+  return findings.filter(
+    (finding) =>
+      ids.includes(finding.id) &&
+      [finding.rule, ...(citedRules(finding.text) ?? [])].some((rule) =>
+        guarded.has(rule),
+      ),
+  );
+}
+
 /** Settled by the referee alone: the ledger, decisions.md and the judges card all say so. */
 function settleAlone(pr, argv, kind) {
   const { values, rest } = flags(argv);
@@ -510,7 +527,21 @@ function settleAlone(pr, argv, kind) {
     throw new Error('a discard needs the decision that took it: --id D<k>');
   if (kind === 'ticket' && !values.ticket?.trim())
     throw new Error('a ticket needs its id, or --ticket "to file"');
-  const { dir } = bout(pr);
+  const { dir, state } = bout(pr);
+  const judge = values.judge?.trim();
+  const { config } = loadConfig(projectDir(), {
+    contract: false,
+    venue: state.venue ?? 'backend',
+  });
+  const guarded = needJudge(
+    readLedger(dir).findings,
+    ids,
+    config.findingsNeedJudge,
+  );
+  if (guarded.length && !judge)
+    throw new Error(
+      `${guarded.map((f) => f.id).join(', ')} cite${guarded.length === 1 ? 's' : ''} a rule the referee may not settle alone (${(config.findingsNeedJudge ?? []).join(', ')}): fix it, escalate it, or add --judge "<what the human said>"`,
+    );
   const at = now();
   const change =
     kind === 'discard'
@@ -522,7 +553,7 @@ function settleAlone(pr, argv, kind) {
   for (const finding of settled)
     appendFileSync(
       join(dir, 'decisions.md'),
-      `- ${at} · ${values.id ?? finding.id} · referee · cornerman finding ${finding.id} ${verb}: ${reason} · «${finding.text}»\n`,
+      `- ${at} · ${values.id ?? finding.id} · ${judge ? 'judge' : 'referee'} · cornerman finding ${finding.id} ${verb}: ${reason}${judge ? ` (the human: ${judge})` : ''} · «${finding.text}»\n`,
     );
   const cardPath = join(dir, 'judges-card.md');
   if (existsSync(cardPath)) {
@@ -623,6 +654,8 @@ if (isMain(import.meta.url)) {
   }
   try {
     run(rest);
+    // An X0 finding and its status go to Engram (quiet without it).
+    if (command !== 'audit') await syncAfter(rest[0]);
   } catch (error) {
     console.error(`findings: ${error.message}`);
     process.exit(1);

package/ring/scripts/judges-card.mjs

@@ -50,6 +50,17 @@
 // State lives in ~/.claude/ring/<owner>/<repo>/<pr>/ (RING_HOME overrides the root), never in the
 // session scratchpad: that one is wiped when the session restarts. state.json stays minimal (worktree, branch, base, lastReviewed,
 // active, venue); a state without venue is a backend bout, from before venues existed; round-bells are read from GitHub and the tip from git, so they never go stale here.
+import { archConfig, archStatus, SETUP_HINT } from './arch-gate.mjs';
+import {
+  conceptsSinceRelay,
+  liveLines,
+  relayDue,
+  undecidedProposals,
+  withConceptClosed,
+  withProposalDecision,
+  wrestlerIds,
+} from './relay.mjs';
+import { resumeSection } from './compact-hook.mjs';
 import { boutFormatGate } from './format-gate.mjs';
 import { execFileSync } from 'node:child_process';
 import {
@@ -103,7 +114,9 @@ import {
   unloggedEscalationNotice,
 } from './preparation.mjs';
 import { handOffWarning, withChronicleUrl } from './sparring-chronicle.mjs';
-import { parsePlan, PLAN } from './tech-plan.mjs';
+import { refereeRecall, syncAfter } from './engram.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';
@@ -237,10 +250,24 @@ function open(argv) {
       dir,
     }),
   );
+  warnWithoutArchGate(worktree, venue);
   console.log(dir);
 }
 
-function summary([pr]) {
+/** A bout in a repo with no architecture gate reviews layers only by eye: say so when it opens. */
+function warnWithoutArchGate(worktree, venue) {
+  try {
+    const config = archConfig(worktree, venue);
+    if (archStatus(worktree, config).configured) return;
+    console.error(
+      `judges-card: WARNING: this repo has no architecture gate, so layer and dependency rules are reviewed only by eye; ${SETUP_HINT}.`,
+    );
+  } catch {
+    // The warning is advice: a repo the gate cannot read still gets its bout.
+  }
+}
+
+async function summary([pr]) {
   const dir = currentDir(pr);
   const state = readState(dir);
   const tip = git(state.worktree, ['rev-parse', 'HEAD']);
@@ -283,6 +310,38 @@ function summary([pr]) {
       read('judges-card.md').trim(),
     ].join('\n'),
   );
+  const { config } = loadConfig(projectDir(), {
+    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,
+  });
+  if (learned)
+    console.log(
+      [
+        '',
+        '## Learned in earlier bouts of this repo (Engram: fouls not to repeat, verdicts, precedents)',
+        learned,
+      ].join('\n'),
+    );
 }
 
 /**
@@ -535,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}` : ''}`,
   );
 }
 
@@ -609,6 +683,11 @@ function close([pr]) {
   const dir = currentDir(pr);
   const blocked = auditBlocks(readLedger(dir), { closing: true });
   if (blocked) throw new Error(`bout #${pr} does not close yet: ${blocked}`);
+  const proposals = undecidedProposals(
+    readFileSync(join(dir, 'judges-card.md'), 'utf8'),
+  );
+  if (proposals)
+    throw new Error(`bout #${pr} does not close yet: ${proposals}`);
   const state = readState(dir);
   const tip = state.lastApproved ?? state.lastReviewed;
   if (tip) {
@@ -859,8 +938,99 @@ function playByPlayUrl([pr, url]) {
   );
 }
 
+/**
+ * A concept closed after its review: recorded, and the wrestlers that carried it retired. The next
+ * concept goes to a fresh wrestler; every `relayEvery` concepts the referee relays first.
+ */
+function concept([pr, name, ...argv]) {
+  const { range } = options(argv);
+  const dir = currentDir(pr);
+  const state = readState(dir);
+  const next = withConceptClosed(state, {
+    name,
+    range,
+    at: new Date().toISOString(),
+    wrestlers: wrestlerIds(liveLines(dir)),
+  });
+  writeState(dir, next);
+  const { config } = loadConfig(projectDir(), {
+    contract: false,
+    venue: state.venue ?? DEFAULT_VENUE,
+  });
+  const steps = [
+    `concept ${next.concepts.length} «${name}» closed (${range}); ${next.retiredWrestlers.length} wrestler(s) retired: do not send them the next concept.`,
+    relayDue(next, config.relayEvery)
+      ? `Relay first (${conceptsSinceRelay(next)} concepts since the last one): rewrite the card's «How to resume» so a new session or a compaction resumes from it, then judges-card.mjs relay ${pr}. brief.mjs briefs no wrestler until then.`
+      : null,
+    `Next concept: brief.mjs wrestler ${pr} --mode resume --vars <file with nextConcept>, launched with prompt "ring-brief: <path>".`,
+  ];
+  console.log(steps.filter(Boolean).join('\n'));
+}
+
+/** The referee's relay: the card's «How to resume» is current, written after the last concept. */
+function relay([pr]) {
+  const dir = currentDir(pr);
+  const state = readState(dir);
+  const last = (state.concepts ?? []).at(-1);
+  const cardPath = join(dir, 'judges-card.md');
+  const resume = resumeSection(readFileSync(cardPath, 'utf8'), 20000);
+  const names = last
+    ? [
+        last.name,
+        last.range,
+        ...last.range.split('..').filter((sha) => sha.length >= 7),
+      ]
+    : [];
+  if (last && !names.some((name) => name && resume.includes(name)))
+    throw new Error(
+      `the card's «How to resume» does not mention the last concept («${last.name}», ${last.range}): write where the bout is, what is next and what waits on the human, then relay`,
+    );
+  if (last && statSync(cardPath).mtimeMs < Date.parse(last.at))
+    throw new Error(
+      `the card was not touched since concept «${last.name}» closed: rewrite its «How to resume» first`,
+    );
+  const next = {
+    ...state,
+    relays: [
+      ...(state.relays ?? []),
+      {
+        at: new Date().toISOString(),
+        afterConcepts: (state.concepts ?? []).length,
+      },
+    ],
+  };
+  writeState(dir, next);
+  console.log(
+    `relay recorded after ${(state.concepts ?? []).length} concept(s); the next wrestler can be briefed.`,
+  );
+}
+
+/** A rulebook proposal of the card, accepted or rejected with its reason. */
+function proposal([pr, n, verdict, ...argv]) {
+  const { why } = options(argv);
+  const dir = currentDir(pr);
+  const cardPath = join(dir, 'judges-card.md');
+  const decided = { accept: 'accepted', reject: 'rejected' }[verdict];
+  if (!decided)
+    throw new Error('usage: proposal <pr> <n> accept|reject --why "<why>"');
+  writeFileSync(
+    cardPath,
+    withProposalDecision(
+      readFileSync(cardPath, 'utf8'),
+      n,
+      decided,
+      why,
+      new Date().toISOString().slice(0, 10),
+    ),
+  );
+  console.log(`proposal ${n} ${decided}`);
+}
+
 const COMMANDS = {
   open,
+  concept,
+  relay,
+  proposal,
   'play-by-play-url': playByPlayUrl,
   'page-answers': pageAnswers,
   'page-verdicts': pageVerdicts,
@@ -880,12 +1050,15 @@ 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|approve-contract|title-defense|play-by-play-url|page-answers|page-verdicts|plan …',
+      '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 …',
     );
     process.exit(1);
   }
   try {
-    run(rest);
+    await run(rest);
+    // What the bout learned goes to Engram after each command that may change it (quiet without it).
+    if (['log', 'concept', 'relay', 'proposal', 'close'].includes(command))
+      await syncAfter(rest[0]);
   } catch (error) {
     console.error(`judges-card: ${error.message}`);
     process.exit(1);

package/ring/scripts/mask-guard.mjs

@@ -10,6 +10,7 @@
 //
 // Exit 2 with the reason blocks the command. If the guard itself fails while a bout may be active,
 // 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 { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
@@ -881,6 +882,18 @@ const gitRules = [
       return `The PR branch ${branch} only receives formatted work: ${reason}`;
     },
   },
+  {
+    // Third line: what goes up to the PR branch adds no import a layer may not make (P14).
+    when: (git, ctx) =>
+      git.sub === 'push' && ctx.archBeforePush(git, pushRefspecs(git, ctx)),
+    reason: (git, ctx) => {
+      const { branch, reason } = ctx.archBeforePush(
+        git,
+        pushRefspecs(git, ctx),
+      );
+      return `The PR branch ${branch} only receives work that respects the repo's layers: ${reason}`;
+    },
+  },
   {
     when: (git, ctx) =>
       git.sub === 'push' && ctx.findingsBeforePush(git, pushRefspecs(git, ctx)),
@@ -1283,6 +1296,8 @@ function judgeSegment(segment, words, cwd, ctx) {
       ctx.findingsBeforePushAt(context.path(push.dir), refspecs),
     formatBeforePush: (push, refspecs) =>
       ctx.formatBeforePushAt(context.path(push.dir), refspecs),
+    archBeforePush: (push, refspecs) =>
+      ctx.archBeforePushAt(context.path(push.dir), refspecs),
     isBackupBranch: (push, target) =>
       ctx
         .backupBranchesAt(context.path(push.dir))
@@ -1574,6 +1589,24 @@ function realContext(cwd) {
       }
       return null;
     },
+    // The first push to a bout's PR branch whose range adds an import its layers forbid, or null.
+    // A repo with no gate configured passes (judges-card open warned about it).
+    archBeforePushAt: (dir, refspecs) => {
+      const slug = insideGitRepo(dirOf(dir)) ? slugOf(dirOf(dir)) : null;
+      if (!slug) return null;
+      for (const { source, target } of refspecs) {
+        const bout = boutsOf(slug).find(({ state }) => state.branch === target);
+        if (!bout || source === null) continue;
+        const sha = git(dirOf(dir), [
+          'rev-parse',
+          '--verify',
+          `${source}^{commit}`,
+        ]);
+        const { refusal } = boutArchGate(bout.state, sha);
+        if (refusal) return { branch: target, reason: refusal };
+      }
+      return null;
+    },
     contractApprovals: (where) => {
       const slug = slugWhere(where);
       if (!slug) return {};

package/ring/scripts/relay.mjs

@@ -0,0 +1,127 @@
+// The bout's continuity: one fresh wrestler per concept, the referee's relay every few concepts, and
+// no close while a rulebook proposal waits for its decision. Zero-dependency.
+//
+// A wrestler that carried a concept carries its context too: after `judges-card.mjs concept`, the
+// next concept goes to a new wrestler (`brief.mjs wrestler <pr> --mode resume`), and brief-guard
+// warns (or blocks) a SendMessage to a retired one. Every `relayEvery` concepts the referee rewrites
+// the card's «how to resume» and records it (`judges-card.mjs relay`): until then brief.mjs does not
+// brief the next wrestler, so a compaction (the SessionStart hook puts that section back) or a new
+// session always resumes from a card that is current. `judges-card.mjs close` refuses while a
+// proposal of «For the rulebook / precedents» (an X0 included) has no decision.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { LIVE_LOG } from './live.mjs';
+
+export const PROPOSALS = 'For the rulebook / precedents';
+const DECIDED = /→\s*(accepted|rejected)\b/;
+
+const sectionOf = (lines, heading) => {
+  const start = lines.findIndex((line) => line.startsWith(`## ${heading}`));
+  if (start < 0) return null;
+  const rest = lines.findIndex((line, i) => i > start && /^##\s/.test(line));
+  return { start, end: rest < 0 ? lines.length : rest };
+};
+
+/**
+ * The proposals of the card's «For the rulebook / precedents» section, in order: each item is a
+ * `- ` line with its indented continuation, minus the template's `- <…>` placeholder. PURE.
+ */
+export function proposalsOf(card) {
+  const lines = String(card ?? '').split('\n');
+  const section = sectionOf(lines, PROPOSALS);
+  if (!section) return [];
+  const items = [];
+  let current = null;
+  for (let i = section.start + 1; i < section.end; i += 1) {
+    const line = lines[i];
+    if (line.startsWith('- ')) {
+      current = line.startsWith('- <') ? null : { at: i, text: line };
+      if (current) items.push(current);
+    } else if (current && /^\s+\S/.test(line)) current.text += `\n${line}`;
+    else current = null;
+  }
+  return items.map((item, index) => ({
+    n: index + 1,
+    line: item.at,
+    text: item.text,
+    decided: DECIDED.test(item.text),
+  }));
+}
+
+/** The card with proposal `n` (1-based) decided: `→ accepted|rejected (<at>): <why>`. PURE. */
+export function withProposalDecision(card, n, verdict, why, at) {
+  if (!['accepted', 'rejected'].includes(verdict))
+    throw new Error('a proposal is accept or reject');
+  if (!why?.trim()) throw new Error('a decision on a proposal needs --why');
+  const proposal = proposalsOf(card).find((item) => item.n === Number(n));
+  if (!proposal) throw new Error(`there is no proposal ${n} in the card`);
+  if (proposal.decided)
+    throw new Error(`proposal ${n} is already decided: ${proposal.text}`);
+  const lines = String(card).split('\n');
+  lines[proposal.line] =
+    `${lines[proposal.line]} → ${verdict} (${at}): ${why.trim()}`;
+  return lines.join('\n');
+}
+
+/** Why the bout cannot close for its proposals, or null. PURE. */
+export function undecidedProposals(card) {
+  const open = proposalsOf(card).filter((item) => !item.decided);
+  if (!open.length) return null;
+  return `${open.length} rulebook proposal(s) without a decision: ${open
+    .map((item) => `${item.n}. ${item.text.split('\n')[0].slice(2, 120)}`)
+    .join(
+      ' · ',
+    )}. Decide each with judges-card.mjs proposal <pr> <n> accept|reject --why "<why>" (an accepted one goes to the precedents in its own PR)`;
+}
+
+/** Concepts closed since the last relay. PURE. */
+export const conceptsSinceRelay = (state) => {
+  const concepts = state.concepts ?? [];
+  const last = (state.relays ?? []).at(-1);
+  return last ? concepts.length - last.afterConcepts : concepts.length;
+};
+
+/** Is a relay due before the next wrestler? `every` null or 0 turns it off. PURE. */
+export const relayDue = (state, every) =>
+  Boolean(every) && conceptsSinceRelay(state) >= every;
+
+/** The wrestler agent ids a bout's live feed has seen (what a concept close retires). PURE. */
+export function wrestlerIds(lines) {
+  const ids = new Set();
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line);
+      const id = /^agent (\S+)$/.exec(event.note ?? '')?.[1];
+      if (event.actor === 'luchador' && id) ids.add(id);
+    } catch {
+      // A torn line is skipped.
+    }
+  }
+  return [...ids];
+}
+
+/** The state after a concept closes: the concept recorded and its wrestlers retired. PURE. */
+export function withConceptClosed(state, { name, range, at, wrestlers }) {
+  if (!name?.trim()) throw new Error('a concept needs its name');
+  if (!/^\S+\.\.\S+$/.test(range ?? ''))
+    throw new Error('a concept needs its reviewed range: --range <from>..<to>');
+  return {
+    ...state,
+    concepts: [...(state.concepts ?? []), { name: name.trim(), range, at }],
+    retiredWrestlers: [
+      ...new Set([...(state.retiredWrestlers ?? []), ...wrestlers]),
+    ],
+  };
+}
+
+/** The live lines of a bout, or none. */
+export function liveLines(dir) {
+  try {
+    return readFileSync(join(dir, LIVE_LOG), 'utf8')
+      .split('\n')
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}