@daniellins/power-claude 0.16.3

package/template/.claude/rules/orchestration.md

@@ -0,0 +1,133 @@
+# Orquestração do Ciclo — Sessão Coordenadora e Subagentes
+
+Regra global do ambiente POWER CLAUDE. Aplica-se a qualquer projeto com o framework instalado (detectável por `.claude/skills/pc-full-cycle/` e papéis do ciclo em `.claude/agents/`). Sem o framework, desenvolvimento normal.
+
+## Regra central
+
+**Toda mudança de código roda pelo ciclo com os papéis encarnados em subagentes** — o humano não invoca papéis manualmente. A sessão principal atua como **coordenadora**:
+
+- **Investiga read-only** para diagnosticar antes de despachar — diagnóstico rico no brief economiza o contexto dos subagentes.
+- **Monta briefs completos:** paths/linhas exatos, ACs, limites de autoridade (ex.: dev não faz push) e o que retornar.
+- **Roteia handoffs** entre fases; o resultado resumido de um papel entra no brief do próximo.
+- **Reporta ao humano** apenas marcos e decisões de produto.
+
+## Núcleo garantido + especialistas por gatilho
+
+Núcleo em toda mudança (via `pc-full-cycle`):
+
+```
+planner (story) → po (valida, Draft→Ready) → dev (implementa, sem push) → qa (gate adversarial) → devops (push/PR/merge — exclusivo)
+```
+
+Especialistas entram quando o conteúdo exige. O gatilho fica **registrado na story**, e o PO **não transiciona a Ready com gatilho insatisfeito**:
+
+| Especialista | Gatilho |
+|---|---|
+| analyst | Pesquisa/benchmark necessário antes de especificar |
+| architect | Dependência de arquitetura declarada na story, ou complexidade STANDARD+ |
+| db-architect | DDL, RLS, migrations |
+| ux-architect | Interface nova ou alterada |
+
+Um gatilho pode ser **condicional a outro papel**: ex.: architect aciona só se a forma escolhida pelo ux-architect tocar contrato. Quem decide se o gatilho disparou é o **PO na validação**, não o próprio especialista.
+
+## Eficiência de tokens (OBRIGATÓRIO)
+
+1. **Agente fresco por story** nos papéis de execução (dev/qa/devops): nunca manter um agente vivo através de múltiplas stories — o reprocessamento do transcript cresce quadraticamente com as retomadas. O contexto viaja no brief. Retomada do MESMO agente (SendMessage) só DENTRO do ciclo da mesma story (fix rounds).
+2. **Relatórios ≤15 linhas por contrato:** o retorno de cada subagente se limita a branch/sha, arquivos, verificações e desvios — detalhes, evidências e racionais vão na STORY (o registro auditável), não no relatório. O brief pede isso explicitamente.
+3. **`effort: low` em etapas mecânicas** (transições de status, commits de docs, cópias/relatórios simples) via parâmetro do Agent tool; effort padrão nas etapas de julgamento.
+
+**Ressalva inegociável:** gates de qualidade (validação do PO, gate adversarial do QA) NUNCA são onde se economiza — nenhuma das regras acima os afrouxa.
+
+## Contrato de brief (o que todo dispatch inclui)
+
+1. Paths (e linhas, quando relevante) exatos dos arquivos envolvidos.
+2. ACs da story e critérios de aceite verificáveis.
+3. Limites de autoridade do papel (ex.: dev não faz push; QA não implementa fixes). **Toda restrição ALÉM da autoridade padrão do papel cita a LINHA exata de `.claude/rules/authority.md` que a sustenta** (`authority.md:{linha}`, com a frase da linha); não havendo nenhuma, o campo escreve verbatim "nenhuma restrição além da autoridade padrão do papel" (`DF-SF13.3-1`). **Restrição sem âncora não vale** — o papel obedece a um brief errado sem ter como contestá-lo. Origem: `FINDING-5` do gate `SF13.11`, onde o brief mandou o Dev "não commitar" e `authority.md:10` não sustentava a restrição — a linha lista "commits locais" na coluna "Autoridade exclusiva" do Dev, e o que ela bloqueia na coluna "Proibido" é `git push`, não o commit —, e o resultado foi entregável fora do git.
+4. O que retornar — e a instrução explícita: "relatório final ≤15 linhas; detalhes vão na story". **E a instrução explícita de commitar o artefato exclusivo do papel antes de fechar o turno** — gate file do QA, `Status`/`File List` do Dev, transição `Ready` do PO: o papel roda `git status --short`, não deixa nada seu *untracked*, commita ele mesmo e reporta o sha do commit (`DF-SF13.3-2`). Qual é o artefato exclusivo de cada papel se lê na coluna "Autoridade exclusiva" de `authority.md:9-15`; para o gate file, em `authority.md:17` ("só QA escreve `docs/qa/gates/*.yaml`"). Commitar ANTES de encerrar é do próprio papel, nunca de quem vier depois: o artefato deixado para trás é varrido, sem crédito, para dentro do commit de outro papel. Origem: 3ª ocorrência de "trabalho do papel não commitado" (`docs/stories/sf13.7.story.md`, Change Log `v1.5`) — o gate file da 1ª passada do QA ficou *untracked* e entrou no repo dentro de `40c48ae`, o commit do fix round do `pc-planner`. **E nenhum turno termina "aguardando" um processo em background que ele mesmo lançou** — background não sobrevive ao fim do turno que o lançou; o que não for colhido (lido, verificado) DENTRO do mesmo turno se perde, e o brief nunca instrui um papel a esperar por ele (`DF-SF13.4-1`). Origem: 3 ocorrências da tabela do dono ("agente encerra esperando background que morreu com ele", `docs/stories/epic-sf13-processo-a-prova-de-falhas.md:55`) + 1 ocorrência viva desta rodada (`docs/stories/release-0.16.1.story.md`, Dev Agent Record → Desvios registrados: "Watchdog em background não sobrevive ao fim do turno do agente" — watchdog e monitor lançados em background, nenhuma notificação chegou, corrigido reexecutando em foreground).
+5. **Todo número/afirmação vem com o método de medição** (ver disciplina abaixo) — sem isso o subagente não consegue falsificar, e erro da coordenadora vira premissa.
+
+### Esqueleto do brief (`DF-SF13.3-3`)
+
+Copiar e preencher. Os 5 campos são os 5 itens do contrato acima; os campos 3 e 4 trazem os dois remédios já embutidos (`DF-SF13.3-1` e `DF-SF13.3-2`), justamente para que nenhum dos dois dependa de a coordenadora lembrar deles na hora do dispatch. Campo que não se aplica é preenchido com a frase-padrão, nunca apagado — um campo ausente não se distingue de um campo esquecido.
+
+```text
+[Papel] pc-{papel} — Story {ID} — repo {repo} — branch {branch} @ {sha}
+
+1. Paths exatos (com linhas, quando relevante):
+   - {arquivo}:{linhas} — {o que há ali}
+
+2. ACs / critérios de aceite verificáveis:
+   - {AC-n}: {enunciado} — oráculo: {comando executável}
+
+3. Autoridade: padrão do papel, conforme .claude/rules/authority.md.
+   Restrições ALÉM do padrão (cada uma com âncora obrigatória):
+   - {restrição} — âncora: authority.md:{linha} — "{frase da linha que a sustenta}"
+   Se não houver nenhuma: "nenhuma restrição além da autoridade padrão do papel".
+
+4. O que retornar: relatório final ≤15 linhas (branch/sha, arquivos, verificações,
+   desvios); detalhes, evidências e racionais vão na STORY, não no relatório.
+   Antes de encerrar o turno: rodar `git status --short`, commitar o artefato
+   exclusivo deste papel — {gate file / Status + File List / transição de status} —
+   e reportar o sha do commit. Nada seu pode ficar untracked ao fim do turno.
+   Nenhum processo em background lançado por este turno pode ficar para outro
+   colher: o que não for colhido AGORA some com o fim do turno.
+
+5. Medição: todo número e toda afirmação vêm com o método (comando executado ou
+   linha lida). Amostra é declarada como amostra. Sem método verificado, escrever
+   "não consegui verificar".
+```
+
+## Disciplina de medição da coordenadora (OBRIGATÓRIO)
+
+Nasceu de **7 erros da mesma classe numa única sessão** (2026-08-06/07), todos por **usar contagem ou amostra como se fosse prova**. Nenhum chegou a `main` — os papéis contestaram —, mas cada um custou pelo menos uma rodada.
+
+**1. Contagem NUNCA conclui.** `grep -c`, `wc -l`, `ls | wc`, contagem de diretórios servem para **triagem**. Para **afirmar**, é obrigatório ler a linha inteira (`grep -n` + leitura) ou executar o caso. Em documento longo e estruturado, contagem engana quase sempre — o termo procurado aparece em negação, em change log, em declaração de escopo.
+*Casos: "3 pods" era declaração de escopo; "NÃO satisfeito" era a negação dele; "6 runs" eram diretórios, não rodadas (eram 21).*
+
+**2. Amostra é declarada como amostra.** Testou 1 de N ⇒ escreve "testei 1 de N", nunca "os N". *Caso: rodei o smoke em 1 workflow, vi falhar, escrevi "os 5 falham" — dois davam 4/4 verde.*
+
+**3. Presença de artefato não prova autoria.** Antes de concluir "X usa isto", checar distribuição temporal e origem (`stat`, `git log` do commit que trouxe os arquivos, repetição de parâmetros). *Caso: 21 artefatos de rodada, todos no mesmo minuto, eram evidência de harness — reportei ao dono como uso dele.*
+
+**4. Inferência de subagente não vira fato da coordenadora.** Repassar sempre como inferência **dele**, com o método, para o dono poder duvidar.
+
+**5. Nunca pular etapa do processo por julgamento de tamanho.** *Caso: pulei a 2ª passada de `*review` numa story "pequena"; o PO barrou, e a passada faltante achou 3 bloqueantes — um deles de segurança.*
+
+**6. `A...B` (três pontos) sempre**, para "o que esta branch muda". Dois pontos em branch atrasada mostra o que `main` avançou.
+
+**Regra de ouro:** *se não li a linha nem executei o caso, a frase certa é **"não consegui verificar"*** — custa uma linha; afirmar errado custa uma rodada, ou vira premissa que ninguém reexamina.
+
+## Higiene de documento normativo (OBRIGATÓRIO)
+
+Épico/ADR/regra que **envelhece sem remedição** é a segunda fonte de retrabalho, e a mais silenciosa: fica afirmando o superado até alguém tropeçar, e quem lê **copia de boa-fé**.
+
+1. **Story que fecha uma dívida verifica onde ela está citada** — fechar na origem e deixar as cópias é o padrão observado 3× (épico 2×, ADR 1×).
+2. **Correção de texto superado vem com a negação explícita** ("não mais X; leitura superada, não repetir"), não só com a substituição — porque o defeito costuma ser um AC mandando gravar a frase antiga.
+3. **Documento que afirma completude tem de nomear sobre o quê** ("satisfeito para A e B", nunca "para os 3") — foi assim que se descobriu que o `hn-carousel` estava fora.
+4. **Exemplo/comando dentro de ADR, review ou regra precisa ter sido EXECUTADO** — texto normativo não testado propaga o defeito **com autoridade**. Ocorreu 3×: exemplo de AC no ADR-030, comando com assinatura errada num `*review`, e uma memória da coordenadora afirmando mais do que fora medido.
+5. **Não afirme o estado de outro artefato — delegue a ele** (`DF-SF13.5-4`, `ADR-036`). Documento normativo que precisa se referir ao estado de algo que vive em OUTRO lugar (um checklist, uma story, um diretório, uma release) **cita o path e diz quem manda** ("a fonte é `X`; quem manda é ela, não este parágrafo"), em vez de congelar o estado em prosa. As formas que envelhecem são conhecidas e nomeadas: *"ainda não chegou"*, *"segue pendente/ausente"*, *"bloqueado até Z"*, *"N itens sem Y"*. Quando forem inevitáveis, vêm **na mesma frase** com o path da fonte que as decide — e enumeração de estado (*"os 5 pods sem workflow são…"*) não se escreve em prosa: escreve-se o comando que a produz, ou não se escreve. Os itens 1-4 mandam lembrar num momento futuro; este muda o que se pode escrever no único instante em que o autor está garantidamente presente. **Detector automático desta classe foi medido e recusado** (`ADR-036`: 88% e 67% de falso-positivo) — não existe rede embaixo desta regra, e é por isso que ela não vem sozinha (ver a superfície do `*release` em `pc-devops.md`).
+
+## Práticas de orquestração
+
+1. **Paralelizar frentes independentes** (ex.: dev código ∥ devops infra); barreira só onde há dependência real.
+2. **Worktree para o dev** (`isolation: worktree`) quando houver risco de colisão com outra frente ativa.
+3. **Divergência técnica entre especialistas:** resolver por verificação de código (não por autoridade da coordenadora) e registrar a resolução na story.
+4. **Ficam com o humano:** decisões de produto (escopo, prioridade quando ambígua), trade-offs de risco e ações destrutivas/irreversíveis.
+5. **Usuário testando a working tree principal:** rode **dev e QA em worktrees isoladas** (`isolation: worktree`), QA em porta alternativa, merge só no fim — zero interferência no ambiente do usuário. Como a branch fica travada na worktree do dev, o QA commita o filho direto e a **coordenadora** avança a branch com `git -C <worktree-dev> merge --ff-only`.
+6. **Antes de qualquer commit/escrita de estado próprio, a coordenadora confere `git branch --show-current` E o cwd.** Checkout residual de uma publicação anterior já fez a coordenadora commitar em branch errada (2 incidentes reais).
+7. **Em toda missão `*release`, a coordenadora revisa CHANGELOG e versão ANTES de apresentar o PR ao dono — nunca depois, nunca em paralelo.** O incidente da `0.16.0` (CHANGELOG apresentado como pronto e corrigido em paralelo com o dono já revisando) teve causa-raiz na ordem de operação da coordenadora, não na ausência de um gate de QA formal para `*release` — por isso a correção é de prática de orquestração, não de missão nova do `pc-devops`.
+
+## Memória de papel — o caminho é curadoria humana, não pipeline (`DF-SF12.3-7`)
+
+Um aprendizado de ciclo (o que `.power-claude/cycle/learnings.md` tentava capturar por story, hoje morto e `gitignored`) vira regra ou comportamento duradouro por **curadoria manual do dono**: ele lê o aprendizado, decide que vale a pena reter, e o promove para um arquivo em `.claude/rules/*.md`. Não existe pipeline automático (`learnings.jsonl`, poda, consolidação, orçamento de admissão) — e a prova de que esse caminho já funciona é este próprio arquivo: `orchestration.md` nasceu assim, por curadoria, não por pipeline.
+
+**Por que não existe pipeline:** custo × volume não fecha conta. `.power-claude/cycle/learnings.md` acumulou 18 entradas em 4 meses antes de morrer — volume baixo demais para pagar o aparato que um pipeline exigiria (custo de memória por admissão, poda periódica, consolidação, orçamento de tokens). A arquitetura já está decidida e não é reaberta aqui: memória de papel é da **instância** (`second-brain/.power-claude/`), nunca do `template/` — o framework não acumula aprendizado de uma instalação específica.
+
+## Referências
+
+- Autoridade por papel: `.claude/rules/authority.md`
+- Matriz de modelos: `.claude/rules/model-matrix.md` (e `economy-mode.md` quando o modo econômico está ativo via `/power:modo`)
+- Destino de artefatos ao fechar trabalho (o que documentar, parquear ou descartar): `.claude/rules/curadoria-de-conhecimento.md`
+
+## Por que `planner`/`analyst`/`architect` não recebem hook (`DF-SF12.3-8`)
+
+Os 2 hooks de autoridade desta story (`.claude/hooks/enforce-cycle-authority.cjs`, ver `authority.md`) cobrem `po`/`dev`/`qa`; `devops` já tinha o seu. `planner`, `analyst` e `architect` ficam de fora **por desenho, não por lacuna**: são papéis de **julgamento** (SPEC, pesquisa, decisão de arquitetura) — não existe um predicado de disco que separe uma decisão boa de uma ruim para esse tipo de trabalho (mesma classe de limite nomeada no `ADR-002`). O que os governa é a régua do próprio papel (o gabarito de qualidade descrito em cada `.claude/agents/pc-*.md`), não um hook `PreToolUse`. **Evidência de que isso já funciona, medida, não hipotética:** o achado (d) do `ADR-029` — "0 de 3 erros de coordenadora pegos por qualquer motor, mas pegos por papel lendo o disco e contestando" — e o achado (g) desta própria story (SF12.3): um `pc-qa` despachado para agir fora do próprio limite de papel **recusou, duas vezes**, sem hook nenhum. Disciplina de papel segura a fronteira de julgamento; hook mecaniza só as 2 garantias de autoridade que não podem depender de disciplina (Bloco C/D).

