@orchestrator-claude/definitions 3.34.0 → 3.35.0

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "orchestrator-definitions/v1",
   "namespace": "orchestrator",
-  "version": "3.34.0",
-  "generatedAt": "2026-07-21T01:00:14.980Z",
+  "version": "3.35.0",
+  "generatedAt": "2026-07-27T20:50:12.058Z",
   "definitions": {
     "agents": [
       {
@@ -45,6 +45,14 @@
         "supersedes": null,
         "metadata": {}
       },
+      {
+        "slug": "ciclo-engineer",
+        "file": "agents/ciclo-engineer.md",
+        "version": "1.0.0",
+        "checksum": "sha256:f370f35c80527b16658984e9da65cb58ec4bec74d5647eb6102a4e2f78871a0a",
+        "supersedes": null,
+        "metadata": {}
+      },
       {
         "slug": "code-archaeologist",
         "file": "agents/code-archaeologist.md",
@@ -129,7 +137,7 @@
         "slug": "orchestrator",
         "file": "agents/orchestrator.md",
         "version": "1.0.0",
-        "checksum": "sha256:d6d11650c39bf0fdf2efc011e4e0dfd3f8507deed1d7988e2a8cd4249428392d",
+        "checksum": "sha256:4b7c8555d9fc7f50bb4c39f014bebc18ca1b1fd013517442816e289adce4ac92",
         "supersedes": null,
         "metadata": {}
       },
@@ -271,6 +279,14 @@
         "supersedes": null,
         "metadata": {}
       },
+      {
+        "slug": "ciclo-lane-dispatch",
+        "file": "skills/ciclo-lane-dispatch/SKILL.md",
+        "version": "1.0.0",
+        "checksum": "sha256:6dfb9a1687c7bc265016b3497609a3e1955af1edd13cbc846158fc30819a3d02",
+        "supersedes": null,
+        "metadata": {}
+      },
       {
         "slug": "compositional-intelligence",
         "file": "skills/compositional-intelligence/SKILL.md",
@@ -331,7 +347,7 @@
         "slug": "orchestrator",
         "file": "skills/orchestrator/SKILL.md",
         "version": "1.0.0",
-        "checksum": "sha256:e0e119da1a54af0a6110b08e58400015751374bf21424deede0c6f78c438eb83",
+        "checksum": "sha256:6ddb60e928016c0f11b32f6ec48558618eb6bb70a42eea74a29f1fc562dfc2ab",
         "supersedes": null,
         "metadata": {}
       },
@@ -457,6 +473,14 @@
       }
     ],
     "hooks": [
+      {
+        "slug": "agent-git-guard",
+        "file": "hooks/agent-git-guard.mjs",
+        "version": "1.0.0",
+        "checksum": "sha256:b40c4bbeed6c1b8ceaa4df98a2f359b844aea2154e143e91093394569e0f62ff",
+        "supersedes": null,
+        "metadata": {}
+      },
       {
         "slug": "dangling-guard",
         "file": "hooks/dangling-guard.mjs",
@@ -481,6 +505,14 @@
         "supersedes": null,
         "metadata": {}
       },
+      {
+        "slug": "playwright-output-guard",
+        "file": "hooks/playwright-output-guard.mjs",
+        "version": "1.0.0",
+        "checksum": "sha256:cfc5807a23a0e89a703e09e91bb4c817cc61a6965235191f079bdeb42368e5cf",
+        "supersedes": null,
+        "metadata": {}
+      },
       {
         "slug": "post-compact",
         "file": "hooks/post-compact.mjs",
@@ -497,11 +529,19 @@
         "supersedes": null,
         "metadata": {}
       },
+      {
+        "slug": "pre-agent-dispatch",
+        "file": "hooks/pre-agent-dispatch.mjs",
+        "version": "1.0.0",
+        "checksum": "sha256:2f9e62ecfed182281dfe0aefa9fc4801d1b3aea9226a7d8f0bc52db6ed93326b",
+        "supersedes": null,
+        "metadata": {}
+      },
       {
         "slug": "session-start",
         "file": "hooks/session-start.mjs",
         "version": "1.0.0",
-        "checksum": "sha256:5a7147a2b5a737ac1cd58b276bcdf4f4ceeb309e0858792d52c6cd596e753b0c",
+        "checksum": "sha256:a79a85062149f217483f971f0deb05759179c458b1d819901f357650dedbc67d",
         "supersedes": null,
         "metadata": {}
       },
@@ -525,7 +565,7 @@
         "slug": "subagent-stop",
         "file": "hooks/subagent-stop.mjs",
         "version": "1.0.0",
-        "checksum": "sha256:aad32638b065550dbe83ff9849a849c56f619874ba4e9e49df9257e74218a068",
+        "checksum": "sha256:b16c6215a41b9a3bc1be745980f46d1933fa06d8b21998b193278fec99868755",
         "supersedes": null,
         "metadata": {}
       },
