@thebattlearena/corner 0.8.0 → 0.9.0

package/ring/skills/play-by-play/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: play-by-play
-description: Narrates a ring bout as a Battle Arena sports chronicle (rounds, blows, fouls, bells) with the real time of each event, and publishes it as a private Artifact page that keeps one stable link for the life of the bout. Invoke with `/ring:play-by-play <pr>`, "write the chronicle of the bout", "update the play-by-play".
-argument-hint: "<pr>"
+description: Narrates a ring bout as a Battle Arena sports chronicle (rounds, blows, fouls, bells) with the real time of each event, and publishes it as a private Artifact page that keeps one stable link for the life of the bout. A fight that starts at a sparring is one chronicle from the sparring's opening, two out of three falls. Invoke with `/ring:play-by-play <pr>`, `/ring:play-by-play --sparring <slug>`, "write the chronicle of the bout", "update the play-by-play".
+argument-hint: "<pr> | --sparring <slug>"
 ---
 
 # play-by-play
@@ -25,6 +25,37 @@ re-request closes it), `events` (type, real time `at`, `local` HH:MM, title, det
 `falta`, `juez`, `arbitro`, `bateria`, `campana`. The classification rules are at the top of
 `$RING/scripts/chronicle.mjs`.
 
+### A fight that starts at a sparring
+
+The chronicle starts at the sparring, so its material never ends up scattered:
+
+```bash
+node "$RING/scripts/play-by-play.mjs" --sparring <slug> --tz <the human's time zone> [--extra <json|file>] [--no-gh]
+```
+
+It prints the same shape plus `falls`, `catalogs`, `bouts` and the `page` to write. The fight is
+told in three falls, and every event carries its `fall`, its `round` and its `day` (a fight spans
+days):
+
+1. **First fall, the rudo against the judge** (rounds `s1`, `s2`…): from `open` to the KO, one
+   round per verdict of `history[]` (a rematch closes one and opens the next). The judge's Tapes
+   are attacks at the time the catalog writes next to them; each round's catalog
+   (`blows-round-<n>.md`) is in `catalogs`, every D/B/F/Q blow with its Tape minute, to narrate
+   them by minute of the Tape, never by an invented clock time.
+2. **Second fall, the defense of the técnicos** (round `defense`): from the KO (or the first
+   milestone of the defense, if it came first) through the vestidor (the host gates), the
+   defense opened to the team, its Tapes, the bell and whether the rudo keeps or loses the mask.
+   With «sin equipo» (`no-team`) there is no second fall: that fall comes `skipped` and the
+   third starts at the judge's call; tell it in one line, never as an empty fall.
+3. **Third fall, the referee**: from the hand-off, every bout opened `--from-sparring <slug>`,
+   each with its own rounds (`<pr>/<n>`, as a bout's chronicle has them).
+
+The milestones exist only if the sparring's referee marked them when they happened
+(`sparring.mjs vestidor <slug>`, `sparring.mjs mark <slug> defense|bell|mask-kept|mask-lost|no-team`); `judges-card open
+--from-sparring` marks the hand-off. A moment nobody marked is not in the JSON: say it as a gap,
+or bring its time through `--extra` when someone provided it.
+`/ring:play-by-play <pr>` on a bout opened from a sparring prints the same whole fight.
+
 Times the records do not hold (a battery run the host logs elsewhere, a screenshot the human
 sent) enter only through `--extra` (an array of `{ at, type, title, detail, ref }`, inline or as
 the path of a JSON file), and they stay marked `provided`.
@@ -45,7 +76,9 @@ dark mode, no external scripts, only the Google Fonts stylesheet). Keep its stru
 - masthead with the live status, headline with the PR number, a two-sentence dek, the byline;
 - the fight card (champion vs challenger) and the crew line;
 - the tally (duration, Copilot findings, commits, fouls) and the legend of the eight tags;
-- one section per round, each beat with its time in the margin and its source in `.ref`;
+- one section per round, each beat with its time in the margin and its source in `.ref`; in a
+  fight from a sparring, the rounds go under a header per fall (`h3.fall`), the card is the rudo
+  against the judge, and the first beat of each day says the day;
 - exactly two pull quotes in the whole chronicle;
 - the judges' card table and the sources footer.
 
@@ -62,6 +95,15 @@ link (a second, different link is refused), and every time it stamps `playByPlay
 
 Then offer, once, to put the link in the PR body; do it only with the human's yes.
 
+**A fight from a sparring has one page and one link.** Write it to
+`<sparring dir>/play-by-play.html` (the JSON's `page`), always that path, whether it is refreshed
+from the sparring or from one of its bouts. If `sparring.json` already has `playByPlayUrl`,
+publish with `url` set to it. After every publish from the sparring, run
+`node "$RING/scripts/sparring.mjs" play-by-play-url <slug> <url>`; from a bout,
+`judges-card.mjs play-by-play-url <pr> <url>` as always, which refuses any link but the fight's and
+also stamps the sparring. The sparring keeps its first link for the whole fight, through every
+bout of every repo.
+
 ## Rules
 
 - **No invented times.** A gap is said as a gap: the beat goes where it must have happened, with
@@ -81,3 +123,7 @@ Then offer, once, to put the link in the PR body; do it only with the human's ye
 
 The referee and title-defense refresh it after each round-bell and at each bell (the Copilot
 re-request); `close` publishes the final edition, with the status "Final".
+
+In a sparring, the referee of the sparring publishes it first at `open` and refreshes it after
+each verdict, after the vestidor, when the defense opens and at the bell. Those refreshes report;
+like every chronicle, they decide nothing about the sparring.

package/ring/skills/play-by-play/templates/chronicle.html

@@ -58,6 +58,7 @@ h1 em{font-style:normal;color:var(--red)}
 blockquote{margin:22px 0 22px 74px;padding:0 0 0 18px;border-left:4px solid var(--gold);font-size:21px;line-height:1.45;font-style:italic;max-width:56ch}
 @media (max-width:560px){blockquote{margin-left:0}.beat{grid-template-columns:minmax(0,1fr);gap:2px}}
 .ref{display:block;font-family:var(--f-mono);font-size:12px;color:var(--muted);margin-top:4px;overflow-wrap:anywhere}
+h3.fall{font-family:var(--f-label);font-weight:700;font-size:15px;letter-spacing:.1em;text-transform:uppercase;color:var(--red);margin:56px 0 -28px;border-top:3px double var(--ink);padding-top:10px}
 h3.section{font-family:var(--f-display);font-weight:400;font-size:24px;text-transform:uppercase;margin:52px 0 10px;border-top:3px solid var(--ink);padding-top:12px}
 .tbl{overflow-x:auto;background:var(--paper);border:1px solid var(--rule)}
 table{border-collapse:collapse;width:100%;min-width:600px;font-family:var(--f-label);font-size:15.5px}
@@ -78,6 +79,10 @@ footer{margin-top:44px;font-family:var(--f-label);font-size:14px;color:var(--mut
     t-bateria, t-campana; a foul beat also gets class "falta";
   - .ref under each beat says where the time came from (decision id, sha, review, run);
   - exactly two blockquotes (pull quotes) in the whole chronicle;
+  - a fight from a sparring (--sparring): one <h3 class="fall"> before the first round of each
+    fall of the JSON (first fall: the rudo against the judge; second: the defense of the técnicos;
+    third: the referee), the card is the rudo against the judge, and the first beat of each day
+    says the day (the event's `day`) in its prose;
   - no scripts; only the Google Fonts stylesheet above loads from outside.
 -->
 <div class="wrap">
@@ -105,6 +110,8 @@ footer{margin-top:44px;font-family:var(--f-label);font-size:14px;color:var(--mut
     <span class="tag t-reclamo">{{Reclamo de Copilot}}</span><span class="tag t-dado">{{Golpe dado}}</span><span class="tag t-recibido">{{Golpe recibido}}</span><span class="tag t-falta">{{Falta}}</span><span class="tag t-arbitro">{{Árbitro}}</span><span class="tag t-juez">{{Juez}}</span><span class="tag t-bateria">{{Batería}}</span><span class="tag t-campana">{{Campana}}</span>
   </div>
 
+  <!-- In a fight from a sparring, before the first round of each fall:
+  <h3 class="fall">{{e.g. "Primera caída · el rudo contra el juez"}}</h3> -->
   <!-- One section per round of the JSON; round 0 is the preview ("La previa"). -->
   <section class="round">
     <h2>{{ROUND NAME, e.g. "Round 1 · siete golpes de entrada"}}</h2>

package/ring/skills/referee/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: referee
 description: Orchestrates a refactor or a large delivery on a backend, frontend or mobile PR as its referee, at the venue the PR belongs to. One long-lived wrestler (effort medium) writes in its own worktree; you (effort high) review each commit range with read-only cornermen against a numbered rulebook, send one rebound package at a time, open small do-not-merge round-bell PRs so the human reviews early, decide design doubts yourself from the rulebook and precedents (escalating only a short hard list), and keep a durable judges card so any new session can resume. Invoke with `/ring:referee start <pr>`, `/ring:referee resume [<pr>]`, `/ring:referee close`, "referee the refactor of #N", "resume the bout".
-argument-hint: "start <pr> | resume [<pr>] | close"
+argument-hint: "start <pr> | start --from-sparring <slug> | resume [<pr>] | close"
 ---
 
 # referee
@@ -79,6 +79,50 @@ list reaches the human.
 
 ## 1 · `start <pr>`
 
+**`--from-sparring <slug>`**: the bout cleans the deliverable of a sparring the judge called KO
+(`/ring:sparring`). Before step 1, read `~/.claude/ring/sparrings/<slug>/card.md`
+(`node "$RING/scripts/sparring.mjs" list` names them) and refuse unless its verdict is `ko`. A
+sparring that spanned several repos gets one bout per repo; this one covers this session's repo.
+**The `<pr>` is not needed**: unless the sparring was already promoted (its `sparring.json` names a
+`mainevent` for this repo), run `node "$RING/scripts/sparring.mjs" promote <slug> --repo
+<owner/repo>`. It creates `release/<slug>` from the repo's base, `mainevent/<slug>` from the
+sparring tip, and opens the deliverable PR mainevent → release as a draft; that PR is the bout's
+`<pr>` and `release/<slug>` its **stack base**. The branches:
+
+```
+main
+ └─ release/<slug>               reaches main in one PR at the end (the release exception of the line ceiling)
+     └─ mainevent/<slug>         PR → release; the wrestler cleans everything here, no line ceiling
+         └─ ring/<pr>/round-<n>  round-bells, do-not-merge as always: the human reads each concept
+sparring/<slug>                  do-not-merge, never merged: the evidence of what the KO saw
+```
+
+Never push `sparring/*` to another branch by hand (mask-guard refuses it): `promote` is the only
+way out, and it refuses without a KO. Then the bout runs as always, with three inputs from the card:
+
+- **What the judge validated is the behavior that must not change**: write it as numbered
+  invariants for the concept-mode cornerman, and add characterization tests first (T rules).
+- **The rudo's shortcuts for this repo are the first rebound package**, blockers first.
+- **The contract the sparring drafted goes through §2b** like any other: nothing of it is approved
+  because the sparring used it. Its credentials (by name) are a hard-list item: taking a sandbox
+  key's variable to production is the human's.
+- **Open it with `--from-sparring <slug>`** (step 5): `judges-card.mjs open` refuses a sparring
+  that is not a KO, records `fromSparring` and marks the hand-off on the sparring. The bout is then
+  the third fall of the sparring's chronicle: one page and one link for the whole fight
+  (`/ring:play-by-play`).
+- **That contract is shown to the judge first, without the judge asking for it.** Right after
+  opening the bout (step 5) and before the first wrestler brief: list every file under
+  `config.apiSpec` and `config.dbModels` that changes between the stack base and the PR head
+  (`git diff --name-only <base>...<head> -- <those paths>`), have a cornerman review it (§2b
+  step 3), draw the diagram of every migration (§2b step 4), serve `contract-preview.mjs`, and
+  escalate it all as **one** contract escalation: the preview URL, the spec diff, each migration
+  with its backfill, and your recommendation. Until `approve-contract` records the judge's yes for
+  exactly those files (already committed, so the hashed content is the one at the PR head), the
+  whole contract zone is frozen: the wrestler cleans only what does not touch those files, and no
+  rebound changes them. Starting the cleanup before that escalation is a foul; log it in the
+  judges card.
+
+
 1. `gh pr view <pr> --json number,title,url,headRefName,baseRefName,files`. The **stack base** is
    `baseRefName` unless the human names another one; ask if the PR is part of a stack.
 2. **Venue.** `gh pr diff <pr> --name-only | node "$RING/scripts/config.mjs" venue`, or
@@ -93,7 +137,7 @@ list reaches the human.
    `git worktree add --detach <abs path> origin/<headRefName>` (after `git fetch origin`). Never
    launch the wrestler with `isolation: "worktree"`: that creates another tree on another branch.
 5. Open the bout: `node "$RING/scripts/judges-card.mjs" open --pr <pr> --worktree <abs path>
-   --branch <headRefName> --base <stack base> --venue <venue>`. This activates `mask-guard` for this repo.
+   --branch <headRefName> --base <stack base> --venue <venue> [--from-sparring <slug>]`. This activates `mask-guard` for this repo.
    It refuses to open when `.claude/ring.json` leaves `apiSpec` or `dbModels` empty while the repo
    has specs or migrations: fix the config (paths or globs; `null` means "detect") rather than
    passing `--allow-empty-contract`, which is only for a bout that truly has no contract. Then

package/ring/skills/sparring/SKILL.md

@@ -0,0 +1,408 @@
+---
+name: sparring
+description: Opens a sparring, a quick and deliberately low-quality draft (one PR per repo it touches, back and front included) that only proves whether a feature is worth building, before anyone pays for building it well. A rudo per repo (effort medium) writes it inside a timebox in its own worktree; the draft PR (labels sparring + do-not-merge) is the event the host project's CI catches to deploy a preview; credentials travel by name only. The judge calls KO, rematch or discard, in two out of three falls: a KO passes the host gates (vestidor), faces the team's Tapes until a bell (unless «sin equipo»), keeps or loses the mask, and then hands each branch to a ring bout. Invoke with `/ring:sparring <idea | Linear ticket>`, `/ring:sparring preview <slug>`, `/ring:sparring verdict <slug>`, `/ring:sparring list`, "make a quick draft of this to try it", "spar this feature first".
+argument-hint: '<idea | ticket> | preview <slug> | verdict <slug> | vestidor <slug> | list'
+---
+
+# sparring
+
+A sparring answers one question, "is this worth building?", with evidence. The code is
+disposable in quality, not in behavior: if the judge calls a KO, a ring bout refactors the same
+branch and keeps what the judge validated. You are the referee of the sparring; the rudo writes.
+
+**The judge sees the whole experience, working, never an isolated or superficial piece.** A
+sparring shows the full screen or flow the feature lives in (the list, the detail, the filters and
+the new piece, as the design draws them), and **every control on it works**: search, filters, tabs,
+loaders, pagination or infinite scroll, actions and their errors. The data comes from the back,
+built quick and dirty for the sparring; a mock is only for what cannot be had yet (an external
+provider, data no environment has). A widget on an empty page, or a screen of buttons that do
+nothing, leaves the judge without what they need to call the verdict. The code is thrown away, so
+cutting scope or depth saves nothing that matters: the speed comes from the quality you skip.
+
+## Pace
+
+A sparring is careless code that puts working first, so it is fast or it is wrong. The judge
+clicks a first working version of the whole screen **within 90 minutes** of the interview; the
+rest of the timebox goes to the controls that are still dead. Where time goes, and what you cut:
+
+- **The interview is one message with your proposed answers**; the judge answers with "yes" or a
+  correction. Everything that does not change the hypothesis, the proof, the scope or a hard stop,
+  you decide without asking, then and while the rudos work.
+- **Contract first, in the first 15 minutes.** With several repos, the producer writes the contract
+  (routes, shapes, error codes) to `<sparring dir>/contrato.md` before implementing, and every rudo
+  starts at once against it. The consumer never waits for the producer's code.
+- **Ceremony the rudo skips:** migrations in the repo (tables come from a SQL in `tools/`), OpenAPI
+  and generated types until the last push, typecheck after every edit (only before each push),
+  tests, wiki, DTOs, CQRS, ports, feature flags. Each one goes on the shortcuts list.
+- **Data is seeded locally first**, without asking: synthetic rows, enough to look like the design.
+  A shared database only when the judge asks for it.
+- **Report early, not only at the end:** each rudo reports its first clickable version and then
+  every hour, so a wrong direction is caught at minute 60, not at hour 5.
+
+## 0 · Every time you are invoked
+
+1. **Paths.** `RING` is the plugin root: two directories above this skill's base directory
+   (`${CLAUDE_PLUGIN_ROOT}` when it is expanded). Script: `$RING/scripts/sparring.mjs`. Templates:
+   `$RING/skills/sparring/templates/`. The host contract:
+   `$RING/skills/sparring/references/host-signal.md`.
+2. **The repos are the sparring's, not the session's.** A sparring may target repos other than the
+   checkout this session runs in, and may span several (a back and its front). Every script call
+   names its repo by worktree; never rely on the session's directory.
+3. **Config, per repo.** `node "$RING/scripts/config.mjs" show` run from inside each repo's
+   worktree: read `config.sparring` (label, `previewEnvironment`, `previewTimeoutMin`,
+   `staleDays`) and `config.gates.typecheck`. A repo without `previewEnvironment` has no preview:
+   say it once and plan for a local test.
+4. **State** lives in `~/.claude/ring/sparrings/<slug>/` (`sparring.json`, `card.md`, `tools/`),
+   one directory per sparring whatever repos it spans. It is not a bout: no lookout, no cornermen,
+   no round-bells. A sparring recorded per repo by an older version is merged into one the first time a command reads it; its `tools/` and notes move along, with a symlink left at the old path.
+5. **Lessons.** Read `$RING/skills/sparring/references/lessons.md`: what earlier judges asked for
+   when they called rematch or discard. Plan with them, and paste the ones that apply into every
+   rudo brief.
+6. **Chronicle.** The fight's chronicle starts at `open`, not at the referee bout: publish it then
+   (`/ring:play-by-play --sparring <slug>`) and refresh it after each verdict, after the vestidor,
+   when the defense opens, at the bell and at the mask, marking each of those moments first (§4:
+   `sparring.mjs vestidor <slug>` stamps the vestidor; `sparring.mjs mark <slug>
+defense|bell|mask-kept|mask-lost|no-team` the rest).
+
+## 1 · `/ring:sparring <idea | ticket>`
+
+1. **Read the input first.** When the idea comes with a plan, a ticket or an artifact, check what
+   of it already exists in the code before asking anything: that decides the scope question.
+2. **Short interview** (one message, numbered, answerable in one line each). Skip what the idea or
+   the ticket already says:
+   - **Hypothesis:** "if X exists, the team / customer does Y".
+   - **Proof of value:** what the judge has to _see_ to say yes. Observable and unambiguous; "it
+     looks good" is not one.
+   - **The full screen the judge will see:** which screen or flow, complete, the feature lives in,
+     and what of it already exists. What is missing (the screen the idea stands on, an endpoint, a
+     table) is built quick and dirty or mocked so the whole experience is there; never a
+     placeholder. Ask only what stays out on purpose.
+   - **Repos:** which ones it touches (back, front, both) and their base branches (default: each
+     repo's default branch). All of them belong to this one sparring.
+   - **Designs:** a `.pen` frame, a Figma link or images the rudo has to follow, if any.
+   - **Timebox:** 3 h at most. If it does not fit, split it and spar the riskiest part first.
+   - **Credentials:** which provider lab it needs and the NAMES of the variables
+     (`KAPSO_API_KEY`). Never ask for, accept or repeat a value; if the human pastes one, do not
+     echo it and tell them to rotate it.
+   - **Real sends to the judge:** whether the proof needs a message, call or email that really
+     leaves through the provider (§1.8). Only to the judge's own test destinations.
+3. **Hard stops before starting** (escalate, do not open): a production credential, real money,
+   messages or calls to customers, customer data or PII in fixtures, or a destructive schema
+   change. Those break rule F or the additive-only rule. The one exception is §1.8: real sends to
+   the judge's own allowlisted destinations, with their explicit yes.
+4. **A worktree per repo**, outside every main checkout, e.g. a sibling `<repo>-sparring-<slug>`:
+
+   ```bash
+   git -C <repo checkout> fetch origin
+   git -C <repo checkout> worktree add -b sparring/<slug> <abs path> origin/<base>
+   ```
+
+5. **Open it** with the first repo, then add the others. Credential names are validated: anything
+   that is not `UPPER_SNAKE_CASE` is refused, so a value never lands in the state.
+
+   ```bash
+   node "$RING/scripts/sparring.mjs" open <slug> --worktree <abs path> --base <base> \
+     --hypothesis "<…>" --proof "<…>" [--credentials NAME,NAME]
+   node "$RING/scripts/sparring.mjs" add-repo <slug> --worktree <abs path of the other repo> --base <base>
+   ```
+
+6. **Credentials, locally:** give the judge the path `<worktree>/.env.sparring` of each repo that
+   needs them and the names to fill. They fill it; you never read it back. For a host's preview,
+   give the judge the command to load each missing secret into that host's store
+   (`gh secret set <NAME> --env <previewEnvironment>`); loading secrets is theirs.
+7. **Launch a rudo per repo**, all in the background, each with `templates/rudo-brief.md` filled
+   for its repo (scope, designs, the other repos and what they exchange):
+
+   ```
+   Agent{subagent_type: "ring:rudo", effort: "medium", run_in_background: true,
+         description: "Rudo: <slug> <repo>", prompt: <the brief>}
+   ```
+
+   Never `isolation: "worktree"`. When one repo produces what another consumes (the back's SDK or
+   endpoint for the front), say so in both briefs: the producer goes first and leaves the hand-off
+   in `<sparring dir>/tools/` (§2).
+
+8. **Real sends to the judge** (a message, call or email that really leaves through the provider),
+   only when the proof needs it and the judge said yes. The destinations are **the judge's own and
+   change with every judge**: they are never asked for in chat, never written in code, a fixture,
+   the card, a commit or a log. The judge fills them in `<worktree>/.env.sparring`, one variable
+   per kind, `SPARRING_ALLOWED_<KIND>` (`SPARRING_ALLOWED_PHONES`, `SPARRING_ALLOWED_EMAILS`,
+   `SPARRING_ALLOWED_CHAT_IDS`…), comma-separated. The code that sends:
+   - **closed by default:** an empty or missing variable sends nothing;
+   - sends only when the destination is on the list, normalized the same way on both sides (for
+     phones, digits only);
+   - records every other attempt without sending it (`{ sent: false, reason: "not_allowlisted" }`),
+     so the screen still works with seeded destinations;
+   - logs whether it sent, never the destination.
+
+   The provider's credentials go by name like any other (§1.6); a production key is still a hard
+   stop unless the judge explicitly accepts it for these sends, and then the allowlist is the only
+   guard, so say so. The variables are listed in the card by name, never their values. The
+   allowlist is per sparring and per judge: a later judge fills their own.
+
+## 2 · While the rudos work
+
+- Their doubts come to you: decide them for speed (the fastest way to show the whole experience)
+  and only take to the human what changes the hypothesis, the proof, the scope or the hard stops.
+- Check each report against the hard stops, not against style: a secret in a diff
+  (`git -C <wt> diff <base>...HEAD`), a non-additive migration, a real provider endpoint outside
+  sandbox mode. Any of those goes back to that rudo before anything else.
+- **Hand-off between repos.** Nothing is published to a registry for a sparring. The producer
+  leaves what the consumer needs in `<sparring dir>/tools/` (an SDK as an `npm pack` tarball, a
+  fixture, a mock) and reports its path, the port it serves on and one `curl` that proves it; you
+  forward that to the consumer's rudo, which installs it from there.
+- **Seeding a shared database** (dev, staging) when the proof needs data that does not exist yet,
+  because the feature is new: only with the judge's explicit yes. The rudo prepares it, never runs
+  it: synthetic rows only, each one marked with the sparring's slug, values that can reach nobody
+  (phones with an unassigned prefix, `example.invalid` emails), a dry run that prints what it
+  would write, and a cleanup that deletes only the marked rows, ready **before** seeding. Write the
+  seed and the cleanup commands under "Seed" in the card's notes (below the notes marker, which every rewrite keeps). **The judge runs the seed**, with `!` in
+  their session; the referee and the rudo never write to a shared database, and a write the
+  session's permissions block is never retried another way. Cleaning up is pending until the
+  verdict.
+- At the end of the timebox each rudo stops. A second timebox is the human's call (§4 rematch).
+
+## 3 · The PRs and the preview
+
+1. When a rudo pushed something worth trying, open its repo's PR (`--repo` can be left out only
+   when the sparring has one repo). Each PR body links the other repos of the sparring:
+
+   ```bash
+   node "$RING/scripts/sparring.mjs" pr <slug> --repo <owner/repo> --title "<feature>" \
+     --how-to-test "<steps from the rudo>" --shortcuts "<the rudo's list>"
+   ```
+
+   It opens the draft with the sparring and do-not-merge labels (created in that repo when it
+   lacks them) and the credentials block (names only) and warning. That PR is the event the
+   repo's CI catches.
+
+2. Previews: `node "$RING/scripts/sparring.mjs" preview <slug> --wait` with
+   `run_in_background: true` looks at every repo (or one, with `--repo`), each bounded by its own
+   `previewTimeoutMin`. Give the judge a link only when it printed one; otherwise say exactly what
+   it printed (no preview configured, pending, failure, timed out). Never say "ready to try"
+   without the link in hand.
+3. **Local test** for the repos without a preview: one runbook for the judge, in order. The
+   producer first (how to start it, its port, `.env.sparring`, the `curl` that proves it), then
+   each consumer pointed at it (the env var with the producer's URL, how to install the hand-off
+   from `tools/`, how to start it, the URL to open). Ports must not collide with what the judge
+   already runs; ask when unsure. Locally, the producer accepts requests from any
+   `http://localhost:<port>` origin (CORS), never a single fixed port; that is a shortcut to list.
+4. **Before announcing it, click everything.** A browser pass (Playwright or the like) over each
+   screen at the sizes the design draws, clicking every visible control and listing the ones that
+   do nothing, have no loader or fail silently. A dead control goes back to its rudo; the
+   sparring is not announced until the list is empty or the judge accepted what is left.
+5. Tell the judge, in one short message: **the exact URL of each screen to open** (with its path,
+   not just the host), **the user, workspace or account to enter with**, what to look at first,
+   the links or the runbook, the hypothesis, the proof of value to check, and the credentials
+   warning. A sparring with a front is never announced without the screen's URL.
+
+## 4 · `verdict <slug>`: two out of three falls
+
+The fight has three falls, in this order: the rudo against the judge (verdicts), the defense of the
+técnicos (the team's Tapes, after the vestidor) and the técnico (the referee bout). Mark each
+moment when it happens (`sparring.mjs mark`, §0.6) so the chronicle has its real time.
+
+### First fall · the rudo against the judge
+
+#### The judge attacks with a Tape
+
+When the rudos deliver, the judge attacks: they record their review as a Tape session
+(`battlearena.dev/t/<id>`), voice over their own clicks, and hand it to the battle so it knows every
+blow it took. That Tape is the evidence of the verdict and the brief of the next round.
+
+1. **Read it yourself**, with the Tape tools (`qa_session_overview`, `qa_session_timeline` with
+   speech, `qa_session_errors`, `qa_session_frame` for what was on screen). Never work from a
+   summary someone else wrote.
+2. **One voice: you, the referee of the sparring, write the catalog of blows.** Nobody else
+   (another session, a monitor, a rudo) sends their own version to the rudos; if one reaches you,
+   reconcile it into yours before anything goes out. Two catalogs of one verdict make the rudos
+   fight different fights.
+3. **The catalog** goes to `<sparring dir>/blows-round-<n>.md`, each blow with the Tape minute and
+   the judge's words when they matter:
+   - **Decisions** of the judge (D1, D2…): product calls the rudos apply, never reopen.
+   - **Bugs** (B1…): what broke, how to reproduce it.
+   - **Missing** (F1…): what the judge expected to find.
+   - **Questions for the judge** (Q1…): design doubts the rudos answer with a proposal, not a
+     question back.
+   - **Noise**: what failed on screen but is not the sparring's (a third-party widget, an
+     unrelated 401); listed so nobody fixes it.
+
+   Then split it **by repo**: each rudo gets only its own blows, plus the decisions that touch it.
+
+4. Record the verdict with the Tape as evidence (`--note "Tape <url> (<date time>): D1…; …"`) and
+   link the catalog in the card's notes. The card keeps every round (earlier verdicts stay under
+   "Earlier rounds").
+
+#### The call
+
+Ask the judge for the call and the evidence (a Tape session, screenshots, what they saw), then
+`node "$RING/scripts/sparring.mjs" verdict <slug> <ko|rematch|discard> --note "<why · evidence>"`.
+
+- **rematch:** adjust and try again inside a new timebox; send the rudo what changes.
+- **discard:** list the PRs for the human to close (`gh pr close <n> --delete-branch` is theirs).
+  The card keeps why: a discarded idea is a result too.
+- **ko:** it is worth building, and the first fall is over. It does **not** go to the referee yet:
+  ask the judge, in the same message, whether the team defends it (default) or it goes on «sin
+  equipo». With «sin equipo», `node "$RING/scripts/sparring.mjs" mark <slug> no-team` and jump to
+  the third fall: no vestidor, no defense. Otherwise, the vestidor.
+
+After a **rematch** or a **discard**, distill the judge's reason into a rule that holds for the
+next sparring and append it to `references/lessons.md` (rule, date, slug), unless a lesson already
+says it. That is how one judge's feedback reaches every later sparring, not only this one.
+
+### The vestidor (after the KO, before the team)
+
+Until the KO the sparring stays local, fast and ugly; nothing of what follows is prepared earlier,
+so the rudo neither worries about it nor spends time on it. Now it has to look serious, whatever
+the repo: **every repo of the sparring passes its host's own gates**, so each PR could be deployed
+if needed.
+
+1. `node "$RING/scripts/sparring.mjs" vestidor <slug>` (refused unless the last verdict is `ko`).
+   In each repo's worktree it runs that repo's top-level gates from `.claude/ring.json` (or
+   autodetected): `typecheck`, `lint` and `build` when configured, one at a time through the
+   machine lock; `test` never (it takes paths; the referee bout runs the tests). It prints each
+   gate with its exit code, keeps the logs in `<sparring dir>/vestidor/`, and stamps the
+   `vestidor` milestone only when all of them passed; otherwise it stamps nothing and exits 1.
+2. A red gate goes back to its rudo. A lint rule that only blocks the build may be switched off on
+   the sparring branch, listed as a shortcut. **Typecheck is never switched off.** Run the vestidor
+   again until it passes.
+3. **Now, and only now, the sharing prep**, as one step, expecting all of it to bite at once:
+   - the schema in additive migrations (or loaded into the shared database), not only a `tools/` SQL;
+   - any SDK or hand-off the front needs, vendored on the branch when it is not published;
+   - identity per judge from their session, never one shared operator;
+   - a seed of the shared environment with enough data to look like the local run (§2: the judge
+     runs it). Real data only with the judge's own yes, given in your session, for that environment;
+   - the allowlist of real sends stays closed for everyone but the judge.
+4. **Deploy through the host's own mechanism** (its preview or sandbox workflow), never one of the
+   ring's. Click everything with a logged-in session before sharing the URLs.
+5. **A short guide for the team:** the URLs with their path, how to log in, what to try first,
+   the hypothesis, how to record a Tape and where to send it (ask the judge where).
+
+### Second fall · the defense of the técnicos
+
+The judge opens the arena to the team («¡a la defensa de los técnicos!»), mandatory unless they
+said «sin equipo». The team attacks with a storm of Tapes until **the bell**.
+
+1. **The bell.** The judge sets the time limit when opening the defense:
+   `node "$RING/scripts/sparring.mjs" mark <slug> defense --note "<hours>h"`. Battle Arena will keep
+   it (the ring API, draft PR #779: `POST /v1/ring/bouts/:id/stage` with `defenseHours`); until
+   that is merged and this plugin calls it, the milestone's note is the only record of the limit:
+   tell the judge so.
+2. **The rudo is on defense now**, correcting under fire what the judge accepts as "apply now". Its
+   fear shows only in the live feed, the Ringside and the chronicle, never in a commit or a PR.
+3. **Every Tape goes through the same funnel**: read it yourself (first fall, step 1) and fold it
+   into one catalog of blows for the defense (`blows-round-<n>.md`, the next round, with the
+   judge who gave each blow). Duplicates merge and conflicts between judges go to the main judge as
+   a question; the rudos never get one catalog per teammate.
+4. **Triage before any score.** Nothing the team said reaches a rudo, and nothing counts on the
+   scoreboard, until the main judge has triaged it. Analyze every point of every Tape (none is
+   omitted, not even the ones that look off-topic or are duplicates) and propose, ranked by
+   criticality (blocker: unusable or wrong data · high: breaks or confuses a main flow · medium ·
+   low: cosmetic or nice-to-have), a recommendation for each: apply now, apply in the referee bout,
+   ask the judge, or out of scope. A recommendation is never a decision: **only the judge discards**.
+   Points you would drop stay in the list, marked, with the reason, for the judge to rule on. What
+   the judge accepts becomes the defense's catalog of blows; the rest is recorded with the judge's
+   ruling, so it is not lost. Triage Tapes as they arrive; at the bell every point is ruled.
+   **The triage page is where the judge rules.** Publish it as a private Artifact, in the
+   play-by-play style (one beat per blow, grouped by criticality as rounds, the Tape's start time in
+   the margin). Each blow carries:
+   - who gave it;
+   - its source: every cited minute is a ▶ link to the Battle Arena library's QA view at that
+     second (`/labs/biblioteca?sesion=<recording id>&vista=qa&t=<seconds>`);
+   - its recommendation;
+   - the judge's ruling.
+
+   The ruling lives in the page's `db`, in collection `fallos`, one document per blow ID. Only the
+   judge writes it (rule `{path:"fallos", read:"view", write:"admin"}`); everyone the page is shared
+   with reads it. A ruling is one of:
+   - **Aplica**, with the judge's observation **mandatory** (what to apply and how);
+   - **No aplica**, with an **optional** observation.
+
+   Then the judge marks **Aplicado al Rudo** once the rudo's correction is in, and the page stamps
+   the time.
+
+   You read `fallos` with `ArtifactData`: only `aplica` blows, each with its observation, go to the
+   rudos. You tell the judge when one is corrected so they can mark it applied. Never write a
+   ruling yourself.
+
+   **The judge to the técnicos.** The page closes with one card per teammate who got in the ring:
+   - their Tapes;
+   - their blows;
+   - how many apply, do not apply, or are still pending. These numbers are computed live from
+     `fallos`.
+
+   On each card, the judge leaves their feedback to that person: which blows counted, what was
+   missing, and how to attack better next time. It goes in collection `feedback`, one document per
+   person, and only the judge writes it (`{path:"feedback", read:"view", write:"admin"}`). Nothing
+   moves to the rudos until the judge says the triage is complete.
+
+   **The fight report.** When the judge says the review is complete, read `fallos` and `feedback`
+   and build a PDF report in the Lotería style of the host (its paper, ink, picado and card
+   tokens). Render it as HTML and print it with headless Chrome. Look at the pages before handing
+   it over. The report has four parts:
+   - **The poster:** who got in the ring, the tally (Tapes, blows, apply, do not apply), a table by
+     criticality, and the blows that did not apply with the judge's reason.
+   - **One card per técnico:** Tapes, blows, apply and do not apply. The judge's feedback is
+     polished into «Lo mejor» and «Para la próxima», faithful to what the judge wrote and without
+     typos. Say which lines you added where the judge's note had nothing for that part.
+   - **Next steps by workstream:** product decisions, research before design, design rounds in the
+     host's design tool (with the number of proposals asked for), and direct fixes to the Rudo.
+     Each blow that applies is one row: ID, topic, and a short action you write from the judge's
+     observation. A blow that only refers to another one names it. Check that every blow that
+     applies appears at least once.
+   - **The close of the second fall:** hand off to the arbiter, the bell, the mask, and the third
+     fall.
+
+   The judge's original notes stay in the db. The PDF goes to the judge for validation, and
+   nothing reaches the arbiter until the judge approves it.
+
+5. **At the bell**: `node "$RING/scripts/sparring.mjs" mark <slug> bell --note "<Tapes · accepted
+blows>"`. Late Tapes go to the referee bout as notes, not to the scoreboard.
+6. **The mask.** The scoreboard counts only the accepted blows; the team's Tapes are evidence, not
+   votes. The judge looks at it and decides (never you, never a count, never the server):
+   - **mask kept** (`mark <slug> mask-kept --note "<scoreboard>"`): the team found little; the rudo
+     reaches the referee as a champion, with a short first package;
+   - **mask lost** (`mark <slug> mask-lost --note "<scoreboard>"`): badly hurt; the accepted
+     catalog becomes the referee's first rebound.
+
+### Third fall · the técnico
+
+The next step is `/ring:referee start --from-sparring <slug>`, one bout per repo (a session in each
+repo). It promotes the sparring: `sparring.mjs promote <slug>` (refused unless the last verdict is
+`ko`) creates `release/<slug>` from the repo's base, `mainevent/<slug>` from the sparring tip, and
+opens the deliverable PR mainevent → release as a draft; nobody creates a branch by hand, and
+pushing `sparring/*` elsewhere stays blocked. The sparring and its PR stay do-not-merge, as the
+evidence of what the KO saw; the bout cleans `mainevent/<slug>` and shows the judge the sparring's
+contract before any cleanup. `judges-card.mjs open
+--from-sparring` refuses a sparring that is not a KO, warns when neither `vestidor` nor `no-team`
+was marked, and stamps the `referee` milestone itself (`mark <slug> referee` only when a bout opens
+some other way). The behavior the judge validated is the invariant the bout keeps; the defense's
+catalog is its first rebound when the mask was lost, a short first package when it was kept.
+
+The card and the PR body always carry the fixed warning: the credentials it used are assumed
+rotated. Nobody follows it up.
+
+## 5 · `list`
+
+`node "$RING/scripts/sparring.mjs" list`: every sparring on this machine with its repos and PRs,
+verdict and age.
+Those over `staleDays` without a verdict show `STALE`: bring them to the judge for a call.
+
+## Hard guards
+
+`mask-guard` enforces these on every session, sparring or bout or neither:
+
+- `.env.sparring` is never committed;
+- a `sparring/*` branch is never merged (`git merge sparring/…`) nor pushed to any branch that is
+  not itself `sparring/*`;
+- a PR from `sparring/*` is created only as a draft with the do-not-merge label, and never taken out
+  of draft (`gh pr ready`) or merged (`gh pr merge`).
+
+And these are yours:
+
+- No credential value in any message, file, PR, commit or log. Names only.
+- Sandbox or test mode of every provider; production keys are an escalation, never a shortcut.
+- A real send only to the judge's own allowlisted destinations (§1.8), closed by default; never a
+  destination in a file, a commit or a log.
+- No files in a checkout the sparring does not own; helpers go in `<sparring dir>/tools/`.
+- Every PR is a draft; closing, merging and base changes are the human's.