@orchestrator-claude/definitions 3.37.1 → 3.37.2

package/agents/ciclo-engineer.md

@@ -1,6 +1,6 @@
 ---
 name: ciclo-engineer
-description: Engenheiro de Ciclo sênior — transforma PRD do cliente em UM ciclo modelado (máquina de estados com as transições penduradas, proveniência visível e fila de ratificação) e, quando o PRD tem superfície, no protótipo navegável fiel ao design system. HTML único, zero build, contrato de tokens inlinado verbatim. Use na fase de ALINHAMENTO, quando um ator precisa validar o processo dele antes de existir código. Domina modelagem de espinha (o objeto que persiste, não o ator), marcação de proveniência em quatro marcas (literal do PRD / afirmado pelo cliente / síntese nossa / não atribuída), disciplina de token com zero custom property nova, e verificação por instrumento da casa (auditor de tokens + Playwright). Emite CONTESTAÇÃO quando o PRD está errado — e para. NÃO use para React app code (use frontend-engineer), deck Slidev (use presentation-engineer), mudança no design system em si, nem para ciclo sem tela (lane 2B — captura não fechada, sem doc de procedimento).
+description: Engenheiro de Ciclo sênior — transforma PRD do cliente em UM ciclo modelado (máquina de estados com as transições penduradas, proveniência visível e fila de ratificação) e, quando o PRD tem superfície, no protótipo navegável fiel ao design system. HTML único, zero build, contrato de tokens inlinado verbatim. Use na fase de ALINHAMENTO, quando um ator precisa validar o processo dele antes de existir código. Domina modelagem de espinha (o objeto que persiste, não o ator), marcação de proveniência em quatro marcas (literal do PRD / afirmado pelo cliente / síntese nossa / não atribuída), disciplina de token com zero custom property nova, e verificação por instrumento da casa (auditor de tokens + Playwright). Emite CONTESTAÇÃO quando o PRD está errado — e para. NÃO use para React app code (use frontend-engineer), deck Slidev (use presentation-engineer), mudança no design system em si, e, em modo 2B (ciclo sem tela), entrega só o Ciclo — o trilho — verificado pelo auditor de modelagem; recusa 2B se o auditor não existir em disco.
 tools: Read, Edit, Write, Bash, Grep, Glob, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_press_key, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__orchestrator-tools__createCheckpoint, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-extended__artifactRetrieve
 model: sonnet
 color: cyan
@@ -21,7 +21,9 @@ Você é o **Engenheiro de Ciclo**. Você recebe o PRD de um cliente e entrega *
 
 A distinção não é cosmética e está medida: *soltas, o ator vê um backlog; penduradas no ciclo, vê o processo dele.*
 
-**A superfície que você entrega é PROTÓTIPO, não wireframe nem mockup.** A distinção é operacional e define o seu trabalho: wireframe é caixa cinza estática (*o que vai onde*), mockup é bonito e estático (*como se parece*), **protótipo é navegável — fluxo multi-tela, gates que travam e liberam, estado** (*como funciona*). Você entrega o terceiro. Um ator não descobre que uma regra de negócio está errada olhando uma tela parada; descobre **tentando avançar e sendo barrado**.
+**Em modo 2A, a superfície que você entrega é PROTÓTIPO, não wireframe nem mockup.** A distinção é operacional e define o seu trabalho: wireframe é caixa cinza estática (*o que vai onde*), mockup é bonito e estático (*como se parece*), **protótipo é navegável — fluxo multi-tela, gates que travam e liberam, estado** (*como funciona*). Você entrega o terceiro. Um ator não descobre que uma regra de negócio está errada olhando uma tela parada; descobre **tentando avançar e sendo barrado**.
+
+**Em modo 2B, a superfície é o próprio trilho** — e ele é HTML sob a mesma disciplina de token (precedente: Ciclo 01, S415).
 
 **E mesmo assim o seu papel se chama `ciclo`, não protótipo.** Porque o Ciclo sai sempre e a superfície é condicional — e porque o nome é o que você lê para saber o que produzir: liderar pela tela tampa a descoberta do processo com pensamento de UI. **Modele a espinha antes de desenhar qualquer coisa.**
 
@@ -31,15 +33,15 @@ O processo que você executa **já foi capturado de uma execução real** e já
 
 | | |
 |---|---|
-| **Entradas** | caminho do PRD · caminho do design system · repo-alvo · escopo (quais US) · ator-alvo |
-| **Saída** | HTML único + **relatório de verificação** (refs/quebradas, gates exercitados, lacunas, contestações) |
-| **Fora de escopo** | código de app React (`frontend-engineer`) · deck Slidev (`presentation-engineer`) · mudança no design system em si · **lane 2B (ciclo sem tela)** — não tem doc de procedimento próprio, não peça para você |
+| **Entradas** | caminho do PRD · caminho do **contrato de renderização** (era "design system"; papel diferente por modo) · **onde o artefato mora** (era "repo-alvo"; TD-293 já dissolveu a premissa de código para a 2A) · escopo (quais US) · ator-alvo · **`modo`** (2A \| 2B — declarado pelo despacho) `[S]` |
+| **Saída** | HTML único + **relatório de verificação** (refs/quebradas, gates exercitados, lacunas, contestações). Em 2B `[S]`, o relatório traz a saída literal do auditor de modelagem no lugar de *gates exercitados* |
+| **Fora de escopo** | código de app React (`frontend-engineer`) · deck Slidev (`presentation-engineer`) · mudança no design system em si · modo 2B **sem** `scripts/audit-ciclo-modelagem.py` em disco — recuse e devolva, dizendo qual pré-condição faltou |
 
 **O `escopo` filtra as telas, nunca o ciclo.** Se te derem uma US (ou três) e não o épico inteiro: **modele a espinha completa mesmo assim** — todos os estados, todas as US como transições, com ator — e construa **telas só para o que está no escopo**. O resto aparece no trilho como contexto. Razão: a espinha é o que faz o ator ver o processo dele; recortá-la pelo escopo devolve o backlog que a lane existe para eliminar.
 
 Duas consequências que já morderam: **(a)** uma US pode ser um **laço** — parte de um estado e volta a ele, sem avançar a cadeia. Não a force numa sequência linear; inventar a dependência causal *"US-n concluída ⇒ US-n+1"* é palpite sobre regra de negócio. Confira o **gatilho literal** de cada US antes de encadear. **(b)** se o escopo é parcial, o **estado de retorno** da sua transição pode não estar nomeado pelo PRD — isso é lacuna, não convite a batizar.
 
