@fullchico/harness 0.0.0-stage → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/.claude-plugin/marketplace.json +14 -0
  2. package/LICENSE +21 -0
  3. package/README.md +243 -2
  4. package/bin/harness.js +21 -0
  5. package/install +108 -0
  6. package/package.json +27 -4
  7. package/plugin/.claude-plugin/plugin.json +9 -0
  8. package/plugin/agents/implementador.md +55 -0
  9. package/plugin/agents/orquestrador.md +59 -0
  10. package/plugin/agents/qualidade.md +44 -0
  11. package/plugin/agents/revisor-ambiente.md +86 -0
  12. package/plugin/agents/revisor-bugs.md +153 -0
  13. package/plugin/agents/revisor-spec.md +49 -0
  14. package/plugin/agents/revisor.md +96 -0
  15. package/plugin/agents/seguranca.md +62 -0
  16. package/plugin/bin/sync +322 -0
  17. package/plugin/map.json +387 -0
  18. package/plugin/payload/agents-clean +77 -0
  19. package/plugin/payload/approve +34 -0
  20. package/plugin/payload/arch_check.py +94 -0
  21. package/plugin/payload/compose_check.py +186 -0
  22. package/plugin/payload/conf-apply +22 -0
  23. package/plugin/payload/destroy +21 -0
  24. package/plugin/payload/dev +24 -0
  25. package/plugin/payload/down +20 -0
  26. package/plugin/payload/entrega/despacho.md +186 -0
  27. package/plugin/payload/entrega/fechamento.md +179 -0
  28. package/plugin/payload/entrega/tickets.md +154 -0
  29. package/plugin/payload/env-common.sh +64 -0
  30. package/plugin/payload/fetch +10 -0
  31. package/plugin/payload/gate-check +159 -0
  32. package/plugin/payload/git-hooks/commit-msg +32 -0
  33. package/plugin/payload/git-hooks/pre-commit +19 -0
  34. package/plugin/payload/git-hooks/pre-push +15 -0
  35. package/plugin/payload/hooks/__pycache__/common.cpython-313.pyc +0 -0
  36. package/plugin/payload/hooks/__pycache__/gate_stamp.cpython-313.pyc +0 -0
  37. package/plugin/payload/hooks/common.py +274 -0
  38. package/plugin/payload/hooks/dispatch_guard.py +290 -0
  39. package/plugin/payload/hooks/gate_stamp.py +242 -0
  40. package/plugin/payload/hooks/managed_guard.py +95 -0
  41. package/plugin/payload/hooks/service_guard.py +178 -0
  42. package/plugin/payload/hooks/session_context.py +68 -0
  43. package/plugin/payload/hooks/subagent_context.py +49 -0
  44. package/plugin/payload/integrate +110 -0
  45. package/plugin/payload/learn +7 -0
  46. package/plugin/payload/learn.py +282 -0
  47. package/plugin/payload/manifest_check.py +68 -0
  48. package/plugin/payload/memory +7 -0
  49. package/plugin/payload/memory.py +521 -0
  50. package/plugin/payload/pendings +7 -0
  51. package/plugin/payload/ports-free +55 -0
  52. package/plugin/payload/pr +52 -0
  53. package/plugin/payload/prepare +10 -0
  54. package/plugin/payload/push +44 -0
  55. package/plugin/payload/setup-worktree +61 -0
  56. package/plugin/payload/skills-add +20 -0
  57. package/plugin/payload/skills-search +6 -0
  58. package/plugin/payload/skills-show +6 -0
  59. package/plugin/payload/skills_remote.py +111 -0
  60. package/plugin/payload/subagent-rules.md +14 -0
  61. package/plugin/payload/ticket +67 -0
  62. package/plugin/payload/tickets_check.py +206 -0
  63. package/plugin/payload/up +45 -0
  64. package/plugin/payload/update +45 -0
  65. package/plugin/payload/validate +90 -0
  66. package/plugin/payload/worktree-env +128 -0
  67. package/plugin/skills/aprender/SKILL.md +62 -0
  68. package/plugin/skills/buscar-skills/SKILL.md +73 -0
  69. package/plugin/skills/dream/SKILL.md +92 -0
  70. package/plugin/skills/entregar/SKILL.md +110 -0
  71. package/plugin/skills/entregar/references/spec.md +84 -0
  72. package/plugin/skills/mapear/SKILL.md +85 -0
  73. package/plugin/skills/setup/SKILL.md +66 -0
  74. package/plugin/templates/AGENTS.managed.md +173 -0
  75. package/plugin/templates/AGENTS.project.md +3 -0
  76. package/plugin/templates/CLAUDE.md +10 -0
  77. package/plugin/templates/conductor.toml +16 -0
  78. package/plugin/templates/docs/agents/domain.md +15 -0
  79. package/plugin/templates/docs/agents/issue-tracker.md +23 -0
  80. package/plugin/templates/docs/agents/stack.md +132 -0
  81. package/plugin/templates/harness.conf +61 -0
  82. package/plugin/templates/orca.yaml +10 -0
  83. package/plugin/templates/settings.json +210 -0
