@thebattlearena/corner 0.8.0 → 0.9.0

package/ring/skills/sparring/references/host-signal.md

@@ -0,0 +1,86 @@
+# The sparring signal: what a host project can hook into
+
+The ring never deploys anything. A sparring PR is the event, and each host project decides what
+to do with it. This page is the contract between the two.
+
+## 1. The event: the draft PR
+
+`/ring:sparring` opens a **draft** PR from `sparring/<slug>` with two labels: `sparring` (the host
+can rename it with `sparring.label` in `.claude/ring.json`) and `do-not-merge`. GitHub then emits:
+
+- `pull_request: labeled` when the PR is opened with its labels;
+- `pull_request: synchronize` every time the rudo pushes a new commit.
+
+A host that wants a preview listens to both in its CI:
+
+```yaml
+# .github/workflows/sparring-preview.yml (in the host repo, never in the ring)
+on:
+  pull_request:
+    types: [labeled, synchronize]
+jobs:
+  preview:
+    if: contains(github.event.pull_request.labels.*.name, 'sparring')
+    environment: sparring-preview # protected: the judge approves the deploy (§3)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # … whatever the project does: a hidden Amplify branch, a preview API, a local stack …
+```
+
+A host without a preview does nothing: the referee says so and the judge tests it locally.
+
+A sparring that spans several repos (a back and its front) opens one PR per repo, each from its
+own `sparring/<slug>` branch and each body linking the others. Every repo's CI reacts to its own
+PR and reads its own `.claude/ring.json`: a back may deploy a preview while its front does not.
+
+## 2. The answer: a GitHub deployment
+
+The ring reads the preview back from the **GitHub Deployments API**, for the exact tip of the
+sparring branch, in the environment named by `sparring.previewEnvironment`:
+
+```json
+"sparring": {
+  "label": "sparring",
+  "previewEnvironment": "sparring-preview",
+  "previewTimeoutMin": 20,
+  "staleDays": 7
+}
+```
+
+Amplify, Vercel and Netlify already publish deployments with an `environment_url`. A custom
+workflow publishes one by running in a GitHub `environment` with a `url`, or with the Deployments
+API. `node "$RING/scripts/sparring.mjs" preview <slug> --wait` polls every 30 s, stops on a
+terminal state (`success`, `failure`, `error`, `inactive`) and never waits past
+`previewTimeoutMin`. Only a `success` gives the judge a link; anything else is reported as it is.
+
+## 3. Credentials: names in the PR, values in the host
+
+A sparring against a provider's lab (a sandbox of Kapso, Stripe, an LLM vendor…) needs that
+provider's keys. **No value ever goes through the ring**: not the PR, the commits, the card, nor
+the session log. The PR body declares only the names, in a block the host's CI can parse:
+
+```
+<!-- sparring:credentials
+KAPSO_API_KEY
+KAPSO_WEBHOOK_SECRET
+-->
+```
+
+- The host resolves each name from its own secret store (secrets of the GitHub environment, SSM,
+  Vault…) and injects them into its preview.
+- A secret that does not exist yet is loaded **by the judge**, never by the referee or the rudo;
+  the referee gives the exact command (`gh secret set KAPSO_API_KEY --env sparring-preview`).
+- **Sandbox or test mode only.** A production credential breaks rule F (no real money, messages,
+  calls or customer events); the referee stops and escalates.
+- **Recommended:** protect the `sparring-preview` environment with the judge as required
+  reviewer. Then the secrets are released only when the judge approves that deployment, and a
+  sparring can never take the keys on its own.
+- The credentials a sparring declares are **assumed rotated** once it ends: the card and the PR
+  carry a fixed warning and nobody follows it up.
+
+## 4. The database
+
+A sparring changes the schema **additively only** (new tables or columns, English names) and never
+against production. If the host's preview has a database, it must not be the production one: the
+ring cannot check it, so it is the host's responsibility.

package/ring/skills/sparring/references/lessons.md

