@orchestrator-claude/definitions 3.33.0 → 3.35.0

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/artifact-generator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artifact-generator
-description: Generate client-facing deliverable files (xlsx schedules, pdf decks, csv issue trees, jinja2-templated docs). Load when: "generate xlsx", "build pdf", "compile deliverable pack", "jinja2 template". Do NOT use for code generation.
+description: 'Generate client-facing deliverable files (xlsx schedules, pdf decks, csv issue trees, jinja2-templated docs). Load when: "generate xlsx", "build pdf", "compile deliverable pack", "jinja2 template". Do NOT use for code generation.'
 allowed-tools: Read, Write, Bash
 ---
 

package/skills/artifact-production/SKILL.md

@@ -60,6 +60,34 @@ Always include metadata when storing:
 The artifact-validator hook will automatically validate after storage.
 Status transitions: draft → validated (after passing validation).
 
+### Test Matrix Enumeration (specifier + planner discipline)
+
+When a spec or plan mentions exception/error handling, the test matrix MUST enumerate **one test per distinct exception handler** — not just user-visible behavior paths.
+
+**Concrete rule for network/IO code:** the default exception test matrix includes (at minimum):
+- 2xx success
+- 4xx response (where domain-relevant)
+- 5xx response (where domain-relevant)
+- `Timeout` / `ReadTimeout`
+- `ConnectionError`
+- `SSLError` (when TLS involved)
+- Catch-all `RequestException` / equivalent (when the implementer adds it as a safety net)
+
+**Trigger:** if the spec text contains any of `try` / `except` / `catch` / "fallback" / "retry" / "handler", the planner MUST emit one task per `except` clause expected in the implementation. Implementers adding NEW `except` branches not in the matrix MUST amend the matrix in the same commit (or file a TD if amending the plan is out-of-scope).
+
+**Origin:** S226 wave-3c TD-S226-003 reviewer HIGH-001 (uncovered `ConnectionError` branch, fixed via `5a0d4b4`). Promoted from TD-S226-007 (PL-002).
+
+### TD filing discipline — empirical evidence vs hypothesis
+
+When filing a TD that cites specific external-artifact identifiers (cert chain intermediates, vendor schema field names, government CSV column names, third-party API endpoints, library symbol paths), the TD body MUST separate:
+
+- **Empirical evidence** (command + observable output that was actually run at filing time — `openssl s_client ...`, `curl -v ...`, `python -c "import pandas; print(...)"`, `git log --oneline`, etc.)
+- **Root-cause hypothesis** (the proposed explanation — may name specific identifiers, but flagged as hypothesis-not-yet-verified)
+
+**Prohibited:** citing specific intermediate cert names, schema column names, or API field paths as fact without an empirical probe captured in the TD itself.
+
+**Origin:** S226 wave-3d TD-S226-006 cited wrong intermediate cert (`AC Receita Federal v4` while actual was `RNP ICPEdu GR46 OV TLS CA 2025`). Worked because L1 bundle assembly used `openssl s_client` directly, not BACKLOG-cited names. Promoted from TD-S226-008 (PL-003). Sister to Universal Invariant 6 (`verify_external_artifact_before_implement`) — TD-filing-stage analogue of the implementation-stage rule.
+
 ### Invocation Tracking
 
 After storing artifact, complete the agent invocation:

package/skills/backlog-synthesis/SKILL.md

@@ -38,6 +38,11 @@ Look for:
 ### METRICS: [workflow efficiency observations]
 ```
 
-### Step 5: Update BACKLOG.md
-If significant findings, suggest updates to project-guidelines/BACKLOG.md
-with specific sections to add/modify.
+### Step 5: Persist to Structured State (RFC-033)
+Do NOT grow `BACKLOG.md` (retired to append-only history). Instead, on significant findings, write the three structured surfaces:
+
+1. **`project-guidelines/project-state.yaml`** (hot path — what `session-start.ts` reads). Overwrite the small fields only: `session.{current,previous,updated,last_summary}`, `next_step.{summary,workflow}`, `pending.{critical,high,medium,ci_gating}` (COUNTS of confirmed-actionable items, not prose), `active_work`, `follow_ups`. Keep it small.
+2. **`project-guidelines/sessions/S<NNN>.md`** (cold path). Append the rich session narrative here — one file per session — NOT into BACKLOG.md.
+3. **`project-guidelines/registry.yaml`** (TD/doc status SSOT — RFC-033 Phase 2). Upsert a row for any TD whose status changed or that was newly discovered. Fields: `status` ∈ constitution values (`proposed|accepted|resolved|rejected|...`); `resolution: partial` for partially-shipped work; `verification: verified-S<NNN>` when checked against actual code/commit, `unverified-triage` when carried forward unconfirmed. **registry.yaml — not index.md, not per-TD frontmatter — is the single source of truth for status.** index.md is a manual/generated view (generator + CI-validate tracked by TD-174).
+
+**Verify-before-assert (S294–S298 lesson):** before marking a TD `resolved`, confirm against the actual mechanism/code/commit — never the per-TD frontmatter (`status:` there is known-stale) or BACKLOG prose. When the three sources disagree, the per-vintage mechanism check wins.

package/skills/checkpoint-protocol/SKILL.md

@@ -5,6 +5,13 @@ description: When and how to create workflow checkpoints. Use after completing t
 
 ## Checkpoint Creation Protocol
 
+### Who follows this (TD-171)
+This protocol applies to the `implementer` **and all engineer-type committing agents** — any agent whose tool list holds `mcp__orchestrator-tools__createCheckpoint`: as of S290 that is `implementer`, `azure-devops-engineer`, `presentation-engineer`, `operational-artifact-builder`, `cicd-platform-engineer`, `python-data-engineer`, `frontend-engineer`. Engineer-types commit critical artifacts **outside `src/`** (IaC, pipelines, ETL, decks), so they need per-change git revertability too — "only `src/` commits matter" is wrong.
+
+### Checkpoint vs git (read first)
+- `createCheckpoint` is a **PostgreSQL state snapshot** (RFC-012), **INDEPENDENT of git** — you do NOT need to commit before calling it.
+- **Local commit YES, push NO (TD-171):** you MAY make local git commits for granular revertability, on the **feature branch the orchestrator prepared before dispatching you** (branch-before-dispatch, `/orchestrator` §2c.0). You MUST NEVER `git push` / `git merge` / `gh pr merge` — push/merge is orchestrator-owned (enforced by `agent-git-guard`, TD-169). Return your work in your report; the orchestrator pushes after its independent assert.
+
 ### When to Create
 - After every 3-5 completed tasks
 - After passing a phase gate

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/infographic-engine/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: infographic-engine
+description: Generate premium, data-bound infographics as deterministic SVG/HTML (NEVER AI raster). Load when "infográfico", "infographic", "visual executivo", "diagrama premium", "substituir screenshot por visual", "data visual for deck/proposal", or when presentation-engineer / operational-artifact-builder need editorial-quality visuals from real data. Provides 6 composition archetypes + style presets + MANDATORY Playwright visual validation loop. Do NOT use for charts from raw datasets (use plotting libs), UI screens (use DSVL/storybook-validated-loop), or photo/illustration needs.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Infographic Engine
+
+Capability skill for producing **editorial-quality, data-bound infographics** as deterministic vector artifacts (inline SVG, HTML+CSS, or Vue components for Slidev). Consumed by `presentation-engineer` (decks), `operational-artifact-builder` (proposal PDFs), and main-orchestrator (governance docs).
+
+**Origin:** S263 (TRC deck v2). Lineage: composition discipline partially derived from external designer prompt-craft (raster AI prompts, S263) — the **medium was rejected** (see Core Principles), the **art direction and restraint rules were salvaged**. Validation loop inherits the DSVL/canary pattern (9× empirically validated in TRC).
+
+---
+
+## Core Principles (non-negotiable)
+
+1. **Vector, never AI raster.** Output is SVG/HTML+CSS authored by the model — NOT text-to-image generation. Rationale: (a) typography is exact (PT-BR accents render perfectly); (b) real data binds with fidelity; (c) project design tokens inject natively; (d) output is editable, diffable, reproducible; (e) crisp at any scale, embeds in Slidev/HTML/PDF.
+2. **Data-bound, never decorative.** Every number, label, and proportion in the visual MUST trace to a cited source (spec, matrix doc, research finding). If a value is illustrative, it is labeled as such. No invented statistics.
+3. **One hero per visual.** Every infographic has exactly ONE dominant element (a number, a flow, a hub). Everything else is support. If two things compete for hero, split into two infographics.
+4. **Density budget enforced.** Editorial quality = restraint. Per-archetype caps below are hard limits, not suggestions.
+5. **Visual validation is MANDATORY.** No infographic ships without the render→screenshot→critique loop (§Validation). The model must SEE its output before delivering. This is the quality gate that separates editorial from slop.
+6. **Token fidelity.** When the project has a design system, its tokens are LAW (colors, type, radii, shadows). Style presets (§Presets) apply only when no project DS exists.
+
+## When to use
+
+USE when:
+- A deck/proposal/doc needs a high-quality visual synthesizing real information (system maps, flows, comparisons, KPIs, roadmaps, coverage matrices)
+- Replacing screenshots with executive-grade visuals (C-level audiences want *system and value*, not UI)
+- presentation-engineer or operational-artifact-builder dispatch references an infographic need
+
+DO NOT use when:
+- Plotting a dataset (>20 data points) → use a charting lib or generate the chart programmatically
+- Prototyping UI screens → DSVL / storybook-validated-loop
+- Photographic/illustrative imagery is genuinely required → out of scope, flag to user
+
+---
+
+## Pipeline (6 steps)
+
+### 1 — Brief & data contract
+Extract from the request: **audience** (C-level? technical? client?), **format** (16:9 slide / 1:1 / 9:16 / A4 block), **the one message** this visual must land, and the **data table** (every value + its source). Write the data contract inline before composing. If any value lacks a source → STOP, ask or mark illustrative.
+
+### 2 — Archetype selection
+Pick ONE archetype from the catalog (§Archetypes). If the content fits none, compose from at most TWO archetypes (e.g., hero-KPI + mini-timeline footer). More than two = the brief is overloaded → split.
+
+### 3 — Style resolution
+Resolve in order: (a) project design-system tokens (injected via dispatch context, e.g. `$DESIGN_SYSTEM_REPO`); (b) explicit user direction; (c) skill preset (§Presets). Declare the resolved palette/type stack in a comment block at the top of the artifact.
+
+### 4 — Compose (SVG-first)
+Author the artifact:
+- **SVG standalone** (default): inline `<svg viewBox>`, system font stack or project font, all text as real `<text>` elements (NEVER paths/outlines — must stay editable + accessible).
+- **HTML+CSS canary**: when layout needs flexbox/grid complexity (then screenshot or embed as-is in Slidev).
+- **Vue component** (Slidev targets): SFC wrapping the SVG with props for data — follow the `ROIVisual.vue`/`Timeline3Phases.vue` precedent.
+Apply the grid: 12-col mental grid, 8px spacing base, max 2 font weights + 2 sizes per panel, generous whitespace (≥15% of canvas empty).
+
+### 5 — Visual validation loop (MANDATORY, max 3 iterations)
+1. Render the artifact (open HTML/SVG via Playwright or dev server).
+2. Screenshot at target size (e.g. 1920×1080 for 16:9 slide context).
+3. **Critique against the Anti-Slop Checklist (§Checklist)** — honestly, as a hostile design reviewer.
+4. Fix findings → re-render. Converge when zero checklist violations.
+5. If still failing after 3 iterations → simplify the brief (cut a panel, drop a connector) rather than polish complexity.
+
+### 6 — Package & deliver
+Deliver per target: `.svg` file (+ optional PNG export via Playwright screenshot for raster consumers), or `.vue` component registered in the deck theme. Include the data-contract comment (sources) in the artifact header. Store path + screenshot evidence in the session record.
+
+---
+
+## Archetype Catalog
+
+| # | Archetype | Use when | Hero | Density budget |
+|---|---|---|---|---|
+| A1 | **Hub multi-actor** | One system, N entry points/profiles | Central node | ≤6 satellites, ≤1 bridge-node highlight, ≤8 connectors |
+| A2 | **Mirrored comparison / dual force** | Two pains, two options, before/after | The axis of symmetry | 2 columns, ≤3 items each, 1 convergence element |
+| A3 | **Flow with gate** | Process with checkpoint/blocker | The gate | ≤6 steps, 1 gate, ≤2 branch outcomes |
+| A4 | **KPI hero + support** | One number carries the thesis | The number (≥25% canvas height) | 1 hero + ≤4 support stats |
+| A5 | **Timeline / honest roadmap** | Phases, vision→production | Current-state marker | ≤4 phases, ≤3 bullets each |
+| A6 | **Coverage matrix / map** | Breadth of solution across dimensions | The filled-vs-empty pattern | ≤7×5 cells; cell content = icon/dot + ≤2 words |
+
+Composition skeleton (all archetypes): **Title** (caixa-alta or strong weight, ≤6 words) → **subtitle** (one line: the mechanism or the "so what") → **body** (the archetype) → **footer** (≤3 micro-facts or source line).
+
+## Style Presets (fallback when no project DS)
+
+| Preset | Background | Cards | Strokes | Accent discipline |
+|---|---|---|---|---|
+| `dark-premium` | deep graphite `#16181D` or dark navy, subtle radial gradient | `rgba(255,255,255,0.06)`, radius 8px | 1px `rgba(255,255,255,0.12)` | 1 accent color + 1 critical color, max |
+| `light-editorial` | `#F8F9FA` / paper white | `#FFFFFF` + soft shadow `0 2px 8px rgba(0,0,0,0.08)` | 1px `#E9ECEF` | 1 accent + neutrals |
+
+Shared rules: glow/gradient only if *discreet* and purposeful (≤1 per canvas) · semi-transparent cards over busy areas only · thin-line iconography (Lucide-style), never emoji in C-level artifacts · PT-BR text by default for TRC-sphere work.
+
+## Anti-Slop Checklist (the critique gate of step 5)
+
+Reject and fix if ANY of these is true:
+- [ ] More panels/elements than the archetype budget allows
+- [ ] Two elements compete for hero (nothing dominates)
+- [ ] Any text < 11px equivalent at target render size, or any truncated/overlapping label
+- [ ] >2 font sizes per panel, >3 accent colors total, gratuitous gradients/glows
+- [ ] Connector spaghetti (lines crossing more than once; >budget connectors)
+- [ ] A number/label without source in the data contract
+- [ ] Decorative icons that don't encode meaning ("ícone científico genérico")
+- [ ] Whitespace < 15% of canvas (cramped = cheap)
+- [ ] Typographic crimes: fake small-caps, stretched type, centered long paragraphs
+- [ ] Looks like "AI slop": generic, gradient-heavy, mascot characters, watermark-esque clutter
+- [ ] Off-token: any color/font outside the resolved style (when project DS exists)
+
+## Acceptance gates
+
+- Data contract present in artifact header, all values sourced
+- Validation loop evidence: ≥1 screenshot reviewed, checklist clean
+- Text is real text (selectable in SVG), pt-BR correct (acentuação verificada)
+- Renders correctly at target format without overflow at 100% zoom
+
+## Integration notes
+
+- **presentation-engineer:** import `.vue` infographic components into the Slidev theme (`theme/components/`); register data via props; respect deck token cascade.
+- **operational-artifact-builder:** embed SVG inline in HTML→PDF pipelines (weasyprint/playwright print); PNG fallback only if the PDF toolchain mangles SVG.
+- **DSVL relationship:** DSVL validates *UI screens* against a design system; this skill validates *information graphics* against editorial composition rules. Same canary philosophy, different artifact class.

package/skills/orchestrator/SKILL.md

@@ -63,6 +63,22 @@ 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**:
+
+```
+current=$(git rev-parse --abbrev-ref HEAD)
+# if current is main/master → create/switch to a feature branch FIRST
+git checkout -b <type>-<sN>-<slug>   # e.g. fix-s290-foo, td-171-branch-before-dispatch
+```
+
+**Why (root cause of the S289 breach `4f1f4f37`):** committing agents may make **local** checkpoint commits for granular revertability. `agent-git-guard` (TD-169) blocks push/merge but intentionally **allows** local commit — so if the orchestrator dispatches while sitting on `main`, the agent's local commit lands **directly on the protected branch**. Branch-before-dispatch contains those commits on a feature branch; only the orchestrator pushes, and only **after** its independent assert.
+
+**Enforcement backstop:** the `pre-agent-dispatch` hook (PreToolUse[Agent]) emits a non-blocking `[BRANCH-BEFORE-DISPATCH][TD-171]` alert when a committing agent is dispatched on a protected branch. The alert is a reminder, not a guarantee — **the orchestrator owns the branch decision**. Single branch authority = orchestrator; dispatched agents do NOT open their own branch (and cannot push — agent-git-guard).
+
 **Dispatch template:**
 
 ```
@@ -83,22 +99,58 @@ Sub-agents MUST persist artifacts to MinIO via `artifactStore` (universal rule,
 
 <!-- TODO S182 (OQ-4): per-phase agent override (.phases[n].agent) deferred — S182 will resolve permissive vs registry-validated vs KnownAgent-enum strategy after agent list complete -->
 
-#### 2c.1 Implementer-specific dispatch addenda (TD-S188-002)
+#### 2c.1 Checkpoint + Commit Policy dispatch addenda (TD-S188-002 + TD-S192-003)
+
+**Scope (TD-S192-003 amendment; set re-verified TD-171/S290):** this block applies to **any agent whose tool list includes `mcp__orchestrator-tools__createCheckpoint`**. As of **S290 the ground-truth set (grep `createCheckpoint` over `.claude/agents/*.md`) is the 7 agents**: `implementer`, `azure-devops-engineer`, `presentation-engineer`, `operational-artifact-builder`, `cicd-platform-engineer`, `python-data-engineer`, `frontend-engineer`. (The earlier S195 list was stale — it named `methodology-researcher`, which no longer holds the tool, and omitted `cicd-platform-engineer` / `python-data-engineer` / `frontend-engineer`, added later.) **Keep this set in sync with `COMMITTING_AGENTS` in `.claude/hooks/pre-agent-dispatch.ts`** (the branch-before-dispatch hook, §2c.0) — both derive from the same `createCheckpoint`-holder ground truth; when an agent gains/loses `createCheckpoint`, update both. **Match this set ignoring any plugin prefix** (`orchestrator:implementer` ≡ `implementer`) — the hook already does so via `normalizeAgentName()` (S398); membership is a property of the agent, not of the topology that names it. The earlier version of this section was implementer-only; subsequent sessions (S192 PME phase 2, S194 bug_fix, S195 lint sweep) confirmed the same `createCheckpoint=git-commit` conflation appears across other agents that hold the tool — making the rule agent-agnostic from S195 forward.
 
-When dispatching `implementer` (phase=`implement`), the generic template above is **insufficient**. The S188 implement phase surfaced an 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)`). To prevent recurrence, append the following **commit policy block** to every implementer dispatch prompt:
+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:
+
+- **S188** (`feat(s186)` leak in implementer commits)
+- **S192 phase 2** (methodology-researcher + operational-artifact-builder both invoked createCheckpoint inferring git-commit requirement; see memory `subagent_path_fallback_artifactretrieve_gap_s192phase2`)
+- **S194** commit `e5635f71` `[orchestrator] tasks: Auto-checkpoint after tasks phase` — auto-commit hook fired AFTER `advancePhase("implement")`, captured implement-phase work, but commit msg said `tasks phase` (hard rule (s): hook reads `currentPhase` post-advance → drifts one phase ahead of captured work). See memory `createcheckpoint_hook_phase_label_drift_s194`.
+- **S195** commit `106347d5` `[orchestrator] tasks: Auto-checkpoint after tasks phase` — SAME phase-label drift; commit captured implementer's S195 sweep deletions but msg labels it "tasks". Confirms hard rule (s) is recurring.
+
+To prevent recurrence, append the following **commit policy block** to every dispatch prompt targeting an agent with `createCheckpoint` in its tool list:
 
 ```
 [Commit Policy]
-- createCheckpoint (mcp__orchestrator-tools__createCheckpoint) is a PostgreSQL state snapshot per RFC-012. It is INDEPENDENT of git. You do NOT need to commit before calling it. Calling createCheckpoint with no uncommitted changes is the normal path.
+- createCheckpoint (mcp__orchestrator-tools__createCheckpoint) is a PostgreSQL state snapshot per RFC-012. It is INDEPENDENT of git. You do NOT need to commit before calling it. Calling createCheckpoint with no uncommitted changes is the normal path. createCheckpoint may also trigger an auto-commit hook on the orchestrator side — that hook's commit message is NOT authoritative for phase attribution (hard rule (s) S194/S195: hook reads currentPhase post-advance, drifts one phase ahead). Trust explicit authored commits (`feat|fix|refactor|docs(sN): subject`) for phase attribution in audit/blame archaeology.
 - Commit policy for this dispatch: <one of>
     a) "DO NOT commit — orchestrator owns the closure commit at review gate."
-    b) "Commit per-phase using prefix `<feat|fix|refactor>(s<N>): <subject>` — confirm prefix before commit." (use when implement phase exceeds 80k tokens or spans multiple fases)
-- If you commit, the prefix MUST be: `<feat|fix|refactor>(s<CURRENT_SESSION>):` — do NOT infer from BACKLOG examples or previous session context.
+    b) "Local commit per-phase is OK (granular revertability) using prefix `<feat|fix|refactor>(s<N>): <subject>` — confirm prefix before commit. You are on a dedicated feature branch (the orchestrator branched before dispatching you, §2c.0); commit LOCALLY only." (use when implement/framework/operational/deliver phase exceeds 80k tokens or spans multiple sub-fases)
+- **Push policy (local-commit-YES / push-NO, TD-171):** NEVER `git push`, `git merge`, or `gh pr merge`. Push/merge to a remote is owned EXCLUSIVELY by the main orchestrator, performed only AFTER its independent assert. This is enforced — `agent-git-guard` (TD-169) hard-denies sub-agent push/merge; your local commits are contained on the feature branch the orchestrator prepared (§2c.0). Return your work in your report; the orchestrator reviews, then pushes.
+- If you commit, the prefix MUST be: `<feat|fix|refactor|docs>(s<CURRENT_SESSION>):` — do NOT infer from BACKLOG examples or previous session context.
 ```
 
-Substitute `<CURRENT_SESSION>` with the active session number (e.g., `s189`) and pick **exactly one** of (a) or (b) — never leave both options visible. The block goes **after** `[Task]` and **before** the artifactStore instruction.
+Substitute `<CURRENT_SESSION>` with the active session number (e.g., `s195`) and pick **exactly one** of (a) or (b) — never leave both options visible. The block goes **after** `[Task]` and **before** the artifactStore instruction.
+
+If the orchestrator (main) wants to own all commits, prefer option (a) + call `createCheckpoint` itself after the phase completes — do NOT delegate that call to the dispatched agent.
+
+#### 2c.2 Verify-Before-Assert dispatch addenda (TD-S192-003)
+
+A second cross-cutting concern surfaced from S192 + S193 + S194 + S195 dispatches: sub-agents assert scope coverage from upstream artifact references (file paths, line numbers, persona IDs, artifact IDs) **without verifying empirically**, producing false-positives that cost downstream cycles.
 
-If the orchestrator (main) wants to own all commits, prefer option (a) + call `createCheckpoint` itself after the implement phase completes — do NOT delegate that call to implementer.
+Documented instances:
+- **S192 phase 2** — sub-agent path-fallback gap (TD-S192-002): methodology-researcher cited `.claude/personas/cfo-conservador.md` from BACKLOG context but never confirmed file existed in working tree at dispatch time; persona was actually present but the assumption pattern was visible. See memory `subagent_path_fallback_artifactretrieve_gap_s192phase2`.
+- **S193** — `persona_cfo_conservador_file_absent_s191b` memory documents an instance where the assumption *did* break (persona referenced but file absent in workflow context).
+- **S194** — line range estimates from BACKLOG (`part2.test.ts:40-95`) were off by 13 lines (actual block ended at line 82, not 95); implementer caught this via Read empirically.
+- **S195** — implementer applied verify-before-assert correctly on TD-S191-005: BACKLOG estimated 10 lint errors, real count was 352. Implementer stopped + deferred to TD-S195-001 rather than improvise. **Canonical positive example.**
+
+To prevent recurrence, append the following **verify-before-assert block** to every dispatch prompt:
+
+```
+[Verify-Before-Assert]
+Before asserting any file path, line range, persona ID, artifact ID, or other concrete entity cited in upstream context (BACKLOG, previous artifact, session memory), VERIFY empirically:
+- File path → confirm via Read or Glob that the file exists with expected content
+- Line range → READ the file, confirm structure matches (e.g., describe block boundaries)
+- Persona ID → load `.claude/personas/<id>.md` and confirm the file is present + contains expected fields
+- Artifact ID → call artifactRetrieve and confirm payload structure
+- Lint/test counts → run the actual command (`bun lint`, `bun test`) — do not trust BACKLOG estimates
+
+If empirical verification diverges from the cited assumption (e.g., line range off, file absent, count larger than estimated), STOP and report the divergence in the implementation-report (or equivalent artifact for non-implementer agents). DO NOT improvise to fit the cited assumption — divergence is signal, not noise. Better to defer scope via a new TD than to silently violate the dispatch contract.
+```
+
+The block goes **after** `[Task]` and **before** `[Commit Policy]`. It applies to every agent dispatch, not just those with `createCheckpoint`.
 
 ### 2d. Gate Check
 
@@ -123,6 +175,22 @@ mcp__orchestrator-tools__advancePhase({ workflowId: "..." })
 
 Loop back to 2a for the next phase.
 
+### 2d.1 Post-Implement Signal → docs-guardian dispatch (RFC-034 / System A)
+
+When you `advancePhase` out of `implement` (the workflow enters `review`), the `post-implement.ts` hook fires on `PostToolUse[mcp__orchestrator-tools__advancePhase]` and injects an orchestrator signal:
+
+```
+[ORCHESTRATOR] IMPLEMENT completed for <workflowId> — dispatch the docs-guardian sub-agent before proceeding past the IMPLEMENT gate.
+```
+
+On seeing that signal, dispatch `docs-guardian` (documentation compliance vs `DOCS-CONSTITUTION`) **before** running the review gate / closing the workflow:
+
+```
+Agent(subagent_type: "docs-guardian", prompt: "[Workflow] ... Review documentation compliance for the changes just implemented; report deltas + archival candidates vs DOCS-CONSTITUTION.")
+```
+
+**Why a signal, not direct hook action:** a hook (a node/bash script) cannot spawn a Claude sub-agent in the main-as-orchestrator model (RFC-022) — `post-implement.ts` is a *deterministic trigger* that emits the signal; **the orchestrator owns the dispatch**. The detection is deterministic: the hook reads the live workflow state and emits only when the post-advance `currentPhase === 'review'` (review is reached only by leaving `implement`). Fail-open: if the API is down or env is unset the hook emits nothing — so if you expected the signal and it is absent, dispatch `docs-guardian` anyway as part of review. Skin: MUST rule #5.
+
 ## Step 3 — Complete Workflow
 
 After all phases are done:
@@ -150,6 +218,26 @@ Load these for phase-specific guidance when needed:
 | `/project-conventions` | Before implementation (stack-agnostic; stack-specific context via StackContextBuilder) |
 | `/checkpoint-protocol` | After completing task groups |
 
+## Convergence & Quality Instrumentation (orchestrator self-direction)
+
+Quando uma **assinatura de falha recorrente** aparece, **não repita o caminho que já falhou** — leia o sinal e escolha a alavanca. Tudo aqui é pure-use e preserva `main-as-baton` (RFC-022/ADR-019). A CI crônica (TD-143) é **só mais uma linha**.
+
+| Sinal que você observa | Leitura provável | Alavanca (não repita cego) |
+|---|---|---|
+| **Sub-agent não converge** — specifier/planner re-despachado 2–3× sem passar o gate; adversarial review não baixa `severity:high` | A ambiguidade costuma ser **upstream** (input/requisito), não o agente. Convergência é **limitada**: máx 3 iterações (`feedback_adversarial_reviewer_3_iteration_hard_cap_s183`). | Na 3ª sem convergir, **muda a abordagem**: reframe o input · `/effort xhigh` na re-tentativa · fan-out de N tentativas independentes + síntese (judge-panel) · pivot cirúrgico do main (`m2_pivot_orchestrator_surgical_edit_on_socket_failure_s227`, `bounded_pivot_in_workflow_instead_of_abort_s227e`) · gate ao user. |
+| **"Green" suspeito do implementer** — stub/`expect(true).toBe(true)`, `tsc --noEmit` false-green, comment afirma fix sem guard-code, contagem self-report inflada | Self-report **não é ground-truth**; o gate confiou no relato. (`feedback_trc_frontend_self_report_test_counts_unreliable`, `tsc_noemit_false_green_and_required_field_cascade_seam_s247`, `verify_coverage_metric_independently_not_subagent_selfreport_s233`, `code_comment_claims_fix_without_guard_code_s252`) | **Re-rode os gates você mesmo** (tsc real, `npm run lint` real, vitest com escopo) + reviewer re-roda independente. Contagem = alegação a verificar. Divergência "inflada-mas-verde" também é finding. |
+| **Review acha medium/high DEPOIS da implementação**, recorrente numa área | Defeito caro pego tarde — gate de qualidade só no fim. (`feedback_plan_gate_scope_expansion`, `feedback_staged_dispatch_per_gate_storybook_loop_s268`, `canary_first_gate_for_deck_design_iterations_s267`) | **Shift-left**: front-load adversarial review no gate de plan/spec; staged dispatch por gate; canary-first numa fatia antes do lote. |
+| **CI crônica vermelha / convergência longa** (TD-143) | Problema de **convergência/diagnóstico, não de cobertura** (FEATURE-MATRIX §2); e a premissa do TD pode ser falsa (`feedback_td_premise_can_be_false_positive_verify_before_fixing_s243`). | `/goal "<critério verde>"` como condição de saída + background Bash + Monitor; fan-out workflow read-only **só se** o diagnóstico for amplo; verificar a premissa antes de "consertar". |
+
+### Alavancas (toolbox que a tabela referencia)
+
+- **`/goal`** — condição de saída explícita; **só no main-loop** (nunca sub-agent/workflow-interno; lá dentro `while`/loop-until-dry em JS).
+- **background Bash + Monitor** — comando longo (`gh run watch`, suites) sem travar a sessão (stream, não poll).
+- **Dynamic Workflow fan-out** — N perspectivas/root-causes em paralelo → gate de consenso. Read-only é livre; sub-agent que escreve `src/` ainda bate no `workflow-guard` (Invariante #1). Despachar via `opts.agentType` (honra `model` do frontmatter — probe `wf_b6ec4bc1`); `model` explícito = cinto-de-segurança. **Nunca** `CLAUDE_CODE_SUBAGENT_MODEL` global (sobrescreve frontmatter, quebra a FinOps Matrix).
+- **Agent View `--json`** — poll determinístico de sessions bg (`state`/`waitingFor`/PR-status; coluna PR destaca CI vermelha).
+- **`/effort` (xhigh/ultracode)** — bump de raciocínio na re-tentativa de diagnóstico difícil.
+- **270s heartbeat** — cadência cache-warm pra `/loop`/`ScheduleWakeup` (TTL do prompt-cache = 300s; estudo RUFLO #6).
+
 ## Error Recovery
 
 - **Sub-agent fails** → read the error, fix the issue, re-dispatch.

package/skills/persona-library/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: persona-library
-description: Catalog navigation for `.claude/personas/`. Load when: "find persona", "list personas", "select reviewer persona", "persona by industry", "persona for X industry", "create new persona", or when methodology-researcher / adversarial-reviewer / operational-artifact-builder need persona selection guidance. Provides search/filter/select-for-review primitives + scaffold for new persona authoring.
+description: 'Catalog navigation for `.claude/personas/`. Load when: "find persona", "list personas", "select reviewer persona", "persona by industry", "persona for X industry", "create new persona", or when methodology-researcher / adversarial-reviewer / operational-artifact-builder need persona selection guidance. Provides search/filter/select-for-review primitives + scaffold for new persona authoring.'
 allowed-tools: Read, Grep, Glob, Write
 ---