Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions docs/piloto/protocolo.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,19 @@ Cada fluxo é um serviço com dois ciclos completos. A entrada de cada execuçã

### Refinamento em tasks (ciclo de funcionalidade)

O Agente de Requisitos e Refinamento escreve a história em `docs/backlog/<ID>.md` com regra, cenários BDD e uma seção `## Tasks`, com 1 a 6 tasks `### T<n>: <título>`. Cada task traz `Cenários:`, `Arquivos:` e `Pronto quando:`. O supervisor rejeita a história se faltar algum desses elementos. No G3 são aprovadas a história e a quebra em tasks.
O Agente de Requisitos e Refinamento escreve a história em `docs/backlog/<ID>.md` com regra, cenários BDD e uma seção `## Tasks`, com 1 a 6 tasks `### T<n>: <título>`. Cada task traz `Cenários:`, `Arquivos:` e `Pronto quando:`. O supervisor rejeita a história se faltar algum desses elementos. Regras de negócio novas são propostas pelo mesmo agente em `docs/regras-de-negocio.md`. No G3 são aprovadas a história, a quebra em tasks e as regras novas. Cada decisão do G3 é registrada como comentário na issue, com aprovador, comentário, história e regras propostas. O registro fica no card mesmo que a execução falhe depois.

Depois do G3, cada task é executada em sequência: o Agente de Código implementa só aquela task, o Agente de Testes cobre seus cenários, as verificações de qualidade rodam e o supervisor faz um commit próprio para a task. Ao fim das tasks, sai um único PR, com uma CI e um G5 para a história inteira. Isso mantém o número de intervenções humanas comparável entre os ciclos. O trace registra `tasks_planned`, `task_started` e `task_finished`.
Depois do G3, cada task é executada em sequência: o Agente de Código implementa só aquela task, o Agente de Testes cobre seus cenários, as verificações de qualidade e a suíte da CI (`scripts/ci.sh`) rodam, e o supervisor faz um commit próprio para a task. Se a suíte falhar, o log volta alternadamente para o Agente de Código e para o de Testes, até 3 tentativas. Ao fim das tasks, sai um único PR, com uma CI e um G5 para a história inteira. Isso mantém o número de intervenções humanas comparável entre os ciclos. O trace registra `tasks_planned`, `task_started` e `task_finished`.

O ciclo de bug não passa por refinamento.

## Agentes e limites

| Agente | Atividades | Escrita | Comandos | Turnos | Orçamento (US$) |
|---|---|---|---|---:|---:|
| Requisitos e refinamento | 2, 3 | `docs/backlog/` | nenhum | 20 | 1,50 |
| Código | 6, 7 | serviço do fluxo, `libs/events/` e `web/public/` (exceto testes e, sem seção Interface, `styles.css`); `.pilot/repro/` | pytest, node --test, git somente leitura | 50 | 4,00 |
| Testes | 8, 10 | `tests/` do serviço e de `libs/events/`; `web/tests/` | pytest, node --test, git somente leitura | 40 | 3,00 |
| Requisitos e refinamento | 2, 3 | `docs/backlog/` e `docs/regras-de-negocio.md` (só regras novas) | nenhum | 20 | 1,50 |
| Código | 6, 7 | serviço do fluxo, `libs/events/` e `web/public/` (exceto testes e, sem seção Interface, `styles.css`); `.pilot/repro/` | pytest, node --test, `scripts/ci.sh`, git somente leitura | 50 | 4,00 |
| Testes | 8, 10 | `tests/` do serviço e de `libs/events/`; `web/tests/` | pytest, node --test, `scripts/ci.sh`, git somente leitura | 40 | 3,00 |
| Deploy | 11, 12 | `.pilot/deploy_report.md` | scripts de homologação, compose ps/logs | 20 | 1,00 |

