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

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,70 @@ 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. The same for code that names each channel, provider or flavor it serves (`if chat … if
+voice … if whatsapp`): the core does not know which ones exist; each one is a strategy it delegates
+to, and effects between them travel as events (publish and subscribe).
+
+**R23. A ternary that fills a gap means the gap should not exist.** `x ? x : []`, `x ?? []` repeated
+downstream or a `map` guarded against `undefined` say the value was born optional when it has a
+default: the default lives where the value is born (an empty list, not an optional list), and the
+code downstream stops asking. Every ternary that stays names its two business cases; one that
+cannot is replaced by a named function or a strategy (R22).
+
+**R24. Types come from their source.** A shape the SDK, the API spec or a validation schema already
+defines is imported or derived from it (generated types, the schema's inferred type, the SDK's own
+enums), never rewritten by hand, so it follows the source when the source changes. Closed sets of
+strings (statuses, operations, channels) are those constants or value objects (R6), never loose
+literals compared in an `if`.
+
+**R25. What a provider returns crosses an anti-corruption layer.** A provider's response is
+validated and transformed at the edge, by a schema, into our own model; neither the domain nor the
+client ever receives the raw response. An optional field of the provider is optional only with the
+evidence of when it does not arrive (the provider's docs, a captured response), never by
+assumption.
+
+**R26. Business metrics are not monitoring.** Product analytics records business events, each one
+naming the business question it answers; errors go to the monitoring tool (error tracking,
+alarms, F4). A failed operation is not a business event, and an error is never tracked as one.
+
+**R27. A cross-cutting precondition is checked once, where it is born.** The selected workspace,
+the session, the tenant: validated at one global point (a guard, a provider, a resolver), not in
+every component, hook or handler that uses it (R8).
+
 ## 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 +207,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 +222,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 +231,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
@@ -175,8 +249,10 @@ decides it and records why, or, for the hard list or under `delegation: "human"`
 human with two options, their cost and a recommendation. Meanwhile the author does not touch that
 part and works on something else.
 
-**P10. Effort by role**: whoever writes runs at medium; whoever orchestrates, reviews or gives
-feedback runs at high. Set it explicitly on every launch; never let it be inherited.
+**P10. Model and effort by role**: whoever writes runs on the cheaper model at high effort (the
+wrestler and the rudo on Sonnet); whoever orchestrates, reviews or gives feedback runs on the
+strongest model at high effort. The host can change either per role (`agents` in
+`.claude/ring.json`). Set both explicitly on every launch; never let them be inherited.
 
 **P11. When the host forbids them (`forbidAiTrailers`, the default), commits carry no AI
 attribution trailers**; human co-authors are always fine. Stage by explicit paths.
@@ -189,6 +265,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 +298,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"`
 

package/ring/skills/referee/templates/api-diagram.html

@@ -0,0 +1,115 @@
+<!doctype html>
+<!-- The endpoints of the contract for the judge (references/api-diagram.md). Copy to
+     <bout dir>/api-diagram.html and replace every <…>. Adapted from the architecture type of
+     diagram-design by Cathryn Lavery, MIT: references/diagram-design-LICENSE.md. No scripts: the
+     preview frames it without them. -->
+<html lang="<judge's language, e.g. es>">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title><contract title></title>
+<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<style>
+  :root { --paper:#f5f5f5; --ink:#2d3142; --muted:#4f5d75; --soft:#7a8399; --rule:rgba(45,49,66,0.12); --accent:#eb6c36; }
+  * { box-sizing:border-box; }
+  body { margin:0; background:var(--paper); color:var(--ink); font-family:'Geist',sans-serif; }
+  main { max-width:1080px; margin:0 auto; padding:32px 24px 40px; }
+  .eyebrow { font-family:'Geist Mono',monospace; font-size:12px; letter-spacing:0.14em; color:var(--muted); text-transform:uppercase; margin:0 0 8px; }
+  h1 { font-family:'Instrument Serif',serif; font-weight:400; font-size:1.75rem; margin:0 0 8px; }
+  .sub { color:var(--muted); font-size:14px; margin:0 0 24px; max-width:760px; line-height:1.5; }
+  svg { width:100%; height:auto; display:block; }
+  .card { background:#fff; border:1px solid var(--rule); border-radius:6px; padding:20px; margin-top:24px; overflow-x:auto; }
+  .card h3 { font-size:14px; margin:0 0 12px; }
+  table { border-collapse:collapse; width:100%; font-size:13px; }
+  th { text-align:left; font-family:'Geist Mono',monospace; font-size:11px; letter-spacing:0.08em; text-transform:uppercase; color:var(--soft); font-weight:500; padding:0 12px 8px 0; }
+  td { padding:8px 12px 8px 0; border-top:1px solid var(--rule); vertical-align:top; line-height:1.5; }
+  code { font-family:'Geist Mono',monospace; font-size:12px; }
+  .m { color:var(--accent); font-weight:600; }
+  ul { margin:0; padding-left:18px; font-size:13px; line-height:1.6; }
+  li { margin-bottom:6px; }
+  footer { margin-top:32px; padding-top:12px; border-top:1px solid var(--rule); font-family:'Geist Mono',monospace; font-size:12px; color:var(--soft); }
+</style>
+</head>
+<body>
+<main>
+  <p class="eyebrow">PR #<n> · <API contract></p>
+  <h1><contract title></h1>
+  <p class="sub"><one or two sentences: which endpoints change and for what, in plain words></p>
+
+  <!-- Size the viewBox to the boxes. Columns: callers (x 40), endpoints (x 300), tables (x 760).
+       Draw connectors first, then the boxes on top. -->
+  <svg viewBox="0 0 960 300" role="img" aria-labelledby="api-title api-desc">
+    <title id="api-title"><contract title></title>
+    <desc id="api-desc"><who calls what and which tables it touches, in one sentence></desc>
+    <defs>
+      <marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+        <polygon points="0 0, 8 3, 0 6" fill="#4f5d75"/>
+      </marker>
+      <marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+        <polygon points="0 0, 8 3, 0 6" fill="#eb6c36"/>
+      </marker>
+    </defs>
+    <rect width="100%" height="100%" fill="#f5f5f5"/>
+
+    <!-- Caller → endpoint: a straight line when they share y, otherwise a rounded elbow
+         (M x1,y1 H mid-8 Q mid,y1 mid,y1+8 V y2-8 Q mid,y2 mid+8,y2 H x2). -->
+    <line x1="220" y1="96" x2="298" y2="96" stroke="#4f5d75" stroke-width="1.2" marker-end="url(#arrow)"/>
+    <!-- Endpoint → table: solid = writes, dashed = reads; the label on a paper patch 6 px above. -->
+    <path d="M 660,96 H 702 Q 710,96 710,104 V 172 Q 710,180 718,180 H 758" fill="none" stroke="#eb6c36" stroke-width="1.2" marker-end="url(#arrow-accent)"/>
+    <rect x="672" y="78" width="40" height="12" rx="2" fill="#f5f5f5"/>
+    <text x="692" y="87" fill="#7a8399" font-size="8" font-family="'Geist Mono',monospace" text-anchor="middle" letter-spacing="0.06em">writes</text>
+    <line x1="660" y1="232" x2="758" y2="232" stroke="#4f5d75" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#arrow)"/>
+    <rect x="690" y="214" width="36" height="12" rx="2" fill="#f5f5f5"/>
+    <text x="708" y="223" fill="#7a8399" font-size="8" font-family="'Geist Mono',monospace" text-anchor="middle" letter-spacing="0.06em">reads</text>
+
+    <!-- Caller: grey, tag CALLER. -->
+    <rect x="40" y="64" width="180" height="64" rx="6" fill="rgba(79,93,117,0.10)" stroke="#7a8399" stroke-width="1"/>
+    <rect x="52" y="76" width="52" height="12" rx="2" fill="none" stroke="rgba(45,49,66,0.40)" stroke-width="0.8"/>
+    <text x="78" y="85" fill="#4f5d75" font-size="8" font-family="'Geist Mono',monospace" text-anchor="middle" letter-spacing="0.08em">CALLER</text>
+    <text x="52" y="112" fill="#2d3142" font-size="12" font-weight="600" font-family="'Geist',sans-serif"><screen or action></text>
+
+    <!-- New (or changed) endpoint: accent stroke and tint; method tag, path, then in / out / err. -->
+    <rect x="300" y="64" width="360" height="132" rx="6" fill="rgba(235,108,54,0.08)" stroke="#eb6c36" stroke-width="1"/>
+    <rect x="312" y="76" width="40" height="12" rx="2" fill="none" stroke="rgba(235,108,54,0.50)" stroke-width="0.8"/>
+    <text x="332" y="85" fill="#eb6c36" font-size="8" font-family="'Geist Mono',monospace" text-anchor="middle" letter-spacing="0.08em">NEW</text>
+    <text x="312" y="108" fill="#eb6c36" font-size="12" font-weight="600" font-family="'Geist Mono',monospace">POST</text>
+    <text x="352" y="108" fill="#2d3142" font-size="12" font-weight="600" font-family="'Geist Mono',monospace"><path></text>
+    <line x1="300" y1="118" x2="660" y2="118" stroke="rgba(235,108,54,0.30)" stroke-width="0.8"/>
+    <text x="312" y="138" fill="#2d3142" font-size="12" font-family="'Geist Mono',monospace">in · <param>: <type>, <body field>: <type></text>
+    <text x="312" y="158" fill="#2d3142" font-size="12" font-family="'Geist Mono',monospace">out · 201 { <field>: <type>, … }</text>
+    <text x="312" y="178" fill="#4f5d75" font-size="12" font-family="'Geist Mono',monospace">err · 404 <code> · 409 <code></text>
+
+    <!-- Existing endpoint the change reuses: grey, tag EXISTING, path only plus a note. -->
+    <rect x="300" y="212" width="360" height="56" rx="6" fill="rgba(45,49,66,0.03)" stroke="rgba(45,49,66,0.30)" stroke-width="1"/>
+    <rect x="312" y="222" width="64" height="12" rx="2" fill="none" stroke="rgba(45,49,66,0.40)" stroke-width="0.8"/>
+    <text x="344" y="231" fill="#4f5d75" font-size="8" font-family="'Geist Mono',monospace" text-anchor="middle" letter-spacing="0.08em">EXISTING</text>
+    <text x="312" y="254" fill="#4f5d75" font-size="12" font-family="'Geist Mono',monospace">GET <path></text>
+    <text x="520" y="254" fill="#7a8399" font-size="12" font-family="'Instrument Serif',serif" font-style="italic">unchanged</text>
+
+    <!-- Tables: name only; accent when the model diagram shows them new or changed. -->
+    <rect x="760" y="164" width="160" height="32" rx="6" fill="rgba(235,108,54,0.08)" stroke="#eb6c36" stroke-width="1"/>
+    <text x="772" y="185" fill="#2d3142" font-size="12" font-family="'Geist Mono',monospace"><new_table></text>
+    <rect x="760" y="216" width="160" height="32" rx="6" fill="rgba(45,49,66,0.05)" stroke="#4f5d75" stroke-width="1"/>
+    <text x="772" y="237" fill="#2d3142" font-size="12" font-family="'Geist Mono',monospace"><existing_table></text>
+  </svg>
+
+  <div class="card">
+    <h3><The contract per endpoint></h3>
+    <table>
+      <thead><tr><th>Endpoint</th><th>Request</th><th>Response</th><th>Errors</th><th>Scoping</th></tr></thead>
+      <tbody>
+        <tr><td><code><span class="m">POST</span> <path></code></td><td><params and body></td><td><status and shape></td><td><status · code · when></td><td><tenant / workspace / user></td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="card">
+    <h3><What to validate></h3>
+    <ul>
+      <li><b><decision>:</b> <what it means and what to check></li>
+      <li><b><shortcut of the sparring>:</b> <keep, fix in this bout, or ticket></li>
+    </ul>
+  </div>
+  <footer><Sources: the spec paths on branch …, and the sparring's contrato-&lt;repo&gt;.md files></footer>
+</main>
+</body>
+</html>

package/ring/skills/referee/templates/cornerman-batch.md

@@ -1,15 +1,21 @@
-<!-- Agent{subagent_type: "ring:cornerman", effort: "high"}, several in parallel, before code is
-     touched or when the human asks for a design pass. At most 20 files each. -->
-
-Mode: **batch**. Read only. Worktree `<absolute path>` at its live HEAD; the tree may change while
-you read: cite the lines of the moment. Rulebook `<absolute rulebook path>`.
+Mode: **batch**. Read only. Worktree `{{worktree}}` at its live HEAD; the tree may change while
+you read: cite the lines of the moment. The decisions taken are near the end of this brief and the
+rules after them, at its end (the architecture checklist first). Ring scripts `{{ring}}/scripts`
+(the format gate is `format-gate.mjs` there).
 
 Files (≤20):
-- <path>
+{{files}}
+
+Review in two passes and report both together.
 
-Each file through the lenses of the bout's venue (`config.lenses` from
-`config.mjs show --venue <venue>`): <lenses, one per line>.
+1. **Sweep.** Read each file whole, then go through it lens by lens, every lens of this venue:
+   {{lenses}}. Report everything wrong you find, production risk and behavior as much as design.
+   There is no cap on findings, and a problem no rule fits is still a finding.
+2. **Checklist.** Go over the architecture checklist at the end of this brief against each file
+   and add what the sweep missed.
 
-Return per file the findings with rule ids, one finding per line (the referee registers each line
-with `findings.mjs add --source batch --file`). Then the **open design questions**, numbered, each
-with two options, their cost and your recommendation.
+Return per file the findings, one per line, as `<file:line> — <rule id> — <what is wrong> — <how
+it must be>`. The rule id is one from the rules at the end of this brief, or `X0` when none covers
+it: never drop a finding because no rule fits (the referee registers each line with
+`findings.mjs add --source batch --file`, which refuses a line without a valid id). Then the
+**open design questions**, numbered, each with two options, their cost and your recommendation.

package/ring/skills/referee/templates/cornerman-concept.md

@@ -1,44 +1,42 @@
-<!-- Agent{subagent_type: "ring:cornerman", effort: "high"}. When a concept closes. -->
-
 Mode: **concept**. You are the high-effort reviewer. Read only: no edits, no commits, no index or
 tree writes in the wrestler's worktree.
 
-Worktree `<absolute path>`, base `<base>`, range `<A>..<B>`. Rulebook `<absolute rulebook path>`;
-decisions `<bout dir>/decisions.md`. Ring scripts `<absolute ring path>/scripts`.
+Worktree `{{worktree}}`, base `{{base}}`, range `{{range}}`. The decisions taken are near the end of
+this brief and the rules after them, at its end. Ring scripts `{{ring}}/scripts`.
 
-Commits and what each claims:
-- `<sha>` <subject> — <claim>
+Commits of the concept:
+{{commits}}
 
-Author claims to verify against the base: <…>
+Author claims to verify against the base: {{claims}}
 
 **Behavior: what matters most; any change is a BLOCKER.** Invariants, numbered:
-1. <messages or jobs enqueued: names, ids, options, presence of undefined keys>
-2. <order of side effects>
-3. <payload to providers: keys and order>
-4. <counters, status transitions, error propagation>
-5. <telemetry event names and fields>
-6. Base test assertions: none may change (`git show <base>:<path>` before calling it a blocker).
-
-How to test: `git -C <worktree> archive <B> | tar -x -C <new temp dir>`; install there if needed;
-only the tests of the area, each through `node <ring>/scripts/one-at-a-time.mjs run -- <command>`;
-never a test run and a typecheck at the same time. For a pure-calculation refactor, a differential
-check old vs new that fails if you remove the key piece.
-
-**Design (UI venues, when the concept draws a screen).** You do not have the design tool, so the
-referee hands you the reference: the design file and node id, the measurements read from the live
-node with the time of that reading (sizes, spacing, colors, type, the position of the main action)
-and the path of an export of that node made after its last change. Compare the screenshots of the venue's matrix against them:
-<design file · node id · measurements · export path · screenshots>. A difference not listed by the
-author is a finding; text is judged by the node's content, never by a layer name.
+{{invariants}}
+Base test assertions: none may change (`git show {{base}}:<path>` before calling it a blocker).
+
+How to test: `git -C {{worktree}} archive <tip> | tar -x -C <new temp dir>`; install there if
+needed; only the tests of the area, each through `node {{ring}}/scripts/one-at-a-time.mjs run --
+<command>`; never a test run and a typecheck at the same time. For a pure-calculation refactor, a
+differential check old vs new that fails if you remove the key piece.
+
+**Design, the whole concept at once** (what a range-by-range review cannot see): read the concept
+as one piece through the lenses of this venue, {{lenses}}. An anemic aggregate built across several
+commits, a dependency that points outward once the pieces are together, a condition repeated
+across the files of the concept: each is a finding with its rule id.
+
+**Design of a screen (UI venues):** {{designReference}}. A difference from the reference not
+listed by the author is a finding; text is judged by the node's content, never by a layer name.
 
 **Leftovers (every concept close):**
+
 - Symbols left without production callers: grep, on your copy, every exported or public symbol the
   range touched and every symbol whose caller the range deleted; one used only by its own spec, or
   by nobody, is dead code.
-- Narrating, stale or now-wrong comments in the files the assignment covers: <paths>, including the
-  ones this range did not edit.
-- Commit messages of the range (`git -C <worktree> log --format=%B <A>..<B>`) carrying bout ids
+- Narrating, stale or now-wrong comments in the files the assignment covers: {{leftoverPaths}},
+  including the ones this range did not edit.
+- Commit messages of the range (`git -C {{worktree}} log --format=%B {{range}}`) carrying bout ids
   (D12, P7, HP3, PR5…).
 
-Return: a table per file, a table per invariant (holds / broken + evidence), the leftovers,
-totals, and a one-line verdict: `APPROVED` or `REBOUND: <n> blockers, <m> fixes`.
+Return: a table per file (one finding per row, `| <file:line> | <rule id> | <what> | <how> |`), a
+table per invariant (holds / broken + evidence), the leftovers, totals, and a one-line verdict:
+`APPROVED` or `REBOUND: <n> blockers, <m> fixes`. Every finding cites one of the rules at the end of this brief, or
+`X0` when none covers it.

package/ring/skills/referee/templates/cornerman-range.md

@@ -1,15 +1,20 @@
-<!-- Agent{subagent_type: "ring:cornerman", effort: "high"} -->
-
 Mode: **range**. Read only: no edits, no commits, no index or tree writes in any worktree.
 
-Worktree `<absolute path>`, base `<base>`, range `<A>..<B>`. Review each commit with
-`git -C <worktree> show <sha>` against the rulebook `<absolute rulebook path>` (read it first) and
-the decisions in `<bout dir>/decisions.md`. Only the lines these commits add or change.
+Worktree `{{worktree}}`, base `{{base}}`, range `{{range}}`. Review each commit with
+`git -C {{worktree}} show <sha>` against the rules at the end of this brief (the architecture
+checklist first) and the decisions at its end. Only the lines these commits add or change. Ring
+scripts `{{ring}}/scripts`.
+
+Commits of the range:
+{{commits}}
 
-<Optional: the author claims "<claim>". Verify it against the base; if a single counter, event or
-payload changes, it is a BLOCKER.>
+Author claims to verify against the base (if a single counter, event or payload changes, it is a
+BLOCKER): {{claims}}
 
-Return `file:line — rule id — what is wrong — how it must be`. A changed base test assertion or a
-renamed telemetry event goes first, marked BLOCKER. "<sha>: no findings" when a commit complies.
-No taste, no pre-existing debt. **At most 15 lines.** One finding per line: the referee registers
-each line as a finding (`findings.mjs add --file`), so never wrap one across lines.
+Return one finding per line, exactly `<file:line> — <rule id> — <what is wrong> — <how it must be>`.
+The rule id is the second field and must be one of the rules at the end of this brief (several as `R11/R22`); a
+finding no rule covers carries `X0`, and the referee proposes the rule it lacks. A changed base
+test assertion or a renamed telemetry event goes first, marked BLOCKER. "<sha>: no findings" when a
+commit complies. No taste, no pre-existing debt. **At most 15 lines.** The referee registers each
+line as a finding (`findings.mjs add --file`), which refuses a line without a valid rule id, so
+never wrap one across lines.

package/ring/skills/referee/templates/escalation.md

@@ -2,7 +2,13 @@
      host sets delegation to "human". Under the default "referee" delegation, design doubts are
      decided and recorded, never sent here. Numbered text, answerable as "1. b", by default;
      AskUserQuestion only when the host repo's instructions require it. The wrestler keeps working
-     on something else meanwhile: never leave it idle waiting for an answer. -->
+     on something else meanwhile: never leave it idle waiting for an answer.
+     Keep each question on one numbered line with its options «(a) … · (b) …» and «I recommend
+     (x)» (or «Te recomiendo (x)»): `judges-card.mjs log <pr> escalation <file>` reads them from
+     there for the chronicle's interview, and `log <pr> answer` stamps the judge's reply.
+     Write its context too, in a file of its own, one `## Contexto <n> · <question>` section per
+     question: what each option includes, leaves out and costs. Log it with `--context <file>`;
+     the chronicle shows it under «Ver más información». -->
 
 **Done up to `<sha>`** (<concept>, round-bell #<n>).
 

package/ring/skills/referee/templates/round-bell-body.md

@@ -9,6 +9,10 @@
 
 Production lines, tests excluded: {{productionStat}}
 
+## What changes for whom
+
+{{flowChange}}
+
 ## What to read first
 
 {{readFirst}}

package/ring/skills/referee/templates/wrestler-brief.md

@@ -1,58 +1,45 @@
-<!-- The referee fills every <…> and sends this as the prompt of
-     Agent{subagent_type: "ring:wrestler", effort: "medium", run_in_background: true}.
-     Never `isolation: "worktree"`: that creates a new tree on another branch. -->
+Assignment: {{assignment}}. PR #{{pr}}, branch `{{branch}}`, stack base `{{base}}`.
 
-Assignment: <what and why, in 3 lines>. PR #<pr>, branch `<branch>`, stack base `<base>`.
+Flow change (P15): {{flowChange}}
 
-Worktree: `<absolute worktree path>`. Your cwd resets: every git command is `git -C <worktree> …`.
-Start with: `git -C <worktree> fetch -q origin && git -C <worktree> checkout -B <branch> origin/<branch>`.
-Ring scripts: `<absolute ring path>/scripts` (one-at-a-time.mjs lives there).
-Bout dir: `<bout dir>`. A helper script you need goes in `<bout dir>/tools/`, never in the repo.
+Worktree: `{{worktree}}`. Your cwd resets: every git command is `git -C {{worktree}} …`.
+Start with: `git -C {{worktree}} fetch -q origin && git -C {{worktree}} checkout -B {{branch}} origin/{{branch}}`.
+Ring scripts: `{{ring}}/scripts` (one-at-a-time.mjs lives there).
+Bout dir: `{{boutDir}}`. A helper script you need goes in `{{boutDir}}/tools/`, never in the repo.
 Write only inside your worktree; never in the main checkout or any other tree.
 
-Rulebook: `<absolute rulebook path>` (read it in full; rebounds cite its rule ids).
-Precedents: `<bundled precedents path>` (PRn) and `<host precedents path or "none">` (HPn); rebounds
-cite them too.
-Decisions already taken (do not reopen them): `<bout dir>/decisions.md`.
+Rules: the rulebook and the precedents of this venue ({{venue}}) are at the end of this brief, in
+full. They are the ones in force: apply them while you write, not only when a rebound cites them,
+and check the architecture checklist before every commit.
+Decisions already taken (do not reopen them): the excerpt before the rules; the whole
+ledger is `{{boutDir}}/decisions.md`.
 
-Comments to address: <`gh api repos/<o>/<r>/pulls/<pr>/comments`, plus the list>.
-Reference pattern: <`gh pr diff <n>` of the round-bell the human approved> — replicate it.
+Comments to address: {{comments}}
+Reference pattern: {{referencePattern}}
 
-Order of concepts: 1. <pilot: one small concept, as a sample for the human> 2. <…> 3. <…>
+Order of concepts: {{concepts}}
+One commit per theme, never one commit for a whole concept: a removal goes with the tests it
+updates; a behavior change (what the flow-change line names, or an error that now surfaces
+differently) goes in its own commit with the test that pins it (T6); renames and formatting go
+apart from logic.
 Commit locally and never push: when you close 2–3 commits (or ~200 lines), report the range and
 keep going only if I have not stopped you. The PR branch receives what the cornerman approved, and I
-push it; every commit you close is backed up for you to `ring/<pr>/respaldo`, approved or not. If mask-guard says the review cap is
-reached, report the range and wait for me.
+push it; every commit you close is backed up for you to `{{backupBranch}}`, approved or not. If
+mask-guard says the review cap is reached, report the range and wait for me.
 
-Frozen zones (do not touch): <paths>.
-WAITING ON THE HUMAN (hard list; do not touch): <list>.
+Frozen zones (do not touch): {{frozen}}.
+WAITING ON THE HUMAN (hard list; do not touch): {{waitingOnHuman}}.
 Design doubts go to me, never to the human: I decide them (or escalate them) and tell you.
 
 Gates (from `.claude/ring.json`, each through one-at-a-time; a long run such as a battery adds
 `--monitor <id>` when its command does not match a declared monitor, so it shows on the Scorecard):
-- typecheck: `<command>`
-- tests of what you touched: `<command with {paths}>`
-- lint: `<command>`
+
+- typecheck: `{{gateTypecheck}}`
+- tests of what you touched: `{{gateTest}}`
+- lint: `{{gateLint}}`
 
 Standing conditions: behavior identical; no base test assertion changes (if one has to, stop and
 tell me first); no new flags or env vars; one heavy command at a time; stage by paths;
-forbidAiTrailers is <true|false> (when true, no AI attribution trailers; human co-authors are
-fine); disk floor <5> GB.
+forbidAiTrailers is {{forbidAiTrailers}} (when true, no AI attribution trailers; human co-authors
+are fine); disk floor {{diskFloor}} GB.
 Do NOT run reviewers, review loops or Copilot. Do NOT open ready PRs. Do NOT merge or change bases.
-
----
-
-## Resume variant (a new session relaunches the wrestler)
-
-Same brief, plus at the top:
-
-You are resuming bout #<pr>; the previous wrestler stopped at `<sha>` while working on
-"<last subject>". First `git -C <worktree> status` and `git -C <worktree> diff`: finish and commit
-what was left uncommitted. Then read the open rebounds (`<bout dir>/rebounds.md`) and report the
-commit you are on before continuing with <concept>.
-
-## Cut-off variant (the same wrestler lost its connection)
-
-The API cut you off mid-edit (you were on "<last subject>"). `git status` and `git diff`, finish
-what was left uncommitted, commit it, read the last rebound (`<bout dir>/rebounds.md`) and report
-the commit you are on.

package/ring/skills/referee/templates/wrestler-cutoff.md

@@ -0,0 +1,4 @@
+The API cut you off mid-edit (you were on "{{lastSubject}}", at `{{headSha}}`). `git -C {{worktree}} status`
+and `git -C {{worktree}} diff`, finish what was left uncommitted, commit it, read the last rebound
+(`{{boutDir}}/rebounds.md`) and report the commit you are on. The rules you work by are the ones
+your first brief embedded; nothing about them changed.

package/ring/skills/referee/templates/wrestler-resume.md

@@ -0,0 +1,4 @@
+You are a new wrestler on bout #{{pr}}. The previous one stopped at `{{headSha}}` ("{{lastSubject}}").
+First `git -C {{worktree}} status` and `git -C {{worktree}} diff`: finish and commit what was left
+uncommitted. Then read the open rebounds (`{{boutDir}}/rebounds.md`) and report the commit you are
+on before continuing with {{nextConcept}}.

package/ring/skills/sparring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+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 (Sonnet at effort high by default) 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'
 ---
 
@@ -29,8 +29,16 @@ rest of the timebox goes to the controls that are still dead. Where time goes, 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.
+  (routes, shapes, error codes) to its own `<sparring dir>/contrato-<repo>.md` before implementing,
+  and every rudo starts at once against it. The consumer never waits for the producer's code.
+- **Every contract is written down the moment it is proposed**, with one repo too: each endpoint
+  and each data model a rudo adds or changes goes to `<sparring dir>/contrato-<repo>.md`
+  (`templates/contrato.md`) before it is implemented, with its shortcuts, and stays current when
+  the rudo changes it. **One file per repo, written only by that repo's rudo**: rudos run at the
+  same time, and two editing one file overwrite each other's entries. A rudo reads another repo's
+  file, never writes it. The sparring approves none of it: the referee bout that refactors a KO
+  opens with these bases and takes them to the judge first, because most of the code to build
+  depends on them.
 - **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.
@@ -114,7 +122,8 @@ defense|bell|mask-kept|mask-lost|no-team` the rest).
    for its repo (scope, designs, the other repos and what they exchange):
 
    ```
-   Agent{subagent_type: "ring:rudo", effort: "medium", run_in_background: true,
+   Agent{subagent_type: "ring:rudo", model: "<config.agents.rudo.model>",
+         effort: "<config.agents.rudo.effort>", run_in_background: true,
          description: "Rudo: <slug> <repo>", prompt: <the brief>}
    ```