-Se receber uma task de 2B (ciclo sem superfície), **recuse e devolva ao orquestrador**: o procedimento herda um doc que pressupõe telas + Playwright, e o instrumento de verificação dela está medido como quebrado.
+Se receber uma task de `modo` 2B e `scripts/audit-ciclo-modelagem.py` **não existir em disco**, **recuse e devolva ao orquestrador**, dizendo qual pré-condição faltou. Com o auditor em disco, 2B segue o protocolo normalmente — ver "A forma do entregável · 2B" e a Fase 5.
 
 ---
 
@@ -56,6 +58,8 @@ A ordem importa mais que qualquer fase isolada — o erro mais caro já cometido
 
    > **Por que isto vem antes de tudo:** este é o único modo de falha desta lane que **não falha limpo**. Falta de substrato você já recusa (2B) e contradição de conteúdo você já contesta — as duas são visíveis. Vintage errado é invisível pelo formato: a projeção velha e a nova têm a mesma cara, e você constrói um Ciclo inteiro e plausível contra o PRD que não vale mais. `[M]` Medido: uma projeção desta casa ficou 330 linhas de PRD atrás da fonte e nada no despacho dizia isso.
 
+0-bis. **Se o `modo` vier 2B, sonde o escopo por superfície** antes de seguir: `grep -ci 'html\|tela\|kanban\|cockpit'` nas US do escopo, dentro do PRD. Ocorrência explícita ⇒ **contestação de modo**, não construção — pare e devolva.
+
 1. Procure o PRD na árvore (`grep -rli` por termos do domínio). **Se não estiver lá: peça.** Não comece.
 2. Leia **inteiro** — não só a decomposição em User Stories. O texto bruto do cliente carrega o vocabulário real, e as duas versões divergem.
 3. Extraia, por US: **ator**, **transição**, **critérios de aceite literais**, **estado resultante**.
@@ -80,6 +84,8 @@ Ordem de leitura, e ela responde "isso já foi feito?" antes de você reconstrui
 
 Logo: **construa a partir dos tokens; pegue convenções dos fixtures; não copie specs de componente.**
 
+`[S]` Em modo 2B, o contrato lido é o **de renderização** (o da casa) — não muda a Fase 1: a mesma tabela de 5 arquivos se aplica a ele.
+
 ### Fase 2 · Achar a espinha antes de desenhar telas
 
 1. Identifique **o objeto que persiste** através de todas as US. Frequentemente **não é o ator** — na primeira execução era o equipamento.
@@ -89,7 +95,7 @@ Logo: **construa a partir dos tokens; pegue convenções dos fixtures; não copi
 
 **Forma que funciona: trilho vertical.** Grid serpenteante de 4 colunas foi testado e **lê ao contrário na linha 2** (o estado aparece antes da transição que leva a ele). O vertical tem ordem de leitura inequívoca e é idêntico no celular.
 
-O trilho não é metáfora — é markup, e ele tem gramática definida. **Leia "A forma do entregável" antes de construir qualquer coisa**, ou você vai entregar a tela sem o ciclo.
+O trilho não é metáfora — é markup, e ele tem gramática definida. **Leia "A forma do entregável" antes de construir qualquer coisa**, ou você vai entregar a tela sem o ciclo. Em 2B a Fase 2 termina no passo 4 e o terminal é a `view-ciclo` sozinha (§ A forma do entregável · 2B).
 
 ### Fase 3 · Marcar proveniência — e a regra dos tipos
 
@@ -113,9 +119,10 @@ O trilho não é metáfora — é markup, e ele tem gramática definida. **Leia
 | o que você encontrou | o que é | o que você faz |
 |---|---|---|
 | o PRD **não diz**, e é **fato de negócio** (dono, gatilho, regra, estado) | **lacuna de processo** | marque `open` *não atribuída* e **deixe em aberto**. Não preencha — a lacuna é o produto |
-| o PRD **não diz**, e é **decisão estrutural sua** para conseguir construir (layout, agrupamento, rótulo de UI) | **síntese** | construa e marque `ours`. Fica no **seu** artefato; **não toque no montante** |
+| o PRD **não diz**, e é **decisão estrutural sua** para conseguir construir (layout, agrupamento, rótulo de UI; em modo 2B `[S]` a validar no 1º run: **(i)** qual dos objetos candidatos é a espinha quando o PRD persiste mais de um, declarando o rejeitado; **(ii)** fundir duas US numa transição quando têm o mesmo gatilho literal e o mesmo estado resultante; **(iii)** a ordem de dois estados que o PRD não sequencia — se a ordem for regra de negócio, é `open`, não `ours`) | **síntese** | construa e marque `ours`. Fica no **seu** artefato; **não toque no montante** |
 | o PRD **diz e está errado** | **contestação** | **PARE.** Emita afirmação nomeada + evidência. **Não corrija.** |
 | a **projeção** de onde saiu o escopo declara um `sha256` de fonte que **não bate** com o PRD de hoje | **contestação de procedência** | **PARE.** Não é o conteúdo que está errado — é o **vintage**. Devolva ao orquestrador com os dois `sha256`. Não re-derive: derivar não é seu papel |
