Kronuz/campaign

Campanha

O líder (a sessão principal) transforma os objetivos do proprietário em missões. Um agente contribuidor completa cada missão em seu próprio branch; trabalho de máquina vai para uma fila de jobs que o executa em commits exatos enquanto nenhum agente espera. Um agente revisor examina uma missão a partir de um contexto novo quando seu risco assim exige. campaign land coloca uma missão em main apenas quando suas verificações passaram naquele código exato, cada critério tem a evidência que nomeia e cada revisão necessária foi aceita para o código que viu. Tudo que importa está no repositório, então qualquer agente, incluindo o líder, pode ser substituído.

goals ─► PLAN ─► quests ─► campaign start ─► contributor ─► jobs (quiet) ─► evidence
                                                  │                              │
                                                  └─► reviewer (by risk) ─► accept ─► campaign land

Invariantes

1. Evidência, não narrativa. Uma verificação conta apenas quando um job a executou no código que está sendo integrado; uma linha de diário ou opinião de um revisor nunca é um teste verde.
2. Um escritor por conjunto de arquivos. campaign start recusa conjuntos de arquivos sobrepostos; land recusa alterações fora do conjunto da missão e edições nos arquivos do líder.
3. Critérios antes do código. O líder escreve os critérios de aceitação de cada missão e a evidência que cada um precisa; contribuidores nunca os editam, e uma alteração no arquivo da missão invalida aceitações anteriores.
4. Revisão segue o risco. Um revisor novo por risco que precisa de um; uma aceitação cobre o código que sua revisão viu e o conteúdo exato da revisão.
5. Nada enfraquece silenciosamente. Reduzir um risco, remover uma lente ou uma verificação, dispensar uma revisão, integrar sem CI ou registrar uma integração feita manualmente precisa de uma razão, que a ferramenta registra.
6. Estado vive em arquivos. .campaign/<campaign>/ e git mantêm como a campanha funciona; o que o produto é vai para docs/ do repositório que descreve.
7. Agentes nunca esperam por máquinas, e medições nunca são executadas sem isolamento.
8. O proprietário decide objetivos, escopo e qualquer remoção ou redução de comportamento visível ao usuário. O líder decide o resto e registra em PLAN.md. Campaign nunca aluga máquinas ou cria qualquer outro recurso faturado.

Funções

Função	Faz	Escreve
Proprietário (uma pessoa)	Objetivos, não-objetivos, decisões reservadas	Objetivos do PLAN.md
Líder (a sessão principal)	Planeja missões, lança agentes, aceita revisões, integra, reporta ao proprietário	state.json (apenas através de campaign), arquivos de missão, PLAN.md, main
Contribuidor (agente campaign-contributor)	Uma missão ou tarefa, conforme sua designação	seu branch e diário
Revisor (agente campaign-reviewer)	Uma missão através de uma lente, a partir de um contexto novo	um arquivo de revisão

A designação de um contribuidor nomeia o tipo de trabalho; cada uma, exceto implementação, tem um método em references/assignments/<name>.md. O líder nomeia a designação, o nível do modelo e o esforço em cada lançamento, escolhendo pelo trabalho, nunca por hábito:

Designação	Para	Nível, esforço
implementação	funcionalidades e correções com critérios concretos	econômico, médio para risco baixo e normal; forte, alto para risco alto e crítico, ou após uma tentativa econômica parar
design	listas de missões para planos consequentes; formatos, protocolos, durabilidade, concorrência	forte, alto; max para um design prestes a congelar
pesquisa	raramente: o mecanismo em si é o limite	forte, max
desempenho	criação de perfil e otimização	forte, alto
exploração	um alvo de um lote de exploração, ou uma pergunta rápida	econômico, médio
documentação	docs, guias, READMEs	econômico, médio
manutenção	uma alteração mecânica em vários repositórios	econômico, médio

Os revisores usam o nível forte com alto esforço (max para missões críticas); para missões críticas e o desafio do plano, um revisor de outra família de modelos quando a estrutura oferece uma. Os modelos de cada estrutura para os níveis estão em references/harness.md. Altere um padrão com base em resultados (campaign usage, critérios atendidos, retrabalho), não apenas no preço. O líder faz pequenas edições ele mesmo (uma correção de cinco linhas, um conflito trivial): um lançamento custa mais.

Iniciar uma campanha