package/template/.claude/settings.json

@@ -0,0 +1,50 @@
+{
+  "language": "portuguese",
+  "permissions": {
+    "deny": [
+      "Read(.env)",
+      "Read(.env.*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-git-push-authority.cjs\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-cycle-authority.cjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-ready-oracles.cjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-budget.cjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/skills/pc-apply-qa-fixes/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: pc-apply-qa-fixes
+description: "Aplica os findings de um QA gate FAIL/CONCERNS e devolve a story para re-review — nunca se auto-aprova. Use para: corrigir reprovação de QA, tratar findings do gate, remediar gate FAIL, rodar iteração do loop de fix."
+---
+
+# pc-apply-qa-fixes — Correção de Findings de QA (papel Dev)
+
+Protocolo completo e autocontido. Nenhuma engine externa é necessária.
+
+## Quando usar
+
+Existe gate file em `docs/qa/gates/{story}.yaml` com veredito **FAIL** (ou **CONCERNS** que o humano decidiu tratar). A story voltou para `InProgress`.
+
+## Pré-condições
+
+1. Gate file existe e foi lido por completo.
+2. Você está na branch da story (branch guard de `pc-develop-story` continua valendo — nunca em `main`).
+3. Contagem de iterações do loop conhecida (ver "Limite de iterações").
+
+## Protocolo
+
+> **Protocolos aprofundados (carregue sob demanda):** o passo-a-passo determinístico de 8 fases do loop está em `references/fix-loop.md`; o template estruturado do pedido de correção (antes/depois + verificação por item + constraints de escopo) em `references/fix-request-template.md`. Para julgar se um finding aponta bug real ou é falso positivo antes de corrigir, use o teste de causação de `../pc-review-story/references/false-positive-detection.md`.
+
+### Passo 1 — Inventário TOTAL antes de corrigir
+
+Antes de tocar em qualquer arquivo, monte a tabela de inventário com **TODOS** os findings do gate file (e da seção QA Results). Proibido corrigir "de cabeça" o primeiro finding e descobrir os outros depois — inventário incompleto é a causa clássica de loop desperdiçado.
+
+| # | Finding (do gate) | Severidade | Decisão | Justificativa/Dono |
+|---|---|---|---|---|
+| 1 | ... | bloqueante/menor | FIXED / WON'T_FIX / DEFERRED | ... |
+
+### Passo 2 — Classificar cada finding
+
+Cada finding recebe exatamente uma decisão:
+
+- **FIXED** — corrigido nesta iteração, com causa-raiz tratada (não sintoma mascarado).
+- **WON'T_FIX** — não será corrigido, com justificativa técnica explícita (ex.: fora de escopo dos ACs, comportamento intencional). Precisa convencer o QA na re-review; justificativa fraca vira FAIL de novo.
+- **DEFERRED** — será tratado depois, com **dono nomeado** (story futura criada/apontada, ou humano que assumiu). DEFERRED sem dono e destino não existe.
+
+Nenhum finding pode ficar sem decisão. Silêncio sobre um finding = FAIL automático na re-review.
+
+### Passo 3 — Corrigir os FIXED
+
+- Trate a causa-raiz. Nunca suprima o erro (skip de teste, `ts-ignore`, desligar lint) para o gate "passar".
+- Siga o No Invention: corrija o finding, não aproveite para refactors fora de escopo.
+- Atualize a File List da story com qualquer arquivo novo/modificado.
+- Registre no Dev Agent Record: iteração N do loop, findings tratados, decisões `[AUTO-DECISION]` se houver.
+
+### Passo 4 — Re-rodar TODOS os gates
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+```
+
+Todos verdes na sua execução local, com saída registrada no Dev Agent Record. Se a correção quebrou outra coisa, conserte antes de devolver — devolver com gate vermelho conhecido queima uma iteração do loop à toa.
+
+### Passo 5 — Commit e devolução para re-review
+
+1. Commit local convencional via `pc-commit`: `fix: trata findings do QA gate [Story X.Y]`.
+2. Atualize `Status: InProgress` → `Status: InReview`.
+3. Devolva explicitamente para `pc-review-story` com a tabela de inventário preenchida (finding → decisão → evidência).
+
+**NUNCA se auto-aprove.** Você não seta `Done`, não edita QA Results, não reescreve o veredito do gate file. A palavra final é do papel QA, em contexto independente (`.claude/rules/authority.md`).
+
+## Limite de iterações
+
+O loop FAIL → fix → re-review tem **máximo 3 iterações**.
+
+- Registre no Dev Agent Record qual iteração é esta (1/3, 2/3, 3/3).
+- Na 3ª re-review sem PASS: **PARE e escale ao humano** com: histórico dos 3 vereditos, findings recorrentes, e sua hipótese de causa (AC ambíguo? arquitetura errada? gate mal calibrado?). Nunca afrouxar o gate, nunca "negociar" o veredito com o QA para fechar por cansaço.
+
+## Referência rápida
+
+| Momento | Ação |
+|---|---|
+| Antes de tocar em código | Inventário TOTAL dos findings, cada um com decisão |
+| Antes de devolver | Todos os gates re-executados e verdes |
+| Ao devolver | Status → `InReview` + tabela de inventário para o QA |
+| Iteração 3 sem PASS | Escalar ao humano com histórico — nunca afrouxar o gate |
+
+## Anti-padrões
+
+- Corrigir findings seletivamente e omitir os incômodos.
+- WON'T_FIX como atalho para não trabalhar (justificativa de uma linha vazia).
+- Marcar FIXED sem re-rodar a suíte completa de gates.
+- Editar o gate file do QA para "atualizar" o veredito.
+
+## Exemplo de inventário preenchido
+
+| # | Finding (do gate) | Severidade | Decisão | Justificativa/Dono |
+|---|---|---|---|---|
+| 1 | POST /session retorna 500 com payload válido | bloqueante | FIXED | null check em `session.ts:42`; teste de rota adicionado |
+| 2 | File List omite `utils/token.ts` | menor | FIXED | File List atualizada; conferida contra `git diff --stat` |
+| 3 | Falta rate-limit no endpoint | menor | DEFERRED | Fora dos ACs desta story; criada story 2.4 (dono: humano/PO) |
+| 4 | Log em nível debug em produção | menor | WON'T_FIX | Comportamento intencional atrás de flag `DEBUG`; documentado no Dev Agent Record |
+
+## Casos de borda
+
+- **Finding que você discorda tecnicamente:** WON'T_FIX com argumento técnico completo — o QA arbitra na re-review. Nunca ignore em silêncio nem edite o gate file para remover o finding.
+- **Finding cuja correção exige mudar um AC:** isso não é fix, é mudança de escopo. PARE e escale ao humano — nem Dev nem QA têm autoridade para reescrever ACs.
+- **Dois findings com correções conflitantes:** escolha a resolução que preserva os ACs, registre `[AUTO-DECISION]` com o trade-off e destaque para o QA na devolução.
+- **Finding não reproduzível localmente:** documente a tentativa de reprodução (comandos e saídas). Não marque FIXED sem reproduzir; devolva como pergunta ao QA com a evidência da tentativa.
+
+## Saída esperada
+
+Resposta final contém: tabela de inventário completa (finding → FIXED/WON'T_FIX/DEFERRED + justificativa/dono), saídas resumidas dos gates re-executados, número da iteração do loop, e confirmação de que a story voltou para `InReview` aguardando re-review.

package/template/.claude/skills/pc-apply-qa-fixes/references/fix-loop.md

@@ -0,0 +1,40 @@
+# Fix Loop — as 8 fases da correção de findings
+
+> Protocolo aprofundado do `pc-apply-qa-fixes`. Origem destilada: task `qa-fix-issues.md`. O SKILL.md tem o essencial (inventário → decisão → fix → gates → devolução); este arquivo é o passo-a-passo determinístico completo. Carregue quando o loop tiver múltiplos findings ou verificação não trivial.
+
+**Restrições inegociáveis (valem em todas as fases):** mudança mínima; corrigir SÓ o que está no pedido de fix; sem refactor "de passagem"; sem feature nova; sem corrigir o que não foi reportado. Violação de escopo detectada → **HALT** com "só corrija os findings do gate/fix request".
+
+## Fase 0 — Carregar contexto
+Ler o gate file (e o `QA_FIX_REQUEST.md` se existir) + a story. Fix request/gate ausente → HALT.
+
+## Fase 1 — Parse e priorização
+Extrair cada finding: `id`, `severity`, arquivos afetados, passos de verificação. Montar checklist com `status: pending`. **Ordem de correção: CRITICAL → MAJOR → MINOR** (bloqueante antes de menor).
+
+## Fase 2 — Preparar ambiente
+Conferir branch da story (`git branch --show-current`; nunca `main`) e cwd. Registrar `commitBefore` e branch. Working tree limpa ou só com mudanças esperadas.
+
+## Fase 3 — Corrigir sequencialmente (núcleo)
+Para cada finding, em ordem de severidade: localizar → aplicar **fix mínimo** → marcar `fixed` → logar. Não localizou (talvez já corrigido) → log e segue. Fix exigiria mudança grande/refactor → **HALT** (excede escopo do fix mínimo; ver caso de scope creep no SKILL.md).
+
+## Fase 4 — Rodar gates
+`npm run lint`, `npm test`, `npm run typecheck` (quando aplicável). Falhou → volta à Fase 3. Máx. 3 tentativas, senão HALT. Nunca suprimir erro para "passar".
+
+## Fase 5 — Auto-verificação
+Executar TODOS os passos de verificação do fix request, por tipo: `command` (CLI + checar saída), `api` (curl + resposta), `browser`/`e2e` (UI/fluxo), `manual` (documentar). Qualquer passo falha → volta à Fase 3. Documentar resultado de cada passo (passed + evidência).
+
+## Fase 6 — Commit
+`git add` só nos arquivos modificados para os fixes. Mensagem convencional referenciando os IDs:
+```
+fix: resolve <issueIds> [Story X.Y]
+
+Findings tratados:
+- CRIT-1: <descrição>
+- MAJ-1: <descrição>
+```
+(Use `pc-commit`.)
+
+## Fase 7 — Atualizar e sinalizar re-review
+Atualizar a File List e o Dev Agent Record (iteração N/3, findings tratados, `[AUTO-DECISION]`). Preencher a tabela de inventário (finding → FIXED/WON'T_FIX/DEFERRED + evidência). `Status: InProgress → InReview`. Devolver explicitamente ao `pc-review-story`. **Nunca setar `Done` nem editar o gate file.**
+
+## Fim parcial (nem tudo corrigível)
+Finding que exige escopo além do fix mínimo (ex.: refactor de camada) não vira FIXED forçado: marque como precisa de decisão, explique por quê, e proponha DEFERRED com dono/story de follow-up. Reporte "parcialmente completo" com a lista do que ficou — decisão de escopo é do humano/PO, não do dev.

package/template/.claude/skills/pc-apply-qa-fixes/references/fix-request-template.md

@@ -0,0 +1,70 @@
+# QA Fix Request — template estruturado
+
+> Template do pedido de correção que o QA (`pc-review-story`) entrega ao Dev (`pc-apply-qa-fixes`) quando um gate FAIL/CONCERNS gera trabalho. Origem destilada: task `qa-create-fix-request.md`. Salvar em `docs/qa/gates/{story}-fix-request.md` (ou junto do gate file). Inclui CRITICAL e MAJOR por default; MINOR opcional.
+
+O valor do template: cada finding vem com **antes/depois** concreto, **passos de verificação** por item, e **constraints de escopo explícitos** — é o que impede o loop de virar refactor.
+
+```markdown
+# QA Fix Request: {storyId}
+
+**Gerado:** {timestamp}
+**Fonte:** {gate file / QA Results}
+**Reviewer:** pc-qa
+
+---
+
+## Instruções para o Dev
+
+Corrija SOMENTE os findings abaixo. Não adicione features nem refatore código não relacionado.
+Processo: leia cada finding → corrija o problema específico → verifique com os passos dados →
+marque como corrigido → rode todos os gates antes de concluir.
+
+## Resumo
+
+| Severidade | Qtde | Status                  |
+|------------|------|-------------------------|
+| CRITICAL   | {n}  | Corrigir antes do merge |
+| MAJOR      | {n}  | Corrigir antes do merge |
+| MINOR      | {n}  | Melhorias opcionais     |
+
+## Findings a corrigir
+
+### 1. [CRITICAL] {título}
+
+**ID:** FIX-{story}-001
+**Local:** `caminho/arquivo.ts:45`
+
+**Problema:**
+​```{lang}
+{trecho do código com o problema}
+​```
+
+**Esperado:**
+​```{lang}
+{trecho corrigido, ou descrição do comportamento esperado}
+​```
+
+**Verificação:**
+- [ ] {passo de verificação executável}
+- [ ] {outro passo}
+
+**Status:** [ ] Fixed
+
+---
+
+## Constraints (o Dev DEVE seguir)
+
+- [ ] Corrigir SÓ os findings acima
+- [ ] NÃO adicionar features novas
+- [ ] NÃO refatorar código não relacionado
+- [ ] Rodar `npm test`, `npm run lint`, `npm run typecheck` antes de concluir
+- [ ] Atualizar a File List da story se criar arquivo novo
+
+## Depois de corrigir
+
+1. Marcar cada finding como corrigido aqui.
+2. Atualizar o Dev Agent Record com o resumo (iteração N/3).
+3. Devolver para re-review: `pc-review-story`.
+```
+
+Nota: o `pc-review-story` já emite findings no gate file (formato YAML com `id/severity/ac_afetado/descricao/evidencia/acao_sugerida`). Este template é a forma EXPANDIDA (antes/depois + verificação por item) para quando o loop de fix precisa de mais estrutura que a lista do gate — não substitui o gate file, o complementa.

package/template/.claude/skills/pc-arena/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pc-arena
+description: "Harness de comparação CEGA reutilizável: compara N≥2 braços (pod vs pod, prompt vs prompt, modelo vs modelo, antes/depois de um mecanismo) por rodadas, com insumos congelados por hash, operador de brief fechado, rótulos cegos permutados e mapa SELADO (revelação só após todas as rodadas pontuadas), rubrica ponderada travada ANTES de rodar, tokens por braço/rodada e veredito por eixo (diferença mínima sustentada em K de N; empate é válido). Use para: comparar dois pods/prompts/modelos às cegas, medir regressão de qualidade quando um mecanismo do framework muda, avaliar conversão de squad legado, benchmark cego reutilizável."
+---
+
+# pc-arena — Harness de Comparação Cega (coordenadora)
+
+Skill irmã de `pc-run-pod`. Lá o **pod é dado** e o script é o motor; aqui o **experimento é dado** (N braços, rubrica, insumos) e o motor é **`scripts/arena.cjs`**, na granularidade "rodada de comparação cega". Generaliza o protocolo do benchmark 4-braços (`second-brain/docs/benchmark/PROTOCOLO-4-bracos.md`) para N braços quaisquer — não só 4, não só pod-vs-squad.
+
+**A cegueira é a premissa central** — um embaralhamento silenciosamente errado invalida o experimento inteiro. Por isso a lógica propensa-a-bug (permutação com uniquidade, mapa selado, reveal-gate, hash, tally, veredito) vive **em código testável**, não em prosa: `scripts/arena.cjs` (motor determinístico) + `scripts/arena.test.cjs` (regressão dos 2 bugs reais de embaralhamento que a operação MANUAL do benchmark cometeu). Esta skill é o **protocolo**; a máquina é do motor — do not fake green.
+
+## Fronteira (ADR-002 reaplicada à AVALIAÇÃO)
+
+| MOTOR (`arena.cjs`) — determinístico, provado por fixture | SKILL/HUMANO — julgamento, disciplina |
+|---|---|
+| Permutação de rótulos com bijeção validada (cada braço um rótulo distinto por rodada) | Autorar o brief verbatim do operador |
+| Mapa rótulo→braço selado (`chmod 600`) + **reveal-gate** (recusa revelar até todas as rodadas pontuadas) | Despachar o subagente operador FRESCO por braço |
+| Hash de congelamento dos insumos pinados | Atribuir as notas 0-5 CEGAS por dimensão de julgamento |
+| Soma de tokens por braço/rodada | Decidir a rubrica, os pesos, o limiar e o K-de-N (parâmetros) |
+| Média ponderada RECOMPUTADA + veredito (≥ limiar em K de N; empate) | Ler o relatório e tomar a decisão de produto |
+
+O motor **nunca julga conteúdo** (se a nota "4" é justa) — só recomputa e valida forma. As dimensões da rubrica separam **CHECKS DE MÁQUINA** (PASS/FAIL, `type: machine`) de **JULGAMENTO HUMANO** (0-5, `type: human`), a mesma fronteira veto-vs-checkpoint do resto do framework.
+
+## Invocação (cada comando chama o motor)
+
+```
+/pc-arena init    {expDir} --arms A1,A2,..  --rounds N --rubric {rubric.json}
+/pc-arena pin     {expDir} --round R --inputs {inputs.json}   # congela insumos da rodada (hash)
+/pc-arena score   {expDir} --round R --label W --scores {scores.json}   # nota CEGA por rótulo
+/pc-arena tokens  {expDir} --arm A1 [--round R] --tokens N
+/pc-arena status  {expDir}                                    # rodadas pontuadas / reveal liberado?
+/pc-arena reveal  {expDir}                                    # REVEAL-GATE: só com todas pontuadas
+/pc-arena report  {expDir}                                    # relatório final com revelação
+```
+
+Sob o capô: `node scripts/arena.cjs <cmd> {expDir} …`. Estado durável em `{expDir}/state.json` (blind-safe: notas por RÓTULO, nunca por braço); o mapa secreto vive em `{expDir}/sealed-map.json` (`chmod 600`), lido SÓ pela etapa de revelação.
+
+## Insumos — fixos vs pinados por rodada (§5 do protocolo-fonte)
+
+- **Fixos do experimento inteiro:** o que não varia entre rodadas nem braços (ex.: modelo de imagem, estrutura do entregável). Declarados uma vez.
+- **Pinados por rodada:** os 1-2 insumos variáveis, **iguais para todos os braços na mesma rodada**, travados com hash ANTES de qualquer braço rodar naquela rodada (`pin`). Mudar um insumo depois de ver um resultado invalida o experimento — o hash é a prova de congelamento.
+
+## Rubrica travada ANTES de qualquer rodada (parâmetro, não hardcoded)
+
+`rubric.json` (exemplo — todas as dimensões/pesos/limiar são do USO, nunca constantes da skill):
+
+```json
+{
+  "scale": 5,
+  "dimensions": [
+    { "name": "Editorial", "weight": 0.20, "type": "human" },
+    { "name": "Copy",      "weight": 0.25, "type": "human" },
+    { "name": "Visual",    "weight": 0.20, "type": "human" },
+    { "name": "Estrutura", "weight": 0.15, "type": "machine", "checks": 5 },
+    { "name": "Processo",  "weight": 0.20, "type": "human" }
+  ],
+  "verdict": { "minDiff": 0.3, "kOfN": 3 },
+  "axes": [ { "name": "pod vs squad", "a": "A3", "b": "A1" } ],
+  "prediction": "previsão registrada ANTES (viés de confirmação declarado no relatório)"
+}
+```
+
+Os pesos DEVEM somar 1.0 (o motor recusa se não somam). Dimensão `machine` recebe `{ "passed": <int 0..checks> }` no `score` e vale `(passed/checks)×escala`; dimensão `human` recebe uma nota `0..escala`. A dimensão de estrutura também é reportada como PASS/FAIL agregado no relatório — um braço pode vencer no score e ainda ter falha estrutural desqualificante, e isso fica visível, não escondido na média.
+
+**Processo** (custo/atrito) é medido, não julgado no vazio — a fórmula usada no benchmark real foi `Processo = 5 − 2.5×tokens_norm − 0.3×bloqueios` (`RELATORIO-FINAL.md §2`); registre a fórmula escolhida na `prediction`/notas do experimento antes de rodar.
+
+## O operador é fechado por construção (§6 — No Invention aplicado ao operador)
+
+Cada braço roda num **subagente FRESCO** (nunca o mesmo atravessando braços — vazaria "já sei pedir melhor"). O brief do operador contém **SOMENTE**:
+1. a descrição verbatim congelada do objeto do teste;
+2. o **script de respostas congelado** (todas as elicitações interativas são respondidas SÓ por ele);
+3. quando aplicável, o processo do braço na íntegra.
+
+**Nunca** contexto sobre o experimento, os outros braços ou a rubrica. Nas perguntas de esclarecimento, o operador responde **apenas pelo script** — nunca improvisa, nunca preenche lacuna com julgamento próprio. Sem essa trava, o operador vira uma variável não-controlada capaz de favorecer um braço.
+
+## Fluxo por rodada
+
+1. **`pin`** os insumos da rodada (congela hash) — antes de qualquer braço.
+2. Despache **um operador fresco por braço** com o brief fechado; persista o transcript; registre `tokens`.
+3. Colete os N artefatos, atribua os rótulos cegos da rodada (o motor já os selou no `init`).
+4. Julgue os N artefatos às cegas (`score` por rótulo) — sem saber a origem.
+5. **NÃO revele.** Repita para todas as N rodadas. `reveal`/`report` só depois da última nota — o reveal-gate recusa antes disso (fail-loud), para não deixar o avaliador calibrar sabendo quem "está ganhando".
+
+## Relatório final (`report`) — com revelação
+
+Emite: (1) tabela de revelação rótulo→braço por rodada; (2) scores ponderados por rodada + média + mediana; (3) veredito por eixo (vitória se diferença ≥ `minDiff` em ≥ `kOfN` rodadas; **empate é resultado válido, nunca forçado**); (4) tabela de tokens por braço/rodada; (5) conferência de qualquer `prediction` registrada ANTES, com a **limitação de viés declarada** (uma previsão vista antes do julgamento é viés conhecido — a conferência é autoavaliação declarada, não validação cega de terceiro).
+
+## Limites (honestos)
+
+- O motor testa permutação/reveal/veredito sobre fixtures, **nunca** a QUALIDADE de um julgamento real — igual a `smoke`/`motor-scripts.test`. A nota 0-5 é humana e continua dependendo de disciplina (brief verbatim, cegueira).
+- Para **N=2** a cegueira é inerentemente fraca (só 2 mapeamentos possíveis); a permutação anti-identidade só se aplica a N≥3.
+- Esta skill entrega o MECANISMO; rodar um experimento em produção é trabalho separado. Não substitui `pc-wave` (que orquestra execução paralela de stories, não avaliação cega).
+
+## Referência
+
+`docs/adr/ADR-009-pc-arena-selagem-e-permutacao-em-motor.md` · motor `scripts/arena.cjs` + suíte `scripts/arena.test.cjs` · página de uso `docs/mecanismos/pc-arena.md` · protocolo-fonte `second-brain/docs/benchmark/PROTOCOLO-4-bracos.md` (+ `RELATORIO-FINAL.md`).

package/template/.claude/skills/pc-close-story/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: pc-close-story
+description: "Bookkeeping final de uma story já aprovada pelo QA (Done): atualiza índice do epic e sugere a próxima. Use para: fechar story Done, atualizar índice do epic, encerrar ciclo de uma story, descobrir a próxima story."
+---
+
+# pc-close-story — Fechamento de Story (bookkeeping pós-Done)
+
+Protocolo completo e autocontido. Nenhuma engine externa é necessária.
+
+## O que esta skill É — e o que NÃO é
+
+É **bookkeeping**: organiza os artefatos de uma story que o QA já aprovou. **NÃO é aprovação**: esta skill **nunca muda status de lifecycle** (Draft/Ready/InProgress/InReview/Done). Se a story não está Done, o caminho é `pc-review-story` — não aqui.
+
+## Gates de entrada (todos obrigatórios; qualquer falha = PARE)
+
+Verifique, com leitura real dos arquivos:
+
+1. **Story está `Status: Done`.** Se estiver em qualquer outro status, pare e informe qual skill do ciclo falta (`pc-validate-story`, `pc-develop-story` ou `pc-review-story`).
+2. **Gate file existe** em `docs/qa/gates/{epic}.{n}-{slug}.yaml`.
+3. **Veredito do gate não é FAIL.** PASS ou CONCERNS fecham normalmente; WAIVED só fecha se `waiver_reason` está preenchido no gate file.
+4. **Seção QA Results existe** na story, escrita pelo papel QA.
+
+Se a story diz Done mas falta gate file (ou o veredito é FAIL), isso é uma **inconsistência de lifecycle**: não conserte silenciosamente — reporte ao humano com os fatos e pare. Alguém pulou o QA gate, e mascarar isso destrói a trilha de auditoria.
+
+## Protocolo
+
+### Passo 1 — Conferência de completude dos artefatos
+
+Confirme que a story contém, preenchidos:
+
+- [ ] Todos os checkboxes de tasks/ACs em `[x]`
+- [ ] File List presente
+- [ ] Dev Agent Record com saídas de gates
+- [ ] Seção de Validação (PO) com veredito GO
+- [ ] Seção QA Results com veredito
+
+Item faltando = anote como pendência de bookkeeping na resposta final (não invente conteúdo para preencher — o dono da seção é o papel correspondente).
+
+### Passo 2 — Atualizar o índice do epic
+
+No arquivo do epic (ex.: `docs/stories/epic-{n}.md` ou o índice usado pelo projeto):
+
+1. Marque a story como concluída (checkbox/status na tabela de stories do epic).
+2. Registre data de conclusão e link para o gate file.
+3. Atualize contadores de progresso do epic, se existirem (ex.: "3/7 stories Done").
+
+Se o epic não tem índice, crie a entrada mínima (tabela de stories com status) — isso é bookkeeping legítimo desta skill.
+
+### Passo 3 — Sugerir a próxima story
+
+1. Leia o índice do epic e identifique stories restantes.
+2. Considere dependências declaradas: sugira a próxima story **desbloqueada** de maior prioridade.
+3. Se a story fechada era a última do epic: sinalize o epic como candidato a encerramento e sugira ao humano a retrospectiva/decisão de próximo epic.
+4. A sugestão é **recomendação, não ação**: não crie nem inicie a próxima story automaticamente.
+
+### Passo 4 — Registro de fechamento
+
+Adicione ao final da story uma seção curta:
+
+```markdown
+## Fechamento
+- Data: {YYYY-MM-DD}
+- Gate: docs/qa/gates/{arquivo}.yaml (veredito: {PASS|CONCERNS|WAIVED})
+- Índice do epic atualizado: {sim/caminho}
+- Próxima sugerida: {story ou "epic completo"}
+```
+
+## Referência rápida
+
+| Gate de entrada | Se falhar |
+|---|---|
+| Story `Done` | Apontar a skill do ciclo que falta e parar |
+| Gate file existe | Reportar inconsistência de lifecycle ao humano |
+| Veredito ≠ FAIL (WAIVED só com justificativa) | Devolver ao ciclo de QA |
+| QA Results presente | Reportar inconsistência ao humano |
+
+## Proibições
+
+- **Nunca alterar status de lifecycle** — nem da story fechada, nem de outras.
+- Nunca editar veredito, findings ou QA Results.
+- Nunca "fechar" story sem gate file válido para destravar o fluxo.
+- Nunca fazer push, criar PR ou tag — publicação é do papel devops.
+
+## Exemplo de entrada no índice do epic
+
+```markdown
+| Story | Título | Status | Gate | Concluída em |
+|---|---|---|---|---|
+| 2.1 | Detecção de sessão no gateway | Done | [PASS](../qa/gates/2.1-sessao-gateway.yaml) | 2026-07-21 |
+| 2.2 | Rate-limit do endpoint | Ready | — | — |
+
+Progresso: 1/2 stories Done.
+```
+
+## Casos de borda
+
+- **Gate CONCERNS com débitos registrados:** feche normalmente, mas copie os débitos para o índice do epic (seção "Débitos conhecidos") — débito invisível é débito perdido.
+- **Gate WAIVED:** feche somente com `waiver_reason` preenchido; replique a justificativa na entrada do índice para a trilha ficar legível sem abrir o YAML.
+- **Duas stories fechando ao mesmo tempo no mesmo epic:** atualize o índice uma vez com as duas entradas; confira que os contadores batem com a tabela.
+- **Story Done de um epic sem pasta/índice ainda:** crie o índice mínimo (tabela acima) e sinalize ao humano que o epic estava sem registro estruturado.
+- **Branch da story ainda não publicada:** o fechamento não depende de push — anote na resposta que a branch aguarda o papel devops, sem executar nada de git remoto.
+
+## Saída esperada
+
+Resposta final contém: resultado dos 4 gates de entrada, pendências de bookkeeping (se houver), o que foi atualizado no índice do epic, e a próxima story sugerida com justificativa de uma linha.