@orchestrator-claude/definitions 3.37.2 → 3.38.0

package/skills/fase-1b-projecao/SKILL.md

@@ -12,6 +12,9 @@ item), cita o documento, mede os itens e carrega o `sha256` dele.
 
 Marcas: `[M]` medido · `[S]` síntese nossa · `[U]` decidido pelo usuário · `[L]` lacuna aberta.
 
+Referências S523 (primeira corrida sobre PRD de autoria, repo do produto `ac4bb439`):
+`PRD-001-v2-Z-1B-S523.md` (Z-23..Z-28) e `COMPARACAO-1B-BRACOS-S523.md` (Z-29, Z-30).
+
 ---
 
 ## 1 · O que esta fase NÃO promete — leia antes de tudo
@@ -19,6 +22,9 @@ Marcas: `[M]` medido · `[S]` síntese nossa · `[U]` decidido pelo usuário ·
 `[M]` **Granularidade não é propriedade do PRD.** Medido na S475 com réplica exata — mesma fonte,
 mesmo pedido, mesma árvore, **zero variáveis**: 55 stories numa execução e **78** na outra, +42%.
 Quatro derivações do mesmo PRD deram **33 · 66 · 55 · 78** stories e **8 · 12 · 11 · 15** épicos.
+`[M]` Réplicas exatas (mesma fonte, mesmo pedido, dois braços): **55 · 78** (S475), **75 · 75**
+(S514, PRD-001 E9), **78 · 75** com **12 · 12** épicos (S523, PRD-001-v2 do produto). O 75 · 75
+sozinho engana; o 12 · 12 com 78 · 75 mostra que épicos podem sair estáveis enquanto stories não.
 
 Consequências operacionais, e nenhuma se conserta melhorando o prompt:
 
@@ -48,6 +54,14 @@ Consequências operacionais, e nenhuma se conserta melhorando o prompt:
 > devolve byte a byte. Não presuma que só resta a fonte de hoje — o controle do experimento
 > costuma já existir.
 
+`[M]` **Primeira projeção de um PRD: não há versão anterior, e os passos 3-4 não são executáveis
+com um braço só.** O controle é uma **réplica** — segundo braço, mesma fonte, mesmo pedido (sha
+igual), worktree própria, e o braço 1 ausente da worktree do braço 2. O passo 3 vira comparação
+**por item** entre braços (escolha os itens antes de abrir o segundo — S523 escolheu 5) e o passo 4
+se decide pelo que a réplica devolve. Sem segundo braço o artefato fica `[L]` "derivabilidade não
+medida" — não é falha, é declaração. Rodar o segundo braço custa uma derivação e é decisão do PM
+(S514 §6 "n = 2 por fonte"; S523 D-043 e Z-28).
+
 ---
 
 ## 3 · O pedido literal — e o que **não** pode entrar nele