1. No checkout principal do repositório inicial: campaign init --name NAME [--ci github]. O proprietário escreve Objetivos, Não-objetivos, Restrições e Decisões Reservadas em .campaign/<campaign>/PLAN.md.
2. Divida os objetivos em missões: campaign new ID --title T --risk R --files GLOBS [--needs IDS] [--after IDS] [--provides C] [--consumes C] [--milestone M] --check NAME[:LEVEL[:MIN]]=CMD. Preencha cada arquivo de missão (.campaign/<campaign>/quests/ID.md): resultado, critérios A1... cada um com a evidência que precisa (Evidência, abaixo), contratos, decisões, o que pode ser integrado antes.
3. Quando a arquitetura é consequente, um revisor (lente design) desafia o plano e a lista de missões antes que algo seja construído. Esta é a única revisão que vale a pena esperar.

Missões

• Tamanho: a menor alteração que entrega um comportamento completo e significativo que um revisor possa manter em mente, geralmente algumas centenas a ~1.500 linhas. Divida as maiores; dobre uma alteração que não vale sua própria integração na missão que atende.
• needs deve ser integrado antes de uma missão começar; after deve ser integrado antes que ela integre. Uma missão pode começar contra uma dependência after apenas porque o arquivo de missão dessa dependência fixa o contrato.
• Contratos (--provides, --consumes) nomeiam APIs, formatos e protocolos, para que campaign check veja duas missões tocando um.
• Tarefas: escritores paralelos dentro de uma missão (campaign start ID --task T --files GLOBS), mesclados no branch da missão pelo líder. A missão ainda é revisada uma vez.
• Incrementos: campaign land ID --upto COMMIT --reason R integra um prefixo que o arquivo da missão "Pode integrar antes" permite (refatorações que preservam comportamento, testes, APIs internas não utilizadas, código por trás de um switch desabilitado). Nunca antes: bytes em disco ou no fio, API pública, comportamento visível ao usuário, ou a parte para a qual a revisão existe.
• Trabalho entre repositórios são várias missões (--repo PATH) ordenadas por after, com um job de integração que fixa o commit de cada repositório (--ref NAME=PATH@REF). A integração é ordenada, nunca atômica: cada estado intermediário deve funcionar.
• Mensagens: um agente com uma descoberta para uma missão em que não está trabalhando, em qualquer campanha na máquina, envia campaign message NAME:ID "text" --from WHO. A missão não pode integrar até que um de seus diários a responda por seu id (msg-N) ou o líder a feche (campaign message ID --close msg-N --reason R); NAME: escreve para o líder daquela campanha e nunca bloqueia uma integração. Detalhes, e outras máquinas: references/host.md, Mensagens.
• Mudanças de escopo: um novo pedido vai para o arquivo da missão primeiro (um critério, ou sua própria missão se pode integrar sozinha), depois para o contribuidor; trabalho substituído é campaign set ID status=dropped reason=....

Caminho direto primeiro

Apenas o que decide o próximo passo o bloqueia. As verificações de portão de uma missão (--check: o build, os testes e a evidência que seu risco exige) bloqueiam sua integração. Suas verificações adiadas (--later: outras plataformas, imersões longas, matrizes completas, fuzzing estendido) são enfileiradas com baixa prioridade no código integrado e devem estar verdes antes que o marco feche. Uma vermelha é um erro em campaign check: corrija adiante ou reverta, então campaign verify ID --deferred as reexecuta em main. A evidência que um risco alto ou crítico precisa (TSan para concorrência, fuzzing para um decodificador, o modelo de crash para durabilidade) é sempre um portão. Fluxos de trabalho CI lentos podem ser tornados não bloqueantes da mesma forma (campaign config ci_later=NAME,...).

Executar uma missão