@@ -0,0 +1,186 @@
1
+ #!/usr/bin/env python3
2
+ """Confere a configuração final do compose antes de o ambiente subir.
3
+
4
+ O `up` roda fora do sandbox do Bash, e o Docker monta qualquer pasta da máquina
5
+ num contêiner. Sem esta checagem, bastaria editar o compose do projeto para um
6
+ contêiner escrever fora dele. A entrada é o JSON que o próprio Docker devolve em
7
+ `docker compose config --format json`, já com variáveis e caminhos resolvidos.
8
+
9
+ Uso: compose_check.py <raiz do projeto> [--summary] < config.json
10
+ Sai 0 se pode subir; sai 1 com os motivos em stderr.
11
+ """
12
+ import json
13
+ import os
14
+ import sys
15
+
16
+ sys.dont_write_bytecode = True
17
+
18
+ # A checagem parte do que é permitido, não do que é perigoso: o formato do compose
19
+ # tem campos demais que dão acesso à máquina para tentar listar todos os ruins.
20
+ # Campo fora destas listas é recusado, com o nome dele, para o dono decidir.
21
+ PLAIN_FIELDS = {
22
+ "image", "command", "entrypoint", "environment", "ports", "expose", "networks", "depends_on",
23
+ "healthcheck", "restart", "container_name", "hostname", "domainname", "working_dir", "user",
24
+ "labels", "annotations", "init", "tty", "stdin_open", "read_only", "platform", "profiles",
25
+ "pull_policy", "stop_grace_period", "stop_signal", "tmpfs", "ulimits", "shm_size", "mem_limit",
26
+ "mem_reservation", "cpus", "cpu_shares", "logging", "extra_hosts", "dns", "dns_search", "links",
27
+ "attach", "scale", "deploy",
28
+ }
29
+ CHECKED_FIELDS = {"volumes", "build", "env_file", "secrets", "configs", "privileged", "pid", "ipc",
30
+ "network_mode", "cap_add", "devices"}
31
+ HOST_NAMESPACES = ("pid", "ipc")
32
+ BUILD_FIELDS = {"context", "dockerfile", "args", "target", "additional_contexts", "labels", "cache_from",
33
+ "platforms", "tags", "pull", "no_cache", "network", "shm_size", "dockerfile_inline"}
34
+
35
+
36
+ def _inside(path: str, root: str) -> bool:
37
+ real, base = os.path.realpath(path), os.path.realpath(root)
38
+ git_dir = os.path.join(base, ".git")
39
+ if real == git_dir or real.startswith(git_dir + os.sep):
40
+ return False
41
+ return real == base or real.startswith(base + os.sep)
42
+
43
+
44
+ def _services(config):
45
+ services = config.get("services") if isinstance(config, dict) else None
46
+ return services if isinstance(services, dict) and services else None
47
+
48
+
49
+ def _named_volume(config, name: str):
50
+ """Motivo para recusar um volume nomeado, ou None. Só o volume local simples passa."""
51
+ declared = (config.get("volumes") or {}).get(name)
52
+ if declared is None:
53
+ return None
54
+ if not isinstance(declared, dict):
55
+ return "em formato inesperado"
56
+ if declared.get("external"):
57
+ return "é externo ao compose"
58
+ if declared.get("driver") not in (None, "local"):
59
+ return f"usa o driver {declared.get('driver')}"
60
+ if declared.get("driver_opts"):
61
+ return "tem opções de driver, que podem apontar para uma pasta da máquina"
62
+ return None
63
+
64
+
65
+ def _build(name: str, build, root: str) -> list:
66
+ if isinstance(build, str):
67
+ build = {"context": build}
68
+ if not isinstance(build, dict):
69
+ return [f"serviço {name}: build em formato inesperado"]
70
+ found = [f"serviço {name}: build usa {key}, que não é permitido" for key in build if key not in BUILD_FIELDS]
71
+ context = str(build.get("context", ""))
72
+ if not _inside(context, root):
73
+ found.append(f"serviço {name}: o build lê uma pasta de fora do projeto ({context})")
74
+ dockerfile = build.get("dockerfile")
75
+ if dockerfile and not _inside(os.path.join(context, str(dockerfile)), root):
76
+ found.append(f"serviço {name}: o Dockerfile fica fora do projeto ({dockerfile})")
77
+ extra = build.get("additional_contexts") or {}
78
+ for value in (extra.values() if isinstance(extra, dict) else extra):
79
+ if not _inside(str(value), root):
80
+ found.append(f"serviço {name}: o build lê um contexto de fora do projeto ({value})")
81
+ return found
82
+
83
+
84
+ def _service(name: str, service: dict, config: dict, root: str) -> list:
85
+ found = [f"serviço {name}: o campo {key} não está entre os permitidos" for key in service
86
+ if key not in PLAIN_FIELDS and key not in CHECKED_FIELDS]
87
+ volumes = service.get("volumes") or []
88
+ if not isinstance(volumes, list):
89
+ found.append(f"serviço {name}: volumes em formato inesperado")
90
+ volumes = []
91
+ for volume in volumes:
92
+ kind = volume.get("type") if isinstance(volume, dict) else None
93
+ if kind == "bind":
94
+ if not _inside(str(volume.get("source", "")), root):
95
+ found.append(f"serviço {name}: monta uma pasta de fora do projeto ({volume.get('source')})")
96
+ elif kind == "volume":
97
+ reason = _named_volume(config, str(volume.get("source", "")))
98
+ if reason:
99
+ found.append(f"serviço {name}: o volume {volume.get('source')} {reason}")
100
+ elif kind != "tmpfs":
101
+ found.append(f"serviço {name}: volume de tipo não permitido ({kind})")
102
+ if "build" in service:
103
+ found += _build(name, service["build"], root)
104
+ for entry in service.get("env_file") or []:
105
+ path = entry.get("path") if isinstance(entry, dict) else entry
106
+ if not _inside(str(path), root):
107
+ found.append(f"serviço {name}: lê um arquivo de variáveis de fora do projeto ({path})")
108
+ if service.get("privileged"):
109
+ found.append(f"serviço {name}: contêiner privilegiado")
110
+ for key in HOST_NAMESPACES:
111
+ if service.get(key) not in (None, "", "private", "shareable"):
112
+ found.append(f"serviço {name}: usa {key} de fora do contêiner ({service.get(key)})")
113
+ mode = service.get("network_mode")
114
+ if mode not in (None, "", "bridge", "none") and not str(mode).startswith("service:"):
115
+ found.append(f"serviço {name}: network_mode {mode} não é permitido")
116
+ if service.get("cap_add"):
117
+ found.append(f"serviço {name}: pede capacidades extras ({', '.join(map(str, service['cap_add']))})")
118
+ if service.get("devices"):
119
+ found.append(f"serviço {name}: acessa dispositivos da máquina")
120
+ return found
121
+
122
+
123
+ def violations(config, root: str) -> list:
124
+ services = _services(config)
125
+ if services is None:
126
+ return ["configuração do compose sem serviços, ou em formato inesperado"]
127
+ found = []
128
+ for name, service in services.items():
129
+ if not isinstance(service, dict):
130
+ found.append(f"serviço {name}: definição em formato inesperado")
131
+ continue
132
+ found += _service(name, service, config, root)
133
+ for kind in ("secrets", "configs"):
134
+ declared = config.get(kind) or {}
135
+ for name, item in (declared.items() if isinstance(declared, dict) else []):
136
+ if not isinstance(item, dict) or item.get("external"):
137
+ found.append(f"{kind} {name}: é externo ao compose ou está em formato inesperado")
138
+ elif item.get("file") and not _inside(str(item["file"]), root):
139
+ found.append(f"{kind} {name}: lê um arquivo de fora do projeto ({item['file']})")
140
+ return found
141
+
142
+
143
+ def summary(config, root: str) -> str:
144
+ services = _services(config) or {}
145
+ base = os.path.realpath(root)
146
+ lines = []
147
+ for name, service in services.items():
148
+ if not isinstance(service, dict):
149
+ continue
150
+ parts = [str(service.get("image") or "build local")]
151
+ ports = [str(p.get("published")) for p in service.get("ports") or [] if isinstance(p, dict) and p.get("published")]
152
+ if ports:
153
+ parts.append("portas " + ", ".join(ports))
154
+ mounts = []
155
+ for volume in service.get("volumes") or []:
156
+ if isinstance(volume, dict) and volume.get("type") == "bind":
157
+ real = os.path.realpath(str(volume.get("source", "")))
158
+ mounts.append(os.path.relpath(real, base) if _inside(real, root) else "FORA DO PROJETO")
159
+ if mounts:
160
+ parts.append("monta " + ", ".join(mounts))
161
+ lines.append(f"{name}: " + " · ".join(parts))
162
+ return "\n".join(lines)
163
+
164
+
165
+ def main() -> int:
166
+ if len(sys.argv) < 2:
167
+ sys.stderr.write("uso: compose_check.py <raiz> [--summary]\n")
168
+ return 1
169
+ try:
170
+ config = json.load(sys.stdin)
171
+ except ValueError:
172
+ sys.stderr.write("compose_check: a configuração do compose não é um JSON válido.\n")
173
+ return 1
174
+ if "--summary" in sys.argv[2:]:
175
+ print(summary(config, sys.argv[1]))
176
+ return 0
177
+ found = violations(config, sys.argv[1])
178
+ for item in found:
179
+ sys.stderr.write(f"ambiente recusado: {item}\n")
180
+ if found:
181
+ sys.stderr.write("O ambiente só sobe com contêineres que enxergam apenas a pasta do projeto.\n")
182
+ return 1 if found else 0
183
+
184
+
185
+ if __name__ == "__main__":
186
+ sys.exit(main())
@@ -0,0 +1,22 @@
1
+ #!/usr/bin/env bash
2
+ # Grava o harness.conf que o agente propôs e o guard acabou de conferir.
3
+ #
4
+ # O agente escreve a proposta em .harness-run/harness.conf e roda `.harness/conf-apply`,
5
+ # sem argumento. O guard confere o formato e guarda a cópia conferida num lugar onde o
6
+ # agente não grava. Este script aplica essa cópia, uma vez. Não há pergunta ao dono: o
7
+ # arquivo é versionado e passa pelos revisores, como o resto da entrega.
8
+ set -uo pipefail
9
+ . "$(dirname "$0")/env-common.sh"
10
+
11
+ APPROVED="$(python3 -I "$HERE/hooks/common.py" conf-approval "$ROOT")" || die "fora de um repositório git."
12
+ [ -f "$APPROVED" ] || die "não há proposta conferida. Escreva .harness-run/harness.conf e rode exatamente: .harness/conf-apply"
13
+
14
+ cp "$APPROVED" "$ROOT/harness.conf.$$.tmp" && mv "$ROOT/harness.conf.$$.tmp" "$ROOT/harness.conf" || die "não consegui gravar o harness.conf."
15
+ rm -f "$APPROVED"
16
+ echo "harness.conf gravado."
17
+
18
+ if [ -n "$(conf_get SERVICES)" ]; then
19
+ "$HERE/worktree-env" || exit $?
20
+ echo "Portas gravadas no .env."
21
+ fi
22
+ echo "Faça o commit do harness.conf."
@@ -0,0 +1,21 @@
1
+ #!/usr/bin/env bash
2
+ # Remove o ambiente da feature deste worktree: contêineres, volumes e imagens locais.
3
+ # Apaga os dados. Nunca roda sobre o ambiente do checkout principal.
4
+ set -uo pipefail
5
+ . "$(dirname "$0")/env-common.sh"
6
+
7
+ cd "$ROOT" || exit 1
8
+ MAIN="$(git worktree list --porcelain | sed -n '1s/^worktree //p')"
9
+ [ "$(cd "$MAIN" && pwd -P)" != "$ROOT" ] || die "este é o checkout principal; o ambiente dele não é removido por aqui."
10
+
11
+ need_compose
12
+ "$HERE/worktree-env" >/dev/null || exit $?
13
+ CONTEXT="$(env_get HARNESS_ENV_CONTEXT)"
14
+ MAIN_CONTEXT="$(sed -n 's/^HARNESS_ENV_CONTEXT=//p' "$MAIN/.env" 2>/dev/null | sed -n 1p)"
15
+ [ -n "$MAIN_CONTEXT" ] || MAIN_CONTEXT="$(basename "$MAIN" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\{1,\}/-/g; s/^-*//; s/-*$//')"
16
+ [ "$CONTEXT" != "$MAIN_CONTEXT" ] || die "este worktree usa o mesmo ambiente do checkout principal ($CONTEXT); não é removido por aqui."
17
+
18
+ "$HERE/down" >/dev/null 2>&1 || true
19
+ compose down -v --rmi local --remove-orphans || die "o Docker não removeu o ambiente."
20
+ rm -f "$(env_record)"
21
+ echo "Ambiente $(env_get COMPOSE_PROJECT_NAME) removido."
@@ -0,0 +1,24 @@
1
+ #!/usr/bin/env bash
2
+ # Roda o app (DEV_CMD do harness.conf) com as portas desta feature.
3
+ # Uso: .harness/dev em primeiro plano
4
+ # .harness/dev --background em segundo plano, com PID e log em .harness-run/
5
+ set -uo pipefail
6
+ . "$(dirname "$0")/env-common.sh"
7
+
8
+ CMD="$(conf_get DEV_CMD)"
9
+ [ -n "$CMD" ] || die "falta DEV_CMD no harness.conf (o comando que roda o app)."
10
+ load_env
11
+ cd "$ROOT" || exit 1
12
+
13
+ if [ "${1:-}" != "--background" ]; then
14
+ exec bash -c "$CMD"
15
+ fi
16
+
17
+ if PID="$(dev_pid)"; then
18
+ die "o app já está rodando em segundo plano (PID $PID). Pare com .harness/down."
19
+ fi
20
+ mkdir -p .harness-run
21
+ [ -f .harness-run/.gitignore ] || echo '*' > .harness-run/.gitignore
22
+ nohup bash -c "$CMD" > .harness-run/dev.log 2>&1 < /dev/null &
23
+ echo $! > .harness-run/dev.pid
24
+ echo "App em segundo plano (PID $(cat .harness-run/dev.pid)). Log em .harness-run/dev.log"
@@ -0,0 +1,20 @@
1
+ #!/usr/bin/env bash
2
+ # Para o app em segundo plano e os contêineres da feature. Mantém os dados.
3
+ set -uo pipefail
4
+ . "$(dirname "$0")/env-common.sh"
5
+
6
+ kill_tree() { # o processo e tudo o que ele iniciou: o app sobe filhos, que seguravam as portas
7
+ local child
8
+ for child in $(pgrep -P "$1" 2>/dev/null); do kill_tree "$child"; done
9
+ kill "$1" 2>/dev/null || true
10
+ }
11
+
12
+ if PID="$(dev_pid)"; then
13
+ kill_tree "$PID"
14
+ echo "App parado (PID $PID)."
15
+ fi
16
+ rm -f "$ROOT/.harness-run/dev.pid"
17
+
18
+ [ -f "$ROOT/.env" ] || { echo "Sem .env neste worktree: não há ambiente para parar."; exit 0; }
19
+ need_compose
20
+ compose stop
@@ -0,0 +1,186 @@
1
+ # Despachar os implementadores
2
+
3
+ ## Antes da primeira rodada
4
+
5
+ **O `harness.conf`** já foi gravado antes de fatiar (`.harness/entrega/tickets.md`).
6
+
7
+ **O ambiente.** Se os testes da entrega precisam de banco ou de outro serviço, suba com
8
+ `.harness/up` e depois `.harness/prepare`. O `up` vai sozinho, sem `&&` nem `;`: só a forma exata
9
+ sai do sandbox. Em projeto novo o compose chega com o ticket de contrato: integre-o primeiro, e
10
+ só então suba o ambiente e despache os demais. Ticket que depende do ambiente não é concluído
11
+ com teste contra um substituto em memória: sem ambiente de verdade ele fica `claimed`. O
12
+ ambiente fica de pé até o envio. Integrado um ticket que muda o schema do banco, rode
13
+ `.harness/prepare` de novo.
14
+
15
+ **A base prova que roda.** Logo depois de integrar o ticket de contrato (e o de fundação, se
16
+ foram separados), e antes de despachar qualquer outro, confira o que os revisores não têm
17
+ como ver, porque rodam antes de o ambiente existir. `up` e `down` vão sozinhos na chamada;
18
+ `prepare` e `dev` rodam dentro do sandbox e não têm essa exigência:
19
+
20
+ 1. `.harness/up`: os serviços sobem.
21
+ 2. `.harness/prepare`: as migrations e o seed rodam.
22
+ 3. `.harness/dev --background`: o aplicativo sobe. Espere e confira que o front e a API
23
+ respondem nos endereços do `.env` (`curl -s -o /dev/null -w "%{http_code}"`); o log fica
24
+ em `.harness-run/dev.log`.
25
+ 4. `.harness/down` encerra o aplicativo que você subiu; depois `.harness/up` de novo, porque
26
+ os implementadores precisam dos serviços.
27
+
28
+ Falhou qualquer um: reabra o ticket dono com o erro como achado. É ajuste de ambiente, e
29
+ não conta como reprovação de revisor no teto de rodadas. Só despache a primeira onda com os
30
+ quatro passos passando.
31
+
32
+ **A tela é exercitada desde a primeira.** Depois de integrar uma onda que tem ticket de tela,
33
+ rode `.harness/validate --profile merge` uma vez: ele compila o aplicativo e roda os testes de
34
+ navegador que já existem. Falhou: rodada de correção para o ticket dono do teste que falhou.
35
+
36
+ **Testes em paralelo.** Os implementadores de uma rodada dividem o ambiente da feature. Se os
37
+ testes usam banco, a spec precisa dizer como cada um isola o seu (um banco de teste por ticket,
38
+ por exemplo). Isso se escreve na spec, antes de despachar: o pedido só leva ponteiros.
39
+
40
+ **O plano.** Monte a tabela das ondas que o grafo dá: quais tickets rodam juntos em cada uma.
41
+ Ela vai no seu relato final, com o que de fato rodou em paralelo.
42
+
43
+ ## A fronteira
44
+
45
+ ```bash
46
+ python3 -I .harness/tickets_check.py docs/specs/<slug> --frontier
47
+ ```
48
+
49
+ A resposta são os tickets abertos cujos bloqueadores já estão concluídos. São esses que
50
+ podem ser feitos agora, em paralelo.
51
+
52
+ ## Uma rodada
53
+
54
+ 1. Pegue da fronteira até `MAX_PARALLEL` tickets. O valor está no `harness.conf`; se não
55
+ estiver, use 3.
56
+ 2. Marque-os como em andamento, com o comando, que também faz o commit:
57
+ `.harness/ticket claim docs/specs/<slug> <NN> <NN>`.
58
+ 3. Dispare todos na mesma mensagem, para rodarem ao mesmo tempo. Para cada ticket, a
59
+ ferramenta de subagente com:
60
+ - o agente: um agente do projeto em `.claude/agents/` cuja descrição cobre a área do
61
+ ticket, se houver; senão `harness:implementador`;
62
+ - `isolation` como `worktree`, para cada um trabalhar na própria cópia, mesmo quando a
63
+ rodada tem um ticket só;
64
+ - o modelo: `haiku`. O ticket de contrato vai em `sonnet`: é ele que define o que todos
65
+ os outros seguem;
66
+ - `run_in_background` como `false`: você espera os implementadores no mesmo turno. Em
67
+ segundo plano o aviso de término iria para a sessão do dono, não para você;
68
+ - o pedido, só com ponteiros:
69
+
70
+ ```pedido harness:implementador
71
+ spec: docs/specs/exemplo/spec.md
72
+ ticket: docs/specs/exemplo/issues/01-nome.md
73
+ leitura: GLOSSARY.md
74
+ ```
75
+
76
+ A linha `leitura` é opcional e só lista arquivos que existem. A spec e o ticket precisam
77
+ estar em commit: o implementador trabalha numa cópia que só tem o que foi commitado.
78
+
79
+ 4. Quando todos voltarem, cada um diz em que branch ficaram os commits. Antes de integrar,
80
+ cada ticket passa pela caça a bugs: dispare um `harness:revisor-bugs` por ticket, todos na
81
+ mesma mensagem, com `run_in_background` como `false`:
82
+
83
+ ```pedido harness:revisor-bugs
84
+ spec: docs/specs/exemplo/spec.md
85
+ ticket: docs/specs/exemplo/issues/01-nome.md
86
+ diff: BASE...HASH_DO_COMMIT
87
+ commit: HASH_DO_COMMIT
88
+ ```
89
+
90
+ **O ticket de contrato tem duas leituras, juntas:** na mesma mensagem do
91
+ `harness:revisor-bugs`, com o modelo `opus`, dispare o `harness:revisor-ambiente`, com as
92
+ mesmas quatro linhas. Um procura defeito de comportamento; o outro, o que só funciona na
93
+ pasta de quem escreveu. O `.harness/integrate` exige os dois nesse commit. Os demais
94
+ tickets passam só pelo `harness:revisor-bugs`, no modelo do agente.
95
+
96
+ **Achado simples não reprova.** O revisor responde `APPROVED` com linhas `PENDENCIA:`, o
97
+ hook as registra e o ticket segue. O teto é de duas pendências abertas por ticket, somando
98
+ as rodadas e os revisores: passou disso, a aprovação não é gravada, mesmo que ele tenha
99
+ escrito `APPROVED`. É rodada de correção, com as pendências como achado. Você não corrige pendência agora nem a discute: elas
100
+ são tratadas no fechamento, e o push é recusado enquanto houver uma aberta
101
+ (`.harness/pendings` lista).
102
+
103
+ `HASH_DO_COMMIT` é a ponta da branch do implementador (`git rev-parse <branch>`), e `BASE` é
104
+ o commit de onde ela saiu (`git merge-base HEAD <branch>`). Reprovou: é rodada de correção
105
+ para aquele ticket, com a resposta como achado, e cada caso apontado entra como teste junto
106
+ com a correção. Os que passaram seguem.
107
+ 5. Junte cada branch aprovada na da feature com
108
+ `.harness/integrate <arquivo do ticket> <branch>`, um ticket por vez. Ele recusa a branch
109
+ que não passou pela caça a bugs naquele commit. O comando
110
+ confere que a branch só mexeu no que o ticket possui, junta, roda a checagem e desfaz a
111
+ junção se ela falhar; no fim apaga os worktrees de agente já integrados. Não junte com
112
+ `git merge` à mão.
113
+ Recusa por posse, conflito ou checagem é uma rodada de correção para aquele ticket: o
114
+ comando diz o motivo. Não resolva conflito à mão: ele mostra que o fatiamento está errado.
115
+ 6. Ticket integrado está `Status: done` e com a checagem passando: o comando garante os dois.
116
+ 7. Peça a fronteira de novo. Repita até ela vir vazia e todo ticket estar concluído.
117
+
118
+ Os worktrees de agente usam o ambiente da feature. Nenhum implementador sobe ambiente. Cada
119
+ um prepara a própria cópia com `.harness/setup-worktree`, que traz o `.env` da feature e
120
+ instala as dependências.
121
+
122
+ **Porta ocupada.** Se a aplicação ou um teste não sobe porque uma porta da feature está em
123
+ uso, rode `.harness/ports-free`, sozinho: ele encerra o processo esquecido por outro agente
124
+ e não toca no que roda da pasta da feature nem nos contêineres. O mesmo comando roda sozinho
125
+ quando um revisor termina.
126
+
127
+ Se um implementador cair sem entregar, o ticket dele fica preso em `claimed` e some da
128
+ fronteira. Reabra-o com `.harness/ticket reopen` e despache de novo.
129
+
130
+ ## Quando o implementador diz que falta algo
131
+
132
+ É uma lacuna da spec ou do ticket. Corrija o documento, faça o commit, reabra o ticket com
133
+ `.harness/ticket reopen` e despache de novo. Não responda a lacuna no pedido.
134
+
135
+ Se o que falta é algo comum (um tipo, um utilitário, uma dependência), ele pertence ao ticket
136
+ de contrato: acrescente o item a esse ticket, reabra-o com
137
+ `.harness/ticket reopen docs/specs/<slug> <NN> "<o que falta>"`, despache-o, integre, e só
138
+ então reabra o ticket que relatou a falta.
139
+
140
+ ## Rodada de correção
141
+
142
+ Quando a checagem ou um revisor reprova:
143
+
144
+ 1. Grave o achado, como veio, em `docs/specs/<slug>/achados/<NN>-rodada-<n>.md` e faça o
145
+ commit. O arquivo precisa estar versionado para o implementador enxergá-lo no worktree dele.
146
+ 2. Reabra o ticket afetado, com `.harness/ticket reopen docs/specs/<slug> <NN> "<motivo>"`,
147
+ e despache-o de novo, com o achado apontado. O implementador começa de uma cópia nova da feature: se a rodada veio de
148
+ uma recusa do `.harness/integrate`, o trabalho anterior não está nela, então diga no achado
149
+ o nome da branch recusada, para ele trazer o que serve com `git merge <branch>`; no conflito
150
+ do arquivo do ticket, vale `Status: open`. Integrado
151
+ o ticket refeito, jogue fora a branch recusada: `.harness/agents-clean --discard <branch>`.
152
+
153
+ ```pedido harness:implementador
154
+ spec: docs/specs/exemplo/spec.md
155
+ ticket: docs/specs/exemplo/issues/01-nome.md
156
+ achado: docs/specs/exemplo/achados/01-rodada-1.md
157
+ ```
158
+
159
+ 3. Quando ele voltar, o revisor que reprovou recebe o mesmo arquivo de achado, para conferir
160
+ a correção e não reler o ticket inteiro:
161
+
162
+ ```pedido harness:revisor-bugs
163
+ spec: docs/specs/exemplo/spec.md
164
+ ticket: docs/specs/exemplo/issues/01-nome.md
165
+ diff: BASE...HASH_DO_COMMIT
166
+ commit: HASH_DO_COMMIT
167
+ achado: docs/specs/exemplo/achados/01-rodada-1.md
168
+ ```
169
+
170
+ No ticket de contrato, o commit novo pede as duas leituras de novo: quem reprovou vai com
171
+ `achado:`; quem tinha aprovado vai com `achado:` também, para conferir só o que a correção tocou.
172
+
173
+ 4. Junte o resultado e volte ao fechamento.
174
+
175
+ **A posse não muda calada.** Se um ticket precisar de um caminho que não possuía, corrija o
176
+ `Owns:` antes de integrar e registre na spec, em "Decisões tomadas sem o dono", o que mudou e
177
+ por quê. Você não faz commit de código: o que não é documento entra por um ticket.
178
+
179
+ **O que você corrige sem despachar ninguém,** porque não é de nenhum ticket: a spec, o
180
+ glossário, os tickets e o `harness.conf` (por `.harness/conf-apply`). Tipo de commit errado
181
+ apontado pelo revisor não se conserta com commit novo: devolva o relato, é decisão do dono.
182
+
183
+ Conte as rodadas **por ticket**. A rodada de correção de um ticket vai em `sonnet`; reprovado
184
+ duas vezes, em `opus`. Cada ticket tem limite de 3 rodadas de correção: na quarta do mesmo
185
+ ticket, pare e devolva o relato do que travou. Só reprovação conta rodada, e só achado severo
186
+ reprova; os outros tickets continuam andando enquanto um está em correção.
@@ -0,0 +1,179 @@
1
+ # Checar, revisar e enviar
2
+
3
+ A ordem importa: primeiro o que é de graça, depois o que custa.
4
+
5
+ ## 1. Ambiente de pé
6
+
7
+ O ambiente da feature (banco, fila, contêiner do navegador) já está de pé desde o despacho e
8
+ fica assim até o envio. Confira com `.harness/up`, sozinho: se já está no ar, ele só avisa.
9
+ Depois de integrar um ticket que mudou o schema, rode `.harness/prepare` de novo.
10
+
11
+ Você não sobe o aplicativo à mão antes do envio. Os testes de ponta a ponta compilam e sobem
12
+ o aplicativo do commit atual por conta própria (o `webServer` do Playwright), e o derrubam ao
13
+ terminar. Se o aplicativo ficou de pé de uma execução anterior, ele ocupa as portas de que os
14
+ testes precisam: rode `.harness/down` e depois `.harness/up`.
15
+
16
+ ## 2. Checagem
17
+
18
+ ```bash
19
+ .harness/validate --profile merge
20
+ ```
21
+
22
+ É a checagem completa: testes de unidade e de integração, fronteiras, build e ponta a ponta.
23
+ Falhou por defeito do código: é uma rodada de correção (`.harness/entrega/despacho.md`), com a
24
+ saída como achado. Falhou porque o ambiente não respondeu: conserte o ambiente e rode de novo;
25
+ isso não é rodada de correção. Revisor só roda sobre código que passou aqui.
26
+
27
+ ## 3. Pendências
28
+
29
+ ```bash
30
+ .harness/pendings
31
+ ```
32
+
33
+ São os achados simples que o caçador de bugs deixou abertos para os tickets passarem. Se a
34
+ lista veio vazia, siga. Senão, cada pendência é corrigida agora, com o teste que ela indica:
35
+ grave a lista em `docs/specs/<slug>/achados/pendencias.md`, faça o commit, e despache um
36
+ `harness:implementador` por ticket dono dos arquivos apontados, com esse arquivo como `achado:`
37
+ (reabra o ticket com `.harness/ticket reopen`). Integre como qualquer rodada de correção e
38
+ volte ao passo 2. Quem fecha a pendência é o caçador de bugs, no passe final abaixo: você não
39
+ tem como fechá-la.
40
+
41
+ ## 4. Revisão
42
+
43
+ Daqui em diante não se faz mais commit: cada commit novo invalida a revisão. Pegue o
44
+ commit do topo e a base da branch:
45
+
46
+ ```bash
47
+ git rev-parse HEAD
48
+ python3 -I .harness/hooks/common.py branch-base "$(git rev-parse HEAD)"
49
+ ```
50
+
51
+ O pedido aos dois revisores é o mesmo. O intervalo cobre a branch inteira, da base
52
+ ao topo:
53
+
54
+ ```pedido harness:seguranca
55
+ diff: BASE...HEAD
56
+ commit: HASH_DO_COMMIT
57
+ ```
58
+
59
+ ```pedido harness:revisor
60
+ diff: BASE...HEAD
61
+ commit: HASH_DO_COMMIT
62
+ spec: docs/specs/exemplo/spec.md
63
+ leitura: GLOSSARY.md
64
+ ```
65
+
66
+ No lugar de `BASE` e de `HASH_DO_COMMIT` vão os dois hashes que você acabou de obter. A
67
+ linha `leitura` é opcional e só lista arquivos que existem. Sem spec, como numa correção de
68
+ bug, o pedido ao `revisor` vai sem a linha `spec:`.
69
+
70
+ Junto com os dois revisores, dispare o portão de qualidade, que roda a checagem completa do
71
+ projeto naquele commit, com o ambiente de pé:
72
+
73
+ ```pedido harness:qualidade
74
+ commit: HASH_DO_COMMIT
75
+ ```
76
+
77
+ E a caça a bugs final, sobre a branch inteira, que procura o que só aparece olhando os módulos
78
+ juntos e confere cada pendência aberta (responde `RESOLVIDA: <id>` para as que foram corrigidas). O pedido é o dos revisores, sem a linha `ticket:`:
79
+
80
+ ```pedido harness:revisor-bugs
81
+ spec: docs/specs/exemplo/spec.md
82
+ diff: BASE...HASH_DO_COMMIT
83
+ commit: HASH_DO_COMMIT
84
+ ```
85
+
86
+ Dispare os quatro na mesma mensagem, com `run_in_background` como `false`, e espere todos
87
+ voltarem. O push exige os quatro vereditos sobre o mesmo commit.
88
+
89
+ Cada revisor termina com `VEREDITO: APPROVED` ou `VEREDITO: REJECTED`. A aprovação é
90
+ gravada por um hook a partir dessa resposta. Você não grava aprovação e não tem como.
91
+
92
+ - **Um revisor reprovou:** é uma rodada de correção, com a resposta dele como achado. Depois
93
+ dela, volte ao passo 2: commit novo pede os quatro vereditos de novo.
94
+ - **A qualidade reprovou:** leia o resumo. Se foi o ambiente que não respondeu, conserte-o e
95
+ dispare só a qualidade de novo. Se foi teste ou build, é rodada de correção.
96
+ - **O caçador de bugs reprovou:** é rodada de correção para os tickets donos dos arquivos
97
+ apontados; cada caso entra como teste junto com a correção.
98
+ - **Os quatro aprovaram:** rode `.harness/pendings`. Vazio: siga. Se sobrou pendência, ela
99
+ não foi corrigida: volte ao passo 3.
100
+
101
+ ## 5. Enviar
102
+
103
+ ```bash
104
+ .harness/push
105
+ ```
106
+
107
+ **Projeto sem remoto.** O comando confere os quatro portões do mesmo jeito e termina dizendo
108
+ que a branch está aprovada e que nada foi enviado. É um fim válido: pule o passo 6 (não há
109
+ pull request), faça o passo 7 e diga ao dono, no relato, o que falta para publicar.
110
+
111
+ É o único caminho até o remoto. Se ele negar, leia o motivo: aprovação faltando para o
112
+ commit atual quer dizer que houve commit depois da revisão, ou que um revisor não fechou
113
+ a resposta no formato: dispare de novo o que faltou. Se o motivo for a branch padrão
114
+ do remoto ter andado, rode `.harness/fetch` e envie de novo; as aprovações continuam
115
+ valendo. Não há como contornar o portão.
116
+
117
+ ## 6. Pull request
118
+
119
+ Escreva o corpo em português, sem assinatura de IA, com a skill `write-pr-description` se
120
+ ela estiver instalada, neste padrão. `.harness/pr` recusa o corpo sem a abertura e sem as
121
+ duas seções marcadas com obrigatória:
122
+
123
+ ```markdown
124
+ <uma a três frases: o que a entrega faz e por quê; quem lê só isto sabe se é o revisor certo>
125
+
126
+ ## Critérios de aceite (obrigatória)
127
+
128
+ | Critério da spec | Teste que o cobre |
129
+ |---|---|
130
+ | <critério, como está na spec> | <arquivo do teste e nome do caso> |
131
+
132
+ ## O que mudou
133
+
134
+ <por módulo; decisão que tinha alternativa real, e por que a alternativa perdeu>
135
+
136
+ ## Validação (obrigatória)
137
+
138
+ <os quatro vereditos com o commit, e a linha final de `.harness/validate --profile merge`>
139
+
140
+ ## Riscos e pendências
141
+
142
+ <o que pode quebrar fora dos arquivos tocados; o que ficou de fora; "nenhum" se for o caso>
143
+ ```
144
+
145
+ Critério sem teste que o cubra não entra na tabela como coberto: escreva "sem teste" e
146
+ explique em Riscos e pendências. O arquivo do corpo não entra em commit:
147
+
148
+ ```bash
149
+ mkdir -p .harness-run && { [ -f .harness-run/.gitignore ] || echo '*' > .harness-run/.gitignore; }
150
+ ```
151
+
152
+ Grave o corpo em `.harness-run/pr-body.md` e abra o pull request:
153
+
154
+ ```bash
155
+ .harness/pr create "<título>" .harness-run/pr-body.md
156
+ ```
157
+
158
+ O título segue o formato dos commits e carrega o tipo mais alto da mudança: `feat` manda
159
+ sobre `fix`. Use só letras, números, espaço e pontuação simples: `&`, `$`, crase, `<`, `>`,
160
+ `;` e `|` fazem o comando ser negado. Os commits são preservados no merge, sem squash.
161
+
162
+ ## 7. Deixar o aplicativo de pé e dizer onde
163
+
164
+ A entrega só termina quando o dono consegue ver o resultado, sem ter de montar nada. Depois
165
+ do envio (`up` sozinho na chamada):
166
+
167
+ 1. `.harness/up` e `.harness/prepare`: o ambiente está de pé e o banco, pronto.
168
+ 2. `.harness/dev --background`: o aplicativo sobe.
169
+ 3. Confira que ele responde: o front e a API nos endereços do `.env` desta feature
170
+ (`curl -s -o /dev/null -w "%{http_code}"`). Se uma porta estiver ocupada, `.harness/ports-free`.
171
+
172
+ No relato final, logo depois do link do pull request:
173
+
174
+ - o endereço do aplicativo, e o da caixa de e-mail de teste se houver;
175
+ - o usuário e a senha de teste, se o sistema tem login;
176
+ - como parar: `.harness/down`.
177
+
178
+ Se o aplicativo não respondeu, diga isso com a última linha de `.harness-run/dev.log`, em vez
179
+ do endereço. Não diga que está de pé sem ter conferido.