@@ -70,6 +84,20 @@ Escreva a saída em <SAIDA>, markdown único, com esta estrutura:
 Quantos épicos e quantas stories saem é resultado, não meta.
 ```
 
+`[M]` **O pedido congelado guarda os placeholders, não os caminhos.** `<PRD>` e `<SAIDA>` viram
+caminhos absolutos de scratchpad no despacho (o `Agent` não tem `cwd`; o `claude -p` tem `cd <WT>`),
+e um pedido com caminho inlinado só é re-executável nesta sessão — e dois braços viram dois shas
+por uma linha (S523 Z-26: `5f742fc7` ≠ `6a256fbb`). Convenção: **um** arquivo de pedido, com o
+texto acima intacto e o `sha256` **do texto com placeholders**, mais uma tabela de binding por
+braço: `braço · sha256 da fonte · <PRD> resolvido · <SAIDA> resolvido · commit da worktree` (é a
+forma do `PRD-001-EPICOS-E-US-S514-PEDIDO.md`). "Mesmo pedido" = mesmo sha do texto; o que difere
+entre braços mora na tabela.
+
+`[S]` **Nomes.** Worktree `<tmp>/wt-<braço>` (`a`, `b`, …); saída dentro da worktree com nome
+**neutro** (`saida.md` — o nome é contaminação residual, S514 §5 item 4); ao promover,
+`<PRD-base>-<braço>.md` (S523 Z-29 usou `-b2`). `[L]` O diretório de promoção segue sem regra na
+`.docs-constitution.yaml` (S513 §5 item 14) — declare o que escolheu.
+
 `[S]` **O que fica de fora, e é a decisão que faz o teste valer.** Regras de conteúdo que a
 projeção anterior declarava — *ator é posição e não cargo*, *nenhuma story nomeia mecanismo*,
 *nada por inferência* — **não entram**, mesmo citando o PRD. Se estão mesmo na fonte, o derivador
@@ -87,22 +115,92 @@ contrato medem; não há como remover sem perder a comparabilidade.
 
 ## 4 · Executor e isolamento
 
-**Executor: `general-purpose`.** `[S]` Não use `specifier` nem `task-generator` — os dois têm
-formato de saída próprio no corpo (spec, tasks atômicas) que empurra a derivação para um molde
-que não é do PRD, contaminando o eixo que se quer medir. Agente **sem** corpo calibrado é a
-escolha certa aqui, e é a razão de esta fase ser skill e não agente.
+`[U]` **Executor decidido: `claude -p --setting-sources project` de dentro da worktree saneada**
+(D-054, PM, 2026-09-21, via Manager — alternativa C do `ASSESSMENT-FASE1B-Z23-Z30-S522.md` §4).
+Não é mais `general-purpose` via `Agent`: esse executor nasce com o contexto da sessão que o
+despacha e foi medido contaminado duas vezes (S513 item 1 citou as autorais verbatim; S523 Z-24
+recebeu as Regras 1-3 do produto) — alternativa A, rejeitada. `[S]` Pela mesma razão não se
+despacha por `specifier` nem `task-generator`: corpo calibrado empurra a derivação para um molde
+que não é do PRD, contaminando o eixo que se quer medir. `[L]` `claude -p --bare` seria "nada além
+do pedido", mas exige `ANTHROPIC_API_KEY` (não lê OAuth; S513 §5 item 13) — fora de alcance hoje.
 
 **Isolamento por construção, não por instrução.** `[M]` Instruir "não olhe a projeção anterior"
 depende do agente obedecer. Derivar numa **worktree de um commit anterior à promoção** dela não
 depende de nada: o arquivo não existe lá.
 
 ```bash
