ContextLab
GitHub

ContextLab

Tentativas

Visão geral

O ContextLab compara três formas de dar contexto a um agente de programação que escreve testes unitários. Ele prepara o material que o agente pode ver, pede uma suíte de testes, guarda a resposta sem alterá-la e só então a executa, em um ambiente separado.

L Local

O agente recebe o arquivo da função e os tipos usados na assinatura dela.

R Recuperado

Recebe o pacote L mais as definições de outros arquivos que a função usa diretamente.

A Autônomo

Começa só com o enunciado e escolhe o que ler, por listagem, leitura e busca.

Três ideias organizam todo o resto:

  • Geração e avaliação são separadas. O agente nunca executa o projeto nem vê o resultado dos testes. Não há segunda chance nem reparo.
  • Tudo fica registrado. O enunciado, o contexto, cada consulta, a resposta, os resultados por caso e as decisões de revisão ficam em arquivos, por tentativa.
  • O que foi congelado não muda. Antes de executar, a configuração, a ordem sorteada e os arquivos do projeto recebem um hash. Se algo mudar depois, o ContextLab se recusa a continuar aquele lote.

Fluxo de uma tentativa

flowchart LR
    A["Manifesto"] --> B["Contexto"] --> C["Geração<br/>Codex"] --> D["Entrega<br/>preservada"] --> E["Avaliação<br/>Docker"] --> F["Revisão<br/>humana"] --> G["Defeitos e<br/>relatórios"]
    E -. "nenhum resultado volta ao agente" .-x C

Uma tentativa é a combinação de projeto, função, agente, estratégia e repetição. Um lote é o conjunto de tentativas de um plano congelado. Uma tentativa pode conter dezenas de casos de teste; o número de tentativas não muda por isso.

Como o contexto é preparado

O código do projeto é lido e analisado, nunca executado. O preparador monta primeiro uma visão preparada do repositório, um conjunto de arquivos virtuais em memória, e é dela que saem as três estratégias.

Na animação, o alvo real calcular_orcamento do OrçaAPI passa pelas três estratégias.

flowchart TD
    I["include do contextlab.json<br/>arquivos candidatos"] --> F{"Filtros"}
    F -- "testes, .git, runs, credenciais,<br/>instruções para agentes, links simbólicos" --> X["Excluído<br/>(motivo registrado)"]
    F -- "aceito" --> D["Remoção dos exemplos doctest<br/>das docstrings e documentos"]
    D --> V[("Visão preparada<br/>arquivos virtuais")]
    V --> L["L: arquivo focal inteiro<br/>+ tipos da assinatura"]
    L --> R["R: L + dependências diretas<br/>de outros arquivos"]
    V --> A["A: todos os arquivos ficam<br/>disponíveis para consulta"]

O que entra e o que fica de fora

  • Só entram arquivos listados em include. Documentos (.md, .rst, .txt) precisam ser indicados pelo caminho exato, sem curinga.
  • Ficam de fora, mesmo se listados: pastas e arquivos de teste, .git, runs, conftest.py, arquivos de credenciais, instruções para agentes (AGENTS.md, CLAUDE.md) e links simbólicos.
  • Um arquivo cujo conteúdo pareça teste ou contenha padrão de chave secreta também é excluído.
  • Exemplos no formato doctest são retirados, porque trazem entradas e respostas esperadas. A numeração das linhas é preservada.

Como o trecho específico é escolhido

O alvo é localizado pelo campo symbol dentro do arquivo path, usando a árvore de sintaxe do Python (AST).

EstratégiaO que é entregueComo é decidido
LO arquivo focal completo e as declarações dos tipos que aparecem na assinatura da função, mesmo que estejam em outro arquivo.Regra fixa. Se não couber no limite de caracteres, a execução é recusada: o pacote L nunca é cortado.
RTudo de L, mais funções, classes e constantes de outros arquivos do projeto usadas no corpo do alvo.Análise estática, profundidade um: não segue as dependências das dependências. Um trecho que não caiba é registrado como omitido.
ANada além do enunciado. Os arquivos da visão preparada ficam disponíveis.O próprio agente escolhe, usando list_files, read_file e search.