@@ -537,6 +577,14 @@
         "supersedes": null,
         "metadata": {}
       },
+      {
+        "slug": "verification-before-completion",
+        "file": "hooks/verification-before-completion.mjs",
+        "version": "1.0.0",
+        "checksum": "sha256:349c03c12d939575d10f46af9d3e1c073b438860303e751d0d96fc51ab1cd924",
+        "supersedes": null,
+        "metadata": {}
+      },
       {
         "slug": "workflow-guard",
         "file": "hooks/workflow-guard.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestrator-claude/definitions",
-  "version": "3.34.0",
+  "version": "3.35.0",
   "description": "Built-in definitions (agents, skills, hooks, workflows, KB seeds) for the Orchestrator ecosystem",
   "type": "module",
   "main": "dist/index.js",

package/personas/INDEX.md

@@ -0,0 +1,46 @@
+# Persona Library — Catalog Index
+
+## Persona Table
+
+| id | role | industry | adversarial_intensity | validated_in |
+|----|------|----------|-----------------------|--------------|
+| diretor-cetico-fmcg | Diretor de Marketing / Brand Director | FMCG (Fast-Moving Consumer Goods) | high | S178 |
+| cfo-conservador | CFO / VP Finance | cross-industry | high | S183 |
+| auditor-compliance | Auditor de Compliance / Compliance Officer | cross-industry (regulado: financeiro, saude, governo) | medium | S199 |
+| designer-perfeccionista | Senior Designer / Design Lead | cross-industry (product, marketing, brand) | medium | S199 |
+| engenheiro-cetico-construcao | Engenheiro Civil Senior / Construction Project Engineer | construcao civil | medium | S193, S199 |
+
+## How to Navigate and Select a Persona
+
+Each persona file lives in `.claude/personas/<id>.md` and follows a uniform schema: YAML
+frontmatter declares identity fields (`id`, `role`, `industry`, `seniority`, `adversarial_intensity`,
+`validated_in`) plus three behavioral lists (`biases`, `vocabulary`, `demands`); the Markdown body
+contains three sections — **Narrative** (backstory and mindset), **Sample Objections** (verbatim
+challenge patterns), and **Adversarial Review Behavior** (severity-classified review rubric).
+
+Select by matching two axes: **industry fit** and **adversarial intensity**. For a financial
+proposal, start with `cfo-conservador` (cross-industry, intensity high) and add `auditor-compliance`
+(intensity medium) when the audience includes a compliance officer or regulator. For a design or
+product deliverable, reach for `designer-perfeccionista`. For construction or infrastructure plans,
+use `engenheiro-cetico-construcao`. For FMCG marketing or brand strategy, use `diretor-cetico-fmcg`.
+When multiple personas apply, run them sequentially: high-intensity personas first to catch blocking
+issues, then medium-intensity for refinement.
+
+Personas with `adversarial_intensity: high` will block approval on structural gaps; those with
+`medium` will flag issues but generally allow progression with documented remediation plans. Use the
+`validated_in` field to gauge battle-testing: a persona that survived a live dry-run (e.g., S178)
+is more calibrated than one freshly scaffolded — treat unvalidated personas as draft until exercised.
+
+## Forward Reference
+
+The `/persona-library` skill (Wave 4, TASK-017) will provide interactive persona selection,
+injection into review prompts, and session-scoped persona stacking. Once available, load it with
+`/persona-library` to automate persona routing based on artifact type and audience context.
+
+---
+
+*Generated: 2026-05-12 — TASK-007 S183 Wave 3*
+*Updated: 2026-05-18 — S199 Step B (validation backlog cleared)*
+*Schema version: all 5 personas pass 10-field audit, list lengths >= 3, 3-section body*
+*Validated ratio: 5/5 (100%) — KPI-02 GREEN. Personas with optional `calibration_evidence` block: 3 (auditor-compliance, designer-perfeccionista, engenheiro-cetico-construcao — S199 Step B dry-run; cfo-conservador + diretor-cetico-fmcg validated pre-framework, no block authored).*
+*S199 avg validation_score (3 personas with block): 0.793 (KPI-03 baseline first-computation).*

package/skills/ciclo-lane-dispatch/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: ciclo-lane-dispatch
+description: Use BEFORE delegating a lane 2A run to ciclo-engineer (PRD do cliente → Ciclo modelado + protótipo navegável). Triggers on "delegar lane 2A", "rodar o ciclo-engineer", "PRD para protótipo", "run de medição do charter", "modelar o ciclo do cliente". Carries the orchestrator side of the lane: pré-voo, prompt de despacho, e — o essencial — como julgar o relatório que volta re-medindo em vez de acreditar. Do NOT use to BUILD the artifact (that is the agent's charter, which it carries itself) nor for lane 2B (ciclo sem tela — captura não fechada).
+---
+
+# Ciclo Lane Dispatch — o lado do orquestrador da lane 2A
+
+O `ciclo-engineer` carrega o **executável** (fases 0–6, dez armadilhas, disciplina de token). Esta
+skill carrega o que **não** cabe nele: o que fazer antes de despachar, e o que fazer com o que
+volta. A separação é por leitor, não por assunto — o agente precisa ser autossuficiente, e o
+orquestrador precisa ser cético.
+
+Marcas de proveniência usadas abaixo: `[M]` medido · `[S]` síntese nossa · `[U]` decidido pelo
+usuário · `[L]` lacuna aberta.
+
+## Quando usar
+
+USE quando for delegar uma corrida da lane 2A: um PRD de cliente vira **Ciclo modelado** (sempre) e
+**protótipo navegável** (quando o PRD tem superfície).
+
+NÃO use para:
+- **construir** o artefato — é a fase do agente, e ele traz o procedimento próprio;
+- **lane 2B** (ciclo sem tela) — não tem doc de procedimento; o agente recusa por construção;
+- deck Slidev (`presentation-engineer`) ou React app code (`frontend-engineer`).
+
+---
+
+## 1 · Pré-voo — quatro checagens, todas antes de escrever o prompt
+
+**1.1 Branch o repo-alvo.** `[U]` O `ciclo-engineer` segura `createCheckpoint`; a Regra 4 do charter
+proíbe despachá-lo com o repo em `main`/`master`. Cheque **o repo-alvo**, não só o teu cwd — são
+repositórios diferentes e é o alvo que o agente escreve.
+
+**1.2 Confirme que a correção está no arquivo que o agente LÊ.** `[S]` Doutrina que mora só num doc
+de processo não chega ao delegado. Se a sessão anterior "corrigiu o charter", faça `grep` no
+`agents/ciclo-engineer.md` pelos termos da correção antes de rodar um teste que depende dela —
+senão o run mede o charter velho e tu credita o resultado ao novo.
+
+**1.3 Meça os cinco insumos do contrato, não os presuma.** São: caminho do PRD · caminho do design
+system · repo-alvo · escopo (quais US) · ator-alvo. O **ator sai do PRD com linha citada**, nunca de
+memória. `[M]` Na S420 cinco das seis correções ao orquestrador foram da mesma família: afirmação
+sobre artefato externo sem probe — o Invariante 6 escrito e não aplicado.
+
+**1.4 Se for run de medição, retire a referência E prove que ela não cobre o alvo.** `[M]` (S420)
+Antes de escrever o prompt, `grep -c` no artefato de referência pelo escopo pretendido. Se ele já
+cobre o alvo, o run mede cópia, não transferência. Quando a referência cobre todo o espaço de
+alvos, a restrição vira ativo: retire-a do agente e **use-a depois como ground truth**.
+
+---
+
+## 2 · O prompt de despacho
+
+Entregue os cinco insumos e mais estas cláusulas:
+
+- **Vedação de referência** (em run de medição): *não leia o conteúdo de artefatos anteriores desta
+  lane; listar o diretório para escolher nome livre é permitido.*
+- **Marca `client` proibida sem registro.** Se tu não passar a conversa do cliente, a marca não
+  existe para o agente e o fato vira lacuna. Sem isso ele marca `client` "porque faz sentido", que é
+  palpite com crachá.
+- **Segure o commit** (§14.6, publicar-antes-de-corrigir): o agente grava e **não** commita; tu
+  commita depois de ler o relatório.
+- **Cláusula de escape.** `[M]` (S420) *"Se o protocolo te obrigar a abrir o arquivo vedado, não
+  abra — registre o conflito."* Produziu duas declarações honestas e espontâneas.
+
+**Neutralidade do dispatch — regra dura.** `[S]` Se o run existe para medir alguma dimensão
+(interatividade, densidade, fidelidade), **não conte isso ao agente**. Dizer "estou medindo teus
+listeners" infla listeners e destrói a comparação com os runs anteriores, que não foram avisados.
+Mantenha o dispatch indistinguível de uma delegação normal.
+
+---
+
+## 3 · Julgar o que volta — re-medir antes de acreditar
+
+Regra S407, e ela não é desconfiança do agente: é a condição 3 do §17 (*resultado medido por
+instrumento, não afirmado*). Um relatório é afirmação até tu medir.
+
+`[M]` O que re-medir pegou, historicamente: na S420, **uma acusação falsa** do delegado ao charter
+(o exemplo que ele disse não existir estava no PRD, linha 166) e **uma "descoberta" que era
+leitura** (análise já presente no artefato de referência, apresentada como julgamento próprio).
+
+### 3.1 Instrumento do eixo mockup→protótipo
+
+```bash
+scripts/audit-prototype-interactivity.sh <artefato.html> [outros.html ...]
+```
+
+Mede telas no escopo, listeners e linhas de JS. Calibração conhecida `[M]` (US04 do PRD Selma/TRC,
+mesma US nos quatro runs):
+
+| run | condição | telas | listeners | JS |
+|---|---|---|---|---|
+| 1 | charter + referência à mão | 7 | 11 | 212 |
+| 2 | charter, ref retirada, sem a forma escrita | 0 | 8 | 156 |
+| 3 | charter com a forma escrita, ref retirada | 0 | 4 | 50 |
+| 4 | charter corrigido, ref retirada | 5 | 17 | 221 |
+| — | s406 (opus, original) | — | 57 | 1551 |
+
+`[M]` O baseline opus **não é comparável no eixo de telas**: ele usa vocabulário próprio
+(`ws-step`, `spine-step`). Compare runs entre si, que compartilham o charter.
+
+### 3.2 Fidelidade do contrato de tokens — a checagem que o auditor NÃO faz
+
+`[M]` (S420) O auditor valida o **grafo de referências** (`var(--x)` aponta para algo declarado).
+Ele **não** compara nome:valor, e por isso passa limpo em token adulterado. Rode também:
+
+```bash
+pares() { grep -ohE '^\s*--[a-z0-9-]+\s*:[^;]+;' "$@" | sed 's/^ *//' | sort -u; }
+diff <(pares <artefato>) <(pares <ds>/variables.css <ds>/variables.dark.css)
+```
+
+Esperado: diff vazio, exit 0, mesma contagem dos dois lados.
+
+### 3.3 O instrumento também mente — e o detector é a discordância
+
+`[M]` (S421) O contador de telas nasceu casando `class="screen` e deu **falso zero** num artefato
+com 5 telas, porque aquele run escreveu `us04-screen`. O veredito impresso foi o mais grave da
+escala ("SEM SUPERFÍCIE no escopo"), e acreditar nele teria invertido a conclusão da sessão.
+
+Duas regras saem disso:
+
+1. **Contador dependente de vocabulário é defeito, não configuração.** Case token de classe, não
+   prefixo literal. Um instrumento validado em N artefatos que compartilham convenção não está
+   validado — está confirmado dentro da própria convenção.
+2. **Quando instrumento e relatório discordam, não escolha: investigue.** `[S]` Nem o instrumento
+   sozinho nem o relatório sozinho pegaram o erro — **a discordância entre os dois pegou**. Suspeite
+   primeiro do instrumento (é mais novo e menos exercitado que o agente), depois do relatório.
+
+### 3.4 O que grep não alcança
+
+`[S]` Gate não se conta por grep. Contagem de `disabled` e de `addEventListener('change')`
+**corrobora** que os gates são estruturais e não decorativos; não substitui percorrer o fluxo no
+browser e ver o botão travar e liberar. Se tu não abriu o browser, diga que não abriu.
+
+---
+
+## 4 · Artefato falho é evidência — não conserte
+
+`[U]` (S420, ratificado) Quando um run sai errado, a tentação é corrigir o HTML. Não corrija:
+**corrija o procedimento e rode de novo**, guardando o artefato falho como baseline. Consertar à mão
+destrói a única medição que tu tinha do estado anterior e transfere para ti um trabalho que era do
+processo.
+
+Corolário: mudança de charter só é creditada depois de um run que a exercite. Autorar normativo em
+cima de correção não medida é como os cinco defeitos da S420 nasceram.
+
+---
+
+## 5 · Fronteiras e lacuna declarada
+
+Esta skill **não** ensina a construir o Ciclo nem o protótipo — isso é do agente, e duplicar aqui
+recria a divergência de duas superfícies narrativas sobre o mesmo estado.
+
+`[L]` **Esta skill não pode passar no teste do §17.** A condição 2 exige que *alguém que não
+escreveu o doc execute a partir dele*, e o único executor possível de uma skill de orquestrador é o
+próprio orquestrador. A pergunta de se o §17 precisa de uma variante para conteúdo
+orquestrador-side segue aberta — prima da lacuna que o §17.4 já registrava sobre a revisão
+pré-disparo, que "não é lane". Enquanto isso, esta skill vale pelo que carrega de medido, não por
+ter atravessado um teste que não a alcança.

package/skills/orchestrator/SKILL.md

@@ -63,6 +63,8 @@ If no variant is set (or variant resolves to `"full"`), all phases execute norma
 | implement | `implementer` | code + tests |
 | review | `reviewer` | review feedback |
 
+**Agent names in this skill are written in canonical (bare) form — the dispatch name is topology-dependent.** Under repo scope (`.claude/agents/`) the harness lists agents bare (`implementer`); under **plugin scope** (graduated harness, RFC-040 §18) it lists them namespaced (`orchestrator:implementer`), and a bare `subagent_type` fails loud (`Agent type 'implementer' not found. Available agents: …`). Always dispatch using the **exact name the harness's available-agent list shows**, adding the plugin prefix when that list has it — every table, template and set below (§2c.1, §2d.1) names agents canonically and should be read the same way. Do **not** source dispatch names from the `[CAPABILITY-MATRIX]` SessionStart block: it derives them from file basenames and prints the bare form under both topologies (measured, S399).
+
 #### 2c.0 Branch-Before-Dispatch precondition (TD-171) — MANDATORY before dispatching a committing agent
 
 Before dispatching **any committing agent** (one whose tool list holds `mcp__orchestrator-tools__createCheckpoint` — see §2c.1 for the exact set), the orchestrator MUST first ensure the working tree is on a **non-protected feature branch**:
@@ -99,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. 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 **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.
 
 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: