@orchestrator-claude/definitions 3.36.0 → 3.37.1
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.
- package/agents/adversarial-reviewer.md +6 -1
- package/agents/api-extractor.md +6 -0
- package/agents/azure-devops-engineer.md +1 -2
- package/agents/business-rule-miner.md +6 -0
- package/agents/cicd-platform-engineer.md +1 -2
- package/agents/ciclo-engineer.md +15 -2
- package/agents/code-archaeologist.md +6 -0
- package/agents/debug-sidecar.md +6 -0
- package/agents/doc-sidecar.md +6 -0
- package/agents/docs-guardian.md +9 -3
- package/agents/frontend-engineer.md +1 -2
- package/agents/{ai-architect.md → harness-architect.md} +26 -5
- package/agents/implementer.md +6 -1
- package/agents/legacy-discoverer.md +6 -0
- package/agents/legacy-synthesizer.md +6 -0
- package/agents/methodology-researcher.md +6 -1
- package/agents/operational-artifact-builder.md +6 -1
- package/agents/orchestrator.md +27 -87
- package/agents/planner.md +6 -1
- package/agents/presentation-engineer.md +5 -4
- package/agents/python-data-engineer.md +0 -1
- package/agents/researcher.md +6 -0
- package/agents/reviewer.md +6 -1
- package/agents/schema-extractor.md +6 -0
- package/agents/software-architect.md +30 -7
- package/agents/specifier.md +6 -1
- package/agents/task-generator.md +6 -1
- package/agents/test-sidecar.md +6 -0
- package/dist/scripts/generate-hooks-matcher.d.ts +106 -0
- package/dist/scripts/generate-hooks-matcher.d.ts.map +1 -0
- package/dist/scripts/generate-hooks-matcher.js +153 -0
- package/dist/scripts/generate-hooks-matcher.js.map +1 -0
- package/dist/scripts/generate-manifest.d.ts +22 -0
- package/dist/scripts/generate-manifest.d.ts.map +1 -1
- package/dist/scripts/generate-manifest.js +67 -2
- package/dist/scripts/generate-manifest.js.map +1 -1
- package/hooks/agent-git-guard.mjs +63 -11
- package/hooks/dangling-guard.mjs +42 -12
- package/hooks/gate-guardian.mjs +38 -8
- package/hooks/hooks.json +3 -9
- package/hooks/lib/api-client.ts +128 -9
- package/hooks/lib/capability-scanner.ts +391 -55
- package/hooks/lib/dispatch-marker.ts +214 -0
- package/hooks/lib/git-checkpoint.ts +34 -37
- package/hooks/lib/observations-helper.ts +14 -1
- package/hooks/mailbox-listener.mjs +69 -17
- package/hooks/playwright-output-guard.mjs +40 -10
- package/hooks/post-implement.mjs +38 -8
- package/hooks/pre-agent-dispatch.mjs +137 -16
- package/hooks/pre-agent-dispatch.ts +82 -15
- package/hooks/session-start.mjs +274 -103
- package/hooks/session-start.ts +250 -69
- package/hooks/subagent-start.mjs +7665 -22
- package/hooks/subagent-start.ts +367 -16
- package/hooks/subagent-stop.mjs +102 -62
- package/hooks/subagent-stop.ts +124 -28
- package/hooks/user-prompt.mjs +43 -13
- package/hooks/verification-before-completion.mjs +63 -11
- package/hooks/workflow-guard.mjs +45 -11
- package/hooks-settings-template.json +1 -7
- package/manifest.json +62 -62
- package/package.json +4 -2
- package/skills/checkpoint-protocol/SKILL.md +19 -4
- package/skills/ciclo-lane-dispatch/SKILL.md +24 -0
- package/skills/fase-1b-projecao/SKILL.md +146 -0
- package/skills/orchestrator/SKILL.md +11 -3
- package/skills/workflow-coordination/SKILL.md +3 -3
- package/hooks/post-compact.mjs +0 -7931
- package/hooks/post-compact.ts +0 -170
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@orchestrator-claude/definitions",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.37.1",
|
|
4
4
|
"description": "Built-in definitions (agents, skills, hooks, workflows, KB seeds) for the Orchestrator ecosystem",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -29,8 +29,9 @@
|
|
|
29
29
|
"hooks-settings-template.json"
|
|
30
30
|
],
|
|
31
31
|
"scripts": {
|
|
32
|
-
"build": "tsc && npm run bundle-hooks && npm run generate-manifest",
|
|
32
|
+
"build": "tsc && npm run bundle-hooks && npm run generate-hooks-matcher && npm run generate-manifest",
|
|
33
33
|
"bundle-hooks": "npx tsx src/scripts/bundle-hooks.ts",
|
|
34
|
+
"generate-hooks-matcher": "npx tsx src/scripts/generate-hooks-matcher.ts",
|
|
34
35
|
"generate-manifest": "npx tsx src/scripts/generate-manifest.ts",
|
|
35
36
|
"test": "vitest run",
|
|
36
37
|
"test:watch": "vitest",
|
|
@@ -40,6 +41,7 @@
|
|
|
40
41
|
},
|
|
41
42
|
"dependencies": {
|
|
42
43
|
"@orchestrator-claude/mcp-server": "^3.32.2",
|
|
44
|
+
"@orchestrator-claude/project-root-resolver": "*",
|
|
43
45
|
"commander": "^14.0.0",
|
|
44
46
|
"chalk": "^5.4.0"
|
|
45
47
|
},
|
|
@@ -6,10 +6,16 @@ description: When and how to create workflow checkpoints. Use after completing t
|
|
|
6
6
|
## Checkpoint Creation Protocol
|
|
7
7
|
|
|
8
8
|
### Who follows this (TD-171)
|
|
9
|
-
This protocol applies to the `implementer` **and all engineer-type committing agents** — any agent whose tool list holds `mcp__orchestrator-tools__createCheckpoint`: as of S290 that is `implementer`, `azure-devops-engineer`, `presentation-engineer`, `operational-artifact-builder`, `cicd-platform-engineer`, `python-data-engineer`, `frontend-engineer`. Engineer-types commit critical artifacts **outside `src/`** (IaC, pipelines, ETL, decks), so they need per-change git revertability too — "only `src/` commits matter" is wrong.
|
|
9
|
+
This protocol applies to the `implementer` **and all engineer-type committing agents** — any agent whose tool list holds `mcp__orchestrator-tools__createCheckpoint`: as of S290 that is `implementer`, `azure-devops-engineer`, `presentation-engineer`, `operational-artifact-builder`, `cicd-platform-engineer`, `python-data-engineer`, `frontend-engineer`. Engineer-types commit critical artifacts **outside `src/`** (IaC, pipelines, ETL, decks), so they need per-change git revertability too — "only `src/` commits matter" is wrong. **That revertability comes from their own local commits, not from `createCheckpoint`** (see "Checkpoint vs git" below — corrected S444).
|
|
10
10
|
|
|
11
11
|
### Checkpoint vs git (read first)
|
|
12
|
-
|
|
12
|
+
|
|
13
|
+
> **CORRECTED S444 (TD-257).** This section previously read *"`createCheckpoint` is a PostgreSQL state snapshot (RFC-012), **INDEPENDENT of git**"*. **That was false, and it was measured false**, not argued: this repo carries **6 tags `orchestrator/*`**, each pointing at a real commit whose subject is `[orchestrator] <phase>: <the description a sub-agent typed>`. Calling the tool writes to git.
|
|
14
|
+
|
|
15
|
+
- `createCheckpoint` **does touch git**: `CheckpointManager.create()` → `GitOperations.createCheckpointCommit()` makes a **real commit**, and `createCheckpointTag()` makes a **real tag** `orchestrator/<phase>/<ISO-timestamp>`. The commit message is `[orchestrator] <phase>: <your description>` — **the text you pass becomes a permanent git commit message**. Write it as if a human will read it in `git log` in a year, because they will.
|
|
16
|
+
- You still do **not** need to commit before calling it — it commits what is already staged (it is not passed a file list, so it does not stage anything itself).
|
|
17
|
+
- **It cannot restore anything, and nothing else can either.** Measured S444: `CheckpointManager.restore()` has no production caller, no REST route (`rg "restore" src/presentation/api/` → 0), reads a `commitHash` that the repository writes hardcoded as `''` (`RepositoryFactory.ts:165`), and ends in `throw new Error('Checkpoint revert not implemented for PostgreSQL')`. Four independent breaks. Treat a checkpoint as an **audit marker**, never as a safety net you can fall back on.
|
|
18
|
+
- **Your real revertability is ordinary git** — the local commits described below, on the feature branch the orchestrator prepared. Not the checkpoint.
|
|
13
19
|
- **Local commit YES, push NO (TD-171):** you MAY make local git commits for granular revertability, on the **feature branch the orchestrator prepared before dispatching you** (branch-before-dispatch, `/orchestrator` §2c.0). You MUST NEVER `git push` / `git merge` / `gh pr merge` — push/merge is orchestrator-owned (enforced by `agent-git-guard`, TD-169). Return your work in your report; the orchestrator pushes after its independent assert.
|
|
14
20
|
|
|
15
21
|
### When to Create
|
|
@@ -28,7 +34,16 @@ This protocol applies to the `implementer` **and all engineer-type committing ag
|
|
|
28
34
|
- "Tasks T-001 to T-005: auth controller + tests"
|
|
29
35
|
- "Pre-refactor checkpoint: before DI migration"
|
|
30
36
|
|
|
31
|
-
### Recovery
|
|
32
|
-
|
|
37
|
+
### Recovery — read the limit before you rely on it
|
|
38
|
+
|
|
39
|
+
`listCheckpoints` is **display only**. Measured S444: its handler does exactly `JSON.stringify(result, null, 2)` into an MCP text block (`packages/mcp-server/src/handlers/checkpoints-handlers.ts:55-66`) — zero side effects, no restore. There is **no recovery path in this system**; see "Checkpoint vs git" above.
|
|
40
|
+
|
|
41
|
+
To *inspect* what was checkpointed:
|
|
33
42
|
1. Call ToolSearch("select:mcp__orchestrator-tools__listCheckpoints")
|
|
34
43
|
2. Call listCheckpoints with: { workflowId }
|
|
44
|
+
|
|
45
|
+
Two things to expect, both measured S444 and neither yet fixed — do not read an empty list as "nothing happened":
|
|
46
|
+
- `GET /api/v1/checkpoints` for this project returned `[]` (HTTP 200, with a positive control returning 200 + real data on the same token), while 6 `orchestrator/*` tags exist in git. **The git side and the database side disagree**, and the database side is the one that is empty.
|
|
47
|
+
- The rows that do get written carry `commit_sha = ''` (`RepositoryFactory.ts:165`), so even a populated list would not point at a recoverable commit.
|
|
48
|
+
|
|
49
|
+
**To actually recover work, use git directly** (`git log`, `git reflog`, `git show`) against your own local commits.
|
|
@@ -41,6 +41,27 @@ system · repo-alvo · escopo (quais US) · ator-alvo. O **ator sai do PRD com l
|
|
|
41
41
|
memória. `[M]` Na S420 cinco das seis correções ao orquestrador foram da mesma família: afirmação
|
|
42
42
|
sobre artefato externo sem probe — o Invariante 6 escrito e não aplicado.
|
|
43
43
|
|
|
44
|
+
**1.3.1 O `escopo` tem procedência, e ela viaja no prompt — não na tua cabeça.** `[M]` (S475) O
|
|
45
|
+
insumo *quais US* não é servido pelo PRD: é servido pela **projeção** (a fase 1b da lane 1). Uma
|
|
46
|
+
projeção só vale se for re-derivável, e o contrato da lane 1 exige três itens juntos no registro
|
|
47
|
+
dela — commit, `sha256` da fonte e o pedido literal (`J4`, §5 do contrato). Antes de despachar:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
# 1. o sha256 que a projecao DECLARA ter derivado (Anexo A.1 dela)
|
|
51
|
+
grep -A1 'sha256.*fonte' <projecao>
|
|
52
|
+
# 2. o sha256 do PRD hoje
|
|
53
|
+
sha256sum <prd>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Se **não** baterem, **não despache**: mande re-derivar (é trabalho de fase 1b, não de lane 2) —
|
|
57
|
+
e re-derivar, nunca editar à mão, porque editar produz documento sincronizado e destrói a chance
|
|
58
|
+
de rodar o teste de derivabilidade. `[M]` Uma projeção desta casa ficou 330 linhas atrás da fonte
|
|
59
|
+
e nada no despacho dizia isso; o modo de falha está medido e é o pior tipo: **não falha limpo,
|
|
60
|
+
preenche** (cláusula *Marca `client` proibida sem registro*, no §2 abaixo, e S469:100).
|
|
61
|
+
|
|
62
|
+
> Referência por conteúdo e não por número de linha, de propósito: esta própria inserção deslocou
|
|
63
|
+
> em +21 as linhas que a versão anterior citava como `:57-59`.
|
|
64
|
+
|
|
44
65
|
**1.4 Se for run de medição, retire a referência E prove que ela não cobre o alvo.** `[M]` (S420)
|
|
45
66
|
Antes de escrever o prompt, `grep -c` no artefato de referência pelo escopo pretendido. Se ele já
|
|
46
67
|
cobre o alvo, o run mede cópia, não transferência. Quando a referência cobre todo o espaço de
|
|
@@ -57,6 +78,9 @@ Entregue os cinco insumos e mais estas cláusulas:
|
|
|
57
78
|
- **Marca `client` proibida sem registro.** Se tu não passar a conversa do cliente, a marca não
|
|
58
79
|
existe para o agente e o fato vira lacuna. Sem isso ele marca `client` "porque faz sentido", que é
|
|
59
80
|
palpite com crachá.
|
|
81
|
+
- **Procedência do escopo, em três campos.** Passe o **caminho da projeção**, o **`sha256` que ela
|
|
82
|
+
declara** e o **caminho do PRD**. Sem os três o agente não tem como conferir vintage, e a Fase 0
|
|
83
|
+
dele manda parar e devolver — corretamente, porque insumo sem procedência é palpite com crachá.
|
|
60
84
|
- **Segure o commit** (§14.6, publicar-antes-de-corrigir): o agente grava e **não** commita; tu
|
|
61
85
|
commita depois de ler o relatório.
|
|
62
86
|
- **Cláusula de escape.** `[M]` (S420) *"Se o protocolo te obrigar a abrir o arquivo vedado, não
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fase-1b-projecao
|
|
3
|
+
description: Use ANTES de derivar um PRD em épicos e user stories — a fase 1b da lane 1, que produz o insumo `escopo (quais US)` que a lane 2A consome. Triggers on "derivar o PRD em épicos", "quebrar o PRD em user stories", "re-derivar a projeção", "o par PRD/projeção está dessincronizado", "fechar J4". Carrega o procedimento de re-derivação, o pedido literal canônico, o isolamento que torna o teste de derivabilidade possível, e — o essencial — o que esta fase NÃO pode prometer. Do NOT use para escrever o PRD (isso é autoria, não tem procedimento) nem para despachar a lane 2A (use ciclo-lane-dispatch).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Fase 1b — a projeção do PRD em épicos e user stories
|
|
7
|
+
|
|
8
|
+
A lane 1 entrega um **par**: o PRD constitucional e a **projeção** dele. Esta skill cobre a
|
|
9
|
+
segunda peça. `[U]` Ela é **fase da lane 1**, não lane nova — o contrato de saída já a contratou
|
|
10
|
+
em `J1` (decomposição rastreável, cada item com referente citado) e `J2` (critério de aceite por
|
|
11
|
+
item), cita o documento, mede os itens e carrega o `sha256` dele.
|
|
12
|
+
|
|
13
|
+
Marcas: `[M]` medido · `[S]` síntese nossa · `[U]` decidido pelo usuário · `[L]` lacuna aberta.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 1 · O que esta fase NÃO promete — leia antes de tudo
|
|
18
|
+
|
|
19
|
+
`[M]` **Granularidade não é propriedade do PRD.** Medido na S475 com réplica exata — mesma fonte,
|
|
20
|
+
mesmo pedido, mesma árvore, **zero variáveis**: 55 stories numa execução e **78** na outra, +42%.
|
|
21
|
+
Quatro derivações do mesmo PRD deram **33 · 66 · 55 · 78** stories e **8 · 12 · 11 · 15** épicos.
|
|
22
|
+
|
|
23
|
+
Consequências operacionais, e nenhuma se conserta melhorando o prompt:
|
|
24
|
+
|
|
25
|
+
1. **Não prometa um número.** Se alguém a jusante precisa de granularidade fixa, ela vem de um
|
|
26
|
+
**corte humano**, não de re-derivar até sair o número desejado — re-derivar até gostar do
|
|
27
|
+
resultado é escolher a amostra depois de ver os dados.
|
|
28
|
+
2. **Divergência de contagem entre duas projeções não é sinal de nada.** Está dentro do ruído.
|
|
29
|
+
3. **O que É estável** (medido em 3 de 3 braços independentes): o **ator** sai como posição do
|
|
30
|
+
fluxo e nunca como cargo · a **espinha** cai das capacidades que o próprio PRD enumera · a
|
|
31
|
+
**cobertura** por referente `§x.y`.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 2 · O procedimento — quatro passos, e o passo 4 é o que quase ninguém roda
|
|
36
|
+
|
|
37
|
+
1. **Fixe a fonte antes de derivar.** `git rev-parse HEAD` e `sha256sum` do PRD; registre os dois.
|
|
38
|
+
Fonte não fixada torna a comparação seguinte impossível de interpretar.
|
|
39
|
+
2. **Derive, guardando o pedido literal.** Escreva o pedido **antes** do despacho e congele-o.
|
|
40
|
+
`[M]` É assim que o item se perde: quem deriva primeiro e pensa em guardar depois não guarda.
|
|
41
|
+
3. **Compare com a versão anterior.** Divergência é **sinal, não estado**.
|
|
42
|
+
4. **Decida de que lado o documento cai.** Se a derivação não for reproduzível a partir da mesma
|
|
43
|
+
fonte, ele não é projeção — é fonte autoral, e passa a exigir **backup** como defesa em vez de
|
|
44
|
+
reconstrução.
|
|
45
|
+
|
|
46
|
+
> `[M]` **O passo 4 é executável mais vezes do que parece.** Se a versão anterior declara o
|
|
47
|
+
> `sha256` da fonte de que derivou, **a fonte velha está em git**: `git show <commit>:<PRD>` a
|
|
48
|
+
> devolve byte a byte. Não presuma que só resta a fonte de hoje — o controle do experimento
|
|
49
|
+
> costuma já existir.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## 3 · O pedido literal — e o que **não** pode entrar nele
|
|
54
|
+
|
|
55
|
+
O pedido é curto de propósito. Fixe **forma**, nunca **conteúdo**:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
Transforme o PRD em épicos e user stories.
|
|
59
|
+
|
|
60
|
+
Fonte única: <PRD>. Não consulte nenhum outro documento deste repositório e não procure
|
|
61
|
+
decomposições anteriores; se encontrar uma, não a abra.
|
|
62
|
+
|
|
63
|
+
Escreva a saída em <SAIDA>, markdown único, com esta estrutura:
|
|
64
|
+
|
|
65
|
+
- épico: heading `## EP-NN — <título>`
|
|
66
|
+
- story: heading `### US-NN.N — <título>`, aninhada no épico a que pertence
|
|
67
|
+
- cada story traz: a formulação "como … / quero … / para …", o critério de aceite, e o
|
|
68
|
+
referente `§x.y` da seção do PRD de onde ela cai
|
|
69
|
+
|
|
70
|
+
Quantos épicos e quantas stories saem é resultado, não meta.
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`[S]` **O que fica de fora, e é a decisão que faz o teste valer.** Regras de conteúdo que a
|
|
74
|
+
projeção anterior declarava — *ator é posição e não cargo*, *nenhuma story nomeia mecanismo*,
|
|
75
|
+
*nada por inferência* — **não entram**, mesmo citando o PRD. Se estão mesmo na fonte, o derivador
|
|
76
|
+
chega nelas sozinho, e chegar **é** a evidência de derivabilidade. Colocá-las no pedido faz o
|
|
77
|
+
passo 4 medir obediência ao pedido em vez de derivabilidade da fonte: verde por vacuidade.
|
|
78
|
+
|
|
79
|
+
`[M]` Funciona: com o pedido acima, três braços independentes produziram **zero** cargos e
|
|
80
|
+
nomearam a espinha correta sem instrução.
|
|
81
|
+
|
|
82
|
+
`[L]` **Contaminação residual, declarada:** fixar os headings `## EP-NN` / `### US-NN.N` já
|
|
83
|
+
entrega parte da forma escolhida pela versão anterior. Mantida porque é o que os comandos do
|
|
84
|
+
contrato medem; não há como remover sem perder a comparabilidade.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 4 · Executor e isolamento
|
|
89
|
+
|
|
90
|
+
**Executor: `general-purpose`.** `[S]` Não use `specifier` nem `task-generator` — os dois têm
|
|
91
|
+
formato de saída próprio no corpo (spec, tasks atômicas) que empurra a derivação para um molde
|
|
92
|
+
que não é do PRD, contaminando o eixo que se quer medir. Agente **sem** corpo calibrado é a
|
|
93
|
+
escolha certa aqui, e é a razão de esta fase ser skill e não agente.
|
|
94
|
+
|
|
95
|
+
**Isolamento por construção, não por instrução.** `[M]` Instruir "não olhe a projeção anterior"
|
|
96
|
+
depende do agente obedecer. Derivar numa **worktree de um commit anterior à promoção** dela não
|
|
97
|
+
depende de nada: o arquivo não existe lá.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
git worktree add --detach <tmp>/wt b4b1eba4 # commit anterior a promocao
|
|
101
|
+
git show HEAD:<PRD> > <tmp>/wt/<PRD> # so a fonte e trocada
|
|
102
|
+
git grep -l 'EP-0[1-9]\|US-0[1-9]\.' b4b1eba4 -- ':!*agent-memory*' # esperado: vazio
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
O último comando é o que transforma "isolado" em **medido**. Rode-o e cole a saída.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## 5 · O que medir na volta — e o instrumento certo
|
|
110
|
+
|
|
111
|
+
Use os comandos que o contrato registra, nunca os inventados na hora:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
grep -cE '^## EP-' <projecao> # epicos
|
|
115
|
+
grep -cE '^### US-' <projecao> # stories
|
|
116
|
+
grep -oE '§[0-9]+(\.[0-9]+)*' <projecao> | sort -u # cobertura por referente
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
> `[M]` **Para medir se o delta da fonte atravessou, olhe o ITEM que a emenda tocou — nunca o
|
|
120
|
+
> agregado.** Medido S475: contagem e sobreposição de referentes não distinguem troca de fonte de
|
|
121
|
+
> ruído (réplica pura dá 95%/88%; trocar a fonte dá 85–91% — dentro do ruído). O mesmo delta
|
|
122
|
+
> aparece **limpo e reprodutível** no item específico: a seção emendada saiu como *item aberto* na
|
|
123
|
+
> fonte velha e como *requisito* nas **duas** réplicas da fonte nova. O agregado afoga o sinal.
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## 6 · Fechar `J4` — três itens, juntos
|
|
128
|
+
|
|
129
|
+
> Uma projeção só é projeção se vier com o que a torna re-derivável: **commit** da fonte,
|
|
130
|
+
> **`sha256`** da fonte, e o **pedido literal**. Faltando qualquer um, o artefato não é projeção —
|
|
131
|
+
> é **segunda fonte**, e passa a exigir backup porque não há de onde reconstruir.
|
|
132
|
+
|
|
133
|
+
`[M]` O item que se perde é sempre o terceiro. Escreva o pedido antes do despacho e o dispatch
|
|
134
|
+
**vira** o registro; guardá-lo depois depende de lembrar, e a primeira execução desta fase nesta
|
|
135
|
+
casa não lembrou.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 7 · Erro de classe a evitar
|
|
140
|
+
|
|
141
|
+
`[M]` **Quando um insumo "falta", meça no artefato que deveria servi-lo, não no que está à mão.**
|
|
142
|
+
O insumo *quais US* nunca seria servido pelo PRD — é servido pela projeção. `grep 'US-'` na fonte
|
|
143
|
+
dá zero, e o zero é real enquanto a conclusão é falsa.
|
|
144
|
+
|
|
145
|
+
`[M]` **Re-derivar, nunca editar à mão.** Editar as peças dessincronizadas produz um documento
|
|
146
|
+
sincronizado e **destrói a única chance de rodar o passo 4**.
|
|
@@ -114,7 +114,8 @@ To prevent recurrence, append the following **commit policy block** to every dis
|
|
|
114
114
|
|
|
115
115
|
```
|
|
116
116
|
[Commit Policy]
|
|
117
|
-
- createCheckpoint (mcp__orchestrator-tools__createCheckpoint)
|
|
117
|
+
- createCheckpoint (mcp__orchestrator-tools__createCheckpoint) WRITES TO GIT. Corrected S444 (TD-257) — this line used to say it was "INDEPENDENT of git", and that was measured false: calling it runs CheckpointManager.create() -> GitOperations.createCheckpointCommit() (a real commit, message `[orchestrator] <phase>: <your description>`) plus createCheckpointTag() (a real tag `orchestrator/<phase>/<ISO-timestamp>`). Evidence: 6 such tags exist in this repo, each on a commit carrying the description a sub-agent typed. CONSEQUENCE FOR YOU: the description you pass becomes a permanent public git commit message — write it accordingly. You still do NOT need to commit before calling it (it commits what is already staged and stages nothing itself), so calling it with a clean tree is the normal path. It CANNOT restore anything: restore() has no production caller, no REST route, and the stored commit_sha is hardcoded to '' — a checkpoint is an audit marker, never a safety net.
|
|
118
|
+
- SEPARATE MECHANISM, do not confuse: an unattended auto-commit hook (subagent-stop -> createCheckpointIfNeeded) has historically committed on its own, NOT triggered by your createCheckpoint call. Its commit message is NOT authoritative for phase attribution (hard rule (s) S194/S195: it reads currentPhase post-advance and drifts one phase ahead). Measured S444 under TD-257: 212 such commits, 68% capturing only machine noise, one (`01c28adf`) deleting 1627 lines of production code under the message "Auto-checkpoint after tasks phase". Trust explicit authored commits (`feat|fix|refactor|docs(sN): subject`) for phase attribution in audit/blame archaeology — never the auto-checkpoint label.
|
|
118
119
|
- Commit policy for this dispatch: <one of>
|
|
119
120
|
a) "DO NOT commit — orchestrator owns the closure commit at review gate."
|
|
120
121
|
b) "Local commit per-phase is OK (granular revertability) using prefix `<feat|fix|refactor>(s<N>): <subject>` — confirm prefix before commit. You are on a dedicated feature branch (the orchestrator branched before dispatching you, §2c.0); commit LOCALLY only." (use when implement/framework/operational/deliver phase exceeds 80k tokens or spans multiple sub-fases)
|
|
@@ -124,7 +125,7 @@ To prevent recurrence, append the following **commit policy block** to every dis
|
|
|
124
125
|
|
|
125
126
|
Substitute `<CURRENT_SESSION>` with the active session number (e.g., `s195`) and pick **exactly one** of (a) or (b) — never leave both options visible. The block goes **after** `[Task]` and **before** the artifactStore instruction.
|
|
126
127
|
|
|
127
|
-
If the orchestrator (main) wants to own all commits, prefer option (a) + call `createCheckpoint` itself after the phase completes — do NOT delegate that call to the dispatched agent.
|
|
128
|
+
If the orchestrator (main) wants to own all commits, prefer option (a) + call `createCheckpoint` itself after the phase completes — do NOT delegate that call to the dispatched agent. **Know what that call does before making it (corrected S444):** `createCheckpoint` is not a passive record — it creates a real commit *and* a real tag. "Owning all commits" therefore means owning this one too; if the working tree holds unrelated dirt, that dirt is what gets captured under your description. Check `git status` first.
|
|
128
129
|
|
|
129
130
|
#### 2c.2 Verify-Before-Assert dispatch addenda (TD-S192-003)
|
|
130
131
|
|
|
@@ -154,7 +155,12 @@ The block goes **after** `[Task]` and **before** `[Commit Policy]`. It applies t
|
|
|
154
155
|
|
|
155
156
|
### 2d. Gate Check
|
|
156
157
|
|
|
157
|
-
|
|
158
|
+
Two things travel together here and they are **not** the same (identity MUST 2 and 3, split in S478):
|
|
159
|
+
|
|
160
|
+
- **the guarantee (MUST 2)** — no phase advances without a decision **recorded and attributed**. Never auto-approve.
|
|
161
|
+
- **the instrument (MUST 3)** — `AskUserQuestion` by default; a project MAY declare another decision channel in its Charter. Swapping the instrument does not relax the guarantee.
|
|
162
|
+
|
|
163
|
+
Default instrument — after each sub-agent completes, present the artifact summary and ask for approval:
|
|
158
164
|
|
|
159
165
|
```
|
|
160
166
|
AskUserQuestion({
|
|
@@ -163,6 +169,8 @@ AskUserQuestion({
|
|
|
163
169
|
})
|
|
164
170
|
```
|
|
165
171
|
|
|
172
|
+
If this project declares a **delegated** channel instead (see `project-guidelines/technical/GATE-DELEGAVEL-PROPOSTA-S477.md` — proposed, not implemented), then the approver may be an **agent** acting for an **absent** human, and the record MUST say so: who approved, under which delegation, when. Read the answer from a **file**, never from the channel's screen (S476). Never let a timeout fall through to "proceed alone" — that is auto-approval wearing a delegation.
|
|
173
|
+
|
|
166
174
|
- **Approve** → call `advancePhase`, dispatch next phase agent.
|
|
167
175
|
- **Request changes** → re-dispatch same sub-agent with the user's feedback.
|
|
168
176
|
- **Abort** → call `completeWorkflow` with `cancelled` status.
|
|
@@ -25,7 +25,7 @@ Note: ToolSearch results are cached — you only need to fetch each tool once pe
|
|
|
25
25
|
The **main conversation is the orchestrator**. There is no orchestrator sub-agent.
|
|
26
26
|
|
|
27
27
|
- Phase sub-agents (specifier, planner, implementer, etc.) are dispatched via `Agent(subagent_type: "...")` directly from the main conversation
|
|
28
|
-
- Gates between phases
|
|
28
|
+
- Gates between phases: the **guarantee** is a recorded decision by an authorized party, never auto-approve; the **instrument** is `AskUserQuestion` unless the project Charter declares another decision channel (identity MUST 2 and 3, split in S478)
|
|
29
29
|
- The `/orchestrator` skill is the universal entry point
|
|
30
30
|
|
|
31
31
|
### Deterministic Hooks (ADR-013)
|
|
@@ -41,7 +41,7 @@ Orchestration governance is enforced by hooks, not by prompt instructions:
|
|
|
41
41
|
| `prompt-orchestrator` | On user prompt Submit | Injects workflow hints |
|
|
42
42
|
|
|
43
43
|
### Phase Advancement
|
|
44
|
-
1. Present artifact summary
|
|
44
|
+
1. Present the artifact summary and obtain a decision — via `AskUserQuestion`, or via the project's declared channel if it has one. Either way the decision must be **recorded and attributed** before advancing (identity MUST 2)
|
|
45
45
|
2. If user approves: call advancePhase
|
|
46
46
|
3. If user requests changes: re-dispatch the same sub-agent with feedback
|
|
47
47
|
4. The gate-guardian hook provides an additional safety check
|
|
@@ -61,7 +61,7 @@ Orchestration governance is enforced by hooks, not by prompt instructions:
|
|
|
61
61
|
- SPECIFY: spec.md exists in MinIO, has required sections
|
|
62
62
|
- PLAN: plan.md exists, references spec, has architecture section
|
|
63
63
|
- TASKS: tasks.md exists, tasks are atomic, has acceptance criteria
|
|
64
|
-
- IMPLEMENT: requires
|
|
64
|
+
- IMPLEMENT: requires an approval recorded by an authorized party — via `AskUserQuestion` by default. If the project delegates the gate, the record must name the approver and the delegation in force; a delegated approval is **not** a human approval and must not be written as one (identity MUST 2)
|
|
65
65
|
|
|
66
66
|
### Observability
|
|
67
67
|
Hooks automatically track agent invocations via SubagentStart/SubagentStop events.
|