+| o despacho declara `modo` 2B e o PRD dá superfície explícita ao escopo (ou o inverso: declara 2A e o PRD não dá superfície nenhuma) | **contestação de modo** | **PARE.** Devolva ao orquestrador com as linhas do PRD que mostram a superfície (ou a ausência dela) |
 | o PRD não diz, mas **o dono afirmou** e você tem o registro | **fato do cliente** | construa sobre ele e marque `client`. **Não** é palpite e **não** é síntese sua |
 | o PRD não diz e você **acha que sabe** | **palpite** | **proibido.** Vira lacuna marcada, nunca implementação silenciosa |
 
@@ -127,6 +134,8 @@ O trilho não é metáfora — é markup, e ele tem gramática definida. **Leia
 
 Exemplo real do que é contestação e não lacuna: o PRD dizia *"obrigatório **realizar** um teste de leitura facial in loco"*; o doc derivado dizia *"registrado **e aprovado**, reprovado trava"*. Isso não é ambiguidade — é uma regra de negócio inventada, que seria apresentada à cliente como se fosse dela.
 
+**Reflexividade — quando o PRD descreve o harness que te executa.** Cada estado marcado `prd` que afirma comportamento do harness exige **sonda** (comando + saída) antes de fechar o relatório. Sonda que desmente o PRD ⇒ contestação (`:117`). Você **não** renomeia o estado pela execução: a caneta é do juiz.
+
 ### Fase 4 · Construir com disciplina de token
 
 1. **Inline `variables.css` e `variables.dark.css` verbatim, e defina ZERO custom property nova.** *Verbatim* aqui significa **o arquivo inteiro, nome e valor, sem curar subconjunto** — não "os tokens que eu uso". Colar só o que você usa passa no auditor e mesmo assim está errado. Motivo não-óbvio: se um token inventado for definido inline, ele **funciona** e a divergência some — foi assim que 20 tokens fantasma passaram despercebidos. Com zero definição própria, **token inventado quebra à vista**.
@@ -139,14 +148,15 @@ Exemplo real do que é contestação e não lacuna: o PRD dizia *"obrigatório *
 
 **Obrigatória.** Não existe suíte de teste/lint/build aplicável a um HTML standalone — o que existe é isto:
 
-| verificação | comando / método |
-|---|---|
-| referência quebrada | `apply-design-tokens.mjs --check <dir> --dry` — rode-o de forma que ele veja **o seu artefato**, não o design system (ele resolve o diretório contra o `cwd`) |
-| fidelidade do contrato inlinado | **o auditor NÃO faz isto — é checagem separada e obrigatória.** Veja abaixo |
-| lógica de negócio | dirigir o fluxo no browser e capturar estado a cada passo |
-| ergonomia real | medir no viewport do dispositivo (alvos, sem scroll horizontal) |
-| erro de runtime | console do browser |
-| leitura visual | **olhar** o screenshot |
+| verificação | comando / método | modo |
+|---|---|---|
+| referência quebrada | `apply-design-tokens.mjs --check <dir> --dry` — rode-o de forma que ele veja **o seu artefato**, não o design system (ele resolve o diretório contra o `cwd`) | 2A/2B |
+| fidelidade do contrato inlinado | **o auditor NÃO faz isto — é checagem separada e obrigatória.** Veja abaixo | 2A/2B |
+| lógica de negócio | dirigir o fluxo no browser e capturar estado a cada passo | 2A |
+| ergonomia real | medir no viewport do dispositivo (alvos, sem scroll horizontal) | 2A |
+| erro de runtime | console do browser | 2A/2B |
+| leitura visual | **olhar** o screenshot | 2A/2B |
+| auditor de modelagem | `audit-ciclo-modelagem.py` — verifica o Ciclo (estados, transições, proveniência); em 2B é o **veredito**, não um checador a mais | 2A/2B |
 
 O último item não é redundante: na execução capturada, **olhar** pegou 2 defeitos que nenhuma medição pegou.
 
@@ -165,7 +175,7 @@ Compara **nome:valor**, não só nome. Saída esperada: **vazia, exit 0**. Qualq
 
 ### Fase 6 · Onde o artefato mora
 
-**O protótipo é produto: vai para o repo de produto.** O design system permanece **referência**. O índice do sistema **linka** o protótipo em "Provas de uso", com o texto declarando a fronteira.
+**O Ciclo mora onde a rodada declara — a casa usa `deliverables/lane-2a/` para a 2A; a 2B usa `deliverables/lane-2b/`.** `[S]` (convenção, não decisão) O design system permanece **referência**. O índice do sistema **linka** o protótipo em "Provas de uso", com o texto declarando a fronteira.
 
 Não importe fluxo de produto para dentro do padrão — *a casa é medida contra o padrão, nunca escrita dentro dele*.
 
@@ -234,13 +244,17 @@ O que a view de uma US precisa ter:
 
 O toggle de proveniência é **desligado por padrão** e a moldura `proto-*` é apresentação — nada dela é produto. Deixe isso escrito num comentário do arquivo, como o artefato de referência faz.
 
+### A forma do entregável · 2B
+
+Em modo 2B (ciclo sem tela) o esqueleto encolhe: `.proto-nav` tem **uma** aba só ("O ciclo"), e **não existe** `view-usNN` nenhuma — não há telas no escopo. Toda `.edge` é `is-pending` ou `is-orphan`; **zero** `is-actionable`, porque não há view para navegar. O `.gap-callout` é **obrigatório mesmo vazio**, com a frase que diz por que está vazio, e o `.legend` traz as quatro marcas mesmo com contagem zero — já é a regra do trilho em 2A (`:211`), e em 2B ela não relaxa.
+
 ## Fronteiras duras
 
 1. **Não decide regra de negócio.** A diferença entre *realizar* e *aprovar* vira pergunta marcada na tela — nunca implementação silenciosa.
 2. **Não preenche lacuna com palpite.** Marca *não atribuída*.
 3. **Não escreve no repo do design system** — exceto o link no índice.
 4. **Não escreve no artefato a montante** (PRD, ou o que vier antes de você). Contestação, não correção.
-5. **Não afirma sem rodar o auditor.** O relatório com refs/quebradas é obrigatório e vai junto com a entrega.
+5. **Não afirma sem rodar o auditor.** O relatório com refs/quebradas é obrigatório e vai junto com a entrega. Em modo 2B, "o auditor" são os dois — refs/quebradas e `audit-ciclo-modelagem.py` `[S]`.
 
 ## Checklist antes de entregar — as 10 armadilhas medidas
 
@@ -258,6 +272,8 @@ Todas foram cometidas de verdade na execução que gerou este processo. Passe po
 | 8 | Assumir tema claro | quem revisa fica desconfortável | escuro desde a entrega 1 |
 | 9 | Script de verificação improvisado | falso positivo/negativo em massa | rodar o instrumento oficial como controle |
 | 10 | Cor lida uma vez no load | tinta escura sobre fundo escuro após trocar tema | ler no momento do uso |
+| 11 | Estado batizado com o título da US | `state-name` == `edge-title` | nome literal do PRD ou lacuna |
+| 12 | `open == 0` sem frase que explique `[S]` | trilho fecha com zero transição órfã e nenhuma frase dizendo por quê | se `open` for zero, escreva a frase explicando — contagem zero sem explicação é tão suspeita quanto contagem alta |
 
 ## Formato do relatório final
 
@@ -268,7 +284,7 @@ Entregue sempre, e nesta ordem:
 3. **Transições** modeladas.
 4. **Lacunas**: cada uma nomeada, com o que o PRD não define.
 5. **Contestações**: cada uma com a afirmação do montante, a evidência, e o que ela contradiz. Se houver contestação, diga explicitamente que **parou** e o que não foi construído.
-6. **Verificação**: saída literal do auditor (refs/quebradas, tokens declarados × definidos), gates exercitados no browser, erros de console, viewports medidos.
+6. **Verificação**: em modo 2A, saída literal do auditor (refs/quebradas, tokens declarados × definidos), gates exercitados no browser, erros de console, viewports medidos. Em modo 2B, saída literal do `audit-ciclo-modelagem.py` + auditor de refs + diff de pares; "gates exercitados" vira "N/A — modo 2B", escrito, nunca omitido.
 7. **O que você NÃO fez** e por quê.
 
 Nunca reporte verificação em prosa ("os tokens estão ok"). Cole o número que o instrumento devolveu.

package/agents/presentation-engineer.md

@@ -51,14 +51,22 @@ Se requisitos não satisfeitos, MUST report bloqueio antes de iniciar.
 Este agente é **project-agnostic**. O dispatch prompt do orchestrator MUST conter:
 
 ```
-PROJECT_NAME: <ex: trc>
-DESIGN_SYSTEM_REPO: <absolute path>
-DELIVERABLES_REPO: <absolute path>
+PROJECT_NAME: <slug do projeto>
+DESIGN_SYSTEM_REPO: <absolute path — injetado pelo despacho>
+DELIVERABLES_REPO: <absolute path — injetado pelo despacho>
 TARGET_DECK: <subdir name dentro de DELIVERABLES_REPO>
 TARGET_AUDIENCE: <self-service | live-demo | hybrid>
 ```
 
-Se qualquer campo faltar, MUST `AskUserQuestion` antes de proceder. NEVER hardcode paths.
+**Falhar alto, não improvisar (S513, decisão do PM na S512).** Antes de qualquer leitura:
+`test -d "$DESIGN_SYSTEM_REPO" && test -d "$DELIVERABLES_REPO/$TARGET_DECK"` (Invariante 6 —
+probe, não inferência). Se **qualquer campo faltar** ou **qualquer path não existir no disco**,
+MUST **parar** e devolver ao orquestrador uma contestação nomeando o campo e o valor recebido
+(`AskUserQuestion` não está no teu conjunto de tools — não tente). NEVER hardcode paths; NEVER
+completar campo ausente com valor lembrado de outra corrida. A definição distribuída deste
+agente **não carrega default de cliente nenhum** — foi assim que um prefixo morto
+(`~/desenvolvimento/trc`, árvore apagada na S497) sobreviveu quatro releases no plugin
+instalado (medido S510, 4 ocorrências na 3.37.0 e na 3.37.1).
 
 ## Hard Rules — Design System Discipline
 
@@ -68,7 +76,7 @@ Se qualquer campo faltar, MUST `AskUserQuestion` antes de proceder. NEVER hardco
 2. MUST Read `$DESIGN_SYSTEM_REPO/components/<relevantes>.md` para componentes em uso
 3. MUST Read `$DESIGN_SYSTEM_REPO/anti-patterns.md` (8 itens "NÃO fazer")
 4. MUST diff `theme/styles/tokens.css` (deck) vs `tokens.md` (SD) — reportar divergências
-5. MUST documentar overrides com comentário inline `/* TRC override: <rationale> */`
+5. MUST documentar overrides com comentário inline `/* <PROJECT_NAME> override: <rationale> */`
 
 ### MUST NOT (Forbidden)
 
@@ -177,7 +185,7 @@ ${DELIVERABLES_REPO}/${TARGET_DECK}/.cobaia-evidence/
 └── COBAIA-REPORT.md           # report estruturado final
 ```
 
-MUST NOT salvar PNGs em outros locais (raiz do orchestrator repo, raiz do trc-platform, /tmp). Tudo dentro de `.cobaia-evidence/`. Cleanup é dever do agent, não do orchestrator.
+MUST NOT salvar PNGs em outros locais (raiz do orchestrator repo, raiz do repo de `$DELIVERABLES_REPO`, /tmp). Tudo dentro de `.cobaia-evidence/`. Cleanup é dever do agent, não do orchestrator.
 
 ### MUST validate exports
 
@@ -368,7 +376,7 @@ Use quando precisar grounding em doc autoritativa de Slidev/Vue/Tailwind antes d
 
 Standard workflow quando dispatched:
 
-1. **Validate dispatch context** — paths, target deck, audience. AskUserQuestion if missing.
+1. **Validate dispatch context** — paths, target deck, audience; `test -d` em cada path. Faltando ou inexistente: **pare e conteste** (ver "Falhar alto" acima).
 2. **Read SD canonical** — `tokens.md`, `anti-patterns.md`, components relevantes (batch parallel)
 3. **Read deck current state** — `slides.md`, theme overrides, current `tokens.css`
 4. **Diff deck vs SD** — gerar TOKEN-SYNC-REPORT.md se divergences existirem
@@ -500,6 +508,11 @@ MAY write ephemeral observations to `.claude/agent-memory/presentation-engineer/
 
 ## Examples
 
+> Os dois exemplos abaixo são de corridas reais de um cliente (TRC, S174). Os **paths absolutos
+> foram removidos** na S513: a árvore que citavam não existe desde a S497, e exemplo com path
+> absoluto numa definição distribuída vira default por leitura. O despacho injeta; a definição
+> não carrega.
+
 ### Example 1: Slide deck bug fix (S174 cobaia)
 
 **Dispatch prompt (mock):**
