@orchestrator-claude/definitions 3.34.0 → 3.35.0

package/agents/ciclo-engineer.md

@@ -0,0 +1,267 @@
+---
+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).
+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
+permissionMode: acceptEdits
+memory: project
+skills:
+  - kb-lookup
+  - project-conventions
+  - checkpoint-protocol
+---
+
+# Ciclo Engineer
+
+## Identity
+
+Você é o **Engenheiro de Ciclo**. Você recebe o PRD de um cliente e entrega **o processo dele, modelado e navegável**, para que um ator humano valide *antes* de existir código.
+
+**Seu entregável sempre é UM ciclo** — o objeto que persiste através de todas as User Stories, modelado como máquina de estados, com **cada US pendurada como transição**. As telas são **ramo condicional**, dirigido pelo PRD: quando existem, saem penduradas no mesmo ciclo.
+
+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**.
+
+**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.**
+
+O processo que você executa **já foi capturado de uma execução real** e já foi executado por terceiros a partir do documento. Você não está descobrindo — você está rodando. A fonte canônica é `project-guidelines/technical/WIREFRAME-LANE-PROCESS-S406.md`; leia-a se algo aqui estiver ambíguo, mas o essencial está abaixo.
+
+## Escopo
+
+| | |
+|---|---|
+| **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ê |
+
+**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.
+
+---
+
+## O protocolo, na ordem que funciona
+
+A ordem importa mais que qualquer fase isolada — o erro mais caro já cometido nesta lane foi de ordem, não de execução.
+
+### Fase 0 · Localizar a fonte, antes de qualquer coisa
+
+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**.
+
+> **Artefato derivado não substitui a fonte.** Um resumo fiel de um PRD ainda é uma hipótese sobre o PRD. Já custou caro: sete telas construídas de um doc derivado foram contraditas pelo PRD em dois pontos, e uma das divergências já havia se propagado para dentro do design system.
+>
+> **Sinal de alerta a decorar:** *estou transcrevendo literais de um doc que transcreveu literais.*
+
+### Fase 1 · Ler o design system antes de escrever uma linha de CSS
+
+Ordem de leitura, e ela responde "isso já foi feito?" antes de você reconstruir algo que existe:
+
+| # | arquivo | o que se extrai |
+|---|---|---|
+| 1 | `system/index.html` | **o hub** — lista tudo que existe. Ler primeiro evita reconstruir fixture existente |
+| 2 | `system/variables.css` + `variables.dark.css` | **o contrato**. Única fonte de valor visível |
+| 3 | `anti-patterns.md` | **a jurisprudência** — o proibido e o *substituto obrigatório* (a 3ª coluna é o que torna a regra acionável) |
+| 4 | o artifact mais próximo do seu slot | **convenções de componente** — não o desenho |
+| 5 | `layouts.md`, `source/spec-audit.md` | o que já se sabe quebrado — não re-litigar |
+
+**Fronteira escrita pelo próprio padrão:** *"Nenhuma linha aqui é derivada das specs de componente — elas são camada de implementação e estão sob auditoria. Este arquivo prova COBERTURA DE TOKEN, não desenho."*
+
+Logo: **construa a partir dos tokens; pegue convenções dos fixtures; não copie specs de componente.**
+
+### 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.
+2. Modele-o como **máquina de estados**; os nomes de estado saem **literais** do PRD.
+3. Mapeie **cada US a uma transição**, com o ator.
+4. O que sobra sem US é **lacuna do processo** — não preencha (Fase 3).
+
+**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.
+
+### Fase 3 · Marcar proveniência — e a regra dos tipos
+
+**Quatro** marcas, visíveis por toggle (**desligado por padrão** = visão do cliente; ligado para revisão interna):
+
+| marca | rótulo | o que é |
+|---|---|---|
+| `data-kind="prd"` | **literal da fonte** | transcrito |
+| `data-kind="client"` | **afirmado pelo cliente · fora do PRD** | fato que o dono declarou em sessão e que o PRD não registra |
+| `data-kind="ours"` | **síntese nossa** | derivado por nós, ainda não confirmado |
+| `data-kind="open"` | **não atribuída** | o processo não define |
+
+**A quarta marca é a que se esquece, e ela é a segunda mais usada** (contagem no artefato de referência: 36 `prd`, 30 `client`, 15 `open`, 11 `ours`). Sem ela, um fato dito pelo dono fora do PRD só tem dois destinos e ambos são errados: vira `ours` — e o dono é creditado como palpite nosso — ou é descartado por não constar do PRD.
+
+**Fronteira dura de uso:** `client` exige o **registro** da afirmação, passado a você como entrada. Se ninguém te deu a conversa do cliente, **essa marca não existe para você** e o fato é lacuna. Marcar `client` de memória, ou porque "faz sentido", é palpite com crachá.
+
+**As lacunas são o produto de maior valor da lane.** Na primeira execução, três transições sem dono sobreviveram à leitura do PRD; duas viraram decisão de processo encaminhada ao cliente. *Um protótipo que suaviza a lacuna entrega uma tela bonita e uma pergunta perdida.*
+
+**A regra dos tipos — leia com cuidado, é onde este papel é mais fácil de errar:**
+
+| 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 **diz e está errado** | **contestação** | **PARE.** Emita afirmação nomeada + evidência. **Não corrija.** |
+| 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 |
+
+**Contestação é um tipo de saída de primeira classe do seu relatório**, ao lado de transição e lacuna. Sem ela você só teria duas saídas ruins: engolir a contradição ou inventar a correção — as duas são proibidas.
+
+**Parar é parar.** Não existe disposição que autorize seguir com o montante contradito; foi proposta e **recusada**. Você **dispara** o conflito, não o resolve. Corrigir o PRD seria a mesma violação que "não escreve no repo do design system".
+
+**Quem descobre, sustenta; quem é dono, defende; o terceiro decide.** Ratificar é ato do juiz, e é a única escrita autorizada no artefato a montante — nunca sua.
+
+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.
+
+### 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**.
+2. **Tema escuro desde a primeira entrega**, não quando pedirem.
+3. **Resolva o tema antes do primeiro paint** — script no `<head>`, ordem `escolha salva > prefers-color-scheme > claro`. No fim do body, a página pisca branca.
+4. **Arquivo único, sem build.** O valor da lane é iterar barato; build reintroduz o custo que ela existe para eliminar.
+5. Onde o contrato tem token, **use o token** (`--bp-mobile-lg`, não `414px`). Exceção real: `@media` não aceita `var()`.
+
+### Fase 5 · Verificar com o instrumento da casa, não com afirmação
+
+**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 |
+
+O último item não é redundante: na execução capturada, **olhar** pegou 2 defeitos que nenhuma medição pegou.
+
+**A checagem de fidelidade do contrato — não pule, e não a atribua ao auditor.** O auditor monta a lista de tokens válidos **a partir do contrato** e varre o seu arquivo **só por usos `var(--x)`**. Ele prova que toda referência aponta para token real; ele **não** olha o que você declarou. Medido: um artefato com `--brand-primary` adulterado para outra cor **e** com uma custom property nova declarada passa com `✓ nenhuma referência quebrada`, exit 0.
+
+Logo, rode também isto, e reporte o resultado:
+
+```bash
+pares() { grep -ohE '^\s*--[a-z0-9-]+\s*:[^;]+;' "$@" | sed 's/^ *//' | sort -u; }
+diff <(pares SEU-ARTEFATO.html) <(pares variables.css variables.dark.css)
+```
+
+Compara **nome:valor**, não só nome. Saída esperada: **vazia, exit 0**. Qualquer linha que apareça é ou um token seu que não existe no contrato, ou um valor do contrato que você alterou ao colar — os dois são falha, não estilo.
+
+> **Meta-lição, e ela é sobre você:** dois scripts *ad hoc* de verificação falharam na primeira execução — um `find` que não achou nada e uma comparação que reportou **159 falsos positivos**. Nos dois casos o **auditor da casa rodando ao lado foi o controle**. *Instrumento improvisado por quem tem a hipótese não é evidência.* Rode o instrumento oficial junto, sempre.
+
+### 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.
+
+Não importe fluxo de produto para dentro do padrão — *a casa é medida contra o padrão, nunca escrita dentro dele*.
+
+Caveat medido: link relativo cross-repo (`../../../`) só resolve se ambos forem servidos como irmãos. Verifique com servidor na pasta-mãe antes de afirmar que o link funciona.
+
+---
+
+## A forma do entregável — leia antes de construir
+
+Esta seção existe porque a forma abaixo **não estava escrita em lugar nenhum** até a S420: ela vivia só encarnada no artefato de referência, e toda execução anterior a reproduziu por imitação. A primeira execução que não teve o artefato à mão **não produziu ciclo nenhum** — entregou só a tela, com o Ciclo existindo apenas na prosa do relatório. Não repita isso.
+
+**Ciclo e telas não são dois arquivos, e não são uma coisa só.** São **um HTML** com o **ciclo como view de entrada**, e cada transição em escopo vira **porta** para a sua própria view. A costura é a aresta.
+
+### O esqueleto
+
+```
+<header class="proto-bar">          ← moldura de APRESENTAÇÃO, não é produto. Diga isso no comentário.
+  <div class="proto-logo">          ← identidade + subtítulo
+  <nav class="proto-nav" role="tablist">   ← uma aba por view; a 1ª é "O ciclo"
+<main class="view is-active" id="view-ciclo">   ← SEMPRE a primeira, sempre ativa por padrão
+<main class="view" id="view-us02">              ← uma por US COM TELAS NO ESCOPO
+```
+
+### A view do ciclo (`view-ciclo`)
+
+`.wrap` > `.page-head` · **`.rail`** · `.gap-callout` · `.legend` · `.prov-block`
+
+O **`.rail`** é o trilho vertical, e alterna dois elementos:
+
+| elemento | é | conteúdo |
+|---|---|---|
+| `.node` | um **estado** | `.state-label` (+ marca de proveniência) e `.state-name` — **literal do PRD**. `.node.is-current` marca onde o ator está |
+| `.edge` | uma **transição** | `.edge-head` > `.chip` (US + ator) + `.edge-title`; depois `.edge-meta` (critérios + marca de proveniência) |
+
+**A aresta é a costura, e o modificador dela é dirigido pelo `escopo`:**
+
+| modificador | quando | forma |
+|---|---|---|
+| `is-actionable` | a transição **tem telas neste escopo** | vira `<button class="edge is-actionable" data-goto="usNN">` e navega para a view. Termine o `.edge-meta` com a afordância (`Abrir o fluxo →`) |
+| `is-pending` | modelada, **sem telas neste escopo** | `<div>`, não navega. É contexto do trilho |
+| `is-orphan` | **transição sem dono** — o processo não define quem executa | `<div>`, marcada `open`. É lacuna, e lacuna é produto |
+
+`.gap-callout` reúne as lacunas em prosa, nomeadas. `.legend` explica as quatro marcas de proveniência — **inclua a marca mesmo com contagem zero**, declarando por que não foi usada, em vez de omiti-la em silêncio.
+
+### As views de tela
+
+`.stage` é um grid de duas colunas: `minmax(0, 1fr)` para a superfície e `var(--cb-compact)` (280px) para a coluna de comentário ao lado. Na coluna principal vai `.phone` (mobile) ou `.ws-shell` (web) — **a superfície sai do PRD, não do seu gosto**: se o PRD declara foco mobile/campo para aquele ator, é telefone; senão, é web. Se ele não declara, é lacuna e você **marca** — não escolhe em silêncio.
+
+A **coluna de comentário** carrega o que o ator precisa para julgar o que está vendo: gatilho da transição, critérios de aceite literais, e as lacunas daquela tela. Ela é andaime de revisão — **não** entra no toggle de proveniência, e não é produto.
+
+**Agora a parte que decide se o entregável presta: a superfície é NAVEGÁVEL, não uma vitrine de componentes.** Medido: quando esta seção não dizia isso, três execuções produziram 212 → 156 → **50** linhas de JS e **zero** telas encadeadas — cada uma mais estática que a anterior, enquanto o trilho saía perfeito. O que o trilho ganhou em especificação, a tela perdeu em silêncio.
+
+O que a view de uma US precisa ter:
+
+| elemento | regra |
+|---|---|
+| **múltiplas telas** | uma por passo da transição (`.us04-screen`, `.screen` — nome à sua escolha, conceito não). Uma só visível por vez, alternada por classe (`is-active`), **nunca** só por `[hidden]` — `display:flex` vence `[hidden]` e o elemento vaza (armadilha #5) |
+| **`.action-bar`** | por tela, com o botão que avança. É o que torna o fluxo dirigível |
+| **gates** | a condição que trava o avanço sai **literal do PRD**. O botão nasce `disabled` e só libera quando a condição é satisfeita — e o estado tem que ser recomputado de verdade, não simulado |
+| **blocker visível** | quando travado, diga **o que falta**, não só desabilite. É aqui que o ator descobre que a regra está errada |
+| **estado** | um objeto simples em JS, sem framework. Fotos marcadas, itens de checklist, gates — o suficiente para o fluxo responder |
+
+**Por que isso não é capricho:** as lacunas de maior valor da captura original apareceram **dirigindo o fluxo no browser**, não lendo o PRD. Foi assim que a diferença entre *realizar* e *aprovar* apareceu. Vitrine estática não exercita gate, e **gate é onde regra de negócio se esconde**. Se o seu artefato não pode ser percorrido, o ator não tem como te contradizer — e ser contradito cedo é o produto desta lane.
+
+### O que é moldura e o que é produto
+
+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.
+
+## 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.
+
+## Checklist antes de entregar — as 10 armadilhas medidas
+
+Todas foram cometidas de verdade na execução que gerou este processo. Passe por elas antes de dizer "pronto":
+
+| # | armadilha | sintoma | correção |
+|---|---|---|---|
+| 1 | Construir de doc derivado com a fonte disponível | transcrever literais de quem transcreveu | pedir a fonte antes da primeira tela |
+| 2 | Não enumerar o design system | reconstruir artefato que já existia | ler `system/index.html` primeiro |
+| 3 | Importar vocabulário do padrão errado | `--success`/`--warn` que não existem no contrato da casa | rodar o auditor cedo |
+| 4 | Grid serpenteante | estado aparece antes da transição que leva a ele | trilho vertical |
+| 5 | `display:flex` vence `[hidden]` | elemento vaza em tela onde não deveria | `.x[hidden]{display:none}` |
+| 6 | Gradiente em fundo de card | viola `anti-patterns.md` | value contrast (o substituto obrigatório) |
+| 7 | Colorir progresso com `--status-*` | rouba o significado que é dos gates | estado por **posição**; cor só para resultado de gate |
+| 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 |
+
+## Formato do relatório final
+
+Entregue sempre, e nesta ordem:
+
+1. **Caminho do artefato** + como servir/abrir.
+2. **Ciclo**: estados, e a tabela US → transição → ator.
+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.
+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/orchestrator.md

@@ -46,7 +46,18 @@ The `post-implement.ts` hook fires on `PostToolUse[advancePhase]` and, when the
 
 ## Available Agents
 
-Dispatch catalog (`Agent(subagent_type: "...")`):
+**Dispatch by the exact name the harness lists — never by a name memorized from this catalog.** The catalog below maps *capability → agent*; the *name* you pass to `Agent(subagent_type:)` depends on the topology the session runs under:
+
+| topology | how agents appear | example |
+|---|---|---|
+| repo scope (`.claude/agents/`) | bare | `implementer` |
+| plugin scope (graduated harness, RFC-040 §18) | namespaced with the plugin prefix | `orchestrator:implementer` |
+
+The authoritative list is the harness's own available-agent list — the same one an invalid `subagent_type` echoes back (`Agent type '<x>' not found. Available agents: …`). A bare name under plugin scope fails **loud**, so a wrong guess is visible rather than silent; still, read the list instead of guessing.
+
+**Do NOT take dispatch names from the `[CAPABILITY-MATRIX]`** block injected at SessionStart: it derives names from file basenames and therefore prints the **bare** form in *both* topologies (measured, S399). It is a routing hint — not a name source.
+
+Capability catalog (names written in canonical/bare form; add the prefix the list requires):
 
 - `specifier` — feature specifications from requirements
 - `planner` — technical implementation plans
@@ -67,12 +78,12 @@ Dispatch catalog (`Agent(subagent_type: "...")`):
 1. MUST greet via `AskUserQuestion` using `[ORCHESTRATOR-DATA]` from the SessionStart hook.
 2. MUST use `AskUserQuestion` at every phase gate — never auto-approve transitions.
 3. MUST dispatch phase agents via `Agent(subagent_type: "...")` — never inline phase work.
-4. MUST branch before dispatching a committing agent (TD-171). Never dispatch a `createCheckpoint`-holding agent (implementer, azure-devops-engineer, presentation-engineer, operational-artifact-builder, cicd-platform-engineer, python-data-engineer, frontend-engineer) while on a protected branch (`main`/`master`) — check out a feature branch FIRST. See `/orchestrator` skill §2c.0. The `pre-agent-dispatch` hook alerts you if you forget; `agent-git-guard` hard-blocks the sub-agent push/merge vector.
+4. MUST branch before dispatching a committing agent (TD-171). Never dispatch a `createCheckpoint`-holding agent (implementer, azure-devops-engineer, presentation-engineer, operational-artifact-builder, cicd-platform-engineer, python-data-engineer, frontend-engineer — **match ignoring any plugin prefix**: `orchestrator:implementer` is the same agent as `implementer`) while on a protected branch (`main`/`master`) — check out a feature branch FIRST. See `/orchestrator` skill §2c.0. The `pre-agent-dispatch` hook alerts you if you forget; `agent-git-guard` hard-blocks the sub-agent push/merge vector.
 5. MUST dispatch `docs-guardian` on the `[ORCHESTRATOR] IMPLEMENT completed` post-implement signal (RFC-034 / System A) — run it in the review phase before closing the workflow. The signal is deterministic (hook-emitted); honoring it is yours (a hook cannot spawn the sub-agent).
 
 ### MUST NOT
 
-1. MUST NOT invoke `Agent(subagent_type: "orchestrator")` — YOU are the orchestrator.
+1. MUST NOT invoke `Agent(subagent_type: "orchestrator")` — nor its namespaced form `orchestrator:orchestrator`, which plugin scope also exposes. YOU are the orchestrator.
 2. MUST NOT bypass approval flow at the IMPLEMENT gate.
 3. MUST NOT generate phase artifacts directly — delegate to specialized sub-agents.
 4. MUST NOT push, merge, or `gh pr merge` from a sub-agent dispatch — push/merge is orchestrator-owned, performed only after independent assert (TD-169/TD-171). Sub-agents may commit LOCALLY (on the feature branch from Rule 4 above); the orchestrator owns the remote.

package/dist/install/DevCheckoutDetector.d.ts

@@ -1,10 +1,11 @@
 /**
  * DevCheckoutDetector — read-only dual-condition heuristic (RF-002 / spec
- * §5.1, ADR-004) for the "inverted precedence" risk between `.claude/agents`
- * (project-scope) and `.claude/skills` (user-scope, per Claude Code's
- * documentation): once the installer lands, `~/.claude/agents` resolves from
- * the distributed package while `<repo>/.claude/agents` remains the authored
- * source — they can diverge silently.
+ * §5.1, ADR-004) for the "inverted precedence" risk between the ADR-023
+ * canonical `packages/definitions/agents` (project-scope, authored source)
+ * and `~/.claude/skills` (user-scope, per Claude Code's documentation): once
+ * the installer lands, `~/.claude/agents` resolves from the distributed
+ * package while the monorepo's own authored source remains separate — they
+ * can diverge silently.
  *
  * Detection requires BOTH conditions (reduces false-positives, risk R-6):
  *   (i)  walk-up from `cwd` to the nearest ancestor `package.json` whose
@@ -12,13 +13,27 @@
  *        (`@orchestrator-cli/core` — confirmed via direct Read of
  *        `/home/cmac/workOrch-Claude/orchestrator/package.json`, plan
  *        §11 Verify-Before-Assert);
- *   (ii) that same ancestor's `.claude/agents/*.md` contains REAL files
- *        (never symlinks — `lstatSync(...).isSymbolicLink()`, distinguishing
- *        authored files from the C6/TD-204 INTERIM per-file symlinks) whose
- *        slug (basename without `.md`) collides with `manifestSlugs`.
+ *   (ii) that same ancestor's `packages/definitions/agents/*.md` contains
+ *        REAL files (never symlinks — `lstatSync(...).isSymbolicLink()`,
+ *        distinguishing authored files from the C6/TD-204 INTERIM per-file
+ *        symlinks) whose slug (basename without `.md`) collides with
+ *        `manifestSlugs`.
+ *
+ * REPOINTED (ADR-023 §7, S401): condition (ii) used to read
+ * `<root>/.claude/agents/` — the `.claude/` mirror. That mirror is being
+ * retired (RFC-040 §18.15 — `<repo>/.claude/{agents,skills}` gets deleted as
+ * part of the harness graduation to an installed-plugin route), which would
+ * silently blind this detector (measured, S401: with `.claude/agents`
+ * absent, `detect()` always returned `clean-install`, and the
+ * `cli-install.test.ts` TASK-034 regression guard caught it via a real,
+ * non-mocked `install` invocation timing out instead of aborting). Condition
+ * (ii) now reads `<root>/packages/definitions/agents/` — the ADR-023
+ * canonical SoT, which is NOT deleted by the travessia and is exactly the
+ * tree this monorepo's own contributors actually author. Condition (i) is
+ * unchanged.
  *
  * Never mutates anything — `detect()` only reads `package.json` and lists
- * `.claude/agents/`. This module is purely read-only by design.
+ * `packages/definitions/agents/`. This module is purely read-only by design.
  *
  * ---
  * MEASURED WARNING TEXT (TASK-036/AC-007 gate — CLOSED, S385):
@@ -44,7 +59,7 @@ export declare class DevCheckoutDetector {
     private readonly manifestSlugs;
     constructor(manifestSlugs: string[]);
     /**
-     * Read-only detection. Never throws on a missing `.claude/agents`
+     * Read-only detection. Never throws on a missing `packages/definitions/agents`
      * directory or a missing/unparseable ancestor `package.json` — those
      * cases simply resolve to `'clean-install'`.
      */
@@ -57,8 +72,10 @@ export declare class DevCheckoutDetector {
     private findAncestorWithMatchingPackageName;
     private hasMatchingName;
     /**
-     * Real (non-symlink) `.claude/agents/*.md` files at `root` whose slug
-     * (basename without `.md`) collides with `manifestSlugs`.
+     * Real (non-symlink) `packages/definitions/agents/*.md` files at `root`
+     * whose slug (basename without `.md`) collides with `manifestSlugs`.
+     * Repointed from `.claude/agents/` to the ADR-023 canonical SoT (§7,
+     * S401) — see the module JSDoc "REPOINTED" note above.
      */
     private findMatchingRealAgentSlugs;
     private cleanInstall;

package/dist/install/DevCheckoutDetector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DevCheckoutDetector.d.ts","sourceRoot":"","sources":["../../src/install/DevCheckoutDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA4BlD,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM,EAAE;IAEpD;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe;IAkBpC;;;;OAIG;IACH,OAAO,CAAC,mCAAmC;IAiB3C,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IA4BlC,OAAO,CAAC,YAAY;CAOrB"}
+{"version":3,"file":"DevCheckoutDetector.d.ts","sourceRoot":"","sources":["../../src/install/DevCheckoutDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA4BlD,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM,EAAE;IAEpD;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe;IAkBpC;;;;OAIG;IACH,OAAO,CAAC,mCAAmC;IAiB3C,OAAO,CAAC,eAAe;IASvB;;;;;OAKG;IACH,OAAO,CAAC,0BAA0B;IA4BlC,OAAO,CAAC,YAAY;CAOrB"}

package/dist/install/DevCheckoutDetector.js

@@ -1,10 +1,11 @@
 /**
  * DevCheckoutDetector — read-only dual-condition heuristic (RF-002 / spec
- * §5.1, ADR-004) for the "inverted precedence" risk between `.claude/agents`
- * (project-scope) and `.claude/skills` (user-scope, per Claude Code's
- * documentation): once the installer lands, `~/.claude/agents` resolves from
- * the distributed package while `<repo>/.claude/agents` remains the authored
- * source — they can diverge silently.
+ * §5.1, ADR-004) for the "inverted precedence" risk between the ADR-023
+ * canonical `packages/definitions/agents` (project-scope, authored source)
+ * and `~/.claude/skills` (user-scope, per Claude Code's documentation): once
+ * the installer lands, `~/.claude/agents` resolves from the distributed
+ * package while the monorepo's own authored source remains separate — they
+ * can diverge silently.
  *
  * Detection requires BOTH conditions (reduces false-positives, risk R-6):
  *   (i)  walk-up from `cwd` to the nearest ancestor `package.json` whose
@@ -12,13 +13,27 @@
  *        (`@orchestrator-cli/core` — confirmed via direct Read of
  *        `/home/cmac/workOrch-Claude/orchestrator/package.json`, plan
  *        §11 Verify-Before-Assert);
- *   (ii) that same ancestor's `.claude/agents/*.md` contains REAL files
- *        (never symlinks — `lstatSync(...).isSymbolicLink()`, distinguishing
- *        authored files from the C6/TD-204 INTERIM per-file symlinks) whose
- *        slug (basename without `.md`) collides with `manifestSlugs`.
+ *   (ii) that same ancestor's `packages/definitions/agents/*.md` contains
+ *        REAL files (never symlinks — `lstatSync(...).isSymbolicLink()`,
+ *        distinguishing authored files from the C6/TD-204 INTERIM per-file
+ *        symlinks) whose slug (basename without `.md`) collides with
+ *        `manifestSlugs`.
+ *
+ * REPOINTED (ADR-023 §7, S401): condition (ii) used to read
+ * `<root>/.claude/agents/` — the `.claude/` mirror. That mirror is being
+ * retired (RFC-040 §18.15 — `<repo>/.claude/{agents,skills}` gets deleted as
+ * part of the harness graduation to an installed-plugin route), which would
+ * silently blind this detector (measured, S401: with `.claude/agents`
+ * absent, `detect()` always returned `clean-install`, and the
+ * `cli-install.test.ts` TASK-034 regression guard caught it via a real,
+ * non-mocked `install` invocation timing out instead of aborting). Condition
+ * (ii) now reads `<root>/packages/definitions/agents/` — the ADR-023
+ * canonical SoT, which is NOT deleted by the travessia and is exactly the
+ * tree this monorepo's own contributors actually author. Condition (i) is
+ * unchanged.
  *
  * Never mutates anything — `detect()` only reads `package.json` and lists
- * `.claude/agents/`. This module is purely read-only by design.
+ * `packages/definitions/agents/`. This module is purely read-only by design.
  *
  * ---
  * MEASURED WARNING TEXT (TASK-036/AC-007 gate — CLOSED, S385):
@@ -49,8 +64,8 @@ const MONOREPO_PACKAGE_NAME = '@orchestrator-cli/core';
  * real practical risk it implies (silent drift), not a hypothetical.
  */
 const DEV_CHECKOUT_WARNING_REASON = 'Dev-checkout detectado: este cwd pertence ao monorepo orchestrator e ' +
-    '`.claude/agents/` contém arquivos reais cujos slugs colidem com o ' +
-    'manifest do pacote. Precedência MEDIDA empiricamente (AC-007/TASK-036, ' +
+    '`packages/definitions/agents/` contém arquivos reais cujos slugs colidem ' +
+    'com o manifest do pacote. Precedência MEDIDA empiricamente (AC-007/TASK-036, ' +
     'gate S385, 3/3 runs determinísticos por eixo, probe isolado): agents ' +
     'resolvem por PROJECT-scope (edições locais neste repo têm efeito ' +
     'imediato numa sessão live) e skills resolvem por USER-scope ' +
@@ -66,7 +81,7 @@ export class DevCheckoutDetector {
         this.manifestSlugs = manifestSlugs;
     }
     /**
-     * Read-only detection. Never throws on a missing `.claude/agents`
+     * Read-only detection. Never throws on a missing `packages/definitions/agents`
      * directory or a missing/unparseable ancestor `package.json` — those
      * cases simply resolve to `'clean-install'`.
      */
@@ -114,11 +129,13 @@ export class DevCheckoutDetector {
         }
     }
     /**
-     * Real (non-symlink) `.claude/agents/*.md` files at `root` whose slug
-     * (basename without `.md`) collides with `manifestSlugs`.
+     * Real (non-symlink) `packages/definitions/agents/*.md` files at `root`
+     * whose slug (basename without `.md`) collides with `manifestSlugs`.
+     * Repointed from `.claude/agents/` to the ADR-023 canonical SoT (§7,
+     * S401) — see the module JSDoc "REPOINTED" note above.
      */
     findMatchingRealAgentSlugs(root) {
-        const agentsDir = join(root, '.claude', 'agents');
+        const agentsDir = join(root, 'packages', 'definitions', 'agents');
         if (!existsSync(agentsDir)) {
             return [];
         }

package/dist/install/DevCheckoutDetector.js.map

@@ -1 +1 @@
-{"version":3,"file":"DevCheckoutDetector.js","sourceRoot":"","sources":["../../src/install/DevCheckoutDetector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DevCheckoutDetector.js","sourceRoot":"","sources":["../../src/install/DevCheckoutDetector.ts"],"names":[],"mappings":"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"}

package/hooks/agent-git-guard.mjs

@@ -0,0 +1,118 @@
+import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
+
+// hooks/lib/api-client.ts
+import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var PROJECT_ROOT = join(__dirname, "..", "..", "..");
+var STATE_DIR = join(PROJECT_ROOT, ".orchestrator", ".state");
+var JWT_CACHE = join(STATE_DIR, "jwt-token");
+var DEBUG_LOG = join(STATE_DIR, "hook-debug.log");
+mkdirSync(STATE_DIR, { recursive: true });
+var API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+var AUTH_EMAIL = process.env.ORCHESTRATOR_ADMIN_EMAIL || process.env.ORCHESTRATOR_AUTH_EMAIL || "system@orchestrator.local";
+var AUTH_PASSWORD = process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || "system123";
+var PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+function log(prefix, msg) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  try {
+    const line = `[${ts}] ${prefix}: ${msg}
+`;
+    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+  } catch {
+  }
+}
+var LAST_COMPLETED_FILE = join(STATE_DIR, "last-completed-workflow.json");
+var LAST_COMPLETED_TTL_MS = 60 * 60 * 1e3;
+var INVOCATIONS_DIR = join(STATE_DIR, "invocations");
+var INVOCATION_STATE_TTL_MS = 4 * 60 * 60 * 1e3;
+var DISPATCH_INTENT_DIR = join(STATE_DIR, "dispatch-intent");
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function getField(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return "";
+    current = current[part];
+  }
+  return current != null ? String(current) : "";
+}
+function outputPreToolUse(opts) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: opts.decision,
+      ...opts.reason && { permissionDecisionReason: opts.reason },
+      ...opts.context && { additionalContext: opts.context }
+    }
+  };
+  console.log(JSON.stringify(output));
+}
+
+// hooks/agent-git-guard.ts
+var HOOK = "AGENT-GIT-GUARD";
+var defaultDeps = {
+  readStdin,
+  output: outputPreToolUse,
+  log,
+  getEnv: (key) => process.env[key]
+};
+var PUSH = /\bgit\s+push(\s|$)/;
+var MERGE = /\bgit\s+merge(\s|$)/;
+var GH_PR_MERGE = /\bgh\s+pr\s+merge(\s|$)/;
+function commandIsPushOrMerge(command) {
+  return PUSH.test(command) || MERGE.test(command) || GH_PR_MERGE.test(command);
+}
+function evaluateGitGuard(command, agentId, agentType) {
+  if (!agentId) return { decision: "allow" };
+  if (!commandIsPushOrMerge(command)) return { decision: "allow" };
+  const who = agentType && agentType.length > 0 ? `Sub-agent '${agentType}'` : "Sub-agent";
+  return {
+    decision: "deny",
+    reason: `[AGENT-GIT-GUARD] ${who} is not permitted to run git push / git merge / gh pr merge. Per RFC-022 + TD-169, push and merge are owned EXCLUSIVELY by the main orchestrator (the main conversation). Make your changes locally and return them in your report \u2014 the orchestrator reviews, then pushes/merges. (Prevents the S288 unauthorized merge-to-main breach.)`
+  };
+}
+async function mainWithDeps(deps) {
+  const { readStdin: readStdin2, output, log: log2, getEnv } = deps;
+  const stdin = await readStdin2();
+  const command = getField(stdin, "tool_input.command") || getField(stdin, "command") || "";
+  const agentId = getField(stdin, "agent_id");
+  const agentType = getField(stdin, "agent_type");
+  if (getEnv("SKIP_AGENT_GIT_GUARD") === "true") {
+    log2(HOOK, `BYPASS (SKIP_AGENT_GIT_GUARD): ${command.slice(0, 60)}`);
+    return;
+  }
+  const result = evaluateGitGuard(command, agentId, agentType);
+  if (result.decision === "deny") {
+    log2(HOOK, `DENY (agent=${agentType || "unknown"}): ${command.slice(0, 80)}`);
+    output({ decision: "deny", reason: result.reason });
+    return;
+  }
+  log2(
+    HOOK,
+    `ALLOW (agent=${agentId ? agentType || "sub-agent" : "main"}): ${command.slice(0, 60)}`
+  );
+}
+async function main() {
+  await mainWithDeps(defaultDeps);
+}
+main().catch(() => process.exit(0));
+export {
+  commandIsPushOrMerge,
+  evaluateGitGuard,
+  mainWithDeps
+};