@thebattlearena/corner 0.9.1-beta.70 → 0.10.0

package/ring/skills/referee/SKILL.md

@@ -39,7 +39,7 @@ 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
    first time a script resolves it; if both exist, the new one wins and the old one is reported on
@@ -59,7 +59,7 @@ list reaches the human.
      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 +67,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 +104,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 +133,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 +147,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 +156,13 @@ 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
+run_in_background: true, prompt: <templates/wrestler-brief.md filled>}`. 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);
@@ -171,11 +182,28 @@ way out, and it refuses without a KO. Then the bout runs as always, with three i
    - 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.
    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.
    `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
@@ -185,11 +213,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 +226,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 +251,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 +272,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 +289,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,
@@ -276,7 +319,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 +330,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 +370,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 +483,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>]`
 

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._

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

@@ -22,7 +22,7 @@ expression.
 `if (existing) { …; return } create(...)`. Lookups that may legitimately find nothing return a
 list or a null object, not a hidden null from a finder that should have failed.
 
-**R4. Very few comments.** Only a non-obvious *why*, in one line. Remove comments that narrate
+**R4. Very few comments.** Only a non-obvious _why_, in one line. Remove comments that narrate
 what or how, repeat the name, tell the history of the refactor, or describe another layer. Keep the
 comment that guards a measured incident ("a 400 from the provider does not burn the key, measured
 on <date>"): deleting it invites the bug back.
@@ -57,7 +57,8 @@ a large block becomes a helper or its own function.
 identical methods (merge them unless the difference means something to the caller). Dependencies
 point inward: the domain imports nothing from application or infrastructure; adapters implement
 the ports the consumer owns, translate foreign errors and types at the border, and live by
-technology.
+technology. The same condition repeated across files is a finding even when every piece works on
+its own: it lives in one place (a value object, a rule, a specification) and the rest call it.
 
 **R12. Every value object is a class**, with a private constructor, named static factories and
 methods with its behavior; never an interface plus a frozen object plus loose functions. A plain
@@ -71,6 +72,42 @@ existing value object when there is one. Constructors used for dependency inject
 methods, a named option, a value object or polymorphism. The same for optional callbacks whose mere
 presence changes the semantics: use a discriminated result.
 
+**R15. Every new file earns its place with one business sentence**: in the language of the
+domain, which fact of the customer it serves and what it will be used for next. A file without
+that sentence does not enter.
+
+**R16. The backend follows the business narrative, not the screen.** A field, filter or query that
+exists only to paint a view, or only to validate before another action (a "preview"), is a
+finding: the view composes what the business already exposes.
+
+**R17. Every optional carries its reason.** Each new `?`, nullable or optional field in a DTO,
+command, event or entity is justified in one sentence; otherwise it is required or has a default.
+A union like `X | null` where null means "a different operation" becomes two commands.
+
+**R18. An aggregate is born valid.** What gives it meaning exists from its factory; no aggregate
+is created empty and completed later by setters or a second call.
+
+**R19. Primitives do not cross boundaries.** Commands, events and ports carry value objects
+(R12), not `string | null` or loose ids; the primitive is parsed once at the edge.
+
+**R20. Before a new endpoint or command, list the existing ones that could do it** and why they do
+not serve. A new route that duplicates an existing one under another verb (a PATCH where
+`POST`/`DELETE` on the same resource already exists) is a finding.
+
+**R21. Names come from the ubiquitous language and do not collide with another context.** Before
+naming a module, aggregate or resource, search the repo: a name another bounded context already
+owns (a `catalog` next to an existing `catalogs`) is renamed.
+
+**R22. Design patterns where they fit, and only where they fit.** Conditionals repeated by type,
+state or provider are replaced by the pattern that removes them (a chain of rules or a composed
+specification, Strategy, polymorphism in the value object, Observer for effects between modules,
+Factory Method for creation invariants, polymorphic errors instead of a map of codes; catalog:
+https://refactoring.guru/design-patterns), citing the measured `file:line`. A pattern enters only
+when it is simpler than the conditional it removes; a discarded pattern is written down with its
+reason so it is not proposed again. Example: five chained `if`s assigning a number, with the
+exclusivity rule repeated in three files, become one `AssignmentRule` per rule, reused by the
+backfill.
+
 ## T · Tests as a contract
 
 **T1. In a refactor, no assertion of a test that exists in the base changes.** Moving or renaming a
@@ -142,6 +179,12 @@ purpose, short and clear, and are listed in the PR.
 **F12. A quiet linter is not an approval.** No orphan entries in baselines or allowlists, and the
 gates run clean against the stack base and against the default branch.
 
+**F13. A provider's hard limits count against the base, not the diff.** On a new infrastructure
+resource (metric filters, rules, indexes, queues, alarms), count how many the base already has
+against the provider's quota before approving. _Example: AWS allows 100 metric filters per log
+group; main already had 100 and the PR added 2, so the alarms would not have been created in
+production._
+
 ## P · Review process
 
 **P1. One PR per category.** Business logic and its tests apart from harness, mocks, tooling,
@@ -151,7 +194,7 @@ skills and docs. The deliverable PR carries only code and tests.
 practice is stopped in time, with the approved pattern already applied.
 
 **P3. If the human dislikes the class design, a structural pause.** First ask whether the
-objection is to the *solution* (the behavior) or to the *class design*; a validated solution is not
+objection is to the _solution_ (the behavior) or to the _class design_; a validated solution is not
 redesigned. On a design objection, finish what is mechanical, agree a target architecture with the
 human and resume with a single sample concept.
 
@@ -160,7 +203,10 @@ per concept by a read-only reviewer on a fixed range of commits.
 
 **P5. File-by-file design review in batches** of at most 20 files through 8 lenses: layer and
 dependencies, coupling, duplication, SOLID, domain model, errors (fail open or closed),
-expressiveness, production risk.
+expressiveness, production risk. Each new file brings its business sentence (R15) and repeated
+conditionals bring their pattern proposal or the reason none fits (R22). **It is mandatory before
+the first commit when the PR creates a module or an aggregate**, not only when the change is
+large or the human asks: a design review that arrives after the cleanup started arrives late.
 
 **P6. One rebound package per review**: `file:line — rule — what is wrong — how it must be`,
 blockers first (base assertion changed, event renamed, behavior changed). What is not applied is
@@ -189,6 +235,20 @@ battery runs once when everything converged.** The targeted reproduction (a dire
 one e2e spec, minutes) must be green on the exact tip that ships before the finding's thread is
 replied to as fixed or resolved; the full validation (hours) runs once, on the final tip.
 
+**P14. The host's rules are not the referee's decisions.** When the host fixes a pattern (a
+repository only through specifications, a layer that may not import another), a deviation is a
+cornerman BLOCKER or goes to the hard list; under `delegation: "referee"` the referee may not
+approve it as a design doubt.
+
+**P15. A PR that changes how a flow works today explains it in plain words before the code**:
+what happens today, what will happen, and who notices. It goes in the wrestler's brief ("Flow
+change" line of `templates/wrestler-brief.md`) and in the round-bell body (`round-bell.mjs open …
+--flow-change "<today …; after …; who notices …>"`, rendered under "What changes for whom").
+
+**P16. Read the execution path before claiming "today it goes through X".** Where a value is
+stored does not say which path uses it; a claim about current behavior cites the call chain that
+runs, not the column or the config that exists.
+
 ## Who decides
 
 The host's `delegation` (`.claude/ring.json`) sets who decides design doubts. With `"referee"`
@@ -208,6 +268,7 @@ bout moving; with `"human"` the referee escalates both lists, as before.
   writes, data deletion).
 - Anything `mask-guard` blocks.
 - A direct contradiction between two instructions of the host repo: it is written down and waits.
+- A deviation from a pattern the host's own rules fix (P14).
 
 ### The referee's under `delegation: "referee"`