## Guarda-corpos
Expand Down Expand Up @@ -77,6 +77,9 @@ Limitação conhecida: o agente de Deploy roda sem sandbox, pois precisa do Dock
| `outra` | Humano, ao reprovar |
| `criterio_aceitacao` | Automática: história ou relatório fora do padrão |
| `ci_quebrado` | Automática |
| `suite_vermelha` | Automática: suíte local falhou antes do commit |
| `correcao_bloqueada` | Automática: o agente não conseguiu alterar nada para corrigir a CI |
| `registro` | Automática: falha ao comentar na issue |
| `limite_execucao` | Automática: turnos ou orçamento |
| `erro_agente` | Automática |
| `violacao_escopo` | Automática |
Expand Down
4 changes: 3 additions & 1 deletion orchestrator/agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
TEST_COMMANDS = (
("pytest",),
("node", "--test"),
("bash", "scripts/ci.sh"),
("python", "-m", "pytest"),
("git", "status"),
("git", "diff"),
Expand Down Expand Up @@ -49,6 +50,7 @@ def system_prompt(self, worktree: Path) -> str:
DEPLOY = AgentSpec("deploy", "deploy.md", (*READ_TOOLS, "Write", "Bash"), 20, 1.0, False)


BUSINESS_RULES = "docs/regras-de-negocio.md"
WEB_CODE = "web/public/"
WEB_TESTS = "web/tests/"
WEB_STYLES = "web/public/styles.css"
Expand All @@ -61,7 +63,7 @@ def policy_for(spec: AgentSpec, service: str, worktree: Path, visual_changes: bo
events_tests = "libs/events/tests/"
styles = () if visual_changes else (WEB_STYLES,)
scopes: dict[str, dict] = {
"requisitos": {"writable": ("docs/backlog/",)},
"requisitos": {"writable": ("docs/backlog/", BUSINESS_RULES)},
"codigo": {
"writable": (service_dir, "libs/events/", WEB_CODE, ".pilot/repro/"),
"write_excluded": (service_tests, events_tests, *styles),
Expand Down
4 changes: 4 additions & 0 deletions orchestrator/console.py
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,10 @@ def format(self, r: dict) -> str | None:
return f" verificações de qualidade: {ok if r['passed'] else fail + ' ' + '; '.join(r['problems'])}"
case "regression_check":
return f" teste de regressão falha sem a correção: {ok if r['failed_on_base'] else fail}"
case "suite_result":
return f" suíte de testes (tentativa {r['attempt']}): {ok + ' verde' if r['passed'] else fail + ' falhou'}"
case "issue_commented":
return f" {ok} decisão do {r['gate']} registrada na issue #{r['issue']}"
case "pr_opened":
return f" PR aberto: {r['url']}"
case "ci_result":
Expand Down
65 changes: 61 additions & 4 deletions orchestrator/flows.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
import json
import shutil
import subprocess
from dataclasses import dataclass
from pathlib import Path

from orchestrator.agents import CODIGO, DEPLOY, REQUISITOS, TESTES, AgentSpec, policy_for
from orchestrator.agents import BUSINESS_RULES, CODIGO, DEPLOY, REQUISITOS, TESTES, AgentSpec, policy_for
from orchestrator.checks import (
Task,
changed_files,
Expand Down Expand Up @@ -151,6 +152,7 @@ async def _implement_task(self, task: Task, position: int, total: int) -> None:
f"Crie testes automatizados para os critérios e cenários da task {task.id}.\n\n{context}",
)
await self._quality_checks(current_task_only=True)
await self._ensure_suite_passes()
self._commit(f"feat({self.service}): {task.id} {task.title}")
self.trace.emit("task_finished", task=task.id)

Expand All @@ -169,7 +171,10 @@ async def _approve_story(self) -> None:
for _ in range(MAX_REWORK_ROUNDS):
self._phase("G3: aprovação da história")
story = (self.worktree / self.story_path).read_text(encoding="utf-8")
decision = self._gate("G3", f"{self.worktree / self.story_path}\n\n{story}")
rules = self._rules_diff()
rules_section = f"\n\nAlteração proposta em {BUSINESS_RULES}:\n{rules}" if rules else ""
decision = self._gate("G3", f"{self.worktree / self.story_path}\n\n{story}{rules_section}")
self._record_g3_on_issue(decision)
if decision.decision != "rejected":
return
await self._agent(
Expand All @@ -178,6 +183,54 @@ async def _approve_story(self) -> None:
)
raise RunAborted("rejected", "História reprovada no G3 além do limite de rodadas")

def _rules_diff(self) -> str:
return run(["git", "diff", "--", BUSINESS_RULES], self.worktree).stdout.strip()

def _record_g3_on_issue(self, decision: GateDecision) -> None:
"""Registra no card a saída do refinamento e a decisão humana, mesmo que a execução falhe depois."""
if not self.demand.issue:
return
outcome = {"approved": "aprovada", "edited": "aprovada com edição humana", "rejected": "reprovada"}
lines = [
f"### G3: história {outcome[decision.decision]}",
"",
f"- Aprovador: {decision.approver}",
f"- Execução: `{self.run_id}`",
f"- Esforço humano: {decision.human_minutes:.1f} min",
]
if decision.comment:
lines.append(f"- Comentário: {decision.comment}")
if decision.decision != "rejected":
story = (self.worktree / self.story_path).read_text(encoding="utf-8")
lines += ["", f"<details open><summary>História e tasks (<code>{self.story_path}</code>)</summary>", "", story, "", "</details>"]
rules = self._rules_diff()
if rules:
lines += ["", f"<details><summary>Regras de negócio propostas (<code>{BUSINESS_RULES}</code>)</summary>", "", "```diff", rules, "```", "", "</details>"]
try:
self.platform.comment_issue(self.worktree, self.demand.issue, "\n".join(lines))
self.trace.emit("issue_commented", issue=self.demand.issue, gate="G3", decision=decision.decision)
except subprocess.CalledProcessError as error:
self._failure("registro", f"Não foi possível comentar na issue #{self.demand.issue}: {error.stderr}")

async def _ensure_suite_passes(self) -> None:
"""Roda a mesma suíte da CI antes do commit, para teste vermelho não chegar ao PR."""
for attempt in range(1, MAX_REWORK_ROUNDS + 1):
result = run(["bash", "scripts/ci.sh", self.service], self.worktree, check=False)
passed = result.returncode == 0
log = (result.stdout + result.stderr)[-6000:]
self.trace.emit("suite_result", passed=passed, attempt=attempt, output="" if passed else log)
if passed:
return
self._failure("suite_vermelha", f"Suíte de testes falhou antes do commit (tentativa {attempt})")
spec = CODIGO if attempt % 2 else TESTES
await self._agent(
spec,
"A suíte de testes (`bash scripts/ci.sh`) falhou. Encontre a causa e corrija dentro da sua área, "
"sem enfraquecer testes válidos. Se a causa estiver fora da sua área, não contorne: explique-a.\n\n"
f"<log_testes>\n{log}\n</log_testes>\n\n{self.demand_block}",
)
raise RunAborted("aborted", "Suíte de testes continuou falhando antes do commit")

async def _bug(self) -> str:
self._record_coverage("before")
self._phase("Reprodução e correção do defeito")
Expand Down Expand Up @@ -239,6 +292,7 @@ def _work_files(self) -> list[str]:
async def _deliver(self, title: str, committed: bool = False) -> str:
if not committed:
await self._quality_checks()
await self._ensure_suite_passes()
self._phase("Commit e pull request")
self._commit(title)
else:
Expand Down Expand Up @@ -267,11 +321,13 @@ async def _wait_ci(self, pull_request: PullRequest) -> None:
if result.passed:
return
self._failure("ci_quebrado", f"CI falhou na tentativa {attempt}", log=result.log)
await self._agent(
fix = await self._agent(
CODIGO,
f"A CI falhou. Corrija a causa sem enfraquecer os testes.\n\n<log_ci>\n{result.log}\n</log_ci>",
)
self._commit(f"fix({self.service}): corrige falha de CI")
if not self._commit(f"fix({self.service}): corrige falha de CI"):
self._failure("correcao_bloqueada", fix.text, agent="codigo")
raise RunAborted("aborted", "O agente de Código não conseguiu alterar nada para corrigir a CI")
self.platform.push(self.worktree, self.branch)
raise RunAborted("aborted", "CI continuou falhando após o limite de tentativas")

Expand Down Expand Up @@ -308,6 +364,7 @@ async def _rework(self, pull_request: PullRequest, decision: GateDecision) -> No
if decision.rework_target in ("testes", "ambos"):
await self._agent(TESTES, feedback)
await self._quality_checks()
await self._ensure_suite_passes()
self._commit(f"fix({self.service}): atende revisão do G5")
self.platform.push(self.worktree, self.branch)
await self._wait_ci(pull_request)
Expand Down
11 changes: 11 additions & 0 deletions orchestrator/platform.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ def sync_merged(self, worktree: Path) -> None: ...

def tag_release(self, worktree: Path, tag: str) -> None: ...

def comment_issue(self, worktree: Path, number: int, body: str) -> None: ...


class GitHubPlatform:
name = "github"
Expand Down Expand Up @@ -114,6 +116,12 @@ def tag_release(self, worktree: Path, tag: str) -> None:
run(["git", "tag", tag], worktree)
run(["git", "push", "origin", tag], worktree)

def comment_issue(self, worktree: Path, number: int, body: str) -> None:
body_file = worktree / ".pilot" / "issue_comment.md"
body_file.parent.mkdir(exist_ok=True)
body_file.write_text(body, encoding="utf-8")
run(["gh", "issue", "comment", str(number), "--body-file", str(body_file)], worktree)


class LocalPlatform:
"""Ensaio sem GitHub: branch local como base e CI executada na máquina."""
Expand Down Expand Up @@ -152,3 +160,6 @@ def sync_merged(self, worktree: Path) -> None:

def tag_release(self, worktree: Path, tag: str) -> None:
run(["git", "tag", f"rehearsal-{tag}"], worktree)

def comment_issue(self, worktree: Path, number: int, body: str) -> None:
"""Ensaios não escrevem no card real."""
3 changes: 2 additions & 1 deletion orchestrator/prompts/codigo.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ Fronteira:
- Git, push, PR e deploy são exclusivos do supervisor. Testes definitivos são do Agente de Testes.
- Comandos permitidos: `pytest`, `python -m pytest` e `git status|diff|log|show`, sem encadeamento ou redirecionamento.
- Um bloqueio de guarda-corpo é definitivo: não tente contorná-lo por outro caminho.
- Comandos de teste do front: `node --test "web/tests/*.test.js"`.
- Comandos de teste do front: `node --test "web/tests/*.test.js"`. A suíte completa da CI: `bash scripts/ci.sh <serviço>`.
- Documentação e regras de negócio (`docs/`) não são da sua área. Se a demanda depender delas, registre como pendência.

Front (`web/public/`):
- Altere a tela quando a demanda precisar ser usada por ela, por exemplo uma ação nova ou um dado novo exibido. Siga as convenções de front do AGENTS.md.
Expand Down
5 changes: 3 additions & 2 deletions orchestrator/prompts/requisitos.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Fronteira: você rascunha; o PO e o tech lead aprovam a história e as tasks no

Critérios de aceitação do seu trabalho:
- O arquivo é criado exatamente no caminho indicado.
- Há pelo menos uma linha `Regra: RN-xx` referenciando `docs/regras-de-negocio.md`. Se a demanda criar regra nova, use o próximo número livre e descreva-a na história.
- Há pelo menos uma linha `Regra: RN-xx` referenciando `docs/regras-de-negocio.md`. Se a demanda criar regra nova, use o próximo número livre, descreva-a na história e acrescente a linha correspondente na tabela de `docs/regras-de-negocio.md`. A regra é aprovada pela equipe no G3, junto com a história. Não altere regras existentes; se uma precisar mudar, registre em "Questões em aberto".
- Cada comportamento tem um cenário BDD iniciado por `Cenário:`, incluindo casos de exceção.
- Eventos novos ou alterados são listados com tipo e campos.
- A seção `## Tasks` divide a implementação em 1 a 6 tasks, cada uma com cabeçalho `### T1: <título>`, `### T2: ...` e assim por diante.
Expand All @@ -18,7 +18,8 @@ Como quebrar em tasks:
- `Cenários:` os cenários BDD que ela cobre, pelo nome;
- `Arquivos:` os arquivos que provavelmente muda;
- `Pronto quando:` o critério objetivo de conclusão.
- Não crie task só de testes nem só de documentação. Os testes de cada task são escritos junto com ela.
- Não crie task para registrar regras ou documentação: isso é feito por você, no refinamento. Também não crie task só de testes.
- Não crie task só de documentação. Os testes de cada task são escritos junto com ela.
- Se a demanda precisar ser usada pela tela, inclua uma task de front (`web/public/`) depois das tasks da API.
- Decisões visuais vêm apenas da seção `<interface>` da demanda, escrita pela equipe técnica. Sem ela, a task de front reutiliza os componentes existentes; qualquer necessidade visual vai para "Questões em aberto".

Expand Down
6 changes: 4 additions & 2 deletions orchestrator/prompts/testes.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,14 @@ Você cria cenários e testes automatizados com pytest, usando `InMemoryBus` e `

Fronteira:
- Escreva somente em `services/<serviço-da-demanda>/tests/`, `libs/events/tests/` e `web/tests/`. Nunca altere código de produção: se um teste revelar defeito, relate na resposta final.
- Comandos permitidos: `pytest`, `python -m pytest`, `node --test "web/tests/*.test.js"` e `git status|diff|log|show`, sem encadeamento ou redirecionamento.
- Comandos permitidos: `pytest`, `python -m pytest`, `bash scripts/ci.sh <serviço>`, `node --test "web/tests/*.test.js"` e `git status|diff|log|show`, sem encadeamento ou redirecionamento.
- Se a demanda alterar o front, teste as funções de `web/public/lib.js` em `web/tests/<assunto>.test.js`, com `node:test` e `node:assert/strict`, cada teste com ao menos uma asserção.
- Você não aprova a própria suíte: a revisão é humana no gate G5.

Critérios de aceitação:
- Cada teste verifica comportamento observável, com asserções significativas. Nada de teste vazio ou tautológico.
- Cada teste verifica comportamento observável do sistema, com asserções significativas. Nada de teste vazio ou tautológico.
- Nunca teste documentação (`docs/`, `AGENTS.md`, histórias): regras de negócio se verificam pelo comportamento que produzem.
- Antes de terminar, rode `bash scripts/ci.sh <serviço>` e deixe a suíte verde. O supervisor roda a mesma suíte antes do commit.
- Em ciclo de funcionalidade, cada cenário BDD da história tem ao menos um teste, referenciado na docstring.
- Em ciclo de bug, o teste de regressão precisa falhar no código sem a correção. O supervisor verifica isso.
- Use apenas dados sintéticos.
Expand Down
Loading
Loading