@orchestrator-claude/definitions 3.37.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.
Files changed (69) hide show
  1. package/agents/adversarial-reviewer.md +6 -1
  2. package/agents/api-extractor.md +6 -0
  3. package/agents/azure-devops-engineer.md +1 -2
  4. package/agents/business-rule-miner.md +6 -0
  5. package/agents/cicd-platform-engineer.md +1 -2
  6. package/agents/ciclo-engineer.md +15 -2
  7. package/agents/code-archaeologist.md +6 -0
  8. package/agents/debug-sidecar.md +6 -0
  9. package/agents/doc-sidecar.md +6 -0
  10. package/agents/docs-guardian.md +9 -3
  11. package/agents/frontend-engineer.md +1 -2
  12. package/agents/{ai-architect.md → harness-architect.md} +8 -3
  13. package/agents/implementer.md +6 -1
  14. package/agents/legacy-discoverer.md +6 -0
  15. package/agents/legacy-synthesizer.md +6 -0
  16. package/agents/methodology-researcher.md +6 -1
  17. package/agents/operational-artifact-builder.md +6 -1
  18. package/agents/orchestrator.md +27 -87
  19. package/agents/planner.md +6 -1
  20. package/agents/presentation-engineer.md +5 -4
  21. package/agents/python-data-engineer.md +0 -1
  22. package/agents/researcher.md +6 -0
  23. package/agents/reviewer.md +6 -1
  24. package/agents/schema-extractor.md +6 -0
  25. package/agents/software-architect.md +10 -5
  26. package/agents/specifier.md +6 -1
  27. package/agents/task-generator.md +6 -1
  28. package/agents/test-sidecar.md +6 -0
  29. package/dist/scripts/generate-hooks-matcher.d.ts +106 -0
  30. package/dist/scripts/generate-hooks-matcher.d.ts.map +1 -0
  31. package/dist/scripts/generate-hooks-matcher.js +153 -0
  32. package/dist/scripts/generate-hooks-matcher.js.map +1 -0
  33. package/dist/scripts/generate-manifest.d.ts +22 -0
  34. package/dist/scripts/generate-manifest.d.ts.map +1 -1
  35. package/dist/scripts/generate-manifest.js +67 -2
  36. package/dist/scripts/generate-manifest.js.map +1 -1
  37. package/hooks/agent-git-guard.mjs +63 -11
  38. package/hooks/dangling-guard.mjs +42 -12
  39. package/hooks/gate-guardian.mjs +38 -8
  40. package/hooks/hooks.json +3 -9
  41. package/hooks/lib/api-client.ts +128 -9
  42. package/hooks/lib/capability-scanner.ts +391 -55
  43. package/hooks/lib/dispatch-marker.ts +214 -0
  44. package/hooks/lib/git-checkpoint.ts +34 -37
  45. package/hooks/lib/observations-helper.ts +14 -1
  46. package/hooks/mailbox-listener.mjs +69 -17
  47. package/hooks/playwright-output-guard.mjs +40 -10
  48. package/hooks/post-implement.mjs +38 -8
  49. package/hooks/pre-agent-dispatch.mjs +137 -16
  50. package/hooks/pre-agent-dispatch.ts +82 -15
  51. package/hooks/session-start.mjs +274 -103
  52. package/hooks/session-start.ts +250 -69
  53. package/hooks/subagent-start.mjs +7665 -22
  54. package/hooks/subagent-start.ts +367 -16
  55. package/hooks/subagent-stop.mjs +102 -62
  56. package/hooks/subagent-stop.ts +124 -28
  57. package/hooks/user-prompt.mjs +43 -13
  58. package/hooks/verification-before-completion.mjs +63 -11
  59. package/hooks/workflow-guard.mjs +45 -11
  60. package/hooks-settings-template.json +1 -7
  61. package/manifest.json +62 -62
  62. package/package.json +4 -2
  63. package/skills/checkpoint-protocol/SKILL.md +19 -4
  64. package/skills/ciclo-lane-dispatch/SKILL.md +24 -0
  65. package/skills/fase-1b-projecao/SKILL.md +146 -0
  66. package/skills/orchestrator/SKILL.md +11 -3
  67. package/skills/workflow-coordination/SKILL.md +3 -3
  68. package/hooks/post-compact.mjs +0 -7931
  69. 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.37.0",
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
- - `createCheckpoint` is a **PostgreSQL state snapshot** (RFC-012), **INDEPENDENT of git** — you do NOT need to commit before calling it.
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
- If you need to check previous checkpoints:
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) is a PostgreSQL state snapshot per RFC-012. It is INDEPENDENT of git. You do NOT need to commit before calling it. Calling createCheckpoint with no uncommitted changes is the normal path. createCheckpoint may also trigger an auto-commit hook on the orchestrator side — that hook's commit message is NOT authoritative for phase attribution (hard rule (s) S194/S195: hook reads currentPhase post-advance, drifts one phase ahead). Trust explicit authored commits (`feat|fix|refactor|docs(sN): subject`) for phase attribution in audit/blame archaeology.
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
- After each sub-agent completes, present the artifact summary and ask for approval:
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 use `AskUserQuestion` — never auto-approve
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 to user via AskUserQuestion
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 human approval via AskUserQuestion
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.