1. campaign start ID cria quest/<campaign>/ID em seu próprio worktree com um diário. Lance um contribuidor em segundo plano, para que possa ser retomado por mensagem, com o prompt "Contribuidor" (references/prompts.md); execute missões em paralelo apenas quando estiverem prontas, disjuntas e não esperando na mesma máquina.
2. O contribuidor trabalha em seu worktree, mantém seu diário atualizado e produz evidências como jobs: campaign job submit --quest ID --level L --minutes M -- CMD e campaign verify ID. Quando apenas jobs restam, ele registra seus ids e encerra sua vez.
3. O líder espera com um campaign wait --commits em segundo plano (sem tokens até que um job termine, um branch se mova ou uma mensagem chegue), então retoma o contribuidor por mensagem enquanto seu contexto é pequeno (cerca de 150k tokens). Um contexto maior, ou uma estrutura que não pode retomá-lo, recebe um contribuidor novo com o prompt "Retomar", que reconstrói a partir do diário e dos registros de job.
4. Quando o diário diz "pronto para revisão", o líder define status=review e lança os revisores que o risco exige; cada um escreve .campaign/<campaign>/reviews/ID-LENS.md. O líder repassa descobertas bloqueantes para o contribuidor por id.
5. campaign accept ID LENS assim que uma revisão aprova, ou após MUDANÇAS com os jobs confirmadores (Risco e revisão); ele commita o arquivo de revisão com a aceitação. Então campaign land ID, que também remove os worktrees da missão, branches mesclados e slot de build, e nomeia o que manteve.

Lotes de exploração

Para uma lista que vale a pena caçar (linhas perdedoras de um benchmark fresco, hotspots de perfil, código pouco comprovado, um backlog de pequenos bugs), envie vários contribuidores econômicos de uma vez, um alvo cada, alvos de uma medição recente em main atual: references/assignments/exploration.md. Tamanho o lote por seus alvos e pelo que o líder pode revisar e integrar, nunca por cota ociosa.

Risco e revisão

Risco (primeira correspondência vence)	Antes de construir	Antes da integração final
crítico: irreversível (congelar um formato ou protocolo para lançamento, migrar dados de usuários, remover comportamento visível ao usuário)	aprovação do proprietário; uma revisão design	a revisão de alto risco, mais evidência de aceitação que o próprio revisor executou
alto: formatos persistentes, protocolos de fio, durabilidade, concorrência, superfícies de segurança, APIs públicas compartilhadas	uma revisão design quando uma decisão é cara de reverter	uma revisão pela lente do risco dominante (durability, security ou correctness)
normal: funcionalidades e correções comuns	—	uma revisão correctness, ou --waive REASON para uma pequena alteração com evidência forte
baixo: docs, testes, ferramentas, edições mecânicas, refatorações que preservam comportamento	—	verificações verdes; o líder lê o diff

• Um revisor por padrão, carregando cada questão de risco que a missão levanta (o prompt nomeia três a cinco). Um segundo apenas para uma questão que precisa de conhecimento separado ou independência.
• Uma revisão está vinculada ao que viu. Ela nomeia o commit que revisou (Commit:), um veredito, e uma tabela de descobertas com um ID, Bloqueante (sim ou não) e Tipo (defeito, lacuna, nica) por linha. Um APROVA cobre o código daquele commit; commits que tocam apenas .campaign/ o mantêm. Editar a revisão após a aceitação anula a aceitação.
• Correções são confirmadas por jobs, não por re-revisões. Para cada descoberta bloqueante, reexecute sua sonda ou o novo teste como um job no commit corrigido, então campaign accept ID LENS --confirm C1=JOB --confirm C2=JOB. Um job confirma apenas se passou no código aceito no repositório da missão; um defeito bloqueante precisa de código alterado; a ferramenta registra se a mesma sonda falhou no commit revisado. Uma correção que altera arquivos que a revisão nunca viu volta para o revisor (a revisão nomeia o commit corrigido e aprova), a menos que --fix-scope REASON diga por que não adiciona mecanismo (um teste de regressão para uma descoberta).
• Duas rodadas de correção, então pare. Uma terceira significa que a missão ou design está errado: re-planeje ou pergunte ao proprietário. Descobertas não bloqueantes tornam-se uma missão de acompanhamento ou são descartadas com uma razão.
• Um design é revisado uma vez. Resolva comportamento contestado com um modelo executável ou teste, não outra rodada de texto.
• O que uma missão deve passar muda apenas no registro: campaign set ID ... --weaken REASON reduz seu risco, remove uma lente, ou remove, altera ou adia uma verificação; a mudança é mantida em seu histórico, mostrada por campaign status ID, e anula suas aceitações. A revisão que um risco exige (uma revisão de código acima de baixo, uma revisão de design para crítico) não pode ser removida, e uma dispensa é recusada assim que uma revisão existe.
• Revisão do sistema em eventos, não em um calendário: quando campaign check reporta duas missões alterando um arquivo ou um contrato, pergunte a um revisor (lente system) essa questão específica.
• Rendimento: campaign status --reviews conta vereditos e defeitos bloqueantes. Uma revisão opcional (risco normal) que não encontra nada material em cerca de cinco missões de um tipo é descartada para aquele tipo; revisões altas e críticas nunca são descartadas por rendimento.