-git worktree add --detach <tmp>/wt b4b1eba4          # commit anterior a promocao
-git show HEAD:<PRD> > <tmp>/wt/<PRD>                 # so a fonte e trocada
-git grep -l 'EP-0[1-9]\|US-0[1-9]\.' b4b1eba4 -- ':!*agent-memory*'   # esperado: vazio
+# 1. ache o commit anterior a promocao da projecao anterior (ou do primeiro arquivo que cita EP-/US-)
+git log --diff-filter=A --format='%h %s' -- <projecao-ou-arquivo-que-bate> | tail -1   # -> <C>
+git worktree add --detach <tmp>/wt-<braco> <C>^        # commit ANTERIOR ao que adicionou
+git show HEAD:<PRD> > <tmp>/wt-<braco>/<PRD>            # so a fonte e trocada
+git grep -l 'EP-0[1-9]\|US-0[1-9]\.' <C>^ -- ':!*agent-memory*'   # esperado: vazio (exit 1)
+git grep -l 'EP-0[1-9]\|US-0[1-9]\.' HEAD -- ':!*agent-memory*'   # controle positivo: NAO vazio
+```
+
+`[M]` O último par de comandos é o que transforma "isolado" em **medido**: vazio no commit da
+worktree **e** não-vazio em `HEAD`. Em `HEAD` o grep **bate sempre** que o repo tiver um relatório
+de comparação (todo repo que roda esta fase mais de uma vez tem) — se bater, **recue ao commit
+anterior ao arquivo que bate** (`<C>^`) e repita; não é falha, é o controle positivo funcionando.
+Rode os dois e cole a saída. *(S513 §5 item 5; S514-PEDIDO l.53-58; S523 Z-23: `0730d9da` bateu em
+1 arquivo, `ddc0ed2^ = a929a22` vazio.)*
+
+`[M]` **A prova da árvore não cobre o executor.** O `git grep` acima mede o que existe na worktree;
+não mede o que o harness injeta no derivador. Medido: `general-purpose` via `Agent` nasce com o
+`CLAUDE.md` do role/sessão (S513, citou as autorais verbatim) e com o `CLAUDE.md` do repo (S523
+Z-24, Regras 1-3 do produto); `claude -p --setting-sources project` de dentro da worktree recebe o
+`CLAUDE.md` do repo e os plugins do `.claude/settings.json` dele (TD-316) — e `--tools` **não**
+filtra as MCP, só as nativas. É por isso que a worktree é **saneada** antes do despacho:
+
+```bash
+# 2. saneie a worktree (a fonte nao e tocada; o grep de isolamento acima roda no COMMIT, nao na arvore)
+rm <WT>/CLAUDE.md <WT>/.claude/settings.json <WT>/.mcp.json
+git -C <WT> status --short        # esperado: exatamente os 3 " D " de governanca — declare-os no cabecalho
+# 3. despache (S513-PEDIDO l.55-63, SEM --no-session-persistence: o transcript e a prova)
+cd <WT> && claude -p \
+  --setting-sources project \
+  --tools "Read,Write,Grep,Glob" \
+  --permission-mode acceptEdits \
+  --model 'claude-opus-5[1m]' \
+  --output-format json \
+  "<pedido da §3, com <PRD> e <SAIDA> substituídos>"    # guarde o session_id do JSON de saida
+```
+
+`[S]` A árvore passa a divergir do commit em **três arquivos de governança** — nem a fonte nem a
+saída; declare os três no cabeçalho do artefato (§6). O `rm` não toca o repo: é a working tree de
+`<C>^` com a fonte trocada, e `git worktree remove` a desfaz.
+
+`[M]` **A prova do executor é o transcript persistido** (`.jsonl` da sessão do derivador). Ele fica
+em `~/.claude/projects/<cwd com "/" trocada por "-">/<session_id>.jsonl`. Cole os três:
+
+```bash
+J=~/.claude/projects/<cwd-codificado>/<session_id>.jsonl
+# (a) roster: esperado = so as 4 de --tools; mcp__ = 0
+jq -r 'select(.attachment.type=="prompt_snapshot") | .attachment.tools[]?.name' "$J" | sort -u \
+  | awk '{t++} /^mcp__/{m++} END{print "total="t+0, "mcp__="m+0}'
+# (b) contexto inicial = o registro "instructions" (arquivos injetados, por tipo) + o proprio pedido.
+#     esperado: NENHUM "Project" (o CLAUDE.md do repo) e 0 EP-/US- no que foi injetado
+jq -r 'select(.attachment.type=="instructions") | .attachment.files[] | "\(.type) \(.path) \(.content|length)B"' "$J"
+jq -r 'select(.attachment.type=="instructions") | .attachment.files[].content' "$J" | grep -c 'EP-0\|US-0'
+# (c) cada Read: esperado = so <PRD>
+jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use")
+       | "\(.name) \(.input.file_path // "")"' "$J" | sort | uniq -c
 ```
 
-O último comando é o que transforma "isolado" em **medido**. Rode-o e cole a saída.
+Sem transcript, "nenhum outro documento foi consultado" é autorrelato (S513 §5 item 12). `[M]`
+Medido na S523 (harness `2.1.278`, worktree de `a8121ba2` do repo do harness, sonda de 1 prompt):
+saneada → roster **4, `mcp__` 0**, `instructions` sem `Project`, hook 0 (sessão `7dd2882a`); a
+mesma árvore **sem** o `rm` → roster 68, `mcp__` 64 (serena 29, playwright 25, Claude Docs 8,
+context7 2), `Project` = `CLAUDE.md` do repo, `hook_success` 2 (sessão `5a825395`). É o
+falsificador de TD-316 §4 satisfeito nesta versão do harness; um harness em que o roster **não**
+zere na worktree saneada derruba esta seção — meça antes de derivar, não depois. *(S523 Z-24; D-054.)*
+
+`[L]` **Canal residual que C não fecha, declarado:** o registro `instructions` da worktree saneada
+ainda carrega **um** arquivo `AutoMem` — o `MEMORY.md` da auto-memória do repo
+(`~/.claude/projects/<repo>/memory/MEMORY.md`), que mora **fora** da worktree e o `rm` não alcança
+(a worktree resolve para o diretório de projeto do repo-mãe). `[M]` S523: 1810 B, **0** `EP-`/`US-`,
+nos dois braços; o braço B da S514 (harness anterior) não o tinha. Enquanto a lacuna estiver aberta,
+o snippet (b) é a prova: cole a linha `AutoMem …` e o `0`; se der > 0, a derivação está contaminada
+por esse canal e a decisão de fechá-lo (não é saneamento de árvore, é memória do usuário) é do PM.
 
 ---
 
@@ -113,9 +211,16 @@ Use os comandos que o contrato registra, nunca os inventados na hora:
 ```bash
 grep -cE '^## EP-'  <projecao>      # epicos
 grep -cE '^### US-' <projecao>      # stories
