@thebattlearena/corner 0.8.0 → 0.9.0

package/ring/scripts/sparring.mjs

@@ -0,0 +1,1161 @@
+#!/usr/bin/env node
+// Sparring drafts: a quick, low-quality draft that only proves whether a feature is worth building
+// (/ring:sparring). One sparring may span several repos (a back and its front): one hypothesis,
+// one card and one verdict, a worktree, a branch and a PR per repo. Zero-dependency.
+//
+//   node sparring.mjs open <slug> --worktree <abs> --base <branch> --hypothesis <text>
+//                              --proof <text> [--credentials NAME,NAME]
+//   node sparring.mjs add-repo <slug> --worktree <abs> --base <branch>
+//   node sparring.mjs pr <slug> --title <text> [--repo <owner/repo>] [--how-to-test <text>]
+//                              [--shortcuts <text>] [--dry-run]
+//   node sparring.mjs preview <slug> [--repo <owner/repo>] [--wait]
+//   node sparring.mjs verdict <slug> ko|rematch|discard --note <text>
+//   node sparring.mjs vestidor <slug>
+//   node sparring.mjs mark <slug> vestidor|defense|bell|mask-kept|mask-lost|no-team|referee
+//                              [--note <text>]
+//   node sparring.mjs play-by-play-url <slug> <url>
+//   node sparring.mjs promote <slug> [--repo <owner/repo>] [--title <text>] [--dry-run]
+//   node sparring.mjs list
+//
+// `mark` stamps a moment of the fight (two out of three falls) at the time it happens, so the
+// chronicle (play-by-play --sparring) has it with its real time; `play-by-play-url` records the
+// fight's one chronicle link and stamps every publish to it. `vestidor`, only after a KO, runs each
+// repo's own whole-repo gates (typecheck, lint, build; never test, which takes paths) in its
+// worktree, one at a time through the machine lock, and stamps the vestidor only when all passed.
+//
+// State lives in `<ring home>/sparrings/<slug>/sparring.json`, never `state.json`: a sparring is not
+// a bout, so mask-guard's bout rules (review cap, approved pushes) never hold the rudo back. It
+// belongs to no repo: each repo of the sparring is named by its worktree, and its config, labels
+// and PR come from there, never from the session's checkout. The PR is the event: it is opened as a
+// draft on `sparring/<slug>` with the sparring and do-not-merge labels, and the host's CI decides
+// what to do with it (deploy a preview or nothing). The ring only reads the preview back from the
+// GitHub Deployments API. Credentials are handled by NAME only: the host resolves their values.
+//
+// A KO is promoted, never merged: `promote` creates `release/<slug>` from the repo's base and
+// `mainevent/<slug>` from the sparring tip, and opens the deliverable PR mainevent → release as a
+// draft. The ring bout cleans `mainevent/<slug>` (no line ceiling there: the round-bells are what
+// the human reads); the sparring and its PR stay do-not-merge as the evidence of what the KO saw.
+// It is the only way a sparring's code leaves `sparring/*`: mask-guard still refuses that push by
+// hand, and `promote` refuses unless the verdict is `ko`.
+//
+// Ringside shows each open sparring like a bout: every command but `list` registers the session
+// that runs it (CLAUDE_CODE_SESSION_ID → `sessions`, so live-hook feeds this sparring from it) and
+// writes what it did to `<sparring dir>/live.jsonl` (árbitro; the verdict is the juez's).
+import { execFileSync, spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  DEFAULTS,
+  DO_NOT_MERGE,
+  isMain,
+  loadConfig,
+  RING_ROOT,
+  repoSlug,
+  ringHome,
+  SPARRING_PREFIX,
+} from './config.mjs';
+import { render } from './judges-card.mjs';
+import {
+  FINAL_VERDICTS,
+  record,
+  registerSparringSession,
+  SPARRING_FILE,
+  sparringsHome,
+} from './live.mjs';
+import { labelExists } from './round-bell.mjs';
+import {
+  checkMilestone,
+  withChronicleUrl,
+  withMilestone,
+} from './sparring-chronicle.mjs';
+
+export const TEMPLATES = join(RING_ROOT, 'skills', 'sparring', 'templates');
+export const VERDICTS = ['ko', 'rematch', 'discard'];
+export const STATE_FILE = SPARRING_FILE;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const CREDENTIAL = /^[A-Z][A-Z0-9_]*$/;
+const TERMINAL = ['success', 'failure', 'error', 'inactive'];
+const POLL_SECONDS = 30;
+
+export const sparringBranch = (slug) => `${SPARRING_PREFIX}${slug}`;
+
+/** The line of a sibling repo in a sparring PR body, before and after its PR exists. PURE. */
+export const siblingLine = (repo, url) =>
+  `- \`${repo}\`: ${url ?? '_PR not opened yet_'}`;
+
+/** A PR body with `repo`'s pending sibling line pointing at `url`; unchanged when absent. PURE. */
+export const withSiblingUrl = (body, repo, url) =>
+  body.replace(siblingLine(repo, null), siblingLine(repo, url));
+
+/** The wait before the next preview poll: never past the deadline, so --wait stays bounded. PURE. */
+export const nextPollSeconds = (deadline, now) =>
+  Math.max(0, Math.min(POLL_SECONDS, (deadline - now) / 1000));
+export const MAINEVENT_PREFIX = 'mainevent/';
+export const RELEASE_PREFIX = 'release/';
+
+/**
+ * What `promote` does for one repo, given the branches its origin already has. PURE. Throws unless
+ * the verdict is `ko`, and when the main event already exists (a second promote would overwrite
+ * the cleanup). The release is reused when it exists: back and front may share the slug, never
+ * the repo, so each repo gets its own.
+ */
+export function promotionPlan(state, entry, remoteHeads) {
+  if (state.verdict?.call !== 'ko')
+    throw new Error(
+      `sparring "${state.slug}" is not a KO (${state.verdict?.call ?? 'no verdict'}): only a KO is promoted`,
+    );
+  const release = `${RELEASE_PREFIX}${state.slug}`;
+  const mainevent = `${MAINEVENT_PREFIX}${state.slug}`;
+  if (remoteHeads.includes(mainevent))
+    throw new Error(
+      `${entry.repo} already has ${mainevent}: the sparring was promoted; the bout works there`,
+    );
+  return {
+    release,
+    mainevent,
+    pushes: [
+      ...(remoteHeads.includes(release)
+        ? []
+        : [`origin/${entry.base}:refs/heads/${release}`]),
+      `origin/${entry.branch}:refs/heads/${mainevent}`,
+    ],
+  };
+}
+
+/** The `gh pr create` arguments of the deliverable PR. PURE. */
+export const mainEventArgs = ({ title, release, mainevent, bodyFile }) => [
+  'pr',
+  'create',
+  '--draft',
+  '--base',
+  release,
+  '--head',
+  mainevent,
+  '--title',
+  title,
+  '--body-file',
+  bodyFile,
+];
+
+/** Throws unless `slug` is a short kebab-case name. PURE. */
+export function checkSlug(slug) {
+  if (!SLUG.test(slug ?? ''))
+    throw new Error(
+      `"${slug}" is not a sparring slug: lowercase letters, digits and dashes, up to 40`,
+    );
+  return slug;
+}
+
+/**
+ * `"KAPSO_API_KEY, KAPSO_WEBHOOK_SECRET"` → the names. PURE. Anything that is not an env-var-like
+ * name is refused, so a value pasted by mistake (`KEY=abc`, a token) never reaches a PR body.
+ */
+export function parseCredentials(text) {
+  const names = String(text ?? '')
+    .split(/[\s,]+/)
+    .filter(Boolean);
+  const bad = names.filter((name) => !CREDENTIAL.test(name));
+  if (bad.length)
+    throw new Error(
+      `credentials are declared by NAME only (UPPER_SNAKE_CASE); refusing ${bad.length} value(s) that are not a name. Never pass a secret value to the ring.`,
+    );
+  return [...new Set(names)];
+}
+
+/** The block the host's CI reads to know which secrets the preview needs. PURE. */
+export function credentialsBlock(names) {
+  if (!names.length) return '';
+  return ['<!-- sparring:credentials', ...names, '-->'].join('\n');
+}
+
+/** The names a PR body declares, back from its block. PURE. */
+export function declaredCredentials(body) {
+  const block = /<!-- sparring:credentials\n([\s\S]*?)-->/.exec(body ?? '');
+  return block ? parseCredentials(block[1]) : [];
+}
+
+/** The fixed warning: credentials used by a sparring are assumed rotated. PURE. */
+export function credentialWarning(names) {
+  if (!names.length) return '_This sparring declares no credentials._';
+  const list = names.map((name) => `\`${name}\``).join(', ');
+  return `> ⚠️ This sparring used sandbox credentials (${list}). They are assumed rotated.`;
+}
+
+/** The `gh pr create` arguments of a sparring PR. PURE. */
+export function createArgs({ title, base, head, bodyFile, label }) {
+  return [
+    'pr',
+    'create',
+    '--draft',
+    '--base',
+    base,
+    '--head',
+    head,
+    '--title',
+    `[sparring] ${title} (do not merge)`,
+    '--body-file',
+    bodyFile,
+    '--label',
+    label,
+    '--label',
+    DO_NOT_MERGE,
+  ];
+}
+
+/**
+ * The preview of the newest deployment, from its statuses (newest first, as GitHub returns them).
+ * PURE. Returns { state, url, done }: `done` once the state is terminal.
+ */
+export function previewOf(statuses) {
+  const latest = statuses?.[0];
+  if (!latest) return { state: 'pending', url: null, done: false };
+  const url = latest.environment_url || latest.target_url || null;
+  return {
+    state: latest.state,
+    url: latest.state === 'success' ? url : null,
+    done: TERMINAL.includes(latest.state),
+  };
+}
+
+/** Whole days between two ISO dates. PURE. */
+export const ageDays = (from, now) =>
+  Math.floor((Date.parse(now) - Date.parse(from)) / 86_400_000);
+
+/** A sparring with no verdict after `staleDays` is stale. PURE. */
+export const isStale = (state, now, staleDays) =>
+  !state.verdict && ageDays(state.openedAt, now) >= staleDays;
+
+/** One repo of a sparring, as `open` and `add-repo` record it. PURE. */
+export const repoEntry = ({ repo, worktree, base, slug }) => ({
+  repo,
+  worktree,
+  base,
+  branch: sparringBranch(slug),
+  pr: null,
+  url: null,
+  preview: null,
+  shortcuts: null,
+});
+
+/**
+ * The repo of a sparring a command acts on. PURE. `key` is `owner/repo` or a worktree path; with a
+ * single repo it may be omitted. Throws, naming the choices, when it is missing or unknown.
+ */
+export function pickRepo(state, key) {
+  const names = state.repos.map((entry) => entry.repo).join(', ');
+  if (!key && state.repos.length === 1) return state.repos[0];
+  if (!key)
+    throw new Error(`this sparring spans ${names}: say which with --repo`);
+  const entry = state.repos.find((item) =>
+    [item.repo, item.worktree].includes(key),
+  );
+  if (!entry)
+    throw new Error(`"${key}" is not a repo of this sparring (${names})`);
+  return entry;
+}
+
+/**
+ * Sparrings recorded before they spanned repos (one `sparring.json` per repo, flat fields) → one
+ * sparring with a repo each. PURE. `legacy` is [{ repo, state }]; the earliest one gives the
+ * hypothesis, the proof and the date, credentials are the union, and a verdict survives if any
+ * repo had one.
+ */
+export function mergeLegacy(legacy) {
+  const sorted = [...legacy].sort((a, b) =>
+    a.state.openedAt.localeCompare(b.state.openedAt),
+  );
+  const first = sorted[0].state;
+  return {
+    slug: first.slug,
+    hypothesis: first.hypothesis,
+    proof: first.proof,
+    credentials: [
+      ...new Set(sorted.flatMap(({ state }) => state.credentials ?? [])),
+    ],
+    openedAt: first.openedAt,
+    verdict: sorted.map(({ state }) => state.verdict).find(Boolean) ?? null,
+    repos: sorted.map(({ repo, state }) => ({
+      repo,
+      worktree: state.worktree,
+      base: state.base,
+      branch: state.branch,
+      pr: state.pr ?? null,
+      url: state.url ?? null,
+      preview: state.preview ?? null,
+      shortcuts: state.shortcuts ?? null,
+    })),
+  };
+}
+
+function options(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (['--dry-run', '--wait'].includes(argv[i])) {
+      flags[argv[i].slice(2)] = true;
+      continue;
+    }
+    if (argv[i].startsWith('--')) {
+      flags[argv[i].slice(2)] = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    positional.push(argv[i]);
+  }
+  return { flags, positional };
+}
+
+const exec = (bin, args, cwd) =>
+  execFileSync(bin, args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+
+const dirOf = (slug) => join(sparringsHome(), checkSlug(slug));
+
+/** Appends an event to the sparring's live feed. Best effort, like every feed writer. */
+const feed = (slug, raw) => record(dirOf(slug), raw);
+const refereeDid = (slug, label, extra = {}) =>
+  feed(slug, { actor: 'arbitro', state: 'done', label, ...extra });
+const fileOf = (slug) => join(dirOf(slug), STATE_FILE);
+
+/** Every legacy per-repo record: `<ring home>/<owner>/<repo>/sparring-<slug>/sparring.json`. */
+function legacyRecords() {
+  const home = ringHome();
+  const dirs = (dir) =>
+    existsSync(dir)
+      ? readdirSync(dir, { withFileTypes: true })
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => entry.name)
+      : [];
+  return dirs(home)
+    .filter((owner) => owner !== 'sparrings')
+    .flatMap((owner) =>
+      dirs(join(home, owner)).flatMap((repo) =>
+        dirs(join(home, owner, repo))
+          .filter((name) => name.startsWith('sparring-'))
+          .map((name) => ({
+            repo: `${owner}/${repo}`,
+            slug: name.slice('sparring-'.length),
+            file: join(home, owner, repo, name, STATE_FILE),
+          })),
+      ),
+    )
+    .filter(({ file }) => existsSync(file));
+}
+
+const legacyFiles = (slug) =>
+  legacyRecords().filter((record) => record.slug === slug);
+
+/** Files of a legacy directory the merge regenerates or already handled: never moved. */
+const REGENERATED = [STATE_FILE, 'sparring.migrated.json', 'card.md'];
+
+/**
+ * Moves `src` to `dst` and leaves a symlink at `src`, so a rudo or a session that kept the old
+ * path still finds it. Two directories merge child by child; anything already at `dst` stays
+ * where it was and is returned as a conflict, never overwritten.
+ */
+function moveLeavingLink(src, dst) {
+  if (lstatSync(src).isSymbolicLink()) return [];
+  if (!existsSync(dst)) {
+    renameSync(src, dst);
+    symlinkSync(dst, src);
+    return [];
+  }
+  if (!statSync(src).isDirectory() || !statSync(dst).isDirectory())
+    return [src];
+  return readdirSync(src).flatMap((name) =>
+    moveLeavingLink(join(src, name), join(dst, name)),
+  );
+}
+
+/**
+ * The sparring `slug`. Legacy per-repo records are merged into one the first time: each record is
+ * renamed to `sparring.migrated.json` so it is never merged twice, and everything else in its
+ * directory (`tools/`, notes, PR bodies) moves to the sparring's directory, with a symlink left
+ * behind at the old path.
+ */
+function readSparring(slug) {
+  if (existsSync(fileOf(slug)))
+    return JSON.parse(readFileSync(fileOf(slug), 'utf8'));
+  const legacy = legacyFiles(checkSlug(slug));
+  if (!legacy.length)
+    throw new Error(`no sparring "${slug}" (${fileOf(slug)})`);
+  const state = mergeLegacy(
+    legacy.map(({ repo, file }) => ({
+      repo,
+      state: JSON.parse(readFileSync(file, 'utf8')),
+    })),
+  );
+  writeSparring(state);
+  const conflicts = [];
+  for (const { file } of legacy) {
+    renameSync(file, file.replace(/sparring\.json$/, 'sparring.migrated.json'));
+    const old = dirname(file);
+    for (const name of readdirSync(old).filter((n) => !REGENERATED.includes(n)))
+      conflicts.push(
+        ...moveLeavingLink(join(old, name), join(dirOf(slug), name)),
+      );
+  }
+  console.error(
+    `sparring: merged ${legacy.length} per-repo record(s) of "${slug}" into ${fileOf(slug)}`,
+  );
+  if (conflicts.length)
+    console.error(
+      `sparring: left in place because the merged directory already has a file with that name: ${conflicts.join(', ')}`,
+    );
+  return state;
+}
+
+function writeSparring(state) {
+  mkdirSync(dirOf(state.slug), { recursive: true });
+  writeFileSync(fileOf(state.slug), JSON.stringify(state, null, 2) + '\n');
+  writeCard(state);
+}
+
+const template = (name) => readFileSync(join(TEMPLATES, name), 'utf8');
+
+const repoLine = (entry) =>
+  [
+    `| \`${entry.repo}\``,
+    `\`${entry.branch}\` on \`${entry.base}\``,
+    entry.pr ? `#${entry.pr} ${entry.url}` : '_no PR yet_',
+    entry.preview?.url ?? '_no preview_',
+    `\`${entry.worktree}\` |`,
+  ].join(' | ');
+
+const shortcutsOf = (state) =>
+  state.repos
+    .filter((entry) => entry.shortcuts)
+    .map((entry) => `**${entry.repo}:** ${entry.shortcuts}`)
+    .join('\n\n') || '_Not stated yet._';
+
+/** Everything the referee writes below this line survives every rewrite of the card. */
+export const NOTES_MARKER =
+  '<!-- notes: everything below this line is kept when the card is rewritten -->';
+
+/** The referee's notes of a card: what follows the marker, or nothing. PURE. */
+export function keptNotes(card) {
+  const at = (card ?? '').indexOf(NOTES_MARKER);
+  return at === -1
+    ? ''
+    : card.slice(at + NOTES_MARKER.length).replace(/^\n+/, '');
+}
+
+const verdictLine = (verdict) =>
+  `**${verdict.call}** · ${verdict.at} · ${verdict.note}`;
+
+/** Earlier rounds, oldest first: every verdict but the last. PURE. */
+export function earlierRounds(history) {
+  const earlier = (history ?? []).slice(0, -1);
+  if (!earlier.length) return '_None._';
+  return earlier
+    .map((verdict, i) => `${i + 1}. ${verdictLine(verdict)}`)
+    .join('\n');
+}
+
+function writeCard(state) {
+  const card = join(dirOf(state.slug), 'card.md');
+  const notes = existsSync(card) ? keptNotes(readFileSync(card, 'utf8')) : '';
+  const rendered = render(template('sparring-card.md'), {
+    slug: state.slug,
+    openedAt: state.openedAt,
+    repos: [
+      '| Repo | Branch | PR | Preview | Worktree |',
+      '| ---- | ------ | -- | ------- | -------- |',
+      ...state.repos.map(repoLine),
+    ].join('\n'),
+    hypothesis: state.hypothesis,
+    proof: state.proof,
+    credentials: credentialWarning(state.credentials),
+    shortcuts: shortcutsOf(state),
+    verdict: state.verdict
+      ? verdictLine(state.verdict)
+      : '_Waiting on the judge._',
+    earlierRounds: earlierRounds(state.history),
+  });
+  writeFileSync(
+    card,
+    `${rendered.trimEnd()}\n\n${NOTES_MARKER}\n\n${notes}`.trimEnd() + '\n',
+  );
+  return card;
+}
+
+/** The branch a worktree has checked out (unborn included), or null when HEAD is detached. */
+function checkedOutBranch(worktree) {
+  try {
+    return exec('git', ['symbolic-ref', '--short', 'HEAD'], worktree);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The repo a worktree belongs to, refusing a relative path and a worktree that is not on
+ * `sparring/<slug>`: otherwise the rudo commits on one branch while `pr` opens another.
+ */
+function repoAt(worktree, slug) {
+  if (!isAbsolute(worktree ?? ''))
+    throw new Error('--worktree must be an absolute path');
+  const expected = sparringBranch(slug);
+  const branch = checkedOutBranch(worktree);
+  if (branch !== expected)
+    throw new Error(
+      `${worktree} is on ${branch ?? 'a detached HEAD'}, not ${expected}: create the sparring worktree on that branch first`,
+    );
+  return repoSlug(worktree);
+}
+
+function open(argv) {
+  const { flags, positional } = options(argv);
+  const [slug] = positional;
+  checkSlug(slug);
+  const missing = ['worktree', 'base', 'hypothesis', 'proof'].filter(
+    (key) => !flags[key],
+  );
+  if (missing.length) throw new Error(`open needs --${missing.join(', --')}`);
+  const credentials = parseCredentials(flags.credentials);
+  const repo = repoAt(flags.worktree, slug);
+  if (existsSync(fileOf(slug)) || legacyFiles(slug).length)
+    throw new Error(
+      `sparring "${slug}" already exists: add this repo with add-repo, or pick another slug`,
+    );
+  const state = {
+    slug,
+    hypothesis: flags.hypothesis,
+    proof: flags.proof,
+    credentials,
+    openedAt: new Date().toISOString(),
+    verdict: null,
+    repos: [
+      repoEntry({ repo, worktree: flags.worktree, base: flags.base, slug }),
+    ],
+  };
+  writeSparring(state);
+  refereeDid(slug, 'abrió el sparring', {
+    detail: state.hypothesis,
+    fields: { repo },
+  });
+  console.log(
+    `sparring ${slug} opened · ${repo} on ${sparringBranch(slug)}\ncard: ${join(dirOf(slug), 'card.md')}`,
+  );
+}
+
+function addRepo(argv) {
+  const { flags, positional } = options(argv);
+  const [slug] = positional;
+  if (!flags.worktree || !flags.base)
+    throw new Error('add-repo needs --worktree and --base');
+  const repo = repoAt(flags.worktree, slug);
+  const state = readSparring(slug);
+  if (state.repos.some((entry) => entry.repo === repo))
+    throw new Error(`${repo} is already in sparring "${slug}"`);
+  writeSparring({
+    ...state,
+    repos: [
+      ...state.repos,
+      repoEntry({ repo, worktree: flags.worktree, base: flags.base, slug }),
+    ],
+  });
+  refereeDid(slug, 'sumó un repo', { detail: repo });
+  console.log(
+    `sparring ${slug} now spans ${[...state.repos.map((e) => e.repo), repo].join(', ')}`,
+  );
+}
+
+/** Creates the label in the repo of `cwd` (the sparring's worktree) unless it is already there. */
+function ensureLabel(cwd, name, color, description, dryRun) {
+  if (labelExists((bin, args) => exec(bin, args, cwd), name)) return;
+  const args = [
+    'label',
+    'create',
+    name,
+    '--color',
+    color,
+    '--description',
+    description,
+  ];
+  if (dryRun) return console.log(`[dry-run] gh ${args.join(' ')}`);
+  exec('gh', args, cwd);
+}
+
+const withRepo = (state, repo, change) => ({
+  ...state,
+  repos: state.repos.map((entry) =>
+    entry.repo === repo ? { ...entry, ...change } : entry,
+  ),
+});
+
+function pr(argv) {
+  const { flags, positional } = options(argv);
+  const [slug] = positional;
+  if (!flags.title) throw new Error('pr needs --title');
+  const state = readSparring(slug);
+  const entry = pickRepo(state, flags.repo);
+  if (entry.pr)
+    throw new Error(
+      `${entry.repo} already has #${entry.pr} in sparring "${slug}"`,
+    );
+  const { config } = loadConfig(entry.worktree, { contract: false });
+  const shortcuts = flags.shortcuts ?? entry.shortcuts ?? '';
+  const siblings = state.repos
+    .filter((item) => item.repo !== entry.repo)
+    .map((item) => siblingLine(item.repo, item.url))
+    .join('\n');
+  const bodyFile = bodyFileOf(slug, entry.repo);
+  writeFileSync(
+    bodyFile,
+    render(template('pr-body.md'), {
+      slug,
+      hypothesis: state.hypothesis,
+      proof: state.proof,
+      siblings: siblings || '_This sparring has no other repo._',
+      howToTest:
+        flags['how-to-test'] ??
+        '_The preview link, once the host publishes it._',
+      shortcuts: shortcuts || '_None stated._',
+      credentials: credentialWarning(state.credentials),
+      credentialsBlock: credentialsBlock(state.credentials),
+    }),
+  );
+  const args = createArgs({
+    title: flags.title,
+    base: entry.base,
+    head: entry.branch,
+    bodyFile,
+    label: config.sparring.label,
+  });
+  ensureLabel(
+    entry.worktree,
+    config.sparring.label,
+    'F26464',
+    'Sparring draft: proves value, never merged',
+    flags['dry-run'],
+  );
+  ensureLabel(
+    entry.worktree,
+    DO_NOT_MERGE,
+    'B60205',
+    'Temporary review PR: never merge',
+    flags['dry-run'],
+  );
+  if (flags['dry-run'])
+    return console.log(
+      `[dry-run] gh ${args.map((a) => JSON.stringify(a)).join(' ')}`,
+    );
+  const url = exec('gh', args, entry.worktree);
+  const number = Number(/\/pull\/(\d+)/.exec(url)?.[1]) || null;
+  writeSparring(withRepo(state, entry.repo, { pr: number, url, shortcuts }));
+  refereeDid(slug, 'abrió el PR', {
+    detail: entry.repo,
+    ...(number ? { pr: number, url } : {}),
+  });
+  console.log(`sparring PR (${entry.repo}): ${url}\nbody: ${bodyFile}`);
+  linkSiblings(state, entry.repo, url);
+}
+
+const bodyFileOf = (slug, repo) =>
+  join(dirOf(slug), `pr-body-${repo.replace('/', '-')}.md`);
+
+/**
+ * Points the PRs opened earlier at the one just opened: their bodies were written while it did
+ * not exist yet. Edits the live body (keeping what anyone changed on GitHub). A failure is
+ * reported, never thrown: the new PR is already open and recorded.
+ */
+function linkSiblings(state, repo, url) {
+  for (const sibling of state.repos.filter(
+    (item) => item.repo !== repo && item.pr,
+  )) {
+    try {
+      const body = exec(
+        'gh',
+        ['pr', 'view', String(sibling.pr), '--json', 'body', '-q', '.body'],
+        sibling.worktree,
+      );
+      const linked = withSiblingUrl(body, repo, url);
+      if (linked === body) continue;
+      const file = bodyFileOf(state.slug, sibling.repo);
+      writeFileSync(file, `${linked}\n`);
+      exec(
+        'gh',
+        ['pr', 'edit', String(sibling.pr), '--body-file', file],
+        sibling.worktree,
+      );
+      console.log(`${sibling.repo} #${sibling.pr} now links ${url}`);
+    } catch (error) {
+      console.error(
+        `could not link ${url} from ${sibling.repo} #${sibling.pr}: ${error.message}`,
+      );
+    }
+  }
+}
+
+/** One look at the deployments of the branch tip. Throws when gh cannot say. */
+function lookPreview(entry, environment) {
+  const sha = exec(
+    'git',
+    ['ls-remote', 'origin', `refs/heads/${entry.branch}`],
+    entry.worktree,
+  ).split(/\s+/)[0];
+  if (!sha) return { state: 'no-branch', url: null, done: true, sha: null };
+  const deployments = JSON.parse(
+    exec(
+      'gh',
+      [
+        'api',
+        `repos/{owner}/{repo}/deployments?sha=${sha}&environment=${encodeURIComponent(environment)}&per_page=1`,
+      ],
+      entry.worktree,
+    ) || '[]',
+  );
+  if (!deployments.length)
+    return { state: 'pending', url: null, done: false, sha };
+  const statuses = JSON.parse(
+    exec(
+      'gh',
+      [
+        'api',
+        `repos/{owner}/{repo}/deployments/${deployments[0].id}/statuses?per_page=1`,
+      ],
+      entry.worktree,
+    ) || '[]',
+  );
+  return { ...previewOf(statuses), sha };
+}
+
+const sleep = (seconds) =>
+  new Promise((done) => setTimeout(done, seconds * 1000));
+
+/** Waits for one repo's preview, bounded by its previewTimeoutMin; null when it configured none. */
+async function previewOfRepo(entry, wait) {
+  const { config } = loadConfig(entry.worktree, { contract: false });
+  const environment = config.sparring.previewEnvironment;
+  if (!environment) return null;
+  // Bounded on purpose: a wait never outlives previewTimeoutMin, and stops on a terminal state.
+  const deadline = Date.now() + config.sparring.previewTimeoutMin * 60_000;
+  let seen = lookPreview(entry, environment);
+  while (wait && !seen.done && Date.now() < deadline) {
+    await sleep(nextPollSeconds(deadline, Date.now()));
+    if (Date.now() >= deadline) break;
+    seen = lookPreview(entry, environment);
+  }
+  return {
+    ...seen,
+    environment,
+    timedOut: wait && !seen.done,
+    timeoutMin: config.sparring.previewTimeoutMin,
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+async function preview(argv) {
+  const { flags, positional } = options(argv);
+  const [slug] = positional;
+  let state = readSparring(slug);
+  const entries = flags.repo ? [pickRepo(state, flags.repo)] : state.repos;
+  for (const entry of entries) {
+    const seen = await previewOfRepo(entry, flags.wait);
+    if (!seen) {
+      console.log(
+        `${entry.repo}: no preview configured (its .claude/ring.json has no sparring.previewEnvironment); the judge tests it locally`,
+      );
+      continue;
+    }
+    state = withRepo(state, entry.repo, { preview: seen });
+    refereeDid(slug, seen.url ? 'preview lista' : 'sin preview', {
+      detail: entry.repo,
+      ...(seen.url
+        ? { url: seen.url, health: 'ok' }
+        : { health: 'warn', reason: seen.state }),
+    });
+    const at = seen.sha ? ` @ ${seen.sha.slice(0, 9)}` : '';
+    console.log(
+      seen.url
+        ? `${entry.repo}: preview ready (${seen.environment}${at}): ${seen.url}`
+        : `${entry.repo}: no preview link: ${seen.state}${seen.timedOut ? ` after ${seen.timeoutMin} min` : ''} (${seen.environment}${at})`,
+    );
+  }
+  writeSparring(state);
+}
+
+function verdict(argv) {
+  const { flags, positional } = options(argv);
+  const [slug, call] = positional;
+  if (!VERDICTS.includes(call))
+    throw new Error(`the verdict is one of ${VERDICTS.join(', ')}`);
+  if (!flags.note)
+    throw new Error('verdict needs --note (why, with the evidence)');
+  const state = readSparring(slug);
+  if (FINAL_VERDICTS.includes(state.verdict?.call))
+    throw new Error(
+      `sparring "${slug}" already has a final verdict (${state.verdict.call}): it cannot be called again`,
+    );
+  const verdict = { call, note: flags.note, at: new Date().toISOString() };
+  writeSparring({
+    ...state,
+    verdict,
+    history: [
+      ...(state.history ?? (state.verdict ? [state.verdict] : [])),
+      verdict,
+    ],
+  });
+  feed(slug, {
+    actor: 'juez',
+    state: 'done',
+    label: `veredicto ${call}`,
+    detail: flags.note,
+  });
+  console.log(
+    `sparring ${slug}: ${call}\ncard: ${join(dirOf(slug), 'card.md')}`,
+  );
+}
+
+/**
+ * The gates the vestidor runs, in this order: the ones that say whether the branch could be
+ * deployed. `test` is left out on purpose: the host's test gate takes `{paths}` (the whole suite is
+ * not one of its gates) and the referee bout runs the tests of what it touches.
+ */
+export const VESTIDOR_GATES = ['typecheck', 'lint', 'build'];
+
+/**
+ * What the vestidor runs, per repo of the sparring, in order. PURE. Refuses unless the last verdict
+ * is a KO. `gatesOf(entry)` gives that repo's resolved gates. Each step is { repo, worktree, runs,
+ * skipped, problems }: a problem (no gate at all, a gate that takes `{paths}`) fails the vestidor
+ * without running anything for that gate.
+ */
+export function vestidorPlan(state, gatesOf) {
+  const call = state.verdict?.call ?? 'no verdict';
+  if (call !== 'ko')
+    throw new Error(
+      `the vestidor comes after a KO; sparring "${state.slug}" is at ${call}`,
+    );
+  return state.repos.map((entry) => {
+    const gates = gatesOf(entry) ?? {};
+    const configured = VESTIDOR_GATES.filter((gate) => gates[gate]).map(
+      (gate) => ({ gate, command: gates[gate] }),
+    );
+    const byPaths = configured.filter((run) => run.command.includes('{paths}'));
+    return {
+      repo: entry.repo,
+      worktree: entry.worktree,
+      runs: configured.filter((run) => !byPaths.includes(run)),
+      skipped: VESTIDOR_GATES.filter((gate) => !gates[gate]),
+      problems: [
+        ...(configured.length
+          ? []
+          : [
+              'no typecheck, lint or build gate (configure it with /ring:weigh-in)',
+            ]),
+        ...byPaths.map(
+          (run) =>
+            `${run.gate} takes {paths}; the vestidor needs a whole-repo command`,
+        ),
+      ],
+    };
+  });
+}
+
+/**
+ * The vestidor's result from its plan and the exit code of each run ({ repo, gate, code }). PURE.
+ * Passes only when every repo ran something, nothing had a problem and every code is 0. `note` is
+ * the one line the milestone keeps: `owner/repo: typecheck 0 · lint 0 · build 0`.
+ */
+export function vestidorOutcome(plan, results) {
+  const codeOf = (repo, gate) =>
+    results.find((r) => r.repo === repo && r.gate === gate)?.code ?? null;
+  const failed = plan.flatMap((step) => [
+    ...step.problems.map((problem) => `${step.repo}: ${problem}`),
+    ...step.runs
+      .filter((run) => codeOf(step.repo, run.gate) !== 0)
+      .map(
+        (run) =>
+          `${step.repo}: ${run.gate} exited ${codeOf(step.repo, run.gate) ?? 'without running'} (${run.command})`,
+      ),
+  ]);
+  const note = plan
+    .map(
+      (step) =>
+        `${step.repo}: ${step.runs.map((run) => `${run.gate} ${codeOf(step.repo, run.gate)}`).join(' · ') || 'nothing ran'}`,
+    )
+    .join('; ');
+  return { passed: failed.length === 0, failed, note };
+}
+
+const MILESTONE_LABELS = {
+  vestidor: 'pasó al vestidor',
+  defense: 'abrió la defensa',
+  bell: 'campana de la defensa',
+  'mask-kept': 'conserva la máscara',
+  'mask-lost': 'pierde la máscara',
+  'no-team': 'sin equipo: directo al árbitro',
+  referee: 'pasó al árbitro',
+};
+
+/** Stamps a milestone on the sparring, tells the feed and says to refresh the chronicle. */
+function stamp(slug, state, kind, note) {
+  const next = withMilestone(state, kind, note);
+  writeSparring(next);
+  refereeDid(slug, MILESTONE_LABELS[kind], { detail: note });
+  console.log(
+    `sparring ${slug}: ${kind} at ${next.milestones.at(-1).at}; refresh the chronicle (/ring:play-by-play --sparring ${slug})`,
+  );
+}
+
+function mark(argv) {
+  const { flags, positional } = options(argv);
+  const [slug, kind] = positional;
+  checkMilestone(kind);
+  stamp(slug, readSparring(slug), kind, flags.note);
+}
+
+/** The last lines of a gate's output, for the referee to see why it failed. PURE. */
+const tail = (text, lines = 20) =>
+  String(text ?? '')
+    .trimEnd()
+    .split('\n')
+    .slice(-lines)
+    .join('\n');
+
+/**
+ * Runs one gate in its repo's worktree through the machine lock (one-at-a-time, as every heavy
+ * command of the ring) and keeps its whole output in `<sparring dir>/vestidor/`.
+ */
+function runGate(slug, step, run) {
+  const out = spawnSync(
+    process.execPath,
+    [join(HERE, 'one-at-a-time.mjs'), 'run', '--', run.command],
+    {
+      cwd: step.worktree,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+  const log = join(
+    dirOf(slug),
+    'vestidor',
+    `${step.repo.replace('/', '-')}-${run.gate}.log`,
+  );
+  mkdirSync(dirname(log), { recursive: true });
+  const output = `${out.stdout ?? ''}${out.stderr ?? ''}${out.error ? `\n${out.error.message}` : ''}`;
+  writeFileSync(log, `$ ${run.command}\n${output}`);
+  const code = out.status ?? 1;
+  console.log(`${step.repo} · ${run.gate}: exit ${code} · ${run.command}`);
+  if (code !== 0)
+    console.log(`  log: ${log}\n${tail(output).replace(/^/gm, '  | ')}`);
+  return { repo: step.repo, gate: run.gate, code };
+}
+
+function vestidor(argv) {
+  const { positional } = options(argv);
+  const [slug] = positional;
+  const state = readSparring(slug);
+  const plan = vestidorPlan(state, (entry) =>
+    existsSync(entry.worktree)
+      ? loadConfig(entry.worktree, { contract: false }).config.gates
+      : null,
+  );
+  const results = [];
+  for (const step of plan) {
+    if (!existsSync(step.worktree)) {
+      step.problems = [`its worktree ${step.worktree} is gone`];
+      continue;
+    }
+    console.log(
+      `${step.repo}: ${step.runs.map((run) => run.gate).join(', ') || 'nothing to run'}${step.skipped.length ? ` (not configured: ${step.skipped.join(', ')})` : ''}`,
+    );
+    for (const run of step.runs) results.push(runGate(slug, step, run));
+  }
+  const outcome = vestidorOutcome(plan, results);
+  if (!outcome.passed) {
+    feed(slug, {
+      actor: 'arbitro',
+      state: 'done',
+      label: 'no pasó el vestidor',
+      detail: outcome.note,
+      health: 'fail',
+      reason: outcome.failed[0],
+    });
+    throw new Error(
+      `the vestidor did not pass; nothing was stamped:\n- ${outcome.failed.join('\n- ')}`,
+    );
+  }
+  stamp(slug, state, 'vestidor', outcome.note);
+}
+
+function playByPlayUrl(argv) {
+  const { positional } = options(argv);
+  const [slug, url] = positional;
+  if (!slug || !url) throw new Error('usage: play-by-play-url <slug> <url>');
+  const next = withChronicleUrl(
+    readSparring(slug),
+    url,
+    undefined,
+    'this fight',
+  );
+  writeSparring(next);
+  refereeDid(slug, 'publicó la crónica', { url });
+  console.log(
+    `play-by-play link for sparring ${slug}: ${url} (published ${next.playByPlay.publishedAt})`,
+  );
+}
+
+/**
+ * After a KO: per repo, `release/<slug>` from its base (reused if it exists), `mainevent/<slug>`
+ * from the sparring tip, and the deliverable PR mainevent → release as a draft. The bout then
+ * starts on that PR (`/ring:referee start --from-sparring <slug>`).
+ */
+function promote(argv) {
+  const { flags, positional } = options(argv);
+  const [slug] = positional;
+  let state = readSparring(slug);
+  const entries = flags.repo ? [pickRepo(state, flags.repo)] : state.repos;
+  for (const entry of entries) {
+    if (!flags['dry-run']) exec('git', ['fetch', 'origin'], entry.worktree);
+    const heads = exec(
+      'git',
+      ['ls-remote', '--heads', 'origin'],
+      entry.worktree,
+    )
+      .split('\n')
+      .map((line) => line.split(/\s+/)[1]?.replace('refs/heads/', ''))
+      .filter(Boolean);
+    const plan = promotionPlan(state, entry, heads);
+    const bodyFile = join(
+      dirOf(slug),
+      `mainevent-body-${entry.repo.replace('/', '-')}.md`,
+    );
+    writeFileSync(
+      bodyFile,
+      [
+        `Entregable del sparring \`${slug}\` (KO: ${state.verdict.note}).`,
+        '',
+        `- Borrador que validó el KO: ${entry.url ?? `\`${entry.branch}\``} (do-not-merge, no se mezcla).`,
+        `- Esta rama nace de su punta; el combate del ring la limpia aquí. Llega a \`main\` por \`${plan.release}\`.`,
+        '- Antes de limpiar, el contrato (spec y modelos) se le muestra al juez y queda congelado hasta que lo apruebe.',
+        '',
+        `Hipótesis: ${state.hypothesis}`,
+      ].join('\n'),
+    );
+    const args = mainEventArgs({
+      title: flags.title ?? `${slug}: entregable del sparring`,
+      release: plan.release,
+      mainevent: plan.mainevent,
+      bodyFile,
+    });
+    if (flags['dry-run']) {
+      for (const refspec of plan.pushes)
+        console.log(`[dry-run] git push origin ${refspec}`);
+      console.log(
+        `[dry-run] gh ${args.map((a) => JSON.stringify(a)).join(' ')}`,
+      );
+      continue;
+    }
+    for (const refspec of plan.pushes)
+      exec('git', ['push', 'origin', refspec], entry.worktree);
+    const url = exec('gh', args, entry.worktree);
+    const number = Number(/\/pull\/(\d+)/.exec(url)?.[1]) || null;
+    state = withRepo(state, entry.repo, {
+      mainevent: {
+        branch: plan.mainevent,
+        release: plan.release,
+        pr: number,
+        url,
+      },
+    });
+    refereeDid(slug, 'promovió el KO', {
+      detail: `${entry.repo}: ${plan.mainevent} → ${plan.release}`,
+      ...(number ? { pr: number, url } : {}),
+    });
+    console.log(`${entry.repo}: ${plan.mainevent} → ${plan.release}: ${url}`);
+  }
+  writeSparring(state);
+}
+
+/** Days before a sparring without a verdict is stale: its first repo's config, else the default. */
+function staleDaysOf(state) {
+  try {
+    return loadConfig(state.repos[0].worktree, { contract: false }).config
+      .sparring.staleDays;
+  } catch {
+    return DEFAULTS.sparring.staleDays;
+  }
+}
+
+function list() {
+  const current = existsSync(sparringsHome())
+    ? readdirSync(sparringsHome()).filter((slug) => existsSync(fileOf(slug)))
+    : [];
+  const legacy = legacyRecords().map((record) => record.slug);
+  const slugs = [...new Set([...current, ...legacy])].sort();
+  if (!slugs.length) return console.log('no sparrings');
+  const now = new Date().toISOString();
+  for (const slug of slugs) {
+    const state = readSparring(slug);
+    const repos = state.repos
+      .map((entry) => `${entry.repo}${entry.pr ? ` #${entry.pr}` : ''}`)
+      .join(', ');
+    console.log(
+      [
+        state.slug,
+        repos,
+        state.verdict?.call ?? 'no verdict',
+        `${ageDays(state.openedAt, now)} d`,
+        isStale(state, now, staleDaysOf(state)) ? 'STALE' : '',
+      ]
+        .filter(Boolean)
+        .join(' · '),
+    );
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const [command, ...rest] = process.argv.slice(2);
+  const run = {
+    open,
+    'add-repo': addRepo,
+    pr,
+    preview,
+    verdict,
+    vestidor,
+    mark,
+    'play-by-play-url': playByPlayUrl,
+    promote,
+    list,
+  }[command];
+  if (!run) {
+    console.error(
+      'Usage: node sparring.mjs open <slug> … | add-repo <slug> --worktree <abs> --base <b> | pr <slug> --title <t> [--repo <owner/repo>] | preview <slug> [--repo <owner/repo>] [--wait] | verdict <slug> ko|rematch|discard --note <t> | vestidor <slug> | mark <slug> <milestone> [--note <t>] | play-by-play-url <slug> <url> | promote <slug> [--repo <owner/repo>] [--title <t>] [--dry-run] | list',
+    );
+    process.exit(1);
+  }
+  Promise.resolve()
+    .then(() => run(rest))
+    .then(() => {
+      // Reading the list is not refereeing: only the commands that act register the session.
+      const session = process.env.CLAUDE_CODE_SESSION_ID;
+      if (command !== 'list' && session)
+        registerSparringSession(dirOf(rest[0]), session);
+    })
+    .catch((error) => {
+      console.error(
+        `sparring: ${error.stderr?.toString().trim() || error.message}`,
+      );
+      process.exit(1);
+    });
+}