@@ -0,0 +1,50 @@
+# Lessons from verdicts
+
+What a judge said when calling `rematch` or `discard`, distilled into a rule that holds for the
+next sparring. The referee reads them in §0, pastes the ones that apply into each rudo brief, and
+appends a line here whenever a verdict leaves a new lesson (§4). A lesson is written as a rule, not
+an anecdote, with the date and the sparring that left it.
+
+- **Working, not superficial.** «El prototipo no tiene que quedar superficial, tiene que ser
+  funcional, el código fuera pero funcional». A metric on an empty page lets the judge decide
+  nothing: build the whole screen of the design, and every control does something.
+  _(2026-10-28, tira-morada-metricas)_
+- **The data comes from the back, not from front mocks.** The judge wants to see the services
+  resolve the information. A front mock only covers what no environment can give yet.
+  _(2026-10-28, tira-morada-metricas)_
+- **No data? Seed it.** A new feature has no workspace with activity: do not hunt for one, inject
+  synthetic rows and prove the endpoints resolve them. Locally first, without asking; a shared
+  database only when the judge asks, and the judge runs it with `!`.
+  _(2026-10-28, tira-morada-metricas)_
+- **Careless code is fast code.** A sparring in its fifth hour is paying for quality nobody asked
+  for: see «Pace» in the SKILL. _(2026-10-28, tira-morada-metricas)_
+- **A real send goes only to the judge's own destinations.** When the proof needs a message that
+  really leaves (Responder enviando de verdad), the judge fills their own test destinations in
+  `SPARRING_ALLOWED_<KIND>`; every judge brings theirs. Closed by default, the rest recorded as
+  `not_allowlisted`, and no destination ever written in a file. _(2026-10-28, tira-morada-metricas)_
+- **Choosing pieces is not approving the composition.** «Pero no hiciste las propuestas en pen»: when
+  the judge picks pieces out of several proposals, how they sit together goes through the design
+  tool (2–4 compositions) before any code. _(2026-10-29, tira-morada-metricas)_
+- **Keep a list of rejected patterns and check everything against it.** After ~15 rejected
+  proposals the same patterns kept coming back (a side bar on the left, a right column, a solid
+  pill on the current word). The referee keeps the list in the blows file, every brief carries it,
+  and it applies to what is already implemented too: one rejected bar was still in the code.
+  _(2026-10-29, tira-morada-metricas)_
+- **After two rejected rounds, start from named real references.** «Letras de Spotify», «Otter»,
+  «Notas de voz»: a proposal anchored to a product the judge knows converges faster than one
+  invented from scratch. _(2026-10-29, tira-morada-metricas)_
+- **One voice to the judge.** Options and choices go through the referee only; when two sessions
+  presented the same options, the judge answered a third one and the choice arrived secondhand.
+  _(2026-10-29, tira-morada-metricas)_
+- **Measure data as present only when it is non-empty.** `tool_calls` exists as a key in 98 % of
+  the calls but has an action in 19 %; a design built on the 98 % promised a fill it could not
+  keep. _(2026-10-29, tira-morada-metricas)_
+- **The click pass reloads and slows down.** Bugs the judge saw (a quote lost on reload, a deep
+  link outside the first page, loaders that flash in 5 ms) only show with a reload and a simulated
+  delay (`?delay=`); a click pass without them reports green. _(2026-10-29, tira-morada-metricas)_
+- **A partial screenshot is not a diagnosis.** «Todos los turnos marcan 0:00» came from a capture
+  showing only the first three turns, which really are in the first second. Before calling a bug,
+  read the data behind the screen (the API response) and the part of the screen that is not in the
+  capture. _(2026-10-29, tira-morada-metricas)_
+- **A question that blocks goes first, alone.** «El centrado del player no me necesitas no?, por que ese aun no lo veo implementado»: the question had been repeated at the end of five long status messages and the judge never saw it. When the next step waits on the judge, open the message with the question and its options, and leave the status for after. _(2026-10-30, tira-morada-metricas)_
+- **Sharing prep waits for «la defensa de los técnicos».** Migrations, the host build (a full typecheck and `next build`, not only `next dev`), a vendored SDK, identity per judge and a seed of the shared environment are done ONLY when the judge hints the team will attack it, never in advance. When that happens, expect all five to bite at once: this sparring had its tables only in a tools/ SQL, an SDK that existed only as a local tarball, one shared operator for every judge, a template DB without the workspace, and a type error only `next build` caught. _(2026-10-30, tira-morada-metricas)_

