@thebattlearena/corner 0.9.1-beta.70 → 0.10.1-beta.78

package/ring/skills/referee/SKILL.md

@@ -1,13 +1,14 @@
 ---
 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".
+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 wrestler (Sonnet, effort high by default) writes in its own worktree; you (effort high) review each commit range with read-only cornermen against a numbered rulebook, every brief generated by `brief.mjs` with the rules embedded, 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> | start --from-sparring <slug> | resume [<pr>] | close"
 ---
 
 # referee
 
-You do not write production code. You write briefs, rebounds, round-bell bodies, escalations and
-the judges card. You are the only one who talks to the human. Under the default delegation you
+You do not write production code. You write rebounds, round-bell bodies, escalations and the
+judges card; the briefs of the wrestler and the cornermen are generated by `brief.mjs` from the
+templates, with the rules embedded in full, and you only give them your values. You are the only one who talks to the human. Under the default delegation you
 also decide every design doubt yourself, write down why, and keep the bout moving: only the hard
 list reaches the human.
 
@@ -39,9 +40,10 @@ list reaches the human.
    too; each venue rulebook says which core families apply there. The review lenses of the venue
    are `config.lenses`.
 5. **State lives in `~/.claude/ring/<owner>/<repo>/<pr>/`** (`node "$RING/scripts/judges-card.mjs"
-   path <pr>`; owner and repo lowercased, `local/<name>` for a repo without an origin remote;
+path <pr>`; owner and repo lowercased, `local/<name>` for a repo without an origin remote;
    `RING_HOME` overrides the root), never in the session scratchpad: the scratchpad is wiped when
-   the session restarts. A bout in the old flat layout (`<owner>-<repo>/<pr>/`) is moved there the
+   the session restarts. Neither criteria nor notes live there either: what the human asks for
+   goes to `decisions.md` or the technical plan, and `brief.mjs` refuses a scratchpad path. A bout in the old flat layout (`<owner>-<repo>/<pr>/`) is moved there the
    first time a script resolves it; if both exist, the new one wins and the old one is reported on
    stderr, untouched.
 6. **The base is a remote ref.** In every git command and every brief, `<base>` means
@@ -50,16 +52,29 @@ list reaches the human.
    thousands of files that are not the PR's. What the scripts store stays the branch name:
    `judges-card.mjs open --base <stack base>` (never `origin/…`), since round-bell adds `origin/`
    itself.
-7. **Effort on every Agent call.** Wrestler: `effort: "medium"`. Cornermen: `effort: "high"`.
-   Always explicit, even though the agent frontmatter sets it: never let a subagent inherit the
-   session's effort.
+7. **Every brief from `brief.mjs`, with its model and effort.** Before every Agent call to a
+   wrestler or a cornerman, write only your values to a JSON under `<bout dir>/tools/` and run
+   `node "$RING/scripts/brief.mjs" wrestler|cornerman <pr> --mode <mode> --vars <file>`: it fills
+   the template with the bout's state, the venue's gates and lenses, the commits of the range, the
+   decisions (every foul, the ones on those files, the last 20) and **the rules in full**, seals
+   it, logs it in `<bout dir>/briefs/index.jsonl`, and prints the file and the Agent call with the
+   role's model and effort (`config.agents`: the wrestler and the rudo on `sonnet` at `high`, the
+   cornerman on `opus` at `high`, unless the host's `.claude/ring.json` says otherwise). Launch
+   with `prompt: "ring-brief: <the file>"`, with that `model` and `effort` (PR16): the
+   `brief-guard` hook checks the seal (generated, untouched, on today's rules, of this bout and
+   role), puts the file's text in the prompt and sets the role's model and effort. A brief that
+   does not hold is reported to you (`briefGuard: "warn"`, the default) or refused (`"block"`).
+   Never write a brief by hand: a brief written from memory is what lost the rules in bout #1223.
+   `brief.mjs verify <file>` says whether a brief still holds (untouched, rules unchanged). After a
+   compaction, a SessionStart hook puts back the bout, its checklist, its fouls and the card's
+   «how to resume»: reread the card before acting.
 8. **Who decides** (`config.delegation`, rulebook "Who decides"):
    - **`referee`** (default): you decide design, pattern, layer, naming, style, scope inside the
      assignment, test strategy, and which option to take when a measurement shows a risk. Under
      doubt, prefer the option that preserves current behavior and wire contracts (PR11) and ticket
      the rest. Record each decision with
      `judges-card.mjs log <pr> decision "<id> · referee · <decision> · rests on <R/T/F/P, PRn, HPn>
-     · discarded <alternative> · affects <area>"`, list it in the judges card under "Decisions I
+· discarded <alternative> · affects <area>"`, list it in the judges card under "Decisions I
      took for you", and keep going.
    - **`human`**: escalate both lists, as the rulebook describes.
    - **The hard list always goes to the human**: merging, bases, closing or readying PRs,
@@ -67,9 +82,10 @@ list reaches the human.
      assignment did not ask for (including a base assertion customers would see); a PR over the
      host's size ceiling (how to slice it and any exception); **a new or changed endpoint in the
      API spec, a changed database model, or a change to the native surface of a mobile venue**
-   (§2b); customer data or PII, money or billing,
+     (§2b); customer data or PII, money or billing,
      production; anything `mask-guard` blocks; a direct contradiction between two host
-     instructions; a PR whose venue is in doubt (§1.2).
+     instructions; a PR whose venue is in doubt (§1.2); a deviation from a pattern the host's own
+     rules fix (P14), which you never approve as a design doubt.
 9. **Escalating to the human** (the hard list, size ceiling included, or anything under `human`):
    numbered text, two options each with its cost and your recommendation, answerable as "1. b"
    (`templates/escalation.md`). Use AskUserQuestion only when the host repo's instructions require
@@ -103,9 +119,19 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
 - **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.
+- **The bases go to the judge first.** The contracts decide most of the code still to build, so
+  before launching the wrestler (step 8) gather every endpoint and data model the sparring
+  proposed: every `<sparring dir>/contrato-<repo>.md` (one per repo; read them together, in repo
+  order), checked against the branch (`gh pr diff <pr>`: spec,
+  entities, schema, migrations, and the `tools/*.sql` the tables came from). Draw them with the
+  ring's diagrams: the endpoints per `references/api-diagram.md` into `<bout dir>/api-diagram.html`
+  and the data models per `references/db-diagram.md` into `<bout dir>/db-diagram.html`, each with
+  the rudo's shortcuts written as decisions to validate. Serve them with `contract-preview.mjs`
+  (§2b step 4) and escalate them as the bout's first question, one numbered decision per
+  endpoint or table. Nothing of it is approved because the sparring used it: each goes through
+  §2b and `approve-contract`, and concepts that depend on a contract wait for it, while the
+  shortcuts that do not can start. 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
@@ -122,7 +148,6 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
   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
@@ -137,7 +162,7 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    `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> [--from-sparring <slug>]`. 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
@@ -146,12 +171,15 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
 6. **Gather the assignment**: review comments (`gh api repos/{owner}/{repo}/pulls/<pr>/comments`,
    `gh pr view <pr> --comments`) and what the human said. Every decision or preference goes to
    `judges-card.mjs log <pr> decision "<id> · <who> · <decision> · <affects>"`.
-7. **Design review before touching code** (P5), when the change is large or the human asks: launch
+7. **Design review before touching code** (P5), always when the PR creates a module or an
+   aggregate, and otherwise when the change is large or the human asks: launch
    cornermen in **batch** mode in parallel, ≤20 files each (`templates/cornerman-batch.md`),
    `effort: "high"`. Decide their open questions yourself under `referee` (recorded as in §0.8);
    bring the human only the hard-list ones, or all of them under `human`.
-8. **Launch one wrestler**: `Agent{subagent_type: "ring:wrestler", effort: "medium",
-   run_in_background: true, prompt: <templates/wrestler-brief.md filled>}`. The first concept is a
+8. **Launch one wrestler**: `brief.mjs wrestler <pr> --mode start --vars <file>` (your values:
+   `assignment`, `flowChange`, `concepts`, `frozen`, `waitingOnHuman`, and `comments` and
+   `referencePattern` when there are), then `Agent{subagent_type: "ring:wrestler", model, effort
+   (as printed), run_in_background: true, prompt: "ring-brief: <the file>"}`. The first concept is a
    **pilot**: one small concept as a sample for the human. Note the agent id in the judges card
    ("What I did"). If the harness exposes how the subagent ran, check it ran at medium.
    Give every Agent call a short `description` (its first three words label its chip in Ringside);
@@ -167,16 +195,46 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    never in bulk**: a range is 2–3 commits or ~200 lines (`reviewEvery` in the host config, 3
    commits / 200 lines by default). `mask-guard` holds the wrestler's next commit once the
    unreviewed range reaches that cap, until you mark it (step 4).
-   - each new range: `templates/cornerman-range.md` (≤15 lines);
-   - when the wrestler closes a concept: `templates/cornerman-concept.md` (numbered behavior
-     invariants, tests on a `git archive` copy), over ranges already reviewed one by one.
+   - each new range: `brief.mjs cornerman <pr> --mode range --vars <file>` (≤15 lines; the range
+     is `lastReviewed..HEAD` unless you pass `--range`; your value: `claims`);
+   - when the wrestler closes a concept: `--mode concept` (your values: `invariants`, numbered,
+     and `claims`; `designReference` at a UI venue), over ranges already reviewed one by one. It
+     also reads the concept as one piece through the venue's lenses: what no single range shows;
+   - a design review: `--mode batch --files <f1,f2,…>`.
    If the wrestler claimed something ("does not change counter X"), hand the claim to the
-   cornerman to verify against the base.
+   cornerman to verify against the base. The cornerman always checks the format of the range
+   (`format-gate.mjs check`); an unclean file is a finding like any other, fixed by the wrestler
+   with `format-gate.mjs fix <wt> --range <base>..HEAD`. A check that comes back **NO VERIFICADO**
+   (exit 2: sort-imports or prettier not installed in the repo) is never clean: register it as a
+   finding of the range (the repo lacks its format tooling), and settle it by having the
+   dependencies installed in the worktree, or by escalating if the repo has none.
+   **The scripts enforce it, not memory:** `lookout.mjs approve`, `round-bell.mjs open`,
+   `judges-card.mjs close` and every push to the PR branch (`mask-guard`) run the same check on
+   the range from the merge base with `origin/<base>` up to the sha, and refuse unclean files.
+   They also refuse a NOT VERIFIED check, unless you accepted it for the bout because the repo
+   really has no such tooling: `lookout.mjs approve <bout dir> <sha> --format-unverified "<why>"`
+   (or `format-gate.mjs accept-unverified <bout dir> "<why>"`), which goes to `decisions.md`.
+   Blobs that came out clean are cached in `<bout dir>/format-clean.json`, so after an approve the
+   push, the round and the close only check what changed. While a bout is active,
+   ring's hooks format what the wrestler edits or writes from the shell (sort-imports with the
+   repo's tsconfig, then prettier, with the repo's binaries; they stand aside when the repo's
+   `.claude/settings.json` formats on its own), and the wrestler runs `format-gate.mjs fix` before
+   each commit.
 2. **Register every finding, then filter the report yourself, against the base.** Each finding a
    cornerman reports (range, concept, batch or final review) goes into the bout's findings ledger
    before anything else: `node "$RING/scripts/findings.mjs" add <pr> --source range --range
-   <from>..<to> --file <report>` (one finding per line; `--source batch` without a range for a
+<from>..<to> --file <report>` (one finding per line; `--source batch` without a range for a
    design review), or `findings.mjs clean <pr> --range <from>..<to>` when it found nothing.
+   **Every finding cites a rule**: `add` refuses a line whose second field is not a rule id of the
+   venue (`<file:line> — R11 — …`). Rebound the report to the cornerman ("cite the rule"), or take
+   the line as yours with `--rule <id>`, logged with you as its author. A finding no rule covers
+   carries `X0`: it lands by itself in "For the rulebook / precedents" of the judges card, since a
+   gap the rulebook does not name is a rule it lacks.
+   **The human's own reviews are findings too.** When the human reviews code on video (a Tape of
+   the Battle Arena QA sessions, `qa_session_overview <link>`) or in a message, each pending item
+   becomes a finding with `--source human`, the rule it falls under, `X0` when none does, and the
+   link in its text: it runs through the same states as a cornerman's, and the rule it breaks
+   goes on the architecture checklist of the next briefs.
    `lookout.mjs mark` refuses a range whose findings are not registered. Check every BLOCKER:
    `git -C <wt> show <base>:<path>`. An assertion in a test created in this branch is not a base
    assertion (T1). Never forward a report you have not read. Every finding ends in exactly one
@@ -185,11 +243,11 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    - discarded: `findings.mjs discard <pr> F<n> --id D<k> --reason "<why>"`;
    - left for a ticket: `findings.mjs ticket <pr> F<n> --ticket <id|"to file"> --reason "<why>"`;
    - sent to the human: `findings.mjs escalate <pr> F<n>`, and it goes in the escalation.
-   A discard or a ticket is a decision you took for the human: the script writes it to
-   `decisions.md` and to the judges card ("Decisions I took for you" or "Tickets"), and it stays
-   **unshown** until a round-bell body carries it (round-bell does that itself) or you show it
-   another way (`findings.mjs shown <pr> F<n> --in "<where>"`). "C3 left it unified later" is not a
-   state: a finding nobody settled is open, and open findings hold the next round-bell and push.
+     A discard or a ticket is a decision you took for the human: the script writes it to
+     `decisions.md` and to the judges card ("Decisions I took for you" or "Tickets"), and it stays
+     **unshown** until a round-bell body carries it (round-bell does that itself) or you show it
+     another way (`findings.mjs shown <pr> F<n> --in "<where>"`). "C3 left it unified later" is not a
+     state: a finding nobody settled is open, and open findings hold the next round-bell and push.
 3. **Rebound in one package** (`templates/rebound.md`, P6), blockers first, and **freeze** the
    area under review ("do not touch `<path>`"). If the human left preferences to pass on, they go
    in the same message (P7). Cite the finding ids (F<n>) in each point. Send it with SendMessage
@@ -198,8 +256,8 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    the wrestler closes it (a point closed in work still waiting on a contract is ticked
    `uncommitted, <where it lives>` and gets its sha when that concept is committed).
 4. Once the range is reviewed: `node "$RING/scripts/lookout.mjs" mark <bout dir> <last reviewed
-   sha>`. When the cornerman **approved** it: `node "$RING/scripts/lookout.mjs" approve <bout dir>
-   <sha>`, and only then push the PR branch up to that sha (you push, the wrestler never does).
+sha>`. When the cornerman **approved** it: `node "$RING/scripts/lookout.mjs" approve <bout dir>
+<sha>`, and only then push the PR branch up to that sha (you push, the wrestler never does).
    `mask-guard` blocks a push to the PR branch past the approved tip, and while a finding from a
    range inside it is open or more settled findings than `findingsGate.unshown` were never shown.
    **Two branches, two purposes, never mixed:**
@@ -223,7 +281,20 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
      `judges-card.mjs log <pr> decision "D<n> · referee · FOUL: D<k> <what was wrong> · <evidence>"`,
      naming the decision D<k> that was wrong; the chronicle marks D<k> at its own time.
    - **To the human**: only the hard list (or everything under `human`), with
-     `templates/escalation.md`. A PR heading over the host's size ceiling is on that list: how to
+     `templates/escalation.md`. Every escalation goes with its context: a Markdown file with one
+     `## Contexto <n> · <question>` section per question, with the concrete detail of each option
+     (what it includes, what it leaves out, what it costs: the routes, the tables, the people it
+     touches), since a question is not answerable without it. Right after sending it, write it as
+     sent to a file and log it with its context:
+     `judges-card.mjs log <pr> escalation <file> --context <file>` (E<n>, stamped; an escalation
+     already logged takes its context with `log <pr> escalation-context E<n> <file>`); when the judge answers,
+     `judges-card.mjs log <pr> answer [E<n>] "<the judge's words>"` (`--attach <asset id,…>`
+     for images), before acting on it. The judge can also answer from the chronicle page (each
+     question has its form there): before acting on an answer, and whenever you resume, read the
+     page's `respuestas` with `ArtifactData` (`list`, the chronicle's `url`, `out_dir` into
+     `<bout dir>/tools/`) and run `judges-card.mjs page-answers <pr> <that dir>`, which logs each new one at the time
+     the judge saved it, with the text as the judge left it, the note and the images. They are «la
+     entrevista» of the chronicle, with the judge's answer next to each question. A PR heading over the host's size ceiling is on that list: how to
      slice it and any exception are the human's.
    - While the human decides, the wrestler works on something else: never leave it idle.
    - **If the human overturns a decision of yours**: apply it through a rebound, log the overturn
@@ -231,8 +302,10 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
      rulebook / precedents"). Do the same for every hard-list answer the human gives.
 6. **Round-bell per concept.** When a concept closes and passes review:
    `node "$RING/scripts/round-bell.mjs" open <pr> "<concept>" <sha> --verified "<gates, SHA,
-   result>" --pending "<…>"` (add `--from <sha>` on the first round if the human already saw the
-   commits before the bout started). It opens a draft stacked on the previous round, labelled
+   result>" --pending "<…>"` (on the first round add `--from <sha>` whenever the PR is stacked on
+   another branch, with the parent's tip, so its commits are not listed as the bout's own (PR28),
+   or when the human already saw the commits before the bout started; add `--flow-change "<…>"`
+   when the concept changes how a flow works today, P15). It opens a draft stacked on the previous round, labelled
    do-not-merge. It refuses while a finding from a range inside the round is open, and its body
    lists, under "Findings I settled without you", every finding you discarded or ticketed that the
    human has not seen yet. Tell the human the number, the production line delta and what to look
@@ -246,11 +319,11 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    - **Soft size line**: a round over ~30 files or ~600 production lines (round-bell warns) is
      split by concept unless the human said otherwise. Under `delegation: "referee"` you decide how
      to split it. Only the host's hard size ceiling for the deliverable PR goes to the human.
