@jaimevalasek/aioson 1.23.1 → 1.28.0

package/docs/en/5-reference/executable-verification.md

@@ -0,0 +1,165 @@
+# Executable verification — AIOSON (EN)
+
+> **What this is:** the reference for AIOSON's "executable verification" theme (versions 1.24.0–1.28.0).
+> **Reading time:** 8 min.
+> **What you will learn:**
+> - How AIOSON turns binary success criteria into deterministic, runnable checks
+> - The five phases: `verification` + `harness:check`, the fresh-context validator, `spec:analyze`, Wave markers, and Lane B (`forge:compile` + `@forge-run`)
+
+---
+
+## The idea in one paragraph
+
+AIOSON already has two strong foundations: the **`harness-contract.json`** (binary success criteria per feature) and the **SDD artifact chain** (PRD → spec → plan → conformance). The executable-verification theme builds on both to make verification **deterministic** (run a command, read an exit code) and to make specs **compilable** (turn a ready spec into an auditable workflow). Everything is **additive**: the default lane — `@scope-check` → `@dev` → `@qa` → `@validator` — is **unchanged**. The new pieces tighten the verification surface without rerouting existing flows.
+
+The theme ships in five phases.
+
+---
+
+## Phase 1 (v1.24.0) — `harness:check` + the `verification` field
+
+A `harness-contract.json` criterion can now carry an authored **`verification`** field: a shell command that proves the criterion mechanically. `@sheldon` authors it for every mechanically-checkable `binary: true` criterion — preferring the project's own test runner, deterministic, cross-platform, with **exit 0 = pass**. Legacy contracts without `verification` stay valid; `validateContract` only emits an advisory **warning** (never an error) for `binary: true` criteria that lack it.
+
+The new command runs those commands deterministically:
+
+```bash
+# Run every verifiable criterion of the active contract (auto-discovered)
+aioson harness:check . --slug=checkout
+
+# Run only a subset of criteria
+aioson harness:check . --slug=checkout --criteria=C1,C3
+
+# Custom timeout and JSON output (exit 0 = pass)
+aioson harness:check . --slug=checkout --timeout=120000 --json
+```
+
+`harness:check` runs **outside** the self:loop and is **read-only** over `progress.json` — it never mutates circuit-breaker state. It reuses the loop's `runCriteria`/`executeInSandbox` machinery, so it inherits timeouts, process-tree kill, credential redaction, and failure signatures. It persists `last-check-output.json` and emits `criteria_check_failed` telemetry on failure. With `--slug` omitted, it auto-discovers the active contract; `--criteria` runs a subset.
+
+**Validator impact:** `@validator` now runs `harness:check` **first** and copies the exit-code verdicts **verbatim** into `results[].passed`. It only LLM-judges the criteria that have no `verification`. The output schema is unchanged.
+
+See [`harness:check`](./cli-reference.md#harnesscheck) in the CLI reference.
+
+---
+
+## Phase 2 (v1.25.0) — Fresh-context validator (review payload)
+
+`harness:validate` now appends a self-contained **review payload** to the generated `validator-prompt.txt`, so the validator can judge without access to the implementing session:
+
+- (a) the `harness:check` results,
+- (b) the changed-file list (untracked files included; `.aioson/**` framework state filtered out),
+- (c) a unified diff against a resolved base.
+
+```bash
+# Generate the validator prompt with review payload
+aioson harness:validate . --slug=checkout
+
+# Resolve the diff against an explicit base
+aioson harness:validate . --slug=checkout --base=main
+
+# Skip the diff (results + changed files still included)
+aioson harness:validate . --slug=checkout --no-diff
+
+# Cap the embedded diff size
+aioson harness:validate . --slug=checkout --max-diff-bytes=200000
+```
+
+The base is resolved in this order: `--base` > `baseline.json` head > merge-base with `main`/`master` > `HEAD`. `--max-diff-bytes` defaults to `200000` and truncates on a line boundary; `--no-diff` is a pure boolean flag that skips the diff. The payload degrades gracefully outside a git repo. The work lives in a new module, `src/harness/review-payload.js`.
+
+**Protocol:** `@validator` runs in a **fresh, isolated context** — a subagent (Task tool) or a separate session — **never inline** in the implementing session, because implementation history biases the verdict. The flow is:
+
+```text
+harness:check  →  harness:validate  →  isolated subagent run  →  harness:validate (consume verdict)
+```
+
+The final `harness:validate` re-run consumes the verdict back through the circuit breaker.
+
+See [`harness:validate`](./cli-reference.md#harnessvalidate) in the CLI reference.
+
+---
+
+## Phase 3 (v1.26.0) — `spec:analyze` cross-artifact consistency
+
+`spec:analyze` is the **content** sibling of `artifact:validate`. Where `artifact:validate` checks chain **presence** (unchanged), `spec:analyze` checks **consistency of content** across the feature's artifacts before the execution gate:
+
+```bash
+# Analyze cross-artifact consistency
+aioson spec:analyze . --feature=checkout
+
+# JSON output for gate scripting (errors → exit 1)
+aioson spec:analyze . --feature=checkout --json
+```
+
+It runs five deterministic checks:
+
+1. **REQ/AC ID traceability** — declared-but-unreferenced = coverage-gap warning; referenced-but-undeclared = orphan/drift warning (noise-guarded for prose plans).
+2. **Staleness** — an upstream artifact modified after a downstream one = warning (60s tolerance; the project-global `architecture.md` is excluded).
+3. **Readiness** — `blocked` = error; `ready_with_warnings` = info.
+4. **Harness-contract sanity** — schema errors = error; executable-coverage = info.
+5. **AC→contract linkage** = info.
+
+An `error` flips `ok: false` (exit 1 in `--json`). Results persist to `spec-analyze-{slug}.json`. `@scope-check` runs `spec:analyze` in preflight: **errors are blockers, warnings are pre-computed drift evidence**.
+
+See [`spec:analyze`](./cli-reference.md#specanalyze) in the CLI reference.
+
+---
+
+## Phase 4 (v1.27.0) — Wave parallelism markers
+
+`@pm`'s Execution Sequence table gains a **`Wave`** column. Same-wave phases are **file-disjoint and dependency-free**, so they can run in parallel (via isolated subagents or worktrees). Waves run in ascending order, and marking is **conservative**: when in doubt, sequential.
+
+`spec:analyze` gains the **`wave_file_overlap`** check: same-wave phases that share Primary files raise a warning. Plans without a `Wave` column skip the check entirely.
+
+The Wave column is what Phase 5 compiles into `parallel()` blocks.
+
+---
+
+## Phase 5 (v1.28.0) — Lane B: `forge:compile` + `@forge-run`
+
+Lane B is an **opt-in, additive** second lane: it compiles a MEDIUM feature's artifacts into a single auditable, versionable workflow and runs the whole verification cycle end to end. The default lane stays the recommended path.
+
+```bash
+# Compile the feature into a forge-run.workflow.js
+aioson forge:compile . --feature=checkout
+
+# JSON output (hard preflights may refuse)
+aioson forge:compile . --feature=checkout --json
+```
+
+`forge:compile` produces `.aioson/plans/{slug}/forge-run.workflow.js` — a Claude Code dynamic-workflow script committed alongside the spec. Its structure mirrors the whole theme:
+
+- one **`parallel()` per Wave** (file-disjoint dev agents; blocked-wave early stop),
+- a deterministic **`harness:check` convergence loop** bounded by the governor's `error_streak_limit` (sequential fixes — only waves prove disjointness) plus a token-budget guard,
+- a **3-lens adversarial review** (correctness / completeness / regression-risk; majority survives; refute-by-default) for binary criteria **without** `verification`,
+- a **fresh-context validator** stage closing through `harness:validate` → `last-validator-output.json` → `apply-validation`.
+
+**Hard preflights** refuse compilation and name the owning agent: invalid/missing contract, zero executable criteria, plan without a `Wave` column, `spec:analyze` errors, and `wave_file_overlap` (a warning in `spec:analyze`, an **error** here). The generated code is deterministic by construction: pure-literal metadata, plain JS, no `Date.now`/`Math.random`/`new Date`, artifact text via `JSON.stringify` (injection-safe). It **never** runs `feature:close`. New module: `src/harness/plan-waves.js`.
+
+The opt-in entry point is the **`@forge-run`** agent: compile → review with the user (cost warning) → execute via the workflow runtime (never hand-emulated) → report. One feature per run. **PASS** recommends the human run `feature:close`; **FAIL** routes to `@dev` via the normal lane. It never auto-runs `feature:close`/publish.
+
+See [`forge:compile`](./cli-reference.md#forgecompile) in the CLI reference and the [@forge-run agent card](../4-agents/forge-run.md).
+
+---
+
+## How the phases fit together
+
+```text
+@sheldon authors verification ──► harness:check (deterministic, exit 0 = pass)   [Phase 1]
+                                        │
+@scope-check runs spec:analyze ◄────────┤  (errors block, warnings = drift)       [Phase 3]
+@pm fills the Wave column ──────────────┤  (parallelizable, file-disjoint)        [Phase 4]
+                                        │
+default lane:  @dev ► @qa ► harness:validate (review payload)                      [Phase 2]
+                              └► @validator in a FRESH, ISOLATED context
+                                        │
+Lane B (opt-in):  @forge-run ► forge:compile ► run the compiled workflow          [Phase 5]
+```
+
+The default lane and Lane B consume the **same** contract, plan, and `spec:analyze` results — Lane B just compiles them into one executable script.
+
+---
+
+## See also
+
+- [CLI reference](./cli-reference.md) — `harness:check`, `harness:validate`, `spec:analyze`, `forge:compile`
+- [@forge-run agent card](../4-agents/forge-run.md) — the opt-in Lane B entry point
+- [Agents index](../4-agents/README.md) — `@sheldon`, `@pm`, `@scope-check`, `@validator`

package/docs/pt/4-agentes/README.md

@@ -1,6 +1,6 @@
 # Guia de Agentes AIOSON
 
-> Índice com 29 agentes e 1 alias, com situação de uso e saída esperada.
+> Índice com 30 agentes e 1 alias, com situação de uso e saída esperada.
 > Cada agente tem sua ficha — clique no nome para detalhes.
 > `@pair` é alias de `@deyvin` e não possui ficha separada.
 
@@ -20,6 +20,7 @@
 | [@dev](./dev.md) | Implementa a feature | Após planning completo | código + `dev-state.md` |
 | [@qa](./qa.md) | Testa, valida ACs, ciclo autônomo com `@dev` | Após `@dev` | `test-plan.md`, `qa-report-*.md` |
 | [@validator](./validator.md) | Gate final: valida contrato binário de sucesso | Após `@qa`, antes de fechar feature | veredicto em `last-handoff.json` |
+| [@forge-run](./forge-run.md) | Lane B opt-in: compila e roda o workflow de verificação executável de uma feature MEDIUM | MEDIUM com contrato `verification` + plano com Wave | `forge-run.workflow.js` |
 | [@tester](./tester.md) | Engenharia de testes para apps já existentes | Legacy/brownfield ou lacunas graves | `test-inventory.md` |
 | [@pentester](./pentester.md) | Revisão adversarial de segurança | Antes de publicar ou por demanda | `security-findings-*.json` |
 

package/docs/pt/4-agentes/forge-run.md

@@ -0,0 +1,150 @@
+# @forge-run — Compile e execute o workflow da Lane B (verificação executável)
+
+> **Para quem é:** quem tem uma feature MEDIUM com contrato binário e plano por waves, e quer rodar todo o ciclo de execução verificável em um único workflow compilado.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que é a Lane B e por que ela é **opt-in** e **aditiva**
+> - O protocolo: `forge:compile` → revisão com você → execução → relatório
+> - Por que `@forge-run` nunca enfraquece uma verificação nem fecha a feature
+
+---
+
+## Para que serve
+
+A lane padrão de verificação executável (`@scope-check` → `@dev` → `@qa` → `@validator`) continua **inalterada** e é o caminho recomendado. O `@forge-run` é uma **segunda lane (Lane B), opcional e aditiva**: ele compila os artefatos de uma feature MEDIUM num único **workflow versionável** e roda o ciclo inteiro de verificação determinística de ponta a ponta.
+
+Em vez de avançar etapa a etapa manualmente, `@forge-run` gera `.aioson/plans/{slug}/forge-run.workflow.js` — um script de dynamic workflow do Claude Code — e o executa via runtime de workflows. A estrutura compilada reflete o roadmap de verificação executável:
+
+- **`parallel()` por Wave** — fases na mesma wave são disjuntas em arquivos e rodam em paralelo (ver coluna `Wave` do [@pm](./pm.md)).
+- **Loop determinístico sobre `harness:check`** — limitado pelo `error_streak_limit` do governor; fixes são sequenciais.
+- **Revisão adversarial de 3 lentes** — para os critérios que não têm `verification` (e portanto não podem ser checados mecanicamente).
+- **Validador em contexto fresco** — fecha pelo ciclo `apply-validation` (ver [@validator](./validator.md)).
+
+**Regra dura:** uma feature por run. `@forge-run` nunca roda `feature:close` nem publica.
+
+---
+
+## Quando invocar
+
+- Feature **MEDIUM** com `harness-contract.json` contendo `verification` por critério (autorado pelo [@sheldon](./sheldon.md)).
+- Plano de implementação com a coluna `Wave` preenchida (produzido pelo [@pm](./pm.md)).
+- `aioson spec:analyze` limpo (sem `errors`) — pré-condição do gate de execução.
+- Quando você quer rodar todo o ciclo de verificação executável como um único workflow reproduzível e versionável.
+
+---
+
+## Quando NÃO invocar
+
+- Features MICRO ou SMALL → use a lane padrão (`@dev` → `@qa` → `@validator`).
+- Contrato sem critérios executáveis, ou plano sem Wave → os preflights duros recusam compilar.
+- `spec:analyze` com `errors` ou `wave_file_overlap` → resolva antes; a Lane B não compila por cima de drift.
+- Você quer apenas validar, não executar → use `@validator` diretamente.
+
+---
+
+## Inputs obrigatórios
+
+A Lane B só compila quando todos os pré-requisitos estão presentes — caso contrário os preflights duros recusam:
+
+- `.aioson/plans/{slug}/harness-contract.json` — contrato **válido**, com pelo menos um critério executável (`verification` presente).
+- `implementation-plan-{slug}.md` — plano com a coluna `Wave` preenchida.
+- `spec-analyze-{slug}.json` sem `errors` e sem `wave_file_overlap`.
+
+---
+
+## Diálogo típico
+
+```
+Você > @forge-run
+
+@forge-run > Feature: checkout-stripe (MEDIUM)
+
+             Preflight da Lane B:
+             - harness-contract.json válido ✓
+             - 5 critérios, 4 com verification (executáveis) ✓
+             - implementation-plan com coluna Wave ✓
+             - spec:analyze → ok, sem errors, sem wave_file_overlap ✓
+
+             $ aioson forge:compile . --feature=checkout-stripe
+             Compilado: .aioson/plans/checkout-stripe/forge-run.workflow.js
+
+             Estrutura do workflow:
+             - Wave 1 (parallel): backend + migrations
+             - Wave 2: frontend
+             - Loop harness:check (limite error_streak: 3, fixes sequenciais)
+             - Revisão adversarial de 3 lentes para C5 (sem verification)
+             - Validador fresh-context → apply-validation
+
+             ⚠ Custo: este workflow roda múltiplas execuções de LLM.
+             Revise o script antes de executar. Aprovar execução? (s/n)
+
+Você > s
+
+@forge-run > Executando via runtime de workflows...
+             Wave 1 ✓  Wave 2 ✓
+             harness:check → 4/4 critérios executáveis PASS
+             Revisão adversarial C5 → PASS
+             Validador fresh-context → overall_score: 1
+
+             RESULTADO: PASS
+             Recomendação: rode `aioson feature:close` manualmente.
+```
+
+---
+
+## Saídas em disco
+
+| Arquivo | Conteúdo |
+|---|---|
+| `.aioson/plans/{slug}/forge-run.workflow.js` | Workflow compilado e versionável (dynamic workflow do Claude Code) |
+| `.aioson/plans/{slug}/last-check-output.json` | Último resultado do `harness:check` consumido pelo loop |
+| `.aioson/plans/{slug}/last-validator-output.json` | Veredicto do validador fresh-context |
+| `.aioson/plans/{slug}/progress.json` | Estado pós-execução (`circuit_state`, `ready_for_done_gate`) |
+
+O código gerado é determinístico por construção: metadados literais, sem `Date.now`/`Math.random`, texto sempre via `JSON.stringify`, e **nunca** invoca `feature:close`.
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/plans/{slug}/harness-contract.json` — contrato e critérios com `verification`
+- `.aioson/context/implementation-plan-{slug}.md` — plano com coluna `Wave`
+- `.aioson/plans/{slug}/spec-analyze-{slug}.json` — consistência cross-artefato (gate de execução)
+- `.aioson/plans/{slug}/progress.json` — estado e `error_streak_limit` do governor
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Compila os artefatos da feature no workflow da Lane B
+aioson forge:compile . --feature={slug}
+
+# (saída parseável)
+aioson forge:compile . --feature={slug} --json
+```
+
+---
+
+## Regras duras
+
+- **Nunca** passa por cima de um preflight que falhou (contrato inválido, zero critério executável, plano sem Wave, `errors` ou `wave_file_overlap` do `spec:analyze`).
+- **Nunca** enfraquece ou remove uma checagem de `verification` para fazer um critério passar.
+- **Nunca** roda `feature:close` nem publica — isso é sempre decisão humana.
+- Uma feature por run.
+
+---
+
+## Handoff típico
+
+- **Vem de:** entrada opt-in pelo usuário (Lane B); pressupõe `@sheldon`, `@pm` e `@scope-check`/`spec:analyze` já concluídos.
+- **PASS:** recomenda que o **humano** rode `aioson feature:close` manualmente.
+- **FAIL:** volta ao `@dev` pela **lane normal** para corrigir e re-verificar.
+
+---
+
+## Próximo passo
+
+- [Ficha do @pm](./pm.md) — produz a coluna `Wave` que vira `parallel()` no workflow
+- [Ficha do @sheldon](./sheldon.md) — autora o campo `verification` por critério
+- [Ficha do @validator](./validator.md) — o validador fresh-context que fecha o ciclo

package/docs/pt/4-agentes/pm.md

@@ -35,6 +35,14 @@ Para o projeto completo (configuração inicial), `@pm` entra após `@ux-ui` e a
 
 ---
 
+## Coluna `Wave` na Execution Sequence (v1.27.0+)
+
+A tabela **Execution Sequence** do `implementation-plan-{slug}.md` ganhou a coluna `Wave`. Fases marcadas na **mesma wave** são **disjuntas em arquivos** (não tocam nos mesmos arquivos) e, portanto, **paralelizáveis** — é exatamente essa marcação que a Lane B do [@forge-run](./forge-run.md) compila em blocos `parallel()`.
+
+A marcação é **conservadora**: na dúvida, o `@pm` deixa sequencial. Só agrupa na mesma wave quando tem certeza de que não há sobreposição de arquivos.
+
+O `aioson spec:analyze` verifica a consistência das waves: mesma wave com arquivos sobrepostos dispara o warning `wave_file_overlap`, que o [@scope-check](./scope-check.md) trata como drift pré-computado.
+
 ## Quando invocar
 
 - Features MEDIUM (obrigatório no workflow — produz Gate C).

package/docs/pt/4-agentes/qa.md

@@ -115,6 +115,8 @@ aioson dossier:show . --slug=checkout-stripe
 - **Vem de:** `@dev`
 - **Vai para:** `@validator` (quando há harness-contract) ou encerramento da feature
 
+> Desde a v1.24.0, o `@validator` roda `aioson harness:check` **primeiro** (verificação determinística, exit 0 = pass) e julga por LLM só os critérios sem `verification`. Ele é ativado a partir do `validator-prompt.txt` autocontido (critérios + resultados do check + diff vs. base) em **contexto fresco e isolado** — não na sessão que implementou. Ver [Ficha do @validator](./validator.md).
+
 ---
 
 ## Próximo passo

package/docs/pt/4-agentes/scope-check.md

@@ -11,9 +11,26 @@ Ele evita drift de escopo: antes de codar, confere se tudo que foi decidido est
 - Após `@dev` e/ou correções de `@qa`/`@tester`/`@pentester`, quando houve mudança material de código ou comportamento.
 - Em reaberturas de feature com risco de quebra de contrato entre o que foi planejado e o que está sendo entregue.
 
+## Preflight determinístico: `spec:analyze` (v1.26.0+)
+
+No modo `pre-dev`, antes de julgar, o `@scope-check` roda `aioson spec:analyze . --feature={slug}` — uma checagem **determinística** de consistência entre artefatos, executada **antes do gate de execução**. Ela cobre:
+
+- rastreabilidade REQ/AC (gaps e órfãos);
+- staleness (upstream modificado depois do downstream);
+- readiness `blocked` (vira `error`);
+- sanidade do contrato e vínculo AC→contrato;
+- `wave_file_overlap` (mesma wave + arquivos sobrepostos — ver coluna `Wave` do [@pm](./pm.md)).
+
+Interpretação:
+
+- **`errors` são blockers** — `spec:analyze` retorna `ok:false` e o `@scope-check` não libera para `@dev`.
+- **`warnings` são evidência de drift pré-computada** — entram no relatório como divergências a confirmar, sem necessariamente bloquear.
+
+O resultado é persistido em `spec-analyze-{slug}.json`.
+
 ## Modos
 
-- `pre-dev` (padrão): valida intenção e plano antes da primeira implementação.
+- `pre-dev` (padrão): valida intenção e plano antes da primeira implementação (roda `spec:analyze`).
 - `post-dev` (opcional): valida se o diff entregue bate com o plano aprovado.
 - `post-fix` (opcional): valida se correções mantiveram o escopo e contrato.
 - `final` (opcional): reconcilia intenção, plano e resultado de fechamento.
@@ -34,6 +51,7 @@ Cria/atualiza:
 
 - `.aioson/context/scope-check.md` (modo projeto)
 - `.aioson/context/scope-check-{slug}.md` (modo feature)
+- `.aioson/plans/{slug}/spec-analyze-{slug}.json` (resultado do `spec:analyze` no `pre-dev`)
 
 O relatório deve indicar:
 

package/docs/pt/4-agentes/sheldon.md

@@ -69,6 +69,8 @@ O `@sheldon` decide entre **enriquecer in-place** ou **criar plano faseado** dep
 
 **Re-entrante:** se `sheldon-enrichment.md` já existir, o `@sheldon` detecta e oferece nova rodada sem refazer do zero. Você pode invocá-lo 2, 3, N vezes — cada rodada fecha mais gaps.
 
+**Campo `verification` no contrato (v1.24.0+):** ao gerar o `harness-contract.json`, o `@sheldon` agora autora um comando de shell `verification` para **todo critério `binary:true` mecanicamente verificável** (exit 0 = pass). Ele prefere o test runner do próprio projeto, mira em comandos determinísticos e cross-platform. Com isso, `aioson harness:check` consegue verificar o critério de forma determinística, fora do `self:loop`, e o `@validator` copia o exit code verbatim no veredicto. Contratos legados sem o campo continuam válidos (o `@validator` cai no julgamento por LLM para esses critérios).
+
 ## Como ele lê seu projeto
 
 1. `.aioson/context/project.context.md` — stack e classificação.

package/docs/pt/4-agentes/validator.md

@@ -86,6 +86,26 @@ Apenas e exclusivamente:
 
 ---
 
+## Ativação em contexto fresco (v1.24.0+)
+
+A ativação preferida do `@validator` é o **`validator-prompt.txt` autocontido** gerado por `aioson harness:validate`. Esse prompt embute um REVIEW PAYLOAD com tudo que ele precisa para julgar sem depender de chat anterior:
+
+- os critérios do `harness-contract.json`;
+- os **resultados do `harness:check`** (verificação determinística, exit 0 = pass);
+- a lista de arquivos alterados e o **diff unificado vs. base resolvida** (`--base` > `baseline.json` > merge-base `main`/`master` > `HEAD`; default `--max-diff-bytes` 200KB; `--no-diff` omite). Fora de git, degrada graciosamente.
+
+Por isso o `@validator` roda em **contexto fresco e isolado** — subagente (Task tool) ou sessão separada, nunca inline na sessão que implementou. O histórico de implementação enviesa o veredicto.
+
+**Ordem de operações:**
+
+1. Roda `harness:check` **primeiro** e copia o exit code **verbatim** em `results[].passed` — não re-julga o que a máquina já decidiu.
+2. Só usa julgamento por LLM nos critérios **sem** `verification` (não verificáveis mecanicamente).
+3. O schema de saída permanece inalterado (`overall_score: 1 | 0`).
+
+Fluxo completo: `harness:check` → `harness:validate` → execução isolada → re-rodar `harness:validate` para o output ser consumido pelo circuit breaker (`apply-validation`).
+
+---
+
 ## Handoff típico
 
 - **Vem de:** `@qa` (recomenda `@validator` no relatório quando `harness-contract.json` existe).

package/docs/pt/5-referencia/autopilot-handoff.md

@@ -57,6 +57,25 @@ Uma vez que o `@dev` inicial termina, o autopilot retoma automaticamente:
 
 `@tester` e `@pentester` só executam quando os seus triggers disparam (`@qa` identifica gaps de cobertura → `@tester`; superfície sensível auth/secrets/data → `@pentester`).
 
+### Protocolo de contexto fresco do @validator
+
+O `@validator` roda em contexto **fresco e isolado** (subagente/Task tool ou sessão separada), nunca inline na sessão que implementou — o histórico de implementação enviesa o veredito. Quando o autopilot roteia para `@validator`, a sequência é:
+
+```
+harness:check                  → roda os criteria[].verification deterministicamente (exit code = veredito)
+  ↓
+harness:validate               → gera validator-prompt.txt com REVIEW PAYLOAD autocontido:
+                                   (a) resultados do harness:check
+                                   (b) lista de arquivos alterados (untracked incluídos, .aioson/** filtrado)
+                                   (c) diff unificado vs base resolvida (--base > baseline.json > merge-base > HEAD)
+  ↓
+execução isolada em subagente  → @validator julga só os critérios sem verification, em contexto limpo
+  ↓
+harness:validate (de novo)     → consome o veredito pelo circuit breaker (waiting_validation/apply-validation)
+```
+
+O review payload torna o prompt do validador **autocontido**: ele não precisa explorar o repositório. O diff tem teto de tamanho (`--max-diff-bytes`, default 200KB, truncamento em fronteira de linha); `--no-diff` omite o diff; fora de repo git, degrada graciosamente. A máquina de estados `waiting_validation`/`apply-validation` permanece inalterada.
+
 ---
 
 ## Condições de parada
@@ -124,6 +143,20 @@ Você > aioson feature:close . --feature=minha-feature
 
 ---
 
+## Lane B — execução compilada (alternativa opt-in)
+
+Para features **MEDIUM**, existe uma lane de execução alternativa ao autopilot em tempo real: a **Lane B**, acionada pelo agente `@forge-run` (`/forge-run`). Em vez de encadear agentes vivos, o `@forge-run` **compila** os artefatos da feature num `.aioson/plans/{slug}/forge-run.workflow.js` (via `aioson forge:compile`) e o executa pelo runtime de workflows.
+
+O workflow compilado embute o mesmo ciclo de revisão: um `parallel()` por Wave → convergência no `harness:check` → revisão adversarial de 3 lentes para critérios binários sem `verification` → validador fresh-context fechando por `harness:validate` → `apply-validation`. Como a lane normal, ele **nunca** roda `feature:close`/publish: PASS recomenda o humano rodar `feature:close`; FAIL volta ao `@dev` pela lane normal. Uma feature por run.
+
+Quando preferir cada uma:
+- **Autopilot (lane normal)** — handoffs determinísticos entre agentes vivos; padrão para SMALL e MEDIUM.
+- **Lane B (`@forge-run`)** — execução compilada, reproduzível e versionável de uma feature MEDIUM; opt-in, com aviso de custo antes de rodar.
+
+Veja [SDD Automation Scripts — forge:compile](./sdd-automation-scripts.md#forgecompile-lane-b).
+
+---
+
 ## Próximos passos
 
 - [SDD Framework](./sdd-framework.md) — sequência completa MICRO/SMALL/MEDIUM

package/docs/pt/5-referencia/comandos-cli.md

@@ -225,6 +225,8 @@ Scripts determinísticos que movem verificações de estado, validação de arte
 | `feature:export` | **Copia** todos os artefatos de uma feature para um `--out` limpo, sem mexer na origem; gera `INDEX.md` | Exportar specs para analisar fora, entregar a cliente, ou usar o AIOSON só como gerador de specs. Veja [feature-export.md](./feature-export.md) |
 | `gate:check` | Valida pré-requisitos e artefatos de um phase gate (A/B/C/D); retorna PASS ou BLOCKED | Antes de avançar para o próximo agente |
 | `artifact:validate` | Verifica a cadeia completa de artefatos de uma feature (PRD → spec → plano → conformance) | A qualquer momento para checar completude |
+| `spec:analyze` | Irmão de **conteúdo** do `artifact:validate`: consistência cruzada entre os artefatos (rastreabilidade REQ/AC, staleness, readiness, sanidade do contrato, vínculo AC→contrato, overlap de waves) antes do gate de execução | No preflight do `@scope-check` — errors viram blockers, warnings viram evidência de drift |
+| `forge:compile` | **Lane B:** compila os artefatos de uma feature MEDIUM num `forge-run.workflow.js` auditável e versionável (parallel por Wave → convergência no `harness:check` → revisão adversarial → validador fresh-context) | Quando quer execução compilada e reproduzível via `@forge-run`; nunca roda `feature:close`/publish |
 | `workflow:execute` | Monta e executa o plano de agentes baseado na classificação; aceita `--dry-run` e `--start-from` | Para orquestrar features sem o dashboard |
 | `runner:run` | Executa uma tarefa ou worker diretamente pelo runner | Quando quer executar fora do loop principal de sessão |
 | `runner:queue` | Enfileira tarefas no runner com prioridade e agente designado | Para execução assíncrona ou batch de tarefas |
@@ -304,6 +306,8 @@ Controle do loop autônomo `self:loop` com scope guard, budget enforcement, huma
 
 | Comando | O que faz | Quando usar |
 |---|---|---|
+| `harness:check` | Roda os comandos `criteria[].verification` do contrato deterministicamente, **fora do self:loop** (read-only sobre `progress.json`); exit 0 = pass | Verificação determinística avulsa dos critérios; o `@validator` roda primeiro e copia o veredito verbatim |
+| `harness:validate` | Gera o `validator-prompt.txt` com **review payload autocontido** (resultados do `harness:check` + arquivos alterados + diff vs base resolvida) e consome o veredito pelo circuit breaker | Antes de executar o `@validator` em contexto fresco e isolado |
 | `harness:approve` | Aprova um gate humano pendente no loop (persiste decisão auditável) | Quando o loop pausou em `HUMAN_GATE` e você quer retomá-lo |
 | `harness:reject` | Rejeita um gate humano (encerra a tentativa com resumo; requer `--reason`) | Quando quer cancelar a tentativa atual após revisão humana |
 | `harness:status` | Visão do estado do loop: circuito, iteração N/M, budget, checks, gates pendentes, próxima ação | Sempre que quiser saber o que o loop está fazendo ou por que parou |
@@ -1668,7 +1672,7 @@ Valida pré-requisitos e artefatos. Retorna PASS ou BLOCKED com lista de evidên
 aioson artifact:validate . --feature=checkout --json
 ```
 
-Verifica toda a cadeia PRD → spec → plano → conformance e indica o próximo artefato faltante.
+Verifica toda a cadeia PRD → spec → plano → conformance e indica o próximo artefato faltante. Para checar a **consistência de conteúdo** entre os artefatos (não só a presença), veja `spec:analyze` no exemplo 58.
 
 ### 48. Atualizar pulse ao final da sessão
 
@@ -1723,14 +1727,14 @@ aioson workflow:execute . \
   --classification=SMALL \
   --dry-run
 
-# Executar de verdade
-aioson workflow:execute . --feature=checkout --tool=claude
-
-# Executar com política agentica persistida para o gateway
-aioson workflow:execute . --feature=checkout --tool=codex --agentic --max-dev-qa-cycles=3
-
-# Retomar do dev (pular product e analyst)
-aioson workflow:execute . \
+# Executar de verdade
+aioson workflow:execute . --feature=checkout --tool=claude
+
+# Executar com política agentica persistida para o gateway
+aioson workflow:execute . --feature=checkout --tool=codex --agentic --max-dev-qa-cycles=3
+
+# Retomar do dev (pular product e analyst)
+aioson workflow:execute . \
   --feature=checkout \
   --tool=claude \
   --start-from=dev
@@ -1878,6 +1882,57 @@ aioson harness:preview .aioson/context/retro/checkout.md
 
 ---
 
+### 58. Verificar critérios deterministicamente com harness:check
+
+Roda os comandos `criteria[].verification` do `harness-contract.json` **fora do self:loop**, de forma determinística. Read-only sobre `progress.json` — o estado do circuit breaker continua exclusivo de `harness:validate`/`apply-validation`.
+
+```bash
+# Rodar todos os critérios verificáveis do contrato ativo (auto-descoberto)
+aioson harness:check . --slug=checkout
+
+# Rodar um subconjunto de critérios
+aioson harness:check . --slug=checkout --criteria=C1,C3
+
+# Com timeout customizado e saída JSON (exit 0 = pass)
+aioson harness:check . --slug=checkout --timeout=120000 --json
+```
+
+Reusa o mesmo motor do loop (timeouts, kill de process-tree, redaction de credenciais, failure signatures). Persiste `last-check-output.json` e emite telemetria `criteria_check_failed`. O `verification` é campo autorado por critério — o `@sheldon` o escreve para todo critério `binary:true` mecanicamente verificável; contratos legados sem o campo continuam válidos (gera apenas WARNING advisory). O `@validator` roda `harness:check` **primeiro** e copia o veredito do exit code verbatim. Veja [Loop Guardrails](./loop-guardrails.md#harnesscheck--verificação-determinística-avulsa).
+
+---
+
+### 59. Validar consistência cruzada com spec:analyze
+
+Irmão de **conteúdo** do `artifact:validate` (que checa só presença). Roda checagens determinísticas entre os artefatos da feature antes do gate de execução.
+
+```bash
+# Analisar a consistência cruzada dos artefatos da feature
+aioson spec:analyze . --feature=checkout
+
+# Saída JSON para scripting de gate (errors → exit 1)
+aioson spec:analyze . --feature=checkout --json
+```
+
+Checagens: rastreabilidade REQ/AC (ids declarados nunca usados downstream = gap; ids usados sem declaração = órfão/drift), staleness (upstream modificado após downstream gerado), readiness (`blocked` = error, `ready_with_warnings` = info), sanidade do contrato e vínculo AC→contrato, mais `wave_file_overlap` (fases da mesma Wave com Primary files sobrepostos). Severidades: **error** vira `ok:false`/exit 1; **warning** = drift provável; **info** = dívida. Persiste `spec-analyze-{slug}.json` em `.aioson/context/`. O `@scope-check` roda no preflight: errors são blockers, warnings viram evidência de drift pré-computada.
+
+---
+
+### 60. Compilar a Lane B com forge:compile
+
+Compila os artefatos de uma feature MEDIUM num script de dynamic workflow auditável e versionável, commitado junto da spec. Entrada opt-in via `@forge-run`.
+
+```bash
+# Compilar a feature num forge-run.workflow.js
+aioson forge:compile . --feature=checkout
+
+# Saída JSON (preflights duros podem recusar a compilação)
+aioson forge:compile . --feature=checkout --json
+```
+
+Gera `.aioson/plans/{slug}/forge-run.workflow.js`: um `parallel()` por Wave (devs em arquivos disjuntos) → loop de convergência no `harness:check` (fixes sequenciais, limitado pelo `error_streak_limit` do governor + guarda de orçamento) → revisão adversarial de 3 lentes para critérios binários **sem** `verification` → estágio de validador fresh-context fechando pelo ciclo normal `harness:validate` → `apply-validation`. Preflights duros recusam compilar (contrato inválido/ausente, zero critério executável, plano sem coluna Wave, errors do `spec:analyze`, `wave_file_overlap`) e nomeiam o agente dono (`@sheldon`, `@pm`, `@discovery-design-doc`). O script gerado **nunca** roda `feature:close`/publish.
+
+---
+
 ## Atalhos úteis
 
 ```bash