package/ring/skills/sparring/templates/pr-body.md

@@ -0,0 +1,34 @@
+**Sparring draft: it proves whether this is worth building. Never merge it.** The code is
+deliberately quick and dirty; if the judge calls it a KO, it passes the host gates, faces the
+team's review and then a ring bout refactors this branch
+(`/ring:referee start <pr> --from-sparring {{slug}}`).
+
+## Hypothesis
+
+{{hypothesis}}
+
+## The other repos of this sparring
+
+{{siblings}}
+
+## Proof of value
+
+What has to be seen to say "yes, this is worth it":
+
+{{proof}}
+
+## How to test it
+
+{{howToTest}}
+
+## Shortcuts the rudo took
+
+The debt a KO turns into the first rebound package of the bout.
+
+{{shortcuts}}
+
+## Credentials
+
+{{credentials}}
+
+{{credentialsBlock}}

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

@@ -0,0 +1,47 @@
+<!-- The referee fills every <…> and sends this as the prompt of
+     Agent{subagent_type: "ring:rudo", effort: "medium", run_in_background: true}.
+     Never `isolation: "worktree"`: the worktree already exists. -->
+
+Sparring `<slug>`: <the feature, in 3 lines>. Your repo: `<owner/repo>`, branch `sparring/<slug>`,
+base `<base>`.
+Other repos of this sparring: <`owner/repo` — its rudo, and what you exchange with it | none>.
+
+Worktree: `<absolute worktree path>`. Your cwd resets: every git command is `git -C <worktree> …`.
+Ring scripts: `<absolute ring path>/scripts`. Sparring dir: `<sparring dir>`; a helper you need goes
+in `<sparring dir>/tools/`, never in the repo.
+
+Hypothesis: <if X exists, the team / customer does Y>.
+Proof of value (what the judge has to see): <observable, unambiguous>.
+Full screen the judge sees, working (every visible control does something, data from the back): <the screen or flow, complete, as the design draws it; what exists
+already, and what you build quick and dirty or mock so nothing is a placeholder; what stays out on
+purpose>.
+Judge enters as: <user / workspace / account>.
+Seed: <none | what data the proof needs; you prepare it in tools/ (marked rows, unreachable values,
+dry run, cleanup) and the judge runs it>.
+Designs: <paths of .pen frames or images | none>. A `.pen` file is read only through the pencil MCP
+tools, never with Read or Grep.
+Timebox: <≤3> h from now (<end time>). When it runs out, stop and report what you have.
+Pace: a first clickable version of the whole screen within 90 minutes (<time>); report it, then
+every hour. Skip the ceremony: no migration in the repo (tables from a SQL in `tools/`), OpenAPI
+and generated types only before the last push, typecheck only before each push, no tests, wiki,
+DTOs, CQRS, ports or flags. List each skip as a shortcut.
+Blows from the judge for your repo this round (from `<sparring dir>/blows-round-<n>.md`, with the
+Tape minute; decisions are applied, never reopened): <none | the list>.
+Lessons from earlier verdicts that apply here: <lines from references/lessons.md | none>.
+
+Credentials (by NAME, never a value): <NAME, NAME | none>. Locally they live in
+`<worktree>/.env.sparring`, which the judge fills and you never commit, print or echo.
+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`>.
+
+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>.
+
+Hand-off between repos (when there are other repos): the producer leaves what the consumer needs in
+`<sparring dir>/tools/` (an SDK as `npm pack` tarball, a fixture, a mock) and reports its path, the
+port it serves on and one `curl` that proves it; the consumer installs it from there, never from a
+registry the sparring published to.
+
+Push only to `sparring/<slug>`: `git -C <worktree> push origin HEAD:sparring/<slug>`. Then report;
+the referee opens the PR. Do NOT open ready PRs, merge, change bases, or push anywhere else.

package/ring/skills/sparring/templates/sparring-card.md

@@ -0,0 +1,33 @@
+# Sparring card · {{slug}}
+
+Opened {{openedAt}}. One hypothesis and one verdict for every repo below.
+
+{{repos}}
+
+## Hypothesis
+
+{{hypothesis}}
+
+## Proof of value
+
+{{proof}}
+
+## Shortcuts the rudo took
+
+{{shortcuts}}
+
+## Credentials
+
+{{credentials}}
+
+## Verdict
+
+{{verdict}}
+
+### Earlier rounds
+
+{{earlierRounds}}
+
+<!-- ko: the vestidor (sparring.mjs vestidor {{slug}}), the team's defense until the bell unless «sin equipo»,
+     the mask, then a ring bout per repo refactors its branch (/ring:referee start <pr> --from-sparring {{slug}}).
+     rematch: adjust and test again, inside the timebox. discard: close it; why stays written here. -->

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

@@ -19,10 +19,14 @@ autodetected gates and safe defaults; the file exists so the human decides them
 node "$RING/scripts/config.mjs" detect
 ```
 