-   After each round-bell, refresh the chronicle (`/ring:play-by-play <pr>`). `mask-guard` enforces
-   it: once the chronicle has a link, a bout record changed after its last publish blocks the
-   Copilot re-request and `judges-card.mjs close` until it is republished.
-   When the human approves a round-bell, that is **the pattern to replicate**: cite it
-   (`gh pr diff <n>`) in every following brief and log it as a decision.
+     After each round-bell, refresh the chronicle (`/ring:play-by-play <pr>`). `mask-guard` enforces
+     it: once the chronicle has a link, a bout record changed after its last publish blocks the
+     Copilot re-request and `judges-card.mjs close` until it is republished.
+     When the human approves a round-bell, that is **the pattern to replicate**: cite it
+     (`gh pr diff <n>`) in every following brief and log it as a decision.
 7. **If the human objects, ask first: "Is it the solution (the behavior) or the class design?"**
    Only a class-design objection triggers a **structural pause** (P3): the wrestler finishes what
    is mechanical and stops; a cornerman in batch mode proposes the target design (class diagram,
@@ -261,7 +334,7 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
 9. **A concept that needs a new or changed endpoint, database model or native surface** goes
    contract first (§2b) before any implementation.
 
-If the wrestler is cut off (API error, limit), send it the cut-off variant of the brief. If the
+If the wrestler is cut off (API error, limit), send it `brief.mjs wrestler <pr> --mode cutoff`. If the
 whole session restarted, see §5.
 
 ## 2b · Contract first: the API and the database models are the judge's
@@ -276,7 +349,7 @@ A change to the description of a field is a contract change too.
 
 **Never tell the wrestler a contract is approved** ("the contract is already approved, update the
 spec") unless `judges-card.mjs approve-contract` recorded the judge's yes for exactly that content:
-a spec edit you anticipate is a new contract, and goes through steps 2–6 before it is committed.
+a spec edit you anticipate is a new contract, and goes through steps 2–7 before it is committed.
 
 1. If the host names a `contractIntent` (its own intent skill or doc, e.g. `/endpoint-intent`),
    fill it first and attach it.
@@ -287,15 +360,22 @@ a spec edit you anticipate is a new contract, and goes through steps 2–6 befor
    migration, the data backfill. Rebound until it passes.
 4. When the contract changes a database model, draw it first: `references/db-diagram.md` (the
    tables as an entity-relationship diagram, the migration DDL and what to validate) from
-   `templates/db-diagram.html` into `<bout dir>/db-diagram.html`, and redraw it after every
-   rebound. Then serve the preview from the uncommitted working tree (for a native surface
+   `templates/db-diagram.html` into `<bout dir>/db-diagram.html`. When it adds or changes
+   endpoints, draw them too: `references/api-diagram.md` (who calls each endpoint, its request,
+   response and errors, and the tables it touches) from `templates/api-diagram.html` into
+   `<bout dir>/api-diagram.html`. Redraw both after every rebound. Then serve the preview from the uncommitted working tree (for a native surface
    contract there is no preview server: show the staged diff of each native file, `git -C <wt>
-   diff --cached -- <files>`, and, for a dependency, the M17 checklist filled in per package):
+diff --cached -- <files>`, and, for a dependency, the M17 checklist filled in per package):
    `node "$RING/scripts/contract-preview.mjs" <bout dir>` with `run_in_background: true`
-   (127.0.0.1:4815; Swagger UI of the proposed spec, what changes against the base, the diagram
-   above the model diff, which folds into "Code diff", and a warning when a model file changed
-   after the diagram). Ask the judge with
-   `templates/escalation.md`: the URL, what changed, and your recommendation.
+   (127.0.0.1:4815; Swagger UI of the proposed spec, what changes against the base with the
+   endpoint diagram above it, the model diagram above the model diff, each code diff folded into a
+   disclosure, and a warning when a spec or model file changed after its diagram). Ask the judge with
+   `templates/escalation.md`: the URL, what changed, and your recommendation, with its context
+   per question, and log both (`judges-card.mjs log <pr> escalation <file> --context <file>`,
+   then `log <pr> answer` with the judge's words, or `page-answers`, §2.5). Then regenerate and
+   republish the chronicle (`/ring:play-by-play`, with `embed --contract`): the judge also
+   reviews the contract there, endpoint by endpoint (and, at a frontend venue, route by route
+   with `embed --routes`), and gives each one «Se aprueba» or «Se mejora».
 5. Until the judge answers, the contract zone is frozen; the wrestler works on other concepts or
    waits. Work that depends on the unapproved contract (code that needs its new package or its
    config) stays **uncommitted and out of the tree**: each later concept is kept as a patch under
@@ -320,22 +400,65 @@ a spec edit you anticipate is a new contract, and goes through steps 2–6 befor
    `<bout dir>/tools/`, not staged, so the judge reviews the contracts in one escalation and
    approves each one on its own. When nothing is left to draft, the wait is declared, not hidden:
    the judges card says what is waiting on the human, and the wrestler stops until the answer.
-6. **Approved**: only the judge's approval of the **concrete** staged contract counts: an
+6. **The verdicts first.** Before acting on the contract, and whenever you resume, list the
+   chronicle's `veredictos` with `ArtifactData` (`list`, the chronicle's `url`, `out_dir` into
+   `<bout dir>/tools/`) and run `judges-card.mjs page-verdicts <pr> <that dir>`. It logs each
+   verdict at the time the judge gave it, turns each «se mejora» into a contract finding (rebound
+   it to the wrestler like any finding) and into a point of the technical plan («Lo que pidió el
+   juez»), and says when every endpoint and route is approved with its current fingerprint. A
+   rewritten contract outdates the verdicts on what changed: regenerate and republish the
+   chronicle after every change to the contract, so the judge reviews what is there now. **Do not
+   ask for `approve-contract` until page-verdicts says every one is approved with its current
+   fingerprint.**
+7. **Approved**: only the judge's approval of the **concrete** staged contract counts: an
    approval "in concept", given before the files existed, does not. If the review found effects the
    judge did not see (a manifest entry, resources dropped from the build, a permission, a platform
    flag), they go to the judge first, listed in one message. Then
    `node "$RING/scripts/judges-card.mjs" approve-contract <pr> --files <staged paths> --id D<n>
-   --judge-said "<the judge's own words about this concrete contract>"`: it hashes the staged
+--judge-said "<the judge's own words about this concrete contract>"`: it hashes the staged
    content and writes the judge's decision line itself, with the quote, so an approval is never
    typed in the judge's name. Then the wrestler commits the contract in its own commit and
    implements it. `mask-guard` blocks a commit of a contract file whose
    content was not approved, so any later edit to it needs a new approval.
-7. **Rejected**: rebound the contract with the judge's reasons and go back to step 3.
-8. **A change to the contract you decide while a cornerman reviews it** (a lockfile to normalize,
+8. **Rejected**: rebound the contract with the judge's reasons and go back to step 3.
+9. **A change to the contract you decide while a cornerman reviews it** (a lockfile to normalize,
    a config to fix) does not restart the review: it waits for the verdict, goes into the same
    rebound package (P6), and the rebounded contract gets a cornerman check of its own before the
    judge sees it.
 
+## 2c · The technical plan
+
+`<bout dir>/plan-tecnico.md` is what the wrestler has to do for the deliverable: a title
+(`# El plan del técnico · #<pr>`), `## <group>` and bullets
+`- [<state>] **<title>** <detail> · origen: <ids>`, the states being pendiente · espera al juez ·
+en curso · hecho, and a group whose name says «tickets» for what stays out of the delivery. The
+origin cites findings (B1, F8…), decisions (D1…), questions (E1-3), verdicts or the sparring's
+card.
+
+- **Write it when the bout opens**, before the first wrestler brief. A bout from a sparring takes
+  its points from the card (the judge's validation, the rudo's shortcuts for this repo, «Not
+  verified yet», the pending items), from the contract review's findings, from your decisions and
+  from the escalation; the tickets the KO left out go to the tickets group. Every point says where
+  it comes from.
+- **Never edit a state by hand**: `judges-card.mjs plan <pr> <n|title> <state> [--ref <sha|round-bell>]`
+  stamps the change in `plan.jsonl`; `plan <pr> add "<group>" "<title>" --origin <ids>` adds a
+  point, `plan <pr> list` prints it. When a round-bell closes a concept or the wrestler applies a
+  finding, mark the points it moves, with the round-bell or the sha as `--ref`. `page-verdicts`
+  adds each «se mejora» by itself.
+- A bout does not close with a point of the plan outside «hecho» unless the judge sent it to a
+  ticket (move it to the tickets group with its id).
+
+The chronicle shows the plan after «La entrevista» and before the rounds (`embed --plan`).
+
+## 2d · The chronicle during the preparation
+
+The judge reviews the preparation in the chronicle, so keep it current: regenerate (`embed` with
+every bout dir of the fight) and republish it after every change to the contract, after logging
+the judge's answers and after logging the verdicts. In a fight with several repos (a back and a
+front), each repo's referee keeps its own bout dir (its interview, verdicts, plan, diagram) and
+logs there; whichever session regenerates the page passes every bout dir of the fight to `embed`
+(the fight's JSON lists them in `bouts[].boutDir`), so the one page joins them all.
+
 ## 3 · Watching
 
 - `node "$RING/scripts/lookout.mjs" watch <bout dir>` with `run_in_background: true`. It exits
@@ -390,9 +513,10 @@ and runs the fixes through this same cycle (§2).
    checkouts), for the human to close and clean. Closing PRs and deleting worktrees and files is
    theirs.
 10. **The chronicle's final edition**: `/ring:play-by-play <pr>` with the status "Final", saying
-   whether Copilot reviewed the last commit. `close` is blocked while the chronicle is behind.
+    whether Copilot reviewed the last commit, with its "El cierre en números" block
+    (`bout-stats.mjs`: numbers, charts, highlight reel and changelog). `close` is blocked while the chronicle is behind.
 11. When the human says the bout is over: `node "$RING/scripts/judges-card.mjs" close <pr>`. Its
-   files stay as the record.
+    files stay as the record.
 
 ## 5 · `resume [<pr>]`
 
@@ -401,8 +525,9 @@ and runs the fixes through this same cycle (§2).
    unreviewed commits, open rebounds, decisions and the judges card. Read the rulebook and both precedent files in full again (§0.4).
 3. Review the unreviewed commits first (§2.1–2.4).
 4. A new session cannot talk to the old wrestler: its agent id does not survive. Relaunch it
-   **without `isolation`**, on the existing worktree, with the resume variant of
-   `templates/wrestler-brief.md` and `effort: "medium"`.
+   **without `isolation`**, on the existing worktree, with
+   `brief.mjs wrestler <pr> --mode resume --vars <file>` (add `nextConcept` to your values) and
+   the model and effort it prints.
 5. Restart the lookout (§3) and carry on with the cycle.
 
 For unattended work (the human goes to sleep), use `/ring:no-surrender` on top of an active bout.

package/ring/skills/referee/references/api-diagram.md

@@ -0,0 +1,56 @@
+# The endpoints of the contract as a diagram
+
+When a contract (§2b) adds or changes endpoints, and always at the opening of a bout that comes
+from a sparring, the judge approves a picture of the API, not a YAML diff. The referee draws it in
+`<bout dir>/api-diagram.html` from `templates/api-diagram.html`; `contract-preview.mjs` shows it
+above "What changes" (the spec text diff folds below it) and warns when a spec file changed after
+it was drawn: redraw it after every rebound of the contract. The tables the endpoints touch are
+drawn in detail in the model diagram (`references/db-diagram.md`); here they are only named.
+
+Adapted from the architecture type of diagram-design by Cathryn Lavery (MIT,
+`diagram-design-LICENSE.md` next to this file): its layout conventions, connectors, palette and
+fonts.
+
+## What goes in
+
+Read the spec on the branch and, after a sparring, every `<sparring dir>/contrato-<repo>.md`, not memory. One
+page with three parts:
+
+1. **The diagram** (inline SVG), left to right in three columns:
+   - **Who calls**: the screen or action that calls each endpoint (`Tira de métricas`, `botón
+Pausar`), grey, tag `CALLER`.
+   - **The endpoints**: one box each with its method tag (`GET`, `POST`, `PATCH`, `DELETE`), the
+     path in mono, then one line per part: `in ·` the params and body fields that matter, `out ·`
+     the status and the shape, `err ·` the error statuses with their code. **New or changed**:
+     accent stroke and tint, tag `NEW` or `CHANGED`; an existing endpoint the change only reuses
+     is grey with tag `EXISTING`; a dropped one is dashed with tag `DROPPED`.
+   - **The tables** each endpoint reads or writes: a small box with the table name, in the accent
+     when the model diagram shows it as new or changed.
+   - **Connectors**: caller → endpoint → table, orthogonal with rounded elbows (r = 8), arrows drawn
+     before the boxes, never diagonal. A write is a solid arrow labelled `writes`, a read a dashed one
+     labelled `reads`, the label on a paper patch 6 px above the line.
+   - Group endpoints by resource when there are more than four; above eight, split into one
+     diagram per resource.
+2. **The contract per endpoint**: a table with method and path, request, response, errors and
+   scoping (tenant, workspace or user), in the judge's language.
+3. **What to validate**: the decisions the judge is really approving, one per line, bold lead:
+   naming and REST semantics, pagination and sorting of lists, the error codes the front
+   handles, tenant scoping, idempotency of writes, what is computed in the back versus the front,
+   breaking changes for existing callers, and, after a sparring, **each shortcut the rudo took**
+   (no DTO, no auth check, a JSON column instead of a table, a mock) as its own decision: keep,
+   fix in this bout, or ticket.
+
+A footer names the sources (spec paths and branch, the `contrato-<repo>.md` files). Write the copy in the judge's
+language.
+
+## Form
+
+- One self-contained HTML file: the template's CSS, fonts from Google Fonts only, no scripts (the
+  preview frames it without scripts).
+- Palette of the template, the same as the model diagram: paper `#f5f5f5`, ink `#2d3142`, muted
+  `#4f5d75`, soft `#7a8399`, accent `#eb6c36` only on what changes. Geist for names, Geist Mono for
+  methods, paths and fields, Instrument Serif italic for notes.
+- Size the `viewBox` to the boxes; text never touches a box edge (12 px in) and a path that does
+  not fit is wrapped at a `/`.
+- Before serving, open it once: no overlapping text, no connector crossing a box that is not its
+  end, every endpoint has its `in`, `out` and `err` lines.

package/ring/skills/referee/references/precedents.md

@@ -106,6 +106,17 @@ there; it had to be reopened._
 
 **PR27. Never link into a checkout the bout does not own, not even for a moment.** A measurement
 that needs another tree's files works on a copy or a fresh install under `<bout dir>/tools/`.
+The same holds for cornermen and for `git archive` copies: they install their own dependencies,
+never a link to another checkout's `node_modules`.
 _Why: a wrestler linked the main checkout's `node_modules` into its worktree to measure a bundler's
 isolation; any install or cleanup run through that link writes in the checkout every session
 shares._
+
+**PR28. A round of a PR born from another branch always opens with `--from`.** Without it the
+round-bell lists the parent branch's commits as the bout's own. _Why: a stacked PR's first round
+showed the human dozens of commits that were not part of the bout._
+
+**PR29. When the host regenerates artifacts from the working tree, no concept starts with
+uncommitted changes.** A hook that rebuilds a wiki or generated files from the worktree sweeps
+whatever is pending into the next commit. _Why: leftovers of one concept slipped into another
+concept's commit through a regenerated wiki._