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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Monorepo do piloto instrumentado do trabalho "Desenvolvimento de Software Guiado
- `libs/events/`: contratos de eventos e barramentos
- `web/`: front simples de homologação em http://localhost:8080
- `orchestrator/`: supervisor, agentes (Claude Agent SDK), guarda-corpos, gates e tracing
- `pilot/`: demandas, traces e relatório
- `pilot/`: traces e relatório; as demandas são issues do GitHub com o rótulo `piloto`
- `docs/`: conhecimento do projeto e [protocolo do piloto](docs/piloto/protocolo.md)
- `AGENTS.md`: contexto injetado nos agentes

Expand Down
36 changes: 25 additions & 11 deletions docs/piloto/protocolo.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,37 @@ Define o que é medido e como executar o piloto do processo guiado por agentes (

## Fluxos

Cada fluxo é um serviço com dois ciclos completos.
Cada fluxo é um serviço com dois ciclos completos. A entrada de cada execução é uma **issue do GitHub**.

| Fluxo | Ciclo | Demanda | Passos |
| Fluxo | Ciclo | Issue | Passos |
|---|---|---|---|
| Catálogo | Funcionalidade | CAT-FEAT-01 | Requisitos → G3 → Código → Testes → CI → G5 → Deploy em homologação → G7 |
| Catálogo | Bug | CAT-BUG-01 | Reprodução e patch → Teste de regressão → CI → G5 → Deploy em homologação → G7 |
| Pedidos | Funcionalidade | ORD-FEAT-01 | Igual ao ciclo de funcionalidade |
| Pedidos | Bug | ORD-BUG-01 | Igual ao ciclo de bug |
| Verificação | Guarda-corpo | GRD-01 | Agente de Código recebe um relato com injeção de instrução; sem PR |
| Catálogo | Funcionalidade | #2 CAT-FEAT-01 | Refinamento (história e tasks) → G3 → para cada task: Código → Testes → verificações → commit → PR → CI → G5 → Deploy em homologação → G7 |
| Catálogo | Bug | #3 CAT-BUG-01 | Reprodução e patch → Teste de regressão → CI → G5 → Deploy em homologação → G7 |
| Pedidos | Funcionalidade | #4 ORD-FEAT-01 | Igual ao ciclo de funcionalidade |
| Pedidos | Bug | #5 ORD-BUG-01 | Igual ao ciclo de bug |
| Verificação | Guarda-corpo | #6 GRD-01 | Agente de Código recebe um relato com injeção de instrução; sem PR |

Cada demanda tem uma issue no GitHub (#2 a #6), indicada no campo `issue:` do arquivo da demanda. O PR aberto pelo orquestrador inclui `Closes #N`, então o merge no G5 fecha a issue. A issue do GRD-01 é fechada manualmente depois da execução, com o resultado registrado no trace.
### Issue como card de entrada

- O orquestrador só aceita issues **abertas** com o rótulo `piloto`, exatamente um rótulo `fluxo:<catalog|cart|orders>` e um `ciclo:<feature|bug|guardrail>`. Só quem tem acesso de triagem aplica rótulos, então pessoas de fora não conseguem colocar uma issue para rodar no repositório público.
- O título no formato `[ID] título` define o identificador da demanda. Sem isso, o identificador é `ISSUE-<número>`.
- Só a seção `## Demanda` do corpo vai para os agentes, sempre marcada como dado não confiável. As outras seções (observações, instruções de execução) ficam só para os humanos.
- O PR inclui `Closes #N`, então o merge no G5 fecha a issue. A issue do GRD-01 é fechada manualmente depois da execução.
- Para uma nova demanda, crie uma issue com esses rótulos e rode `--issue <número>`.

### 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.

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`.

O ciclo de bug não passa por refinamento.

## Agentes e limites

| Agente | Atividades | Escrita | Comandos | Turnos | Orçamento (US$) |
|---|---|---|---|---:|---:|
| Requisitos | 2, 3 | `docs/backlog/` | nenhum | 20 | 1,50 |
| Requisitos e refinamento | 2, 3 | `docs/backlog/` | nenhum | 20 | 1,50 |
| Código | 6, 7 | serviço do fluxo e `libs/events/`, exceto `tests/`; `.pilot/repro/` | pytest, git somente leitura | 50 | 4,00 |
| Testes | 8, 10 | `tests/` do serviço e de `libs/events/` | pytest, git somente leitura | 40 | 3,00 |
| Deploy | 11, 12 | `.pilot/deploy_report.md` | scripts de homologação, compose ps/logs | 20 | 1,00 |
Expand Down Expand Up @@ -83,10 +97,10 @@ python3 -m venv .venv
```

```bash
.venv/bin/python -m orchestrator run --flow catalog --cycle feature --operator "Nome (papel)"
.venv/bin/python -m orchestrator run --issue 2 --operator "Nome (papel)"
```

Repita com `--flow catalog --cycle bug`, `--flow orders --cycle feature`, `--flow orders --cycle bug` e `--flow catalog --cycle guardrail`.
Repita com `--issue 4` (ORD-FEAT-01), `--issue 5` (ORD-BUG-01) e `--issue 6` (GRD-01). A #3 (CAT-BUG-01) já foi executada.

Durante a execução, o terminal mostra cada fase do supervisor, as mensagens e ferramentas de cada agente, os bloqueios de guarda-corpo, o custo por agente e as decisões nos gates. Use `--quiet` para ver só os gates. O registro completo continua no trace.

Expand Down
12 changes: 12 additions & 0 deletions docs/templates/historia.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,15 @@ Cenário: <caso de exceção>
|---|---|---|

## Questões em aberto

## Tasks

### T1: <título>
Cenários: <nomes dos cenários cobertos>
Arquivos: <arquivos prováveis>
Pronto quando: <critério objetivo>

### T2: <título>
Cenários: <...>
Arquivos: <...>
Pronto quando: <...>
16 changes: 9 additions & 7 deletions orchestrator/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
from datetime import UTC, datetime

from orchestrator.console import ConsoleLog
from orchestrator.config import RUNS_DIR, SERVICES, TRACES_DIR, WORKTREES_DIR, REPO_ROOT, Settings
from orchestrator.demands import find_demand
from orchestrator.config import RUNS_DIR, TRACES_DIR, WORKTREES_DIR, REPO_ROOT, Settings
from orchestrator.demands import InvalidIssue, fetch_demand
from orchestrator.flows import RunAborted, Supervisor
from orchestrator.gates import ScriptedGates, TerminalGates
from orchestrator.platform import GitHubPlatform, LocalPlatform, run
Expand All @@ -20,9 +20,8 @@
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(prog="orchestrator")
commands = parser.add_subparsers(dest="command", required=True)
pilot = commands.add_parser("run", help="executa um ciclo do piloto")
pilot.add_argument("--flow", choices=SERVICES, required=True)
pilot.add_argument("--cycle", choices=("feature", "bug", "guardrail"), required=True)
pilot = commands.add_parser("run", help="executa o ciclo de uma issue do piloto")
pilot.add_argument("--issue", type=int, required=True, help="número da issue com os rótulos piloto, fluxo: e ciclo:")
pilot.add_argument("--platform", choices=("github", "local"), default="github")
pilot.add_argument("--auto-approve", action="store_true", help="somente ensaio com --platform local")
pilot.add_argument("--operator", help="nome e papel padrão do aprovador")
Expand All @@ -35,10 +34,13 @@ def parse_args() -> argparse.Namespace:
async def execute(args: argparse.Namespace) -> int:
if args.auto_approve and args.platform != "local":
raise SystemExit("--auto-approve só é aceito em ensaios com --platform local")
if args.platform == "github" and shutil.which("gh") is None:
if shutil.which("gh") is None:
raise SystemExit("GitHub CLI (gh) não encontrado; instale e autentique com 'gh auth login'")

demand = find_demand(args.flow, args.cycle)
try:
demand = fetch_demand(args.issue)
except InvalidIssue as error:
raise SystemExit(f"Issue inválida para o piloto: {error}") from error
run_id = f"{datetime.now(UTC):%Y%m%dT%H%M%S}-{demand.id.lower()}"
rehearsal = args.platform == "local"
platform = GitHubPlatform() if args.platform == "github" else LocalPlatform()
Expand Down
33 changes: 33 additions & 0 deletions orchestrator/checks.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,15 @@
import shutil
import subprocess
import tempfile
from dataclasses import dataclass
from pathlib import Path

from orchestrator.config import MAX_TASKS
from orchestrator.platform import run

COVERAGE_LINE = re.compile(r"^TOTAL\s+\d+\s+\d+\s+(\d+)%", re.MULTILINE)
TASK_HEADING = re.compile(r"^###\s+(T\d+):\s*(.+?)\s*$", re.MULTILINE)
NEXT_SECTION = re.compile(r"^##\s", re.MULTILINE)
PYTEST_TESTS_FAILED = 1


Expand All @@ -21,6 +25,25 @@ def changed_since(worktree: Path, base_ref: str) -> list[str]:
return output.split()


@dataclass(frozen=True)
class Task:
id: str
title: str
body: str


def parse_tasks(story: str) -> list[Task]:
headings = list(TASK_HEADING.finditer(story))
tasks = []
for index, heading in enumerate(headings):
end = headings[index + 1].start() if index + 1 < len(headings) else len(story)
segment = story[heading.end():end]
section_end = NEXT_SECTION.search(segment)
body = segment[: section_end.start()] if section_end else segment
tasks.append(Task(heading.group(1), heading.group(2), body.strip()))
return tasks


def story_problems(path: Path) -> list[str]:
if not path.exists():
return [f"arquivo da história não foi criado: {path.name}"]
Expand All @@ -30,6 +53,16 @@ def story_problems(path: Path) -> list[str]:
problems.append("nenhum cenário BDD (linha 'Cenário:') encontrado")
if not re.search(r"^\s*Regra:\s*\S+", text, re.MULTILINE):
problems.append("história não rastreada a uma regra (linha 'Regra: <id>')")
tasks = parse_tasks(text)
if not tasks:
problems.append("nenhuma task no formato '### T1: <título>' na seção '## Tasks'")
if len(tasks) > MAX_TASKS:
problems.append(f"{len(tasks)} tasks; o máximo é {MAX_TASKS}")
if len({task.id for task in tasks}) != len(tasks):
problems.append("identificadores de task repetidos")
for task in tasks:
if not re.search(r"^\s*Cenários:\s*\S+", task.body, re.MULTILINE):
problems.append(f"{task.id} não indica os cenários que cobre (linha 'Cenários: ...')")
return problems


Expand Down
2 changes: 1 addition & 1 deletion orchestrator/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@
REPO_ROOT = Path(__file__).resolve().parent.parent
TRACES_DIR = REPO_ROOT / "pilot" / "traces"
RUNS_DIR = REPO_ROOT / "pilot" / "runs"
DEMANDS_DIR = REPO_ROOT / "pilot" / "demands"
WORKTREES_DIR = REPO_ROOT / ".pilot-worktrees"
PROMPTS_DIR = Path(__file__).resolve().parent / "prompts"

LOCAL_BASE_BRANCH = "pilot-local"
MAX_REWORK_ROUNDS = 3
MAX_TASKS = 6
SERVICES = ("catalog", "cart", "orders")


Expand Down
7 changes: 7 additions & 0 deletions orchestrator/console.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,13 @@ def format(self, r: dict) -> str | None:
return self.paint(f"▶ {r['run_id']} · {r['demand']} ({r['flow']}/{r['cycle']}) · modelo {r['model']} · {r['platform']}", "bold")
case "phase":
return self.paint(f"── {r['name']}", "bold")
case "tasks_planned":
listed = " · ".join(f"{task['id']} {task['title']}" for task in r["tasks"])
return self.paint(f" {len(r['tasks'])} tasks planejadas: {listed}", "bold")
case "task_started":
return self.paint(f"▸ task {r['task']} ({r['position']}/{r['total']}): {r['title']}", "bold")
case "task_finished":
return f" {ok} task {r['task']} commitada"
case "coverage":
percent = "indisponível" if r["percent"] is None else f"{r['percent']}%"
return f" cobertura {'antes' if r['phase'] == 'before' else 'depois'}: {percent}"
Expand Down
61 changes: 46 additions & 15 deletions orchestrator/demands.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,14 @@
import json
import re
from dataclasses import dataclass
from pathlib import Path

from orchestrator.config import DEMANDS_DIR
from orchestrator.config import REPO_ROOT, SERVICES
from orchestrator.platform import run

CYCLES = ("feature", "bug", "guardrail")
PILOT_LABEL = "piloto"
TITLE_WITH_ID = re.compile(r"^\[([A-Z0-9-]+)\]\s*(.+)$")
DEMAND_SECTION = re.compile(r"^## Demanda[ \t]*\n(.*?)(?=^## |\Z)", re.MULTILINE | re.DOTALL)


@dataclass(frozen=True)
Expand All @@ -14,18 +21,42 @@ class Demand:
issue: int | None = None


def parse_demand(path: Path) -> Demand:
_, header, body = path.read_text(encoding="utf-8").split("---\n", 2)
fields = dict(line.split(": ", 1) for line in header.strip().splitlines())
issue = int(fields["issue"]) if "issue" in fields else None
return Demand(fields["id"], fields["flow"], fields["cycle"], fields["title"], body.strip(), issue)
class InvalidIssue(ValueError):
pass


def _single_label(labels: set[str], prefix: str, allowed: tuple[str, ...]) -> str:
values = [label.removeprefix(prefix) for label in labels if label.startswith(prefix)]
if len(values) != 1 or values[0] not in allowed:
raise InvalidIssue(f"a issue precisa de exatamente um rótulo {prefix}<{'|'.join(allowed)}>")
return values[0]


def demand_from_issue(issue: dict) -> Demand:
"""O rótulo `piloto` só pode ser aplicado por quem tem acesso de triagem, o que impede rodar issues de terceiros."""
labels = {label["name"] for label in issue["labels"]}
if PILOT_LABEL not in labels:
raise InvalidIssue(f"a issue #{issue['number']} não tem o rótulo '{PILOT_LABEL}'")
if issue["state"] != "OPEN":
raise InvalidIssue(f"a issue #{issue['number']} está fechada")

match = TITLE_WITH_ID.match(issue["title"])
demand_id, title = (match.group(1), match.group(2)) if match else (f"ISSUE-{issue['number']}", issue["title"])
section = DEMAND_SECTION.search(issue["body"])
body = (section.group(1) if section else issue["body"]).strip()
if not body:
raise InvalidIssue(f"a issue #{issue['number']} não tem descrição da demanda")

return Demand(
id=demand_id,
flow=_single_label(labels, "fluxo:", SERVICES),
cycle=_single_label(labels, "ciclo:", CYCLES),
title=title,
body=body,
issue=issue["number"],
)


def find_demand(flow: str, cycle: str, directory: Path = DEMANDS_DIR) -> Demand:
matches = [
demand for demand in map(parse_demand, sorted(directory.glob("*.md")))
if demand.flow == flow and demand.cycle == cycle
]
if len(matches) != 1:
raise SystemExit(f"Esperada 1 demanda para {flow}/{cycle}, encontradas {len(matches)}")
return matches[0]
def fetch_demand(number: int) -> Demand:
view = run(["gh", "issue", "view", str(number), "--json", "number,title,body,labels,state"], REPO_ROOT)
return demand_from_issue(json.loads(view.stdout))
47 changes: 33 additions & 14 deletions orchestrator/flows.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,11 @@

from orchestrator.agents import CODIGO, DEPLOY, REQUISITOS, TESTES, AgentSpec, policy_for
from orchestrator.checks import (
Task,
changed_files,
changed_since,
coverage_percent,
parse_tasks,
regression_fails_without_fix,
story_problems,
tests_without_assertions,
Expand Down Expand Up @@ -116,24 +118,37 @@ def _commit(self, message: str) -> bool:

async def _feature(self) -> str:
self._record_coverage("before")
self._phase("Requisitos: história e critérios BDD")
self._phase("Refinamento: história, critérios BDD e tasks")
await self._write_story()
await self._approve_story()
self._phase("Implementação")
tasks = parse_tasks((self.worktree / self.story_path).read_text(encoding="utf-8"))
self.trace.emit("tasks_planned", tasks=[{"id": task.id, "title": task.title} for task in tasks])
for position, task in enumerate(tasks, 1):
await self._implement_task(task, position, len(tasks))
return await self._deliver(f"feat({self.service}): {self.demand.title}", committed=True)

async def _implement_task(self, task: Task, position: int, total: int) -> None:
"""Cada task vira um commit próprio, com código e testes verificados antes de seguir para a próxima."""
self.trace.emit("task_started", task=task.id, title=task.title, position=position, total=total)
task_block = f'<task id="{task.id}">\n### {task.id}: {task.title}\n{task.body}\n</task>'
context = f"História completa em {self.story_path}.\n\n{task_block}\n\n{self.demand_block}"
self._phase(f"Task {task.id} ({position}/{total}): implementação")
await self._agent(
CODIGO,
f"Implemente a história aprovada em {self.story_path}.\n\n{self.demand_block}",
f"Implemente somente a task {task.id}. As tasks anteriores já estão commitadas; "
f"não antecipe as seguintes.\n\n{context}",
)
self._phase("Testes automatizados")
self._phase(f"Task {task.id} ({position}/{total}): testes")
await self._agent(
TESTES,
f"Crie cenários e testes automatizados para a história em {self.story_path}, "
f"cobrindo cada cenário BDD.\n\n{self.demand_block}",
f"Crie testes automatizados para os critérios e cenários da task {task.id}.\n\n{context}",
)
return await self._deliver(f"feat({self.service}): {self.demand.title}")
await self._quality_checks(current_task_only=True)
self._commit(f"feat({self.service}): {task.id} {task.title}")
self.trace.emit("task_finished", task=task.id)

async def _write_story(self) -> None:
prompt = f"Escreva a história em {self.story_path}.\n\n{self.demand_block}"
prompt = f"Refine a demanda na história em {self.story_path}, com critérios BDD e tasks.\n\n{self.demand_block}"
for _ in range(MAX_REWORK_ROUNDS):
await self._agent(REQUISITOS, prompt)
problems = story_problems(self.worktree / self.story_path)
Expand Down Expand Up @@ -188,10 +203,11 @@ async def _guardrail(self) -> str:
)
return "completed"

async def _quality_checks(self) -> None:
async def _quality_checks(self, current_task_only: bool = False) -> None:
self._phase("Verificações de qualidade")
for _ in range(MAX_REWORK_ROUNDS):
test_files = [path for path in self._work_files() if is_test_file(path)]
files = changed_files(self.worktree) if current_task_only else self._work_files()
test_files = [path for path in files if is_test_file(path)]
problems = []
if not test_files:
problems.append("nenhum arquivo de teste foi criado ou alterado")
Expand All @@ -213,10 +229,13 @@ async def _quality_checks(self) -> None:
def _work_files(self) -> list[str]:
return sorted({*changed_files(self.worktree), *changed_since(self.worktree, self.platform.base_ref)})

async def _deliver(self, title: str) -> str:
await self._quality_checks()
self._phase("Commit e pull request")
self._commit(title)
async def _deliver(self, title: str, committed: bool = False) -> str:
if not committed:
await self._quality_checks()
self._phase("Commit e pull request")
self._commit(title)
else:
self._phase("Pull request")
pull_request = self.platform.open_pr(self.worktree, self.branch, title, self._pr_body())
self.trace.emit("pr_opened", number=pull_request.number, url=pull_request.url)
await self._wait_ci(pull_request)
Expand Down
Loading