-It prints `gates` (typecheck, test, lint), `detectedFrom` (where each one came from), `missing`
-(what it could not detect) and `existingHostConfig`. If a host config already exists and the user
+It prints `gates` (typecheck, test, lint, and `build` when the repo has one), `detectedFrom` (where
+each one came from), `missing` (what it could not detect) and `existingHostConfig`. If a host config already exists and the user
 did not pass `--refresh`, show it and ask whether to rewrite it before going on.
 
+`build` is optional and never in `missing`: it comes from `package.json` `scripts.build`, a Makefile
+`build` target or `go build ./...`. Only the sparring's vestidor runs it (the host's real build after
+a KO); bouts and `mask-guard` ignore it. Without one, write `null` or leave it out.
+
 Test commands take `{paths}`: the wrestler runs only the tests it touched, never the whole suite.
 A test gate without `{paths}` (for example `make test`) runs everything; say so and ask for a
 by-path variant.
@@ -96,6 +100,14 @@ as "1. b" (AskUserQuestion only when the host repo's instructions require it), a
 
 Do not ask about what you detected: show it and let the human correct it if they want.
 
+10. **Sparring preview** (optional, one question): does this repo's CI deploy a preview for a
+    sparring PR (a draft from `sparring/<slug>` with the `sparring` label)? (a) no (default:
+    `previewEnvironment` stays null and the judge tests sparrings locally); (b) yes, in the GitHub
+    deployment environment `<name>`. Recommend protecting that environment with the judge as
+    required reviewer, so sparring secrets are released only on their approval, and remind them
+    the preview must never use the production database. The host contract is
+    `$RING/skills/sparring/references/host-signal.md`.
+
 ## 3. Write
 
 ```json
@@ -103,7 +115,8 @@ Do not ask about what you detected: show it and let the human correct it if they
   "gates": {
     "typecheck": "<command>",
     "test": "<command with {paths}>",
-    "lint": "<command or null>"
+    "lint": "<command or null>",
+    "build": "<command or null>"
   },
   "validateCommand": null,
   "reproduceCommand": null,
@@ -118,6 +131,7 @@ Do not ask about what you detected: show it and let the human correct it if they
   "reviewEvery": { "commits": 3, "lines": 200 },
   "backupBranch": "ring/{pr}/respaldo",
   "findingsGate": { "open": 0, "unshown": 3 },
+  "sparring": { "previewEnvironment": "sparring-preview", "previewTimeoutMin": 20 },
   "venues": {
     "backend": { "paths": ["apps/api/**", "packages/**"] },
     "frontend": {
@@ -194,6 +208,10 @@ Do not ask about what you detected: show it and let the human correct it if they
   ranges inside it are still open, and a push also waits while more than `unshown` findings the
   referee discarded or ticketed were never shown to the human. Title-defense and close always need
   a fresh full audit (`findings.mjs audit <pr> --full`), whatever this says.
+- `sparring` is optional (default `{ "label": "sparring", "previewEnvironment": null,
+  "previewTimeoutMin": 20, "staleDays": 7 }`): the label of sparring PRs, the GitHub deployment
+  environment the host's CI publishes their preview to, how long `sparring.mjs preview --wait`
+  waits, and after how many days a sparring without a verdict shows as stale.
 - `protectedBranches`: **while a bout is active, `mask-guard` blocks pushes to these branches**,
   including a bare `git push` from one of them. Tell the human both blocks exist when you show the
   config.