O contrato de escopo: definir "pronto"

Por que a condição de saída é a parte que sustenta tudo

Um loop é uma estrutura de controle: while (!done) { learn; analyze; execute; verify; }. O predicado done é avaliado a cada ciclo. Se esse predicado não for decidível a partir do estado observável, o loop não tem garantia de terminação — é, formalmente, um programa sem condição de parada definida. "Melhor", "mais limpo", "pronto para produção" não são predicados sobre estado; são julgamentos subjetivos, então o loop nunca consegue avaliá-los e nunca pode sair de forma legítima.

SCOPE.md vs. GOAL.md vs. um PRD

SCOPE.md é o contrato leve, escrito por humano, com que você inicia qualquer loop não-trivial — seis campos, muitas vezes em menos de uma página. É a entrada do loop, a régua contra a qual o passo decide mede. Não é o mesmo que GOAL.md: GOAL.md é o contrato compilado, de execução autônoma que o passo /goal do Forge emite (em blocos XML: goal / context / constraints / verification / done-when) para uma execução longa sem supervisão — você vai conhecê-lo nas lições 8 e 10. E um PRD é ainda mais amplo: mercado, persona, rollout. Pense nisso como uma escala de zoom: PRD (o porquê & o quê, muitas páginas) → SCOPE.md (o contrato de um loop, uma página) → GOAL.md (o run-contract verificável por máquina contra o qual o loop executa).

O que "mensurável" significa com precisão

Uma cláusula done-when é mensurável quando nomeia (1) uma métrica ou artefato observável, (2) uma comparação ou limiar, e (3) o boundary onde é checada. "Os testes passam" é fraco (quais testes? onde?); "npm test sai com 0 e 0 falhas no CI" é forte. O passo verify (lição 6) roda essa checagem no boundary real — nunca uma alegação, nunca um mock — e o passo decide compara o resultado com este contrato.

O contrato inteiro em um arquivo

# Goal
Cut RHG checkout p95 latency so it stops timing out at peak.

# Context
Checkout lives in services/checkout. Hot path is the cart re-price
call on every keystroke. Prod is us-east, behind a CDN.

# Constraints
- Do NOT change the public /checkout request/response shape.
- No new runtime dependencies.
- Stay on the existing design tokens (no raw hex).

# Done-when
- checkout p95 < 400ms over a 10-minute load test at peak RPS
- 0 responses with status >= 500 during that test
- `npm test` exits 0 with 0 failures in CI
- the /checkout API contract test still passes unchanged