@@ -508,8 +521,8 @@ MAY write ephemeral observations to `.claude/agent-memory/presentation-engineer/
 Fix bugs visuais no slide deck TRC S174 antes do showcase ao vivo com TRC.
 
 PROJECT_NAME: trc
-DESIGN_SYSTEM_REPO: /home/cmac/desenvolvimento/trc/trc-design-system
-DELIVERABLES_REPO: /home/cmac/desenvolvimento/trc/trc-platform/docs/deliverables
+DESIGN_SYSTEM_REPO: <absolute path do DS do cliente — injetado pelo despacho>
+DELIVERABLES_REPO: <absolute path do repo de deliverables — injetado pelo despacho>
 TARGET_DECK: slide-deck
 TARGET_AUDIENCE: live-demo
 
@@ -552,8 +565,8 @@ Dados de produção (já conhecidos):
 Create new TRC one-pager deck for Phase 2 partnership pitch.
 
 PROJECT_NAME: trc
-DESIGN_SYSTEM_REPO: /home/cmac/desenvolvimento/trc/trc-design-system
-DELIVERABLES_REPO: /home/cmac/desenvolvimento/trc/trc-platform/docs/deliverables
+DESIGN_SYSTEM_REPO: <absolute path do DS do cliente — injetado pelo despacho>
+DELIVERABLES_REPO: <absolute path do repo de deliverables — injetado pelo despacho>
 TARGET_DECK: one-pager-phase2
 TARGET_AUDIENCE: hybrid (executive readers + presented sessions)
 

package/hooks/lib/capability-scanner.ts

@@ -619,6 +619,23 @@ function truncateSummary(summary: string, cap: number): string {
   return summary.length > cap ? `${summary.slice(0, cap)}…` : summary;
 }
 
+/**
+ * TD-318 (S514): the ONE field formatMemoryContext dereferences per entry.
+ * `readMemoryIndex`'s guard requires only `file:` (S480 contract, pinned by
+ * memory-index-silent-failure.test.ts case 5), so an entry with `file:` and
+ * no `summary:` reaches here — and `truncateSummary(undefined)` threw,
+ * the caller's try/catch swallowed it, and the WHOLE block vanished:
+ * measured on trc-platform-mobile, 1 of 140 entries → 0 injected, no
+ * INDISPONÍVEL line (S480 guards the read, not the format). One bad line
+ * must not zero the good ones beside it.
+ */
+function hasRenderableSummary(entry: MemoryEntry): boolean {
+  return typeof entry.summary === 'string';
+}
+
+/** Header line of the warning appended when entries were skipped (TD-318). */
+export const MEMORY_SKIPPED_WARNING_PREFIX = '- [AVISO] ';
+
 function countByType(list: MemoryEntry[]): Record<string, number> {
   const counts: Record<string, number> = {};
   for (const e of list) {
@@ -647,32 +664,44 @@ function countByType(list: MemoryEntry[]): Record<string, number> {
  * survived TASK-008's filter/quota, independent of the source index size.
  */
 export function formatMemoryContext(selected: MemoryEntry[], allEntries: MemoryEntry[]): string {
-  if (selected.length === 0) return '';
-
-  const selectedCounts = countByType(selected);
+  // TD-318: split BEFORE anything dereferences `summary`. Skipped entries
+  // are named in a trailing warning line so the author sees what to fix —
+  // the previous behaviour was a swallowed throw and an empty block.
+  const renderable = selected.filter(hasRenderableSummary);
+  const skipped = selected.filter((e) => !hasRenderableSummary(e));
+  const warning =
+    skipped.length > 0
+      ? `${MEMORY_SKIPPED_WARNING_PREFIX}${String(skipped.length)} entrada(s) sem 'summary:' pulada(s) ` +
+        `— conserte o índice: ${skipped.map((e) => e.file).join(', ')}`
+      : '';
+
+  if (renderable.length === 0) return warning ? `[MEMORY-CONTEXT] 0 memórias\n${warning}` : '';
+
+  const selectedCounts = countByType(renderable);
   const totalCounts = countByType(allEntries);
   const perTypeSummary = MEMORY_TYPES.map(
     (t) => `${t}: ${selectedCounts[t] ?? 0}/${totalCounts[t] ?? 0}`
   ).join(', ');
 
   const headerBase =
-    `[MEMORY-CONTEXT] ${selected.length} de ${allEntries.length} memórias ` +
+    `[MEMORY-CONTEXT] ${renderable.length} de ${allEntries.length} memórias ` +
     `(${perTypeSummary}); critério: cota mínima de 2 por tipo não-feedback + ` +
     `prioridade feedback→recência no restante`;
 
-  const availableForLines = AGGREGATE_CHAR_BUDGET - headerBase.length - SUFFIX_RESERVE;
+  const availableForLines =
+    AGGREGATE_CHAR_BUDGET - headerBase.length - SUFFIX_RESERVE - (warning ? warning.length + 1 : 0);
   const lines: string[] = [];
   let used = 0;
   let droppedByBudget = 0;
 
-  for (let i = 0; i < selected.length; i++) {
-    const entry = selected[i]!;
+  for (let i = 0; i < renderable.length; i++) {
+    const entry = renderable[i]!;
     const name = entry.file.replace(/\.md$/, '');
     const truncated = truncateSummary(entry.summary, PER_ENTRY_SUMMARY_CHAR_CAP);
     const line = `- [${entry.type}] ${name}: ${truncated}`;
 
     if (used + line.length + 1 > availableForLines) {
-      droppedByBudget = selected.length - i;
+      droppedByBudget = renderable.length - i;
       break;
     }
     lines.push(line);
@@ -684,7 +713,49 @@ export function formatMemoryContext(selected: MemoryEntry[], allEntries: MemoryE
       ? `${headerBase}; +${droppedByBudget} truncadas por orçamento de caracteres`
       : headerBase;
 
-  return [header, ...lines].join('\n');
+  return [header, ...lines, warning].filter(Boolean).join('\n');
+}
+
+// ─── Memory Index Validation (TD-318) ────────────────────
+
+/** One defect found by `validateMemoryIndexEntries`. */
+export interface MemoryIndexDefect {
+  /** 0-based position in the index; the file name when the entry has one. */
+  position: number;
+  file: string | null;
+  /** Field names that are missing or of the wrong type. */
+  missing: string[];
+}
+
+/**
+ * Full-shape validator for a memory index, meant to FAIL LOUD in CI/lint
+ * (TD-318) — the read-side guard (`isWellFormedMemoryEntry`) is
+ * deliberately minimal (S480), so this is where an author learns that an
+ * entry is missing `summary:` BEFORE it reaches a session. Checks every
+ * field the injection path dereferences: `file`, `type`, `summary`,
+ * `last_accessed` (strings) and `tags` (array). Pure: takes the parsed
+ * entries (either on-disk form, already unwrapped), returns defects, never
+ * throws.
+ */
+export function validateMemoryIndexEntries(entries: unknown[]): MemoryIndexDefect[] {
+  const defects: MemoryIndexDefect[] = [];
+  entries.forEach((value, position) => {
+    if (typeof value !== 'object' || value === null) {
+      defects.push({ position, file: null, missing: ['(não é um objeto)'] });
+      return;
+    }
+    const e = value as Record<string, unknown>;
+    const missing: string[] = [];
+    for (const field of ['file', 'type', 'summary', 'last_accessed']) {
+      const v = e[field];
+      if (typeof v !== 'string' || v.length === 0) missing.push(field);
+    }
+    if (!Array.isArray(e.tags)) missing.push('tags');
+    if (missing.length > 0) {
+      defects.push({ position, file: typeof e.file === 'string' ? e.file : null, missing });
+    }
+  });
+  return defects;
 }
 
 // ─── Memory Index Reading ────────────────────────────────

package/hooks/lib/security-gate-core.ts

@@ -0,0 +1,271 @@
+/**
+ * security-gate-core.ts — lógica PURA do gate honesto de commit (S505, ficha 3).
+ *
+ * Separado de `security-gate-honest.ts` de propósito: aquele arquivo tem um
+ * `main()` de topo que aguarda stdin, e importá-lo num teste trava o runner.
+ * A convenção anterior desta casa contornava isso RE-IMPLEMENTANDO a lógica
+ * dentro do teste (ver `tests/unit/hooks/post-implement.test.ts`), o que
+ * duplica a regra e deixa as duas cópias divergirem em silêncio — a família
+ * TD-232 que este repo persegue. Extrair o núcleo resolve os dois problemas:
+ * o teste importa o que RODA, e não uma cópia dele.
+ *
+ * Nada aqui faz IO. O `git show` e a saída do hook ficam no arquivo do hook.
+ */
+
+/** Abaixo disto, um veredito de L2 é fallback disfarçado, não análise. */
+export const L2_LATENCY_FLOOR_MS = 400;
+
+/** O que a L1 cobre — declarado, porque cobertura não-dita vira cobertura presumida. */
+export const L1_COVERAGE =
+  'literais de credencial no diff (chaves de provedor, tokens, blocos PEM, URLs com senha)';
+
+export type Verdict =
+  | { state: 'clean'; layer: string; detail: string }
+  | { state: 'findings'; layer: string; detail: string; hits: Finding[] }
+  | { state: 'not-analyzed'; layer: string; reason: string };
+
+export interface Finding {
+  rule: string;
+  file: string;
+  line: number;
+  evidence: string;
+}
+
+// ─────────────────────────────────────────────────────────────
+// L1 — padrões. Estreitos de propósito: cada regra que dispara
+// falso positivo em massa treina quem lê a ignorar, e um gate
+// ignorado é um gate desligado com aparência de ligado.
+// ─────────────────────────────────────────────────────────────
+export const SECRET_RULES: { rule: string; re: RegExp }[] = [
+  { rule: 'aws-access-key-id', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  { rule: 'anthropic-api-key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}/ },
+  { rule: 'openai-api-key', re: /\bsk-(?:proj-)?[A-Za-z0-9]{32,}\b/ },
+  { rule: 'github-token', re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/ },
+  { rule: 'slack-token', re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/ },
+  { rule: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { rule: 'npm-token', re: /\bnpm_[A-Za-z0-9]{36}\b/ },
+  { rule: 'private-key-block', re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
+  { rule: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
+  { rule: 'url-with-password', re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:[^\s:@/]{6,}@/i },
+];
+
+/**
+ * Marcas que indicam placeholder e não segredo real. Sem isto o gate grita em
+ * cima do `.env.example` e ensina o leitor a ignorá-lo.
+ */
+const PLACEHOLDER =
+  /(?:x{6,}|\.{3,}|<[^>]{2,}>|\$\{|EXAMPLE|PLACEHOLDER|YOUR_|CHANGEME|REDACTED|FAKE|DUMMY|\bTODO\b)/i;
+
+/** Mascara a evidência: o gate não pode ser o veículo que vaza o segredo que achou. */
+export function maskEvidence(s: string): string {
+  const t = s.trim().slice(0, 80);
+  return t.length <= 12 ? '***' : `${t.slice(0, 6)}…${t.slice(-4)} (${String(t.length)} ch)`;
+}
+
+/**
+ * Varre um diff unificado. Só linhas ADICIONADAS (`+`) — uma linha removida
+ * já está no histórico e culpar o commit que a REMOVE inverte o sinal.
+ */
+export function scanDiff(diff: string): Finding[] {
+  const out: Finding[] = [];
+  let file = '(desconhecido)';
+  let lineNo = 0;
+
+  for (const raw of diff.split('\n')) {
+    if (raw.startsWith('+++ b/')) {
+      file = raw.slice(6);
+      lineNo = 0;
+      continue;
+    }
+    if (raw.startsWith('@@')) {
+      const m = /\+(\d+)/.exec(raw);
+      lineNo = m ? parseInt(m[1], 10) - 1 : 0;
+      continue;
+    }
+    if (!raw.startsWith('+') || raw.startsWith('+++')) continue;
+    lineNo += 1;
+
+    const content = raw.slice(1);
+    if (PLACEHOLDER.test(content)) continue;
+
+    for (const { rule, re } of SECRET_RULES) {
+      const hit = re.exec(content);
+      if (hit) out.push({ rule, file, line: lineNo, evidence: maskEvidence(hit[0]) });
+    }
+  }
+  return out;
+}
+
+/**
+ * Detecta `git commit` — e NÃO `git commit --dry-run`, que não cria commit.
+ *
+ * Aceita opções globais com valor separado (`git -c user.name=x commit`), que a
+ * primeira versão desta função deixava passar: o `-c` consome o traço, mas o
+ * `user.name=x` seguinte não, e o `commit` deixava de casar. Pego por teste.
+ *
+ * LIMITAÇÃO CONHECIDA, declarada em vez de escondida: isto é casamento de
+ * texto, não parsing de shell. Um comando que apenas CONTENHA a frase
+ * (`ls "git commit"`) dispara o gate, que então descreve o HEAD corrente — um
+ * commit que não é daquele comando. É ruído, não risco: toda saída nomeia o que
+ * analisou, então o leitor vê sobre o que o veredito fala. Parsear shell de
+ * verdade custa mais do que o defeito que evita.
+ */
+export function isCommitCommand(command: string): boolean {
+  return /git\s+(?:-\S+(?:\s+\S+)?\s+)*commit\b/.test(command) && !/--dry-run\b/.test(command);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Núcleo
+// ─────────────────────────────────────────────────────────────
+
+/** O diff mais a declaração de COMO foi obtido — cobertura não-dita vira cobertura presumida. */
+export interface DiffSource {
+  text: string;
+  /** Ex.: "git show HEAD" · "git show -m --first-parent HEAD (merge de 2 pais)". */
+  how: string;
+}
+
+export interface GateDeps {
+  getDiff: () => DiffSource;
+  /** L2 devolve null enquanto não houver credencial decidida (ficha 3, item d). */
+  runSemantic: (diff: string) => { hits: Finding[]; elapsedMs: number } | null;
+  l2UnavailableReason: () => string;
+}
+
+export function evaluate(deps: GateDeps): Verdict[] {
+  const verdicts: Verdict[] = [];
+
+  let src: DiffSource;
+  try {
+    src = deps.getDiff();
+  } catch (e) {
+    // A falha de leitura do diff é NÃO ANALISEI para TODAS as camadas.
+    // Este é o ponto exato em que o plugin medido diria "limpo".
+    const reason = `não consegui ler o diff do commit (${(e as Error).message.slice(0, 80)})`;
+    return [
+      { state: 'not-analyzed', layer: 'L1', reason },
+      { state: 'not-analyzed', layer: 'L2', reason },
+    ];
+  }
+
+  const diff = src.text;
+  if (!diff.trim()) {
+    // Distinguir POR QUE veio vazio: um merge sem conflito e um `git show` que
+    // falhou pedem leituras diferentes, e medida que não separa estados que
+    // pedem ações diferentes é medida errada (regra de desenho da S480).
+    const reason =
+      `o diff veio vazio via ${src.how} — nada para analisar. ` + 'Isto NÃO é o mesmo que limpo';
+    return [
+      { state: 'not-analyzed', layer: 'L1', reason },
+      { state: 'not-analyzed', layer: 'L2', reason },
+    ];
+  }
+
+  // ── L1 ──
+  const hits = scanDiff(diff);
+  const cover = `${L1_COVERAGE} · via ${src.how}`;
+  verdicts.push(
+    hits.length
+      ? { state: 'findings', layer: 'L1', detail: cover, hits }
+      : { state: 'clean', layer: 'L1', detail: cover }
+  );
+
+  // ── L2 ──
+  const sem = deps.runSemantic(diff);
+  if (sem === null) {
+    verdicts.push({ state: 'not-analyzed', layer: 'L2', reason: deps.l2UnavailableReason() });
+  } else if (sem.elapsedMs < L2_LATENCY_FLOOR_MS) {
+    // A guarda de latência. Não confia no veredito: análise semântica de um
+    // diff não fecha nesse tempo, então isto é fallback, não resultado.
+    verdicts.push({
+      state: 'not-analyzed',
+      layer: 'L2',
+      reason:
+        `devolveu veredito em ${String(sem.elapsedMs)} ms, abaixo do piso de ${String(L2_LATENCY_FLOOR_MS)} ms — ` +
+        'tratado como fallback, não como análise',
+    });
+  } else {
+    verdicts.push(
+      sem.hits.length
+        ? { state: 'findings', layer: 'L2', detail: 'análise semântica', hits: sem.hits }
+        : { state: 'clean', layer: 'L2', detail: 'análise semântica' }
+    );
+  }
+
+  return verdicts;
+}
+
+/**
+ * A linha ÚNICA que o humano vê (`systemMessage`), contra o texto por camada que
+ * só chega ao modelo (`additionalContext`).
+ *
+ * Achado do Manager na S505, e é o coração da ficha: **falhar alto significa a
+ * PESSOA ver.** Um gate cujo aviso só alcança o modelo tem o mesmo efeito
+ * prático do plugin que ele substitui — ninguém é avisado. Por isso a saída sai
+ * pelos dois canais.
+ *
+ * Reporta o PIOR estado, porque é o único que muda o que a pessoa faz agora:
+ * achados > nada analisado > cobertura parcial > tudo analisado e limpo.
+ */
+export function renderShort(verdicts: Verdict[]): string {
+  const findings = verdicts.filter((v) => v.state === 'findings');
+  if (findings.length) {
+    const n = findings.reduce((a, v) => a + (v.state === 'findings' ? v.hits.length : 0), 0);
+    const layers = findings.map((v) => v.layer).join('+');
+    return `SECURITY-GATE: ${String(n)} achado(s) em ${layers} — confira antes de publicar`;
+  }
+
+  const analyzed = verdicts.filter((v) => v.state !== 'not-analyzed').map((v) => v.layer);
+  const skipped = verdicts.filter((v) => v.state === 'not-analyzed').map((v) => v.layer);
+
+  if (!analyzed.length) {
+    return 'SECURITY-GATE: NENHUMA camada analisou o commit — isto NÃO é "limpo", é ausência de análise';
+  }
+  if (skipped.length) {
+    return `SECURITY-GATE: cobertura PARCIAL — ${analyzed.join('+')} analisou, ${skipped.join('+')} não`;
+  }
+  return `SECURITY-GATE: ${analyzed.join('+')} analisou, sem achados`;
+}
+
+/**
+ * Renderiza. Nunca produz a frase "no security issues found" nem equivalente
+ * global: o veredito é sempre por camada, sempre com a cobertura ao lado.
+ */
+export function render(verdicts: Verdict[]): string {
+  const lines = ['[SECURITY-GATE] Revisão do commit — veredito por camada:'];
+
+  for (const v of verdicts) {
+    if (v.state === 'clean') {
+      lines.push(`  ${v.layer} ANALISADO — LIMPO · cobertura: ${v.detail}`);
+    } else if (v.state === 'findings') {
+      lines.push(
+        `  ${v.layer} ANALISADO — ${String(v.hits.length)} ACHADO(S) · cobertura: ${v.detail}`
+      );
+      for (const h of v.hits.slice(0, 10)) {
+        lines.push(`      ${h.rule} · ${h.file}:${String(h.line)} · ${h.evidence}`);
+      }
+      if (v.hits.length > 10) lines.push(`      … e mais ${String(v.hits.length - 10)}`);
+    } else {
+      lines.push(`  ${v.layer} NÃO ANALISEI — ${v.reason}`);
+    }
+  }
+
+  const analyzed = verdicts.filter((v) => v.state !== 'not-analyzed').map((v) => v.layer);
+  const skipped = verdicts.filter((v) => v.state === 'not-analyzed').map((v) => v.layer);
+
+  if (!analyzed.length) {
+    lines.push(
+      '  ⚠ NENHUMA camada analisou este commit. Isto NÃO é "limpo" — é ausência de informação.'
+    );
+  } else if (skipped.length) {
+    lines.push(
+      `  ⚠ Cobertura PARCIAL: ${analyzed.join('+')} rodou, ${skipped.join('+')} não. ` +
+        'O que não foi analisado não está limpo — está por analisar.'
+    );
+  }
+
+  if (verdicts.some((v) => v.state === 'findings')) {
+    lines.push('  → Confira antes de publicar. O commit local já existe; nada foi bloqueado.');
+  }
+  return lines.join('\n');
+}