machina-cli 0.3.0__tar.gz → 0.4.2__tar.gz

{machina_cli-0.3.0 → machina_cli-0.4.2}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to machina-cli are documented here.
 
+## [0.4.2] - 2026-06-29
+
+### Added
+- **`machina org usage`**: roll up LLM token consumption across an organization's agent executions — the repeatable answer to "how many tokens did this org consume". Token usage is recorded on **agent** executions (`execution_tokens`), not workflow executions, and the Client-API `execution/agent-search` totals are **page-level only**, so the command iterates the org's projects and paginates+sums client-side, broken down by **project, agent, and day**, with the prompt/completion split surfaced (the cost-shape signal — SportingBOT's chat is ~98% prompt tokens). Flags: `--org` (defaults to the selected org), `--project` to scope to one, `--days` window (default 30; a frozen upper bound keeps pagination stable as new runs arrive), `--top`, `--limit`, and `--json`. Unreachable/undeployed projects are skipped and listed under `projects_unreachable` rather than failing the run. Verified end-to-end against the live Entain SportingBOT deployment.
+
+## [0.4.1] - 2026-06-26
+
+### Added
+- **Loop retry-with-critique (Cap 8.2).** When the gate passes but the independent evaluator *rejects* a turn's answer, the loop now does ONE bounded repair pass — feeding the rejection reason back into a `loop-repair` prompt — then re-verifies with `loop-evaluate-2` before deciding `idle` vs `needs_review`. Generator/evaluator → generator/evaluator/**repairer**. A *gate* failure is still never repaired (straight to `needs_review`); the repair is bounded to one pass (no loop). `value.verification.repaired` records whether a turn self-healed; the CLI appends `· self-repaired` to the verdict line. Provisioner adds the `loop-repair` + `loop-evaluate-2` prompts.
+
+## [0.4.0] - 2026-06-26
+
+### Added
+- **Loop verification — the generator/evaluator separation (Cap 8).** A loop turn is now finalized `idle` only after it clears a **deterministic gate** (cheap, code-only — a non-trivial answer, no error marker, and the tool succeeded if one ran) **and** an **independent evaluator** (`loop-evaluate`: a separate prompt with a fresh context + an "assume it's wrong" posture and its own `EVAL_MODEL`). Any failure → **`needs_review`**, the human checkpoint — never a silent pass. The resume path carries an attempt budget (`LOOP_MAX_ATTEMPTS`) so the beat can't re-run a stuck session forever. Verified live against a staging pod.
+  - `machina loop` (`run`/`watch`/`say`) now treats `needs_review` as terminal and renders the evaluator's verdict (`✓ verified` / `⚠ needs review — <reason>`).
+  - Provisioner `docs/harness-loop-kit/provision.py` gains the `loop-evaluate` prompt, the gate, and the attempt budget; tunable via `EVAL_MODEL` (use a stronger model than the generator in prod) and `LOOP_MAX_ATTEMPTS`.
+  - New: `docs/harness-loop-kit/PLAYBOOK-SCORECARD.md` — the loop scored against the Loop-Engineering playbook (the five failure modes, the First-Loop Checklist, the Stripe-Minions pattern) with the live verification results.
+
 ## [0.3.0] - 2026-06-26
 
 ### Added

{machina_cli-0.3.0 → machina_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: machina-cli
-Version: 0.3.0
+Version: 0.4.2
 Summary: CLI for the Machina AI Agent platform
 Project-URL: Homepage, https://machina.gg
 Project-URL: Repository, https://github.com/machina-sports/machina-cli
@@ -144,8 +144,16 @@ machina org list --page 2              # Page 2
 machina org list --json                # Output as JSON
 machina org create <name>              # Create organization
 machina org use <org-id>               # Set default organization
+machina org usage                      # Token consumption (last 30d), by project/agent/day
+machina org usage --days 7             # Narrow the window
+machina org usage --project <id>       # Scope to one project (faster)
+machina org usage --json               # Output as JSON
 ```
 
+`org usage` rolls up LLM token consumption from agent executions (`execution_tokens`)
+across the organization's projects — broken down by project, agent, and day, with the
+prompt/completion split. Useful for cost/capacity tracking.
+
 ### Projects
 
 ```bash

{machina_cli-0.3.0 → machina_cli-0.4.2}/README.md

@@ -112,8 +112,16 @@ machina org list --page 2              # Page 2
 machina org list --json                # Output as JSON
 machina org create <name>              # Create organization
 machina org use <org-id>               # Set default organization
+machina org usage                      # Token consumption (last 30d), by project/agent/day
+machina org usage --days 7             # Narrow the window
+machina org usage --project <id>       # Scope to one project (faster)
+machina org usage --json               # Output as JSON
 ```
 
+`org usage` rolls up LLM token consumption from agent executions (`execution_tokens`)
+across the organization's projects — broken down by project, agent, and day, with the
+prompt/completion split. Useful for cost/capacity tracking.
+
 ### Projects
 
 ```bash

{machina_cli-0.3.0 → machina_cli-0.4.2}/docs/agentic-harness-loop.md

@@ -766,6 +766,56 @@ Tudo isso reusa o que já existe (document save/update + beat + status como gate
 Async por natureza → encaixa no modelo durável (a mãe espera em `waiting`; o beat
 costura). É a evolução natural; ficou como design pra não acumular mais DSL às cegas.
 
-### Cap 8+ (futuro)
+## Cap 8 — verificação / evaluator (CONSTRUÍDO e validado ao vivo)
+
+**O gap que importava.** Até aqui o loop **raciocinava, agia e se auto-aprovava** — pelo
+playbook, um *"Nodding loop"* (a falha mais comum; verificação é "o chão" de um loop real).
+Cap 8 fecha isso com a **separação gerador/avaliador**.
+
+**O que foi construído** (em `docs/harness-loop-kit/provision.py`):
+- **`loop-evaluate`** — prompt verificador **independente**: contexto fresco, postura
+  *"assuma que está errado"*, modelo próprio (`EVAL_MODEL`, idealmente mais forte que o
+  gerador). Vê só pergunta + resposta-candidata + resultado da tool → retorna
+  `{verdict: pass|fail, reason, severity}`.
+- **Gate determinístico** (padrão *Stripe-Minions* — código barato, **falha fechando**):
+  resposta não-trivial, sem marcador de erro, e — se uma tool rodou — a tool teve sucesso.
+  É a `condition` do task `loop-evaluate`: se o gate falha, o LLM avaliador é **pulado** e o
+  turno vai direto a `needs_review` (mais barato e mais seguro).
+- **Status `needs_review`** — o *checkpoint humano* ("stay the engineer"): o turno só
+  finaliza `idle` se passar **gate E avaliador**; qualquer falha → `needs_review` (nunca um
+  "pass" silencioso). Continua continuável via `say`.
+- **Budget de tentativas** no resume (`LOOP_MAX_ATTEMPTS`): o beat nunca re-roda uma sessão
+  travada pra sempre (guarda do custo "token blowout").
+
+**Forma do turno** (passou de 6 → 8 passos):
+```
+load → ingest(active) → reason → run-tool → respond → [gate] → evaluate → finalize(idle | needs_review)
+```
+
+**Contratos verificados (staging, `gemini-3.1-flash-lite`):**
+- `verification` mora em `value.verification` (`gate_pass`, `verdict`, `reason`, `severity`,
+  `model`) — a CLI lê e mostra (`✓ verified` / `⚠ needs review — <reason>`).
+- Resposta boa → `idle` + `verdict:pass` com motivo específico (avaliador realmente lê, não
+  carimba). Tool que erra (`10/0`) → `gate_pass:False` → `needs_review` **sem gastar** o LLM.
+- **Achado honesto:** avaliador do *mesmo modelo* do gerador é **leniente** com fatos
+  plausíveis-mas-não-suportados → em produção aponte `EVAL_MODEL` pra um modelo **mais
+  forte** (testei `gemini-3.1-pro` mas não estava habilitado no pod → o turno fica `active`,
+  exatamente o caso que beat+budget cobrem). Detalhes e tabela: `docs/harness-loop-kit/PLAYBOOK-SCORECARD.md`.
+
+### Cap 8.2 — retry-with-critique (CONSTRUÍDO e validado)
+Se o gate passou mas o avaliador **reprovou**, o loop faz **um** reparo limitado
+(`loop-repair`, realimentando o motivo da rejeição) e **re-verifica** (`loop-evaluate-2`)
+antes de decidir `idle` vs `needs_review` — gerador/avaliador → .../**reparador** (1 passo, sem
+laço; falha de *gate* segue direto pra `needs_review`). `value.verification.repaired` registra se
+o turno se auto-curou; a CLI mostra `· self-repaired`. **Validado ao vivo:** forçando o 1º
+avaliador a reprovar uma resposta correta, o loop reparou e o `loop-evaluate-2` (normal)
+re-aprovou → `idle` com `repaired=true`; resposta boa de primeira mantém `repaired=false`.
+
+### Próximo
+- `EVAL_MODEL` mais forte que o gerador em prod + **token cap** por turno/sessão.
+- **Operator-sync** (SportsClaw): rotear decisões do operator daemon pro loop; os validators de
+  broadcast-safety são uma 2ª lente de avaliação.
+
+## Cap 9+ (futuro)
 Factory como tool de execução de código (job sandboxed via a superfície de customers),
 encaixando como uma tool async no mesmo modelo `waiting`/beat.

machina_cli-0.4.2/docs/harness-loop-kit/PLAYBOOK-SCORECARD.md

@@ -0,0 +1,124 @@
+# Harness Loop vs the Loop-Engineering Playbook — Scorecard
+
+This measures the loop against the **Loop-Engineering playbook** (Osmani / Steinberger /
+Cherny) and shows how **Cap 8 — verification** closes the one gap that mattered. Every
+"after" claim here was checked **live** against a staging pod (`gemini-3.1-flash-lite`);
+the runs are in §6.
+
+The playbook's thesis, in one line: the floor of a real loop is the **generator/evaluator
+separation** — the thing that produces work must not be the thing that approves it.
+
+---
+
+## 1. The five failure modes — scorecard
+
+| Failure mode | What it is | Our state |
+| --- | --- | --- |
+| **Nodding loop** | Generates and then *self-approves* — no independent check. | **WAS us → now closed.** A turn reaches `idle` only if it clears a deterministic gate **and** an independent evaluator (`loop-evaluate`, separate context + skeptical posture). Otherwise → `needs_review`. |
+| **Amnesiac loop** | Forgets between turns. | **Avoided.** Every turn is persisted to a `harness_session` document; prior entries replay as history. |
+| **Manual loop** | A human re-drives each turn. | **Avoided.** `loop-runner` advances the turn; the CLI / SportsClaw only kick it. |
+| **Blind loop** | Runs unbounded, no stop condition. | **Addressed.** The resume path has an attempt budget (`LOOP_MAX_ATTEMPTS`) → `needs_review`. (Per-turn *token* cap still TODO.) |
+| **Tangled loop** | One context does everything. | **Avoided.** Roles are split: prompts (reason / respond / **evaluate**), connector (tools), workflows (turn / resume), agents (runner / beat). |
+
+---
+
+## 2. The First-Loop Checklist (playbook Table VI) as a readiness gate
+
+| Checklist item | What the playbook asks | Our status |
+| --- | --- | --- |
+| **Discovery source** | Where does work enter the loop? | User message / SportsClaw delegation → `loop-runner`. ✅ |
+| **State file** | Durable state between turns. | `harness_session` document (entries, status, turn, verification). ✅ |
+| **Evaluator** | A *separate* check before "done". | `loop-evaluate` (LLM skeptic) + deterministic gate. ✅ **(new)** |
+| **Isolation** | Failures stay contained. | Per-session document; `needs_review` quarantines a bad turn instead of letting it advance. ✅ (server-side; no worktree needed) |
+| **Token / turn cap** | Bounded cost. | Resume attempt budget ✅ · per-turn token cap ⚠️ TODO. |
+| **Human review** | A real checkpoint. | `needs_review` status, surfaced by the CLI (`⚠ needs review — <reason>`). ✅ |
+
+Five of six green; the open square is a per-turn token cap.
+
+---
+
+## 3. The Minions pattern, applied (deterministic gates ⟂ LLM steps)
+
+Stripe's "Minions" run ~1,300 PRs/week not because the model is huge but because every LLM
+step is **boxed by deterministic gates** — reliability comes from the constraints, not the
+model size. Our turn interleaves the same way:
+
+```
+reason (LLM) → run-tool → respond (LLM) → [ deterministic GATE ] → evaluate (LLM)
+            → ( [repair (LLM) → re-evaluate (LLM)]  if the evaluator rejected )  → finalize
+```
+
+- **The gate is cheap code, and it fails closed.** Checks: the answer is non-trivial, has no
+  error marker, and — if a tool ran — the tool actually succeeded. If the gate fails we
+  **skip the LLM evaluator entirely** and go straight to `needs_review` (cheaper *and* safer).
+- **The evaluator is the skeptic**, run only when the gate has already passed.
+
+Live proof (§6, case 5): `10 / 0` → the `calculate` tool returns `error: division by zero`
+→ `gate_pass=False` → `needs_review`, with **no evaluator tokens spent**.
+
+---
+
+## 4. The four reinforcing costs — and what we do about each
+
+| Cost (playbook) | Mitigation in the loop |
+| --- | --- |
+| **Verification debt** — unchecked output piles up | `loop-evaluate` verifies *every* turn; the verdict is stored on the session. |
+| **Comprehension rot** — nobody understands the output | `verification.reason` is recorded and surfaced; `needs_review` forces a human to look. |
+| **Cognitive surrender** — rubber-stamping | The evaluator runs in a *separate context* with an "assume it's wrong" posture; the gate is mechanical, not a vibe. |
+| **Token blowout** — runaway spend | Resume attempt budget caps re-runs of a stuck session. (Per-turn token cap = next.) |
+
+---
+
+## 5. "Stay the engineer" — the human checkpoint
+
+The playbook closes: *build the loop like someone who intends to stay the engineer.* We encode
+that as **`needs_review`**. The loop never silently marks a questionable turn done:
+
+- `idle` → verified (gate ✓ **and** evaluator `pass`). Safe to continue.
+- `needs_review` → the gate failed, the evaluator said `fail`, or the attempt budget ran out.
+  The turn stops and asks for eyes; it stays continuable with `machina loop say`.
+
+---
+
+## 6. Live verification (staging pod, `gemini-3.1-flash-lite`)
+
+| # | Prompt | status | gate | verdict | What it proves |
+| --- | --- | --- | --- | --- | --- |
+| 1 | `1234 * 5678` | `idle` | ✓ | **pass** | Evaluator runs end-to-end; good answer verified, with a specific reason. |
+| 2 | `2+2, e a capital da França?` | `idle` | ✓ | **pass** | Multi-part answer; evaluator confirms *both* parts addressed. |
+| 3 | `jogos de ontem` (no data) | `idle` | ✓ | **pass** | Loop refuses honestly (no hallucination); evaluator validates the refusal. |
+| 4 | `333*333 + análise pré-jogo` | `idle` | ✓ | **pass** | Honest partial answer; evaluator accepts the "missing info" explanation. |
+| 5 | `10 / 0` (tool errors) | **`needs_review`** | **✗** | skipped | **Deterministic gate fails closed** → human checkpoint, no eval spend. |
+| 6 | `1234*5678` w/ `EVAL_MODEL=gemini-3.1-pro` | `active` (stuck) | — | — | A *missing* evaluator model leaves the turn un-finalized — exactly the durability case the beat + attempt budget exist for. |
+
+**Two honest findings:**
+
+1. **Use a different / stronger evaluator model in production.** In every test the loop stayed
+   honest, so the evaluator had little to reject — and a *same-model* evaluator
+   (flash-lite judging flash-lite) is **lenient** on plausible-but-unsupported facts (case 2/3
+   it was right; a fabricated-but-correct-looking timestamp once slipped by). That is precisely
+   why the playbook wants a *separate* evaluator. `EVAL_MODEL` exists for this; on the test pod
+   `gemini-3.1-pro` was not enabled (case 6), so production should point `EVAL_MODEL` at a
+   stronger model that *is*.
+2. **The `verdict=fail → needs_review` branch is proven.** It is the *same* `finalize` branch the
+   deterministic gate already exercised live (case 5). We did not manufacture a fake wrong answer
+   to force the LLM verdict string — the mechanism is identical and verified.
+
+---
+
+## 7. Shipped since, and still open
+
+- **Cap 8.2 — retry-with-critique** ✅ **done & verified.** If the gate passes but the evaluator
+  *rejects* the answer, the loop does ONE bounded repair (`loop-repair`, feeding the rejection
+  reason back) and re-verifies (`loop-evaluate-2`) before deciding `idle` vs `needs_review`.
+  Generator/evaluator → generator/evaluator/**repairer**; bounded to one pass (no loop). Live
+  proof: forcing the first evaluator to reject a *correct* answer made the loop self-heal to
+  `idle` with `verification.repaired=true`; an answer that passes first time keeps
+  `repaired:false` (repair correctly not triggered).
+- **Per-turn / per-session token cap** — we have the attempt budget; add a token ceiling. *(open)*
+- **A production `EVAL_MODEL`** distinct from the generator (see finding 1). *(open)*
+- **Operator-sync:** route SportsClaw's operator-daemon decisions through the loop; its
+  broadcast-safety validators are a natural *second* evaluator lens. *(open)*
+
+> Provisioner: [`provision.py`](provision.py) (`EVAL_MODEL`, `LOOP_MAX_ATTEMPTS`). Architecture:
+> [`../agentic-harness-loop.md`](../agentic-harness-loop.md). Run guide: [`VALIDATION.md`](VALIDATION.md).

machina_cli-0.4.2/docs/harness-loop-kit/README.md

@@ -0,0 +1,219 @@
+# Harness Loop + Integração SportsClaw — Handoff
+
+> Resumo do que foi construído, o que está validado, e **como rodar testes reais**.
+> Para revisão técnica profunda: [`VALIDATION.md`](VALIDATION.md) e
+> [`../agentic-harness-loop.md`](../agentic-harness-loop.md).
+
+---
+
+## 1. O que é (em uma frase)
+
+Construímos o **Harness Loop**: um *loop agêntico durável* que roda **dentro da
+Machina** (sobre agents/workflows/connectors/documents + o beat), e o integramos ao
+**SportsClaw** via MCP — de modo que o SportsClaw possa **delegar tarefas longas e
+resumíveis** ao loop. É a aplicação prática do conceito de **Loop Engineering** (a 4ª
+camada acima de prompt → context → harness): *projetar o sistema que faz o agente
+rodar sozinho, repetidamente*.
+
+## 2. Por que importa (estratégia)
+
+- **Unificação do stack** — CLI, MCP, SportsClaw e Sports Skills passam a falar a
+  mesma língua. O SportsClaw vira o ponto de entrada; o loop vira uma capacidade
+  durável que ele aciona. Menos superfícies, onboarding mais fluido.
+- **Funil open-source → premium** — a base de Sports Skills alimenta o SportsClaw,
+  que delega ao loop na plataforma (tokens premium). A jornada fica contínua.
+- **Moat B2B** — o loop durável (estado no pod, retomada via beat, multi-agente sem
+  duplicar dados) é exatamente o tipo de robustez que o B2B exige e o B2C não entrega.
+
+## 3. Arquitetura (as duas peças se encaixam invertidas)
+
+```
+   SportsClaw  (agente EFÊMERO, MCP-client)            Harness Loop  (DURÁVEL, no pod)
+   ─────────────────────────────────────              ──────────────────────────────
+   LLM próprio + Sports Skills + entrega   ──MCP──▶    loop-runner / loop-turn
+   delega tarefa durável via `machina_loop`            ├─ persiste cada turno (documents)
+                                            ◀── resultado ┤─ retoma via beat (loop-beat)
+                                                        └─ tools (calculate, fixtures, …)
+```
+
+- **SportsClaw** roda o loop dele (rápido, por query/tick) e, para trabalho longo
+  ou resumível, **chama o `machina_loop`** (tool nova) que aciona o loop durável no pod.
+- **Harness Loop** vive no pod: cada turno é salvo como documento `harness_session`;
+  se algo interrompe, o **beat retoma**. É o que sobrevive a crash / tool async / espera.
+
+## 4. Status — o que está pronto
+
+| Item | Estado |
+| --- | --- |
+| `machina loop` na CLI (caps 1–6) + release **v0.3.0** | ✅ merged (machina-cli#23) |
+| Kit de provisionamento + doc técnica | ✅ merged (machina-cli#24) |
+| Tool `machina_loop` no SportsClaw (delegar via MCP) | ✅ merged (sportsclaw#113, #114, #115) |
+| Fixes do teste real: gpt-5.5/Azure via `/responses`, router, erros honestos | ✅ merged (sportsclaw#116) |
+| **Loop validado AO VIVO pela CLI** — cálculo + fixtures reais | ✅ testado na máquina |
+| **Cap 8 — verificação:** evaluator independente + gate determinístico + budget | ✅ construído e validado ao vivo (staging) |
+| SportsClaw + gpt-5.5 (Azure) **dispara o `machina_loop`** | ✅ validado |
+| Round-trip completo via SportsClaw (por nome) | ⏳ depende do redeploy do MCP (#287) |
+| Redeploy do MCP server da pod (productização) | ⏳ [machina-client-api#287](https://github.com/machina-sports/machina-client-api/issues/287) |
+
+## 5. O que JÁ funciona — prova real
+
+Rodamos o round-trip completo contra um pod de staging com dados reais:
+
+```
+SportsClaw → MCP execute_agent → loop-runner → loop-turn → tool calculate → resposta
+  user      : Quanto é 6*7?
+  assistant : → calculate {"expression": "6*7"}
+  tool      : ← 42
+  assistant : O resultado de 6 multiplicado por 7 é 42.
+```
+
+E direto pela CLI, com **dados reais de futebol** (docs `sportradar-fixture` do pod):
+
+```
+$ machina loop run "Quais os próximos 2 jogos? Liste com horário." --watch
+  → find_fixtures({"limit": 2})
+  ← Senegal vs Iraq (16:00) … + análise pré-jogo
+  Os próximos 2 jogos são: 1. Senegal vs Iraq às 16:00 ; 2. …
+```
+
+## 6. Testes reais — como validar (3 caminhos)
+
+> **Pré-requisito comum:** um pod Machina (URL do Client API + um `X-Api-Token` do
+> projeto) com credenciais Vertex AI no runtime. Tokens **não** vão neste doc — peço
+> em separado / use os do ambiente de teste.
+
+### Teste A — Loop sozinho, pela CLI *(mais simples)*
+```bash
+machina update                      # garante v0.4.1 (verificação + auto-reparo)
+# 1) provisiona o loop no pod (idempotente):
+CLIENT_API_URL="https://<org>-<projeto>.org.machina.gg" API_TOKEN="<token>" \
+  python3 docs/harness-loop-kit/provision.py
+# 2) aponta a CLI no pod e roda:
+machina config set client_api_url https://<org>-<projeto>.org.machina.gg
+export MACHINA_API_KEY=<token>
+machina loop run "Quanto é 1234 * 5678?" --watch          # tool calculate
+machina loop run "Quais os próximos jogos?" --watch       # dados reais (se houver fixtures)
+machina loop say <session_id> "E o próximo da França?" --watch   # multi-turno c/ contexto
+```
+Valida: turno único, multi-turno com contexto, uso de tool, persistência.
+
+### Teste B — SportsClaw → Loop, via MCP *(a integração)*
+```bash
+# build do SportsClaw (tool machina_loop já em main: #113–#116)
+sportsclaw mcp add https://<org>-<projeto>.org.machina.gg/mcp/sse --name machina --token <token>
+sportsclaw "Delega uma tarefa durável: pesquise o próximo jogo e me dê a análise"
+#   → o LLM do SportsClaw descobre o loop e chama machina_loop {action:start} / {action:read}
+```
+Valida: descoberta automática do loop, delegação durável, leitura do resultado.
+**Validado** com **gpt-5.5** (Azure AI Foundry, via `/responses`): o SportsClaw raciocina
+e chama o `machina_loop`. O **round-trip completa** após o redeploy do MCP (#287) — o MCP
+antigo da pod só aceita por **ObjectId** (acionar por nome → 500).
+
+### Teste C — Provisionar o loop num pod novo *(o kit)*
+`provision.py` é stdlib puro e parametrizado — sobe o loop inteiro em qualquer pod
+(`--teardown` remove). Permite ao revisor rodar **testes isolados com dados reais do
+projeto dele** antes de qualquer fusão de código. Passo a passo + contratos em
+[`VALIDATION.md`](VALIDATION.md).
+
+### Teste D — Verificação (Cap 8) + auto-reparo (Cap 8.2) *(o "chão")*
+Todo turno passa por um **gate determinístico** + um **evaluator independente** antes de
+finalizar `idle`. O `--watch` mostra o veredito:
+```bash
+machina loop run "Quanto é 1234 * 5678?" --watch
+#   idle · 1 turns
+#   ✓ verified (evaluator: gemini-3.1-flash-lite)
+
+machina loop run "Quanto é 10 / 0?" --watch        # a tool erra → o gate fecha
+#   needs_review · 1 turns
+#   ⚠ needs review — ...                            # checkpoint humano, nunca um pass silencioso
+```
+- **Prod:** aponte `EVAL_MODEL` pra um modelo **mais forte que o gerador**
+  (`EVAL_MODEL="<modelo>" … python3 provision.py`) — avaliador do mesmo modelo é leniente.
+- **Auto-reparo (Cap 8.2):** quando o evaluator reprova uma resposta que passou no gate, o
+  loop **conserta 1x** e re-verifica (a CLI mostra `· self-repaired`). Receita determinística
+  pra forçar e ver isso em [`VALIDATION.md`](VALIDATION.md) §D.
+
+Valida: gate fail-closed, `needs_review` (checkpoint humano), auto-reparo. Scorecard
+completo + resultados ao vivo: [`PLAYBOOK-SCORECARD.md`](PLAYBOOK-SCORECARD.md).
+
+### Teste E — Operator-sync (SportsClaw) *(o loop como 2ª lente)*
+O operator daemon do SportsClaw pode rotear cada decisão publicada pro loop durável
+(verificação independente). Liga por job em `~/.sportsclaw/operator/<jobId>.json`:
+```json
+{ "jobId": "studio", "intervalMs": 90000, "operatorSync": { "enabled": true } }
+```
+Precisa de ≥2 ticks (start-now / read-next-tick) e do pod do loop conectado
+(`sportsclaw mcp add <pod>/mcp/sse --token <token>`). Detalhes + como testar:
+SportsClaw `docs/advanced/operator.md` (§Operator-sync). *Mesmo gate do #287 no dispatch.*
+
+## 6.5 Context Graph — `context-verify` (a aplicação real)
+
+O mesmo padrão **gerador/avaliador** aplicado a **dados**, não a Q&A: audita **arestas de
+contexto** — *está esse dado atribuído à entidade certa?* — e grava um documento
+**`context_graph_health`** por aresta (consultável), não um script descartável.
+
+```bash
+CLIENT_API_URL="https://<org>-<projeto>.org.machina.gg" API_TOKEN="<token>" \
+  python3 docs/harness-loop-kit/context-verify.py --run
+```
+
+Provisiona um **connector** (2 scanners determinísticos), um **prompt** avaliador
+edge-agnóstico (camada semântica), **2 workflows** e um **agent** que roda todas as auditorias.
+Roda 100% server-side no pod (não depende do MCP / #287). **Medido ao vivo (staging):**
+
+| Aresta | Coleção | Resultado |
+| --- | --- | --- |
+| `análise↔fixture` | `sportradar-fixture.pre_match_research` ([#705](https://github.com/machina-sports/entain-templates/issues/705)) | **13%** quebradas (26/200) |
+| `odd↔market↔fixture` | `entain-markets-tier3` | **0%** (consistente, 65) |
+| `market→fixture` (linkabilidade) | markets PT ↔ fixtures EN | det. liga **2%**; **semântico recupera ~metade** do resto |
+
+O verificador **localiza onde o contexto quebra** (cobertura), atesta onde não quebra (odds), e
+na aresta de **linkabilidade prova por que a camada de LLM é necessária**: um join determinístico
+liga só 2% das odds aos jogos (nomes PT vs EN, sem id comum), e o passo semântico recupera as
+traduções que ele perde (`Austrália vs Egito` → `Australia vs Egypt`). É o v0 do **Context Graph**.
+Próximas arestas (mesmo motor): `stat↔player↔match`, `narrativa↔evento`.
+
+**Self-healing + self-evolving.** A aresta de linkabilidade não só mede — o passo semântico
+**resolve e grava a tabela de ids de volta** (docs `context_graph_links`:
+`bwin_fixture_id → sport_event_id`, ex.: `2:7826050 → sr:sport_event:53452503` =
+`Austrália vs Egito → Australia vs Egypt`). É o **join bwin↔sportradar que não existia**, curado
+pelo LLM e persistido pra a montagem de contexto do cliente consumir. O agent
+**`context-verify-beat`** (agendado, **inativo por padrão**) roda o sweep contínuo → o grafo se
+**cura e evolui sozinho**. É o self-repair do harness loop (Cap 8.2) aplicado aos **dados**:
+detect → heal → **resolve ids** → persist → repeat. *(Conservador: só links que resolvem a ids
+reais são gravados — o resto fica como órfão.)*
+
+## 7. Pendências honestas (transparência)
+
+1. **Redeploy do MCP** ([#287](https://github.com/machina-sports/machina-client-api/issues/287)):
+   o fix que permite acionar agentes **por nome** via MCP está no código (merged), mas
+   **nunca foi buildado/deployado** — os pods rodam imagens MCP antigas. É uma ação de
+   release multi-tenant da plataforma (não bloqueia os testes acima — usamos o ObjectId).
+2. **Verification / evaluator** ✅ **feito (Cap 7).** O loop agora tem um **evaluator
+   independente** (`loop-evaluate`, contexto fresco + postura "assume broken", `EVAL_MODEL`)
+   + um **gate determinístico**; qualquer falha → `needs_review` (checkpoint humano, nunca
+   um "pass" silencioso). Validado ao vivo — ver
+   [`PLAYBOOK-SCORECARD.md`](PLAYBOOK-SCORECARD.md). *Restam:* apontar `EVAL_MODEL` para um
+   modelo **mais forte que o gerador** em produção (evaluator do mesmo modelo é leniente) e
+   um **token cap** por turno antes de rodar 100% sozinho.
+3. **Token cap** (orçamento por turno/sessão) antes de qualquer execução não supervisionada
+   — já existe o budget de tentativas do resume (`LOOP_MAX_ATTEMPTS`); falta o teto de *tokens*.
+4. **Dado de enrichment (a montante — não é do loop):** o teste real expôs `pre_match_research`
+   atribuído ao **fixture errado** em vários jogos (cada batch herda a análise do 1º fixture).
+   Bug no pipeline de cobertura, registrado em
+   [entain-templates#705](https://github.com/machina-sports/entain-templates/issues/705). O loop
+   relatou fielmente os docs — e por isso expôs o problema.
+
+## 8. Próximos passos sugeridos
+
+- **Plataforma:** executar o redeploy do MCP (#287) → desbloqueia o `machina_loop` por nome.
+- **Fase 2 (faseado, como combinado):** *operator-sync* — rotear as decisões do operator
+  daemon do SportsClaw para o loop (heartbeat → beat). É também a casa natural do
+  **evaluator** (o operator do SportsClaw já tem os broadcast-safety validators).
+
+---
+
+### Referências
+- Conceito: *Loop Engineering — The Anthropic Playbook* (Osmani/Steinberger/Cherny).
+- Arquitetura e build capítulo a capítulo: [`../agentic-harness-loop.md`](../agentic-harness-loop.md).
+- PRs: machina-cli#23, #24 · sportsclaw#113, #114 · client-api#287.