# Editable surface
- services/checkout/**
- services/checkout/__tests__/**

# Agents
- Executor:  agent-A   (tier: execute)
- Validator: agent-B   (tier: analyze)   # never the builder

Como encontrar / abrir isto

É só um arquivo Markdown que você escreve à mão antes da execução. Crie ou abra a partir da raiz do repo:

# create it next to the work, then open in your editor
$ touch SCOPE.md && $EDITOR SCOPE.md

# confirm a loop run is pointed at it
$ grep -n "Done-when" SCOPE.md

No front-end Forge (lição 8) esse mesmo raciocínio de seis campos é o que o passo /goal compila no GOAL.md autônomo; para um loop interativo rápido você costuma escrever o SCOPE.md à mão e ir direto para a execução.

Como o veredito é computado

O avaliador é uma pequena função pura sobre o texto. Ele varre três sinais: uma métrica (um substantivo mensurável conhecido ou um número-com-unidade), um limiar (uma palavra/operador de comparação ou um alvo) e um boundary (uma frase de "onde" — no CI, em prod, ao longo de um teste). Uma cláusula é measurable só quando os três estão presentes (mais a checagem de ausência de palavras-sensação no modo estrito). Qualquer coisa menos que isso é vague, e o resultado explicita a peça faltante — exatamente o que o passo decide do loop não conseguiria avaliar.

function grade(text, strict) {
  const t = text.toLowerCase();
  const hasMetric    = /\b(p9\d|latency|error rate|uptime|conversion|\d+\s?(ms|s|%))\b/.test(t);
  const hasThreshold = /(under|below|over|above|<|>|>=|<=|at least|exits 0|\d)/.test(t);
  const hasBoundary  = /(in ci|in prod|production|staging|load test|over a)/.test(t);
  const feelings    = /\b(better|faster|fast|good|nice|clean|improv)/.test(t);
  const ok = hasMetric && hasThreshold && hasBoundary && (!strict || !feelings);
  return { ok, hasMetric, hasThreshold, hasBoundary, feelings };
}

O ponto não é o regex — é a forma: métrica + limiar + boundary é o mínimo sobre o qual um passo verify consegue agir. Loops reais deixam um LLM julgar isso em linguagem natural, mas o teste é idêntico: uma máquina, olhando apenas o estado observável, conseguiria retornar verdadeiro ou falso?

Uma constraint é só um done-when que precisa continuar verdadeiro

Note que toda boa constraint tem a mesma forma de um bom done-when: uma métrica/observável, um limiar (muitas vezes "inalterado" ou "zero") e um boundary. "Nenhum hex cru no diff" é métrica (contagem de literais hex) + limiar (= 0) + boundary (o diff). É por isso que a mesma lógica de avaliação funciona para os dois — uma constraint é um invariante que o loop precisa manter a cada passo, enquanto um done-when é a condição que o deixa parar. Fixar a um artefato nomeado e fixo (o conjunto de tokens, o teste de contrato, o lockfile) é o que torna a checagem mecânica em vez de subjetiva.

Níveis são uma cadeia de dependências, registrada no contrato

Cada nível é um booleano que o contrato concede. Um segundo mapa registra o que cada nível requer abaixo dele; um nível concedido cujo pré-requisito está faltando fica insatisfeito — não pode entrar em vigor, então o editor o sinaliza, exatamente como um runner real recusaria agir sobre uma concessão inconsistente. A autorização efetiva que o resumo lê é o maior prefixo satisfeito da cadeia.

const grant = { analyze:false, execute:false, destructive:false };

const requires = {
  analyze:     [],                 // base tier
  execute:     ['analyze'],        // can't change what you can't read
  destructive: ['execute']         // irreversible needs reversible first
};

function missing(tier) { return requires[tier].filter(t => !grant[t]); }
function effective() {        // what the agent may actually do
  return Object.keys(grant).filter(t => grant[t] && missing(t).length === 0);
}

Por que loops AFK param em execute

Uma execução autônoma (lições 7, 9) normalmente recebe analyze + execute e não destructive. O loop pode construir e provar uma mudança o dia todo; o único passo irreversível — colocar em prod — é a bifurcação genuinamente só-do-usuário que dispara um handoff. É também por isso que o Validador recebe só analyze: ele prova, nunca muda. computer-use é apenas-AX e não-bloqueante, então ele nunca sequer alcança o nível execute no sistema real.

Observabilidade, não operação

Tudo neste diagrama roda AFK. O único papel do humano é observabilidade — ler LOOP-LOG.md / status / review.md enquanto a máquina trabalha. O humano não executa nada, nem mesmo o QA. A única exceção é o ramo tracejado destructive: quando o único passo restante é irreversível e genuinamente só-do-usuário, o loop emite um handoff pronto para decisão e bloqueia ali — nunca em outro lugar. Um SCOPE.md bem escrito é o que torna isso seguro: as constraints mantêm os ciclos dentro dos limites sem supervisão, e o done-when mensurável deixa o loop terminar a si mesmo em vez de esperar ser avisado.

A faixa é um AND sobre as cláusulas

Um único array de objetos-cláusula dirige tanto a tabela quanto a faixa. Cada tique relê cada métrica no seu boundary e recalcula o status da cláusula. O gate geral é um AND lógico: a execução está done só quando todas as cláusulas passam — qualquer falha mantém a faixa vermelha e o loop rodando. É o passo decide tornado visível. Note que o humano não faz nada aqui além de ler; o loop recheca a si mesmo e converge.

Por que "pendente" existe

Uma cláusula pode estar pendente — sua checagem não terminou neste ciclo (ex.: o teste de carga de 10 minutos ainda está rodando). Pendente não é passa; o gate trata só uma passagem afirmativa como satisfeita, então uma checagem pela metade nunca consegue disparar uma saída precoce.

Localize o contrato e o log

# the contract you hand-write before a loop
$ $EDITOR SCOPE.md

# the observability artifacts the human reads (never executes)
$ tail -f LOOP-LOG.md          # the loop's running record
$ less review.md               # the AFK QA's observability report

# confirm the gate is wired to your done-when
$ grep -n "Done-when" SCOPE.md

Para onde isto vai depois: a lição 3 (LEARN) é como o agente confirma o Context contra a realidade; a lição 6 (VERIFY) é o gate de prova no boundary real que avalia o Done-when; a lição 8 (o Forge) mostra o passo /goal compilando esse mesmo raciocínio em um GOAL.md autônomo; a lição 9 explica por que o Validador nunca é o construtor.