@thebattlearena/corner 0.9.0 → 0.10.0

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/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

@@ -4,6 +4,9 @@
 
 Assignment: <what and why, in 3 lines>. PR #<pr>, branch `<branch>`, stack base `<base>`.
 
+Flow change (P15; write "none" when no flow changes): today <what happens>; after this PR <what
+will happen>; who notices <role or screen>.
+
 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).

package/ring/skills/sparring/SKILL.md

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

package/ring/skills/sparring/templates/contrato.md

@@ -0,0 +1,29 @@
+# Contracts proposed · {{slug}} · <repo>
+
+<!-- One entry per endpoint or data model a rudo adds or changes, written the moment it proposes
+     it, before implementing it. Nothing here is approved: the referee bout that refactors this
+     sparring opens with these bases, draws them and takes them to the judge (§2b) before any code
+     depends on them. Keep each entry current when the rudo changes it; never delete one, mark it
+     `dropped` with why. -->
+
+## Endpoints
+
+### `<METHOD> <path>` · <repo> · <new | changed | dropped>
+
+- **What it is for:** <the screen or action that calls it>.
+- **Request:** <path and query params, body fields with type and whether required>.
+- **Response:** <status and shape, fields with type; pagination when it lists>.
+- **Errors:** <status · code · when>.
+- **Scoping:** <tenant / workspace / user it is filtered by>.
+- **Shortcut taken:** <what the sparring skipped here: no DTO, no auth check, a mock… | none>.
+
+## Data models
+
+### `<table or entity>` · <repo> · <new | changed | dropped>
+
+- **Columns:** <name · type · nullable / default / unique / index>, one per line; a changed column
+  as `old → new`.
+- **Relations:** <→ other table, cardinality, ON DELETE rule>.
+- **Where it lives in the sparring:** <`tools/<file>.sql`, the entity path, or a JSON mock>.
+- **Backfill of existing rows:** <none | how>.
+- **Shortcut taken:** <a JSON column instead of a table, no index, no tenant FK… | none>.

package/ring/skills/sparring/templates/rudo-brief.md

@@ -34,6 +34,13 @@ Credentials (by NAME, never a value): <NAME, NAME | none>. Locally they live in
 Real sends: <none | which channel really sends (reply, call, email) and the variable with the
 judge's own destinations: `SPARRING_ALLOWED_<KIND>`, closed by default, the rest `not_allowlisted`>.
 
+Contracts: every endpoint or data model you add or change, write it to
+`<sparring dir>/contrato-<repo>.md`, your repo's own file (the other rudos write theirs at the same
+time: read them, never write them; the template is `<absolute ring path>/skills/sparring/templates/contrato.md`) the moment you
+propose it, before implementing it: method, path, request, response, errors and scoping; table,
+columns, relations and where it lives. Keep it current when you change it; a dropped one is marked
+`dropped`, never deleted. It is what the judge reviews first after a KO.
+
 Gate: typecheck only: `<command>`, through one-at-a-time.
 Database: additive only (new tables or columns, English names), and never against production.
 forbidAiTrailers is <true|false>.

package/ring/skills/weigh-in/SKILL.md

@@ -178,6 +178,12 @@ Do not ask about what you detected: show it and let the human correct it if they
   native files under each of its paths). While a bout is active, `mask-guard` locks the gates of
   every venue and the heavy commands of every declared venue (simulators, emulators, native
   builds), and blocks a commit of a native file the judge did not approve.
+- `format` is optional: `{ "tsconfig": "<path>" }` names the tsconfig sort-imports reads the
+  aliases from. Omit it when the repo's own sort-imports script passes `--tsconfig` or the root
+  has `tsconfig.json`: ring takes it from there, so the hooks sort as the repo's `sort` script
+  does. Write it when neither holds (a monorepo whose aliases live in one app's tsconfig). Tell
+  the human if the repo has no `node_modules/.bin/prettier` or `sort-imports`: ring formats with
+  what the repo installs and never downloads them.
 - `delegation` can be omitted when it is `referee`. Write it explicitly only if the human chose
   `human`, or if they want the choice visible in the file.
 - `precedents` is optional: omit it to use `.claude/ring-precedents.md` when that file exists.