Evidência

Cada critério em um arquivo de missão nomeia a evidência que precisa; a tabela de Evidência do diário dá uma linha por critério, e a integração verifica cada linha no código que está sendo integrado:

Critério	Sua linha deve nomear
- A1 ... (sem tag)	um job que passou naquele código (ele, ou o mesmo job reexecutado)
- A2 [artifact] ...	um caminho commitado no repositório da missão
- A3 [decision] ...	um id na tabela de Decisões do PLAN.md
- A4 [manual] ...	quem verificou o que, manualmente; mostrado como manual, nunca como prova automatizada

A prova é proporcional à alegação (references/review.md): testes verificam valores, não contagens; uma correção tem um teste que falha sem ela; uma alegação tem um mutante que um teste mata; sanitizadores em builds separados. Alegações de desempenho seguem references/measurement.md: antes e depois em commits nomeados, exclusive para números que decidem algo, magnitude honesta.

Trabalho de máquina

Nível	Para	Isolamento (quiet)
none	sondas minúsculas de thread única	sem retenção
light	builds, suítes de teste, fuzzing	alguns de uma vez, nice 19
strict	temporizações rápidas, execuções comportamentais	próprios núcleos no Linux; sozinho no macOS
exclusive	números que decidem algo	sozinho; fallback para cronometragem honesta

Um job falha se for morto ou exceder o tempo limite. campaign wait mostra sinais que um job enviou (SIGKILL é sempre a ferramenta, um código de sinal curto é o próprio programa). Cada job executa em seu próprio diretório. Detalhes da fila em references/host.md, Filas.

Comandos

campaign <comando> [<args>]

Comando	Ação
init	Cria um diretório .campaign/<name>/ com PLAN.md e state.json
new	Cria um diretório de missão com quests/<id>.md
start	Prepara um worktree, branch e diário para a missão
set	Altera campos em state.json (status, risco, enfraquecer)
job	Envia um job submit para a fila da máquina; wait bloqueia até que ele termine
verify	Executa jobs que checam as verificações de uma missão no código atual
check	Executa todas as verificações de portão e adiadas no código atual, reporta lacunas
accept	Aceita uma revisão, após confirmações
land	Integra para main ou um branch de marco; mescla worktrees e branches; remove
message	Envia ou fecha uma mensagem para um agente
status	Mostra estado, revisões, descobertas, histórico
wait	Fica em segundo plano sem tokens até que um job termine, um branch se mova ou uma mensagem chegue
undo	Reverte efeitos de comando registrados
config	Lê ou escreve uma chave de configuração
usage	Mostra métricas de uso (tokens de agente, jobs de máquina)

Arquivos de configuração

• ~/.campaign/config — configuração do usuário: model (padrão para agents novos), max_tokens, etc.
• .campaign/config — configuração do repositório: ci_later, integração.
• references/harness.md — modelos para cada nível.
• references/host.md — filas baseadas em host (quiet: Z:4), conectividade de máquina, caminhos de repositório.
• references/prompts.md — prompts de função.
• references/assignments/*.md — métodos de designação.
• references/measurement.md — medição honesta.
• references/review.md — prova proporcional.

Descrever um repositório

• docs/ na raiz do repositório contém, em formato editável: o que o produto faz, conceitos, arquitetura, como construí-lo, quais máquinas ele precisa (se diferente daquelas em references/host.md). Qualquer agente (revisor, contribuidor) pode ler, mas deve citar. O líder mantém fiel ao código.

Fine print

• campaign é idempotente — execute start novamente para um worktree existente; ele retoma.
• Landing é eventual — land pode falhar se main avançou; o agente reinicia com land --rebase.
• Sem aluguel de máquina. A campanha executa jobs localmente na(s) máquina(s) configuradas.
• Substitua qualquer agente. O estado está em arquivos; qualquer sessão pode retomar um contribuidor ou revisor.
• Mantenha as mensagens breves. O token é o recurso; o diário mantém o contexto.
• Aceite por código, não por palavra. A evidência de aceitação é o job que passou; a revisão é o arquivo.
• O proprietário é uma pessoa. O proprietário define os objetivos; a campanha os executa. O líder não define objetivos.