-grep -oE '§[0-9]+(\.[0-9]+)*' <projecao> | sort -u   # cobertura por referente
+grep -oE '§[0-9]+(\.[0-9]+|\.[A-Z]\b)*' <corpo> | sort -u   # cobertura por referente (canonico)
+# <corpo> = corpo derivado entre os marcadores (§6), NAO o arquivo com cabecalho — regra D-018 abaixo
 ```
 
+`[M]` **Sub-área com letra** (`§7.A`) existe em PRD de autoria (S523 Z-25: 11 referentes pelo padrão
+só-numérico, 21 com letra — a D-018 ficaria cega). O padrão acima é o **canônico único**; é
+superconjunto do anterior e devolve os mesmos números nas projeções desta casa (62 · 65 · 73,
+medido). `\b` evita casar `§7.A` em "§7.Além". Não existem dois instrumentos: quando alguém medir
+com outro padrão, o número dele não entra na D-018.
+
 > `[M]` **Para medir se o delta da fonte atravessou, olhe o ITEM que a emenda tocou — nunca o
 > agregado.** Medido S475: contagem e sobreposição de referentes não distinguem troca de fonte de
 > ruído (réplica pura dá 95%/88%; trocar a fonte dá 85–91% — dentro do ruído). O mesmo delta
@@ -123,8 +228,10 @@ grep -oE '§[0-9]+(\.[0-9]+)*' <projecao> | sort -u   # cobertura por referente
 > fonte velha e como *requisito* nas **duas** réplicas da fonte nova. O agregado afoga o sinal.
 
 `[U]` **Quando há mais de um braço válido da mesma fonte, promove-se o de maior cobertura de
-referentes únicos do PRD (`grep -oE '§…' | sort -u | wc -l`); empate → o que terminou primeiro.**
-Regra do PM, D-018 (S514) — antes dela a escolha era arbitrária e declarada como tal.
+referentes únicos do PRD — medida com o padrão canônico de §5, sobre o corpo derivado entre
+marcadores (§6), nunca sobre o arquivo com cabeçalho (S514: 68 no corpo, 73 no arquivo); empate →
+o que terminou primeiro.** Regra do PM, D-018 (S514) — antes dela a escolha era arbitrária e
+declarada como tal. *(S523 Z-30.)*
 
 ---
 
@@ -138,6 +245,15 @@ Regra do PM, D-018 (S514) — antes dela a escolha era arbitrária e declarada c
 **vira** o registro; guardá-lo depois depende de lembrar, e a primeira execução desta fase nesta
 casa não lembrou.
 
+`[M]` **Onde J4 mora, e o que "nunca editar à mão" cobre.** O executor não sabe commit nem sha do
+pedido (por desenho). O arquivo promovido tem **cabeçalho** (J4: commit, sha da fonte, sha do
+pedido, executor com modelo/versão/flags) e **anexos** fora de dois marcadores HTML —
+`<!-- CORPO-DERIVADO-INICIO … sha256 <sha do corpo> -->` e `<!-- CORPO-DERIVADO-FIM -->` — e o
+**corpo derivado verbatim** entre eles. Registram-se **dois** shas: o do corpo (é o que a
+re-derivação compara e o que a D-018 mede) e o do arquivo. "Nunca editar à mão" (§7) é sobre o
+corpo; extraia-o com `awk` ancorado em `^<!-- ` (não pelo texto do marcador, que recorre na prosa —
+S513 §6). *(Prática desde S513; S514 §5 item 10; S523 Z-27 chegou à mesma forma sem a skill dizer.)*
+
 ---
 
 ## 7 · Erro de classe a evitar

package/skills/orchestrator/SKILL.md

@@ -101,7 +101,7 @@ Sub-agents MUST persist artifacts to MinIO via `artifactStore` (universal rule,
 
 #### 2c.1 Checkpoint + Commit Policy dispatch addenda (TD-S188-002 + TD-S192-003)
 
-**Scope (TD-S192-003 amendment; set re-verified TD-171/S290):** this block applies to **any agent whose tool list includes `mcp__orchestrator-tools__createCheckpoint`**. As of **S290 the ground-truth set (grep `createCheckpoint` over `.claude/agents/*.md`) is the 7 agents**: `implementer`, `azure-devops-engineer`, `presentation-engineer`, `operational-artifact-builder`, `cicd-platform-engineer`, `python-data-engineer`, `frontend-engineer`. (The earlier S195 list was stale — it named `methodology-researcher`, which no longer holds the tool, and omitted `cicd-platform-engineer` / `python-data-engineer` / `frontend-engineer`, added later.) **Keep this set in sync with `COMMITTING_AGENTS` in `.claude/hooks/pre-agent-dispatch.ts`** (the branch-before-dispatch hook, §2c.0) — both derive from the same `createCheckpoint`-holder ground truth; when an agent gains/loses `createCheckpoint`, update both. **Match this set ignoring any plugin prefix** (`orchestrator:implementer` ≡ `implementer`) — the hook already does so via `normalizeAgentName()` (S398); membership is a property of the agent, not of the topology that names it. The earlier version of this section was implementer-only; subsequent sessions (S192 PME phase 2, S194 bug_fix, S195 lint sweep) confirmed the same `createCheckpoint=git-commit` conflation appears across other agents that hold the tool — making the rule agent-agnostic from S195 forward.
+**Scope (TD-S192-003 amendment; set re-verified TD-171/S290):** this block applies to **any agent whose tool list includes `mcp__orchestrator-tools__createCheckpoint`**. As of **S531 the ground-truth set (the `tools:` line of `packages/definitions/agents/*.md` holding `createCheckpoint`) is the 9 agents**: `implementer`, `azure-devops-engineer`, `presentation-engineer`, `operational-artifact-builder`, `cicd-platform-engineer`, `python-data-engineer`, `frontend-engineer`, `ciclo-engineer`, `harness-engineer`. (`ciclo-engineer` and `harness-engineer` were added in S531 — D-137/D-153; the first had carried the tool, unlisted, since before the lane 3.) (The earlier S195 list was stale — it named `methodology-researcher`, which no longer holds the tool, and omitted `cicd-platform-engineer` / `python-data-engineer` / `frontend-engineer`, added later.) **Keep this set in sync with `COMMITTING_AGENTS` in `packages/definitions/hooks/pre-agent-dispatch.ts`** (and its mirrors, propagated by `npm run sync:hooks`), with the identity's MUST 5 and with `/checkpoint-protocol` (the branch-before-dispatch hook, §2c.0) — both derive from the same `createCheckpoint`-holder ground truth; when an agent gains/loses `createCheckpoint`, update both. **Match this set ignoring any plugin prefix** (`orchestrator:implementer` ≡ `implementer`) — the hook already does so via `normalizeAgentName()` (S398); membership is a property of the agent, not of the topology that names it. The earlier version of this section was implementer-only; subsequent sessions (S192 PME phase 2, S194 bug_fix, S195 lint sweep) confirmed the same `createCheckpoint=git-commit` conflation appears across other agents that hold the tool — making the rule agent-agnostic from S195 forward.
 
 When dispatching any of those agents, the generic template above is **insufficient**. The S188 implement phase originally surfaced the ambiguity: the implementer interpreted `createCheckpoint` as requiring a git commit beforehand, producing 4 unsolicited commits per dispatch (commit prefix also leaked from BACKLOG context: `feat(s186)` instead of `feat(s188)`). Empirical evidence preserved across sessions:
 

package/skills/release/release.sh

@@ -361,6 +361,53 @@ run_build() {
   log_success "Build completed - dist/ updated with latest templates"
 }
 
+# Put the committed hook bundles back after run_build (S532, D-175).
+# The local build rewrites every packages/definitions/hooks/*.mjs — only the esbuild
+# source-path comments change ("// packages/definitions/hooks/x.ts" -> "// hooks/x.ts"),
+# even with a real node_modules. The .mjs are NOT staged by commit_version_bump, but
+# regenerate_definitions_manifest hashes them, so without this step the bumped manifest
+# carries sha256 of bytes that are not in the repo (v3.37.3 shipped 0/15 hook checksums
+# matching). validate_working_tree guarantees HEAD is the state being released.
+restore_committed_hook_bundles() {
+  echo "♻️  Restoring committed hook bundles (hooks/*.mjs) after build..."
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "  [dry-run] Would run: git checkout HEAD -- packages/definitions/hooks/*.mjs"
+    return
+  fi
+
+  local bundles
+  bundles=$(git ls-files 'packages/definitions/hooks/*.mjs')
+  if [ -z "$bundles" ]; then
+    log_error "No committed hook bundles found under packages/definitions/hooks/"
+    exit 1
+  fi
+
+  # shellcheck disable=SC2086
+  git checkout HEAD -- $bundles
+
+  log_success "Hook bundles restored to HEAD ($(echo "$bundles" | wc -l | tr -d ' ') files)"
+}
+
+# Guard: every hook checksum in the regenerated manifest must be the sha256 of the
+# .mjs blob committed at HEAD — the bytes the release actually ships. Aborts before
+# commit_version_bump if any diverges (TD-330: CI rebuilds the .mjs before testing,
+# so it never judges the committed ones; this is the only check on them).
+verify_manifest_hook_checksums() {
+  node -e '
+    const { execFileSync } = require("node:child_process");
+    const { createHash } = require("node:crypto");
+    const hooks = require("./packages/definitions/manifest.json").definitions.hooks;
+    const bad = hooks.filter((h) => {
+      const blob = execFileSync("git", ["show", `HEAD:packages/definitions/${h.file}`]);
+      return `sha256:${createHash("sha256").update(blob).digest("hex")}` !== h.checksum;
+    });
+    console.log(`${hooks.length - bad.length}/${hooks.length}`);
+    for (const h of bad) console.error(`  checksum != HEAD blob: ${h.file}`);
+    process.exit(bad.length === 0 && hooks.length > 0 ? 0 : 1);
+  '
+}
+
 # Regenerate packages/definitions/manifest.json AFTER the version bump (TD-193).
 # run_build already regenerates the manifest, but it runs BEFORE update_all_versions,
 # so at that point the manifest still carries the OLD version. generate-manifest sources
@@ -389,6 +436,13 @@ regenerate_definitions_manifest() {
     exit 1
   fi
 
+  local hook_match
+  if ! hook_match=$(verify_manifest_hook_checksums); then
+    log_error "Manifest hook checksums do not match the committed hooks/*.mjs ($hook_match)"
+    exit 1
+  fi
+  log_success "Manifest hook checksums match committed bundles ($hook_match)"
+
   log_success "Manifest regenerated and version-synced to $manifest_version"
 }
 
@@ -510,12 +564,14 @@ main() {
   echo ""
   echo "Actions:"
   echo "  1. Build project (update dist/ with latest templates)"
-  echo "  2. Update version in all files"
-  echo "  3. Regenerate definitions manifest from bumped version (TD-193)"
-  echo "  4. Commit version bump"
-  echo "  5. Create git tag $tag"
-  echo "  6. Push main + tag to origin"
-  echo "  7. CI/CD pipeline will publish npm + Docker"
+  echo "  2. Restore committed hook bundles (hooks/*.mjs) the build rewrote"
+  echo "  3. Update version in all files"
+  echo "  4. Regenerate definitions manifest from bumped version (TD-193)"
+  echo "     and assert its hook checksums match the committed .mjs"
+  echo "  5. Commit version bump"
+  echo "  6. Create git tag $tag"
+  echo "  7. Push main + tag to origin"
+  echo "  8. CI/CD pipeline will publish npm + Docker"
   echo ""
 
   if [ "$FORCE" = false ] && [ "$DRY_RUN" = false ]; then
@@ -529,6 +585,7 @@ main() {
 
   # Execute release steps
   run_build
+  restore_committed_hook_bundles
   update_all_versions "$new_version"
   regenerate_definitions_manifest
   commit_version_bump "$new_version"