R pode ficar igual a L. Isso acontece quando a função não usa nada de outro arquivo, ou quando a origem do que ela usa não pode ser determinada sem executar o código, como self.atributo ou from modulo import *. O registro informa essa coincidência, e a aba Contexto de cada tentativa mostra o que foi entregue.

Limites

O limite de contexto é contado em caracteres e soma o pacote inicial com todas as respostas das ferramentas, inclusive releituras e erros. Há também um limite de número de consultas e um de tempo de geração. O enunciado informa esses limites ao agente, com o mesmo texto nas três estratégias. Ultrapassar um deles encerra a sessão sem entrega.

Como o Codex entra na história

O Codex roda no seu computador, numa pasta vazia. Ele só vê código pedindo ao ContextLab, que responde apenas com o pacote da estratégia.

flowchart LR
    CL["ContextLab"] -- "1 · enunciado" --> CX["Codex<br/>pasta vazia"]
    CX <-- "2 · pensa" --> M["Modelo<br/>OpenAI"]
    CX <-- "3 · pede código" --> P[("Pacote<br/>L, R ou A")]
    CX -- "4 · teste pronto" --> T["test_generated.py"]
  1. Enunciado. O ContextLab abre uma sessão nova do Codex e envia qual função testar. Em L e R, o código do pacote já vai junto; em A, não vai nada.
  2. Pensa. O Codex repassa a conversa ao modelo, pela internet.
  3. Pede código. Quando o modelo quer ver mais, usa list_files, read_file ou search. Quem responde é o ContextLab, só com arquivos do pacote, contando caracteres e consultas. Os passos 2 e 3 se repetem até o modelo terminar ou um limite estourar.
  4. Teste pronto. A resposta é gravada sem alteração e a sessão acaba. Só depois o teste vai para o Docker.

Por que a pasta vazia

Para que o único caminho até o código seja o pacote. Com o projeto na pasta, o Codex poderia ler testes ou arquivos fora da estratégia.

Por que fora do Docker

Gerar não executa nada, só produz texto, e o Codex precisa de internet para falar com o modelo. O Docker fica para a etapa que executa código: a avaliação.

O que o agente consegue e não consegue fazer

Consegue

  • Listar, ler e buscar nos arquivos virtuais permitidos.
  • Reler o próprio pacote inicial em L e R.
  • Entregar uma resposta final com o arquivo de teste.

Não consegue

  • Executar comandos, o projeto ou os testes.
  • Abrir arquivos do seu disco: as ferramentas só conhecem os arquivos virtuais.
  • Navegar na internet, usar outras integrações ou a sua configuração pessoal do Codex.
  • Ver testes de referência, defeitos ou resultados de avaliação.

Antes de cada sessão, o ContextLab faz uma sondagem com um servidor falso, local e sem credenciais, para conferir que o Codex realmente recusa um comando e uma leitura fora do pacote. Se a sondagem falhar, a tentativa não começa.

Desfechos possíveis da geração

DesfechoSignificadoConta como
completedO agente entregou uma resposta no formato pedido.Geração observável; segue para a avaliação.
invalid_submissionA resposta não continha um único arquivo Python.Geração observável, reprovada.
limit, timeoutO agente esgotou o contexto, as consultas ou o tempo.Geração observável, reprovada: é resultado da estratégia.
protocol_violationApareceu uma ferramenta ou um evento fora do previsto.Geração observável, reprovada.
infrastructure_errorFalha externa: serviço fora do ar, login, cliente.Não observável; informada à parte.

Como o contêiner funciona

O Docker é usado só para executar os testes. Cada execução sobe um contêiner novo, roda o pytest e se apaga. Por isso ele quase nunca aparece na lista do Docker: dura um ou dois segundos.

flowchart TD
    S["test_generated.py<br/>cópia congelada da entrega"] --> P
    subgraph P ["Preparação, fora do contêiner"]
      C1["Copia o projeto para uma pasta temporária"] --> C2["Retira os testes de referência<br/>e as testemunhas"]
    end
    P --> K
    subgraph K ["Contêiner temporário"]
      direction TB
      M1["/project: código, só leitura"]
      M2["/submission: o teste, só leitura"]
      M3["/results: único lugar gravável"]
      R1["pytest + medição de cobertura<br/>sem rede, sem privilégios,<br/>memória e CPU limitadas"]
      M1 --> R1
      M2 --> R1
      R1 --> M3
    end
    K --> O["Relatório por caso<br/>e cobertura da função"]
    O --> Z["Contêiner removido"]
    O --> V{"Passou tudo e<br/>exercitou o alvo?"}
    V -- "sim" --> W["aguardando revisão"]
    V -- "não" --> X["reprovada"]

Por que é rápido

  • Um contêiner não é uma máquina virtual. Ele é um processo isolado que usa o sistema já em execução.
  • A imagem já vem pronta. Python, pytest, coverage e as dependências do projeto são instalados uma vez, pelo comando setup.
  • Nada é copiado para dentro. As pastas são montadas; o contêiner só lê.

O que protege a avaliação

ControlePara quê
Sem rede (--network=none)O teste gerado não baixa nem envia nada.
Sistema de arquivos só de leituraO teste não altera o código de produção. Um resumo do conteúdo é comparado antes e depois.
Sem privilégios, com limite de memória, CPU e processosUm teste mal escrito não derruba a máquina.
Limite de tempoUma suíte que trava vira timeout, não um resultado.
Testes de referência fora da pastaA suíte gerada é medida sozinha, sem ajuda dos seus testes.

Cobertura focal

A cobertura considera apenas o corpo da função-alvo, não o arquivo inteiro, e só conta o que foi executado durante os testes. Importar o módulo não conta. Funções sem ramificações recebem "não aplicável" na coluna de ramificações, nunca zero.

Revisão humana e defeitos controlados

Passar no pytest não basta para aprovar. Uma suíte que passa fica aguardando revisão, e a aprovação depende de uma pessoa, pelo comando review.

stateDiagram-v2
    [*] --> Pendente
    Pendente --> Gerando
    Gerando --> Infraestrutura: falha externa
    Gerando --> Reprovada: sem entrega válida ou limite esgotado
    Gerando --> Avaliando: entrega preservada
    Avaliando --> Reprovada: erro, falha ou alvo não exercitado
    Avaliando --> AguardandoRevisao: passou em tudo
    AguardandoRevisao --> Reprovada: revisão negativa
    AguardandoRevisao --> Aprovada: revisão positiva
    Aprovada --> [*]
    Reprovada --> [*]

O que a revisão confere

CritérioPergunta
--behavioral-assertionsOs testes verificam valores e comportamentos, e não apenas que a função "não quebrou"?
--no-target-mockA função-alvo foi chamada de verdade, sem ser trocada por uma resposta simulada?
--no-production-changesO código de produção ficou intacto?
--dependency-doublesDependências da função foram trocadas por dublês? Marca para análise separada, sem reprovar.
--http-requestsSó em alvos HTTP de piloto: a rota foi exercitada por requisições reais?

A revisão reexecuta a mesma entrega e guarda a avaliação original. Ela não gera de novo e não permite editar o teste: se o arquivo mudou, o comando recusa.

Defeitos controlados

Um defeito é uma alteração pequena e proposital no código, definida antes da geração. Serve para medir se a suíte percebe quando o comportamento fica errado. Só é medido em suítes aprovadas.

flowchart LR
    A["Suíte aprovada"] --> B["Para cada defeito"]
    B --> C["Testemunha no<br/>código original"]
    C -- "passa" --> D["Testemunha no<br/>código alterado"]
    D -- "falha" --> E["Suíte gerada no<br/>código alterado"]
    E -- "passou" --> F["sobreviveu"]
    E -- "falhou" --> G{"A falha vem do<br/>comportamento alterado?"}
    G -- "sim, na revisão" --> H["detectado"]
    G -- "não" --> I["não atribuído"]
    C -- "falha" --> J["defeito inelegível"]
    D -- "passa" --> J

A testemunha é um teste seu que passa no código original e falha no alterado. Ela prova que o defeito muda mesmo o comportamento. Um defeito sem testemunha válida não entra na conta.

O arquivo contextlab.json

É o manifesto: descreve o experimento inteiro. Ele aponta para o código, sem copiá-lo. No uso por projeto fica em projects/NOME/contextlab.json; na coleta principal, um único manifesto reúne os quatro projetos.

{
  "schema_version": 1,
  "phase": "pilot",                      // demo, pilot ou main
  "seed": 42,                            // semente do sorteio da ordem
  "conditions": ["L", "R", "A"],         // estratégias a executar
  "repetitions": 3,                      // sessões novas por estratégia
  "limits": {
    "context_chars": 30000,              // pacote inicial + respostas das ferramentas
    "tool_calls": 20,                    // consultas por sessão
    "generation_seconds": 120,           // tempo máximo de geração
    "evaluation_seconds": 20             // tempo máximo de cada execução no Docker
  },
  "agents": [
    { "id": "codex", "kind": "codex", "model": "gpt-6.1-sol",
      "auth_file": "~/.codex-work/auth.json" }   // caminho do login, nunca o conteúdo
  ],
  "evaluation": { "backend": "docker", "image": "contextlab-orcamentos:local" },
  "projects": [
    {
      "id": "orcamentos",                // identificador fixo, igual ao nome da pasta
      "name": "OrçaAPI",                 // opcional: nome mostrado na interface
      "root": ".",                       // pasta do projeto, relativa ao manifesto
      "source_roots": ["src"],           // de onde os módulos são importados
      "include": ["src/orcamentos/*.py"],            // o que o agente pode ver
      "evaluation_include": ["src/orcamentos/*.py",  // o que vai para o avaliador
                             "tests/test_orcamentos.py"],
      "targets": [
        {
          "id": "calcular_orcamento",
          "path": "src/orcamentos/orcamentos.py",
          "symbol": "calcular_orcamento",
          "import": "orcamentos.orcamentos:calcular_orcamento",
          "reference_tests": ["tests/test_orcamentos.py"],
          "defects": [
            { "id": "total-sem-desconto",
              "path": "src/orcamentos/orcamentos.py",
              "old": "total=base + frete",
              "new": "total=subtotal + frete",
              "witness": "tests/test_orcamentos.py::test_testemunha_total_desconta_cupom" }
          ]
        }
      ]
    }
  ]
}

Os comentários acima são explicativos. O arquivo real é JSON puro e não aceita comentários.

Campos gerais

CampoValoresO que controla
schema_version1Versão do formato do arquivo.
phasedemo, pilot, maindemo usa testes escritos por você, sem modelo. pilot chama o Codex em ensaios. main é a coleta principal e exige a matriz completa.
seedinteiroSemente do sorteio. A mesma semente produz a mesma ordem.
conditionsL, R, AEstratégias que entram no plano.
repetitionsinteiro ≥ 1Quantas sessões novas por combinação de função e estratégia.
limitsquatro inteirosLimites de contexto, consultas, geração e avaliação. Todos obrigatórios: não há valor implícito.

agents e evaluation

CampoValoresO que controla
agents[].kindcodex, fixturecodex chama o cliente real. fixture carrega um teste já escrito e só vale em demo.
agents[].modeltextoIdentificador exato do modelo. Obrigatório para agentes reais.
agents[].reasoning_efforttextoEsforço de raciocínio do Codex: low, medium, high, xhigh, max ou ultra. Obrigatório na coleta principal; sem ele, vale o padrão do modelo, que muda entre modelos.
agents[].auth_filecaminhoOnde está o login do Codex. Aceita ~. Sem ele, usa a variável CODEX_API_KEY.
agents[].fixture_dirpastaOnde ficam os testes prontos do modo demo.
evaluation.backenddocker, locallocal só é aceito em demo, com --trusted-local. Código gerado por modelo sempre roda no Docker.
evaluation.imagenome da imagemImagem com Python, pytest, coverage e as dependências do projeto.

projects e targets

CampoO que controla
idIdentificador do projeto. Só letras sem acento, números, - e _. No uso por projeto, precisa ser igual ao nome da pasta. Aparece nos nomes das pastas e nos registros, por isso não deve mudar depois da primeira execução.
nameOpcional. Nome de exibição, livre, usado como título desta página. Exemplo: "OrçaAPI".
rootPasta do projeto, relativa ao manifesto.
source_rootsPastas a partir das quais os módulos são importados, como src. Usadas para resolver dependências e para montar o caminho de importação no avaliador.
includeO que pode entrar na visão do agente. Aceita curingas para arquivos Python.
excludeOpcional. Exclusões adicionais dentro do que foi incluído.
evaluation_includeO que é copiado para o avaliador: o código de produção e os testes de referência.
targets[].pathArquivo onde a função está.
targets[].symbolNome da função, ou Classe.metodo.
targets[].importCaminho de importação, no formato modulo:simbolo. Vai para o enunciado.
targets[].test_kindunit (padrão) ou http. O tipo http só vale fora de main.
targets[].reference_testsSeus testes para o alvo. Precisam passar no avaliador antes de qualquer geração e nunca são mostrados ao agente.
targets[].defectsLista de alterações controladas. Cada uma tem id, path, o trecho old (que precisa aparecer exatamente uma vez no arquivo), o trecho new e a witness.

Regras da fase main

Com "phase": "main", o ContextLab só aceita a matriz do experimento: 4 projetos × 3 funções × Codex × L, R e A × 3 repetições = 108 tentativas, com avaliação no Docker e alvos do tipo unit. O congelamento também exige a evidência de um piloto feito com a mesma versão do ContextLab, a mesma imagem, os mesmos limites e o mesmo modelo.

Alterar o contextlab.json vale para os próximos lotes. Lotes já criados guardam a própria cópia congelada e não são afetados.

Passo a passo, comando a comando

O caminho completo de um projeto, do cadastro à análise, com dados reais do piloto do OrçaAPI. Use os botões para pausar ou pular para um comando.

Os mesmos passos, em diagramas para consulta:

contextlab create NOME · cadastrar

flowchart LR
    P["projects/NOME/"] --> S["Procura funções<br/>no código"] --> E["Você escolhe<br/>o alvo"] --> J[("contextlab.json")]

Lê o código sem executá-lo e grava o cadastro: alvo, testes de referência, modo, estratégias, repetições, modelo e imagem. Para mudar depois, use configure.

contextlab NOME setup · preparar o Docker

flowchart LR
    D{"Docker<br/>disponível?"} -- "sim" --> I{"Imagem<br/>existe?"}
    I -- "não" --> B["Constrói a imagem<br/>Python + pytest + coverage"] --> OK["Pronto"]
    I -- "sim" --> OK

Deixa pronta a imagem em que os testes serão executados. Nenhum modelo é chamado.

contextlab NOME plan · ver o plano

flowchart LR
    J[("contextlab.json")] --> M["Alvos × estratégias<br/>× repetições"] --> O["Sorteia a ordem"] --> T["Lista na tela"]

Mostra quais tentativas serão feitas e em que ordem. Não grava nada.

contextlab NOME context · ver o contexto

flowchart LR
    C["Código do projeto"] --> F["Filtra testes,<br/>credenciais e docs"] --> X{"Estratégia"}
    X -- "L" --> L["Arquivo da função"]
    X -- "R" --> R["L + dependências"]
    X -- "A" --> A["Lista de arquivos<br/>disponíveis"]

Mostra exatamente o que o agente receberia, sem gastar uma geração.

contextlab NOME run · executar

É o comando principal. Ele passa por três fases.

flowchart TD
    subgraph V ["1 · Conferências"]
      direction LR
      V1["Codex<br/>responde?"] --> V2["Contexto cabe<br/>no limite?"] --> V3["Docker: referências passam<br/>e testemunhas pegam defeitos?"]
    end
    subgraph Z ["2 · Congelamento"]
      direction LR
      Z1["Grava protocol.lock.json<br/>configuração, ordem e hashes"]
    end
    subgraph T ["3 · Cada tentativa"]
      direction LR
      T1["Monta o<br/>contexto"] --> T2["Codex gera<br/>o teste"] --> T3["Grava a entrega<br/>sem alterar"] --> T4["Docker executa<br/>no projeto completo"] --> T5[("record.json")]
    end
    V --> Z --> T
  • Conferências: se algo falhar aqui, nenhuma geração começa e nada é gasto.
  • Congelamento: a partir daqui o lote não aceita mudanças no código, na configuração ou na ordem.
  • Tentativas: seguem a ordem sorteada. O resultado de uma nunca volta ao agente. Se a execução parar no meio, run --resume LOTE continua de onde parou. Só uma falha de infraestrutura (Docker, rede, serviço, interrupção) é repetida, uma única vez, com o motivo registrado e o original guardado.

Ao final, o teste pode ter passado, mas ainda fica aguardando revisão.

contextlab NOME runs e show ID · conferir

flowchart LR
    R[("record.json")] --> L["runs<br/>uma linha por tentativa"]
    R --> S["show<br/>casos, falhas e código"]

Só leem os registros. Servem para escolher o que revisar.

contextlab NOME review ID · revisar

flowchart TD
    H["Você responde três perguntas<br/>verifica comportamento?<br/>sem mock do alvo?<br/>produção intacta?"] --> E["Docker reexecuta<br/>a mesma entrega"]
    E --> Q{"Aprovada?"}
    Q -- "não" --> N["Reprovada"]
    Q -- "sim" --> D["Docker executa o teste<br/>em cada versão com defeito"]
    D --> A["Você confirma se cada falha<br/>foi causada pelo defeito"] --> F[("Revisão gravada")]

A aprovação depende do teste passar e da revisão humana. Só as suítes aprovadas são testadas contra os defeitos.

contextlab NOME serve · analisar

flowchart LR
    R[("Lotes do projeto")] --> P["Calcula médias,<br/>tokens e custo"] --> W["Esta página<br/>no navegador"]

Só lê. Nada é alterado nos lotes.

Comandos

Há duas formas de usar. Por projeto, para aprender, demonstrar e pilotar: contextlab NOME comando. Por manifesto, para controlar cada etapa da coleta principal: contextlab comando ARQUIVO.

Caminho típico por projeto

flowchart LR
    A["create"] --> B["configure"] --> C["setup"] --> D["plan"] --> E["context"] --> F["run"] --> G["runs / show / serve"] --> H["review"]
    F -. "interrompeu?" .-> F2["run --resume LOTE"] --> G
contextlab create NOMEcadastra um projeto

Procura funções no código que já existe em projects/NOME/, deixa você escolher o primeiro alvo e grava o contextlab.json. Não executa o projeto e não sobrescreve um cadastro existente.

--target ARQUIVO:SIMBOLOEscolhe o alvo sem perguntar.
--reference TESTETeste de referência do alvo. Pode repetir.
--mode demo|pilotModo inicial.
--conditions L R AEstratégias.
--repetitions NRepetições.
--model IDModelo do Codex, obrigatório em pilot.
--auth-file CAMINHOArquivo de login.
--image NOMEImagem Docker do avaliador.
--fixture-dir PASTAPasta dos testes prontos do modo demo.
contextlab NOME configureajusta o cadastro

Muda modo, estratégias, repetições, modelo, login ou imagem. Sem opções, pergunta uma a uma. Aceita as mesmas opções de create, exceto as de alvo. Vale para os próximos lotes.

contextlab NOME setupprepara a imagem Docker

Confere se o Docker está disponível e constrói ou reutiliza a imagem do avaliador. Não inicia gerações.

--dockerfile ARQUIVOReceita própria, quando o projeto tem dependências além de pytest e coverage.
contextlab NOME planmostra o que será executado

Lista as tentativas na ordem sorteada. Não chama o modelo nem o Docker.

--jsonSaída em JSON.
contextlab NOME contextmostra o contexto de uma estratégia

Exibe o pacote que L ou R entregariam, ou a lista de arquivos disponíveis em A. Serve para conferir o material antes de gastar uma geração.

--condition L|R|AEstratégia a inspecionar. Padrão: L.
--target IDObrigatório quando o projeto tem mais de um alvo.
contextlab NOME runexecuta o plano

Cria um lote, valida os testes de referência e as testemunhas, congela o plano e executa cada tentativa: gera, preserva a entrega e avalia.

--max-runs NProcessa no máximo N tentativas nesta chamada. Não reduz o plano.
--resume LOTEContinua um lote. Pula o que já foi registrado. A única exceção é a falha de infraestrutura, repetida uma vez; falhas do agente nunca se repetem.
--trusted-localSó em demo: permite avaliar sem Docker testes escritos por você.
contextlab NOME runslista as tentativas

Uma linha por tentativa de todos os lotes, com a situação. Só consulta.

--jsonSaída em JSON.
contextlab NOME show IDabre uma tentativa no terminal

Mostra contagens, tabela dos casos e detalhes das falhas. O ID tem o formato lote/01 e aparece em runs.

--codeMostra também o teste entregue.
--jsonMostra só o JSON da avaliação mais recente.
contextlab NOME review IDregistra a revisão

Grava as decisões do revisor e reexecuta a mesma entrega. Em suítes aprovadas, executa também os defeitos.

--reviewer NOMEQuem revisou.
--behavioral-assertions yes|noHá verificações de comportamento.
--no-target-mock yes|noO alvo não foi simulado.
--no-production-changes yes|noA produção ficou intacta.
--dependency-doubles yes|noA suíte trocou dependências da função por dublês. Só marca, para análise separada; não reprova.
--http-requests yes|noSó em alvos HTTP.
--defect-attribution ID=yes|noAtribui a falha ao defeito. Pode repetir, uma vez por defeito.
contextlab NOME serveabre esta página

Abre o visualizador com todos os lotes do projeto. É somente leitura. No fluxo por manifesto: contextlab serve RESULTADOS.

--batch LOTEMostra só um lote.
--port NPorta local. Padrão: 8765.
--no-openNão abre o navegador.
--prices ARQUIVO.jsonTarifas de API para estimar o custo. Por projeto, projects/NOME/precos.json é usado automaticamente.
--export ARQUIVO.htmlGrava a página em um arquivo único, que abre sem instalação.

Fluxo por manifesto, usado na coleta principal

flowchart LR
    A["plan"] --> B["doctor"] --> C["prepare"] --> D["validate"] --> E["freeze"] --> F["run"] --> G["review"] --> H["report"]
    P["piloto com alvos<br/>fora da amostra"] -. "evidência exigida em main" .-> E
ComandoO que fazOpções
contextlab plan MANIFESTOMostra a matriz na ordem sorteada.
contextlab doctor MANIFESTOConfere o cliente do Codex: versão, opções exigidas, login e a sondagem das ferramentas. Não chama o modelo.
contextlab prepare MANIFESTOGrava em uma pasta o contexto de um alvo e uma estratégia, para inspeção.--project, --target, --condition, --out
contextlab validate MANIFESTOExecuta os testes de referência e as testemunhas de todos os defeitos.--out, --trusted-local
contextlab freeze MANIFESTOCongela configuração, arquivos, ambiente e ordem em um arquivo .lock.json. Nunca sobrescreve.--out, --evidence
contextlab run LOCKExecuta o plano congelado.--out, --resume, --max-runs, --trusted-local
contextlab review TENTATIVARegistra a revisão de uma pasta de tentativa.as mesmas de review por projeto
contextlab report RESULTADOSExporta results.csv, report.json e report.md, sem reexecutar nada.
contextlab serve RESULTADOSAbre este visualizador para uma pasta de resultados.--port, --no-open, --prices, --export

Todo comando aceita --help. No fluxo por manifesto, --resume não recebe argumento: o arquivo congelado e a pasta de resultados já identificam o lote.

O que fica gravado

Cada lote guarda tudo o que é necessário para conferir uma tentativa sem repeti-la.

projects/NOME/runs/LOTE/
├── protocol.lock.json          plano congelado, com hashes
├── validation/                 referências e testemunhas executadas antes da geração
└── results/
    ├── run.json                cabeçalho da execução
    ├── results.csv  report.json  report.md
    └── PROJETO__ALVO__AGENTE__ESTRATEGIA__REPETICAO/
        ├── record.json         situação, tempos, tokens, avaliação e revisão
        ├── prompt.txt          enunciado enviado, com limites e pacote inicial
        ├── context.json        o que foi preparado, omitido e não resolvido
        ├── response.txt        resposta recebida
        ├── test_generated.py   a entrega, sem alterações
        ├── agent/              eventos do Codex e auditoria das consultas
        ├── evaluation/         resultados por caso e cobertura
        └── reviews/            cada revisão e sua reavaliação

Como ler os números desta página

TermoSignificado
Geração observávelTentativa que chegou a um desfecho atribuível ao agente: entrega válida, entrega inválida ou limite esgotado. Falhas externas ficam de fora e são contadas à parte.
CasosCasos de teste que passaram sobre os que foram executados. Um teste parametrizado gera um caso por conjunto de entradas.
Linhas, Ramif.Cobertura do corpo da função-alvo. Um asterisco indica valor diagnóstico, de uma suíte ainda não aprovada.
DefeitosDefeitos detectados sobre os elegíveis. Só existe depois da aprovação.
Tok. entrada, Tok. saídaTotais informados pelo Codex para a sessão. A entrada soma todas as trocas, por isso cresce com o número de consultas.
CaracteresContexto efetivamente entregue: pacote inicial mais respostas das ferramentas.
Custo est.Estimativa por tarifas de API. Não é a despesa efetiva quando o login é por assinatura.
Custo por suíte aprovadaCusto de todas as gerações observáveis de uma estratégia dividido pelo número de suítes aprovadas.
Avaliação experimental do TCC

Experimento

Doze funções de quatro projetos Python públicos, três estratégias de contexto e três repetições: 108 gerações de testes unitários pelo Codex, cada uma com uma única entrega, avaliada depois em Docker e revisada por uma pessoa. L recebe o arquivo da função; R recebe também as dependências diretas; A explora o repositório sozinho. Os dados brutos estão em experimento-tcc/.

Suítes aprovadas por estratégia

Aprovação por função

suítes aprovadas em 3 repetições

Tokens de entrada por tentativa

cada ponto é uma tentativa
aprovadanão aprovadamédia da estratégia

Esforço por suíte aprovada, por função

Ver tabela

Consumo médio por tentativa

Por que as entregas não foram aprovadas

Nenhuma suíte foi reprovada na revisão humana: todas as reprovações vieram dos critérios automáticos.

O que os dados mostram

    Configuração congelada