@daniellins/power-claude 0.16.3

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

@@ -0,0 +1,108 @@
+---
+name: pc-commit
+description: "Cria commit local convencional com [Story X.Y], stage seletivo e sem push. Use para: commitar trabalho de story, commit convencional local, salvar progresso no git, preparar commits para o devops publicar."
+---
+
+# pc-commit — Commit Local Convencional
+
+Protocolo completo e autocontido. Esta skill produz **commits locais**; publicação (push/PR) é outro papel.
+
+## Quando usar
+
+Ao fechar um bloco coeso de trabalho de uma story: um AC implementado com gates verdes, uma iteração de fix de QA, um ajuste de documentação da story.
+
+## Protocolo
+
+### Passo 1 — Situar-se
+
+```bash
+git branch --show-current
+git status
+git diff --stat
+```
+
+1. **Branch guard:** se estiver em `main`/`master`, PARE — crie/troque para a branch da story (`feat/{epic}.{n}-{slug}`) antes de commitar.
+2. Revise o diff real: você commita o que está no diff, não o que lembra ter feito.
+
+### Passo 2 — Stage SELETIVO
+
+Proibido `git add .` / `git add -A` por reflexo. Adicione arquivo por arquivo (ou por pasta intencional):
+
+```bash
+git add caminho/arquivo-a caminho/arquivo-b
+```
+
+Critérios:
+- Só arquivos que pertencem ao escopo desta story/deste commit.
+- Nunca stagear: `.env*` e segredos, artefatos de build (`dist/`, `.next/`), `node_modules/`, logs, arquivos temporários ou não relacionados que estavam sujos no working tree.
+- Achou arquivo suspeito no diff (segredo, binário inesperado)? Pare e pergunte ao humano.
+
+### Passo 3 — Mensagem convencional com referência de story
+
+Formato:
+
+```
+{tipo}: {descrição imperativa e específica} [Story {epic}.{n}]
+```
+
+| Tipo | Uso |
+|---|---|
+| `feat` | Nova funcionalidade (AC implementado) |
+| `fix` | Correção de bug ou de finding de QA |
+| `test` | Só testes |
+| `docs` | Só documentação/story bookkeeping |
+| `chore` | Config, tooling, manutenção |
+| `refactor` | Mudança estrutural sem alterar comportamento |
+
+Exemplos:
+
+```
+feat: implementa validação de sessão no gateway [Story 2.1]
+fix: trata findings do QA gate (null check na rota) [Story 2.1]
+```
+
+Regras: uma mudança lógica por commit (atômico); descrição diz O QUE muda, corpo (opcional) diz POR QUÊ; sempre com `[Story X.Y]` quando o trabalho pertence a uma story.
+
+### Passo 4 — Commitar e conferir
+
+```bash
+git commit -m "feat: ... [Story X.Y]"
+git log --oneline -1
+git status
+```
+
+`git status` deve mostrar working tree consistente com o que você deliberadamente deixou de fora.
+
+## Proibições absolutas
+
+- **`--force` / `-f`:** nunca, em nenhum comando git desta skill.
+- **`--no-verify`:** nunca. Hooks de pre-commit existem para rodar; se um hook falha, trate a causa, não o bypass.
+- **`git commit --amend` de commit já publicado** (que existe no remote): nunca — reescrever história publicada quebra os outros. Amend só é aceitável em commit ainda local e não compartilhado, e mesmo assim prefira um commit novo.
+- **`git push`:** fora do escopo desta skill, sempre. Push é do papel **devops**, com aprovação humana explícita, somente fast-forward — e o hook `.claude/hooks/enforce-git-push-authority.cjs` garante isso deterministicamente. Ao terminar os commits, informe que a branch está pronta para o devops publicar.
+- Nunca commitar em `main`.
+
+## Dividindo trabalho em múltiplos commits
+
+Se o diff contém mais de uma mudança lógica (ex.: implementação do AC + bookkeeping da story + ajuste de config), divida:
+
+1. Agrupe os arquivos por mudança lógica.
+2. Um `git add` seletivo + um commit por grupo, na ordem: código/testes → docs/story → chore.
+3. Cada commit precisa fazer sentido isolado (compilar/passar gates se aplicável).
+
+```bash
+git add src/session.ts tests/session.test.ts
+git commit -m "feat: implementa detecção de sessão [Story 2.1]"
+git add docs/stories/2.1.story.md
+git commit -m "docs: atualiza File List e Dev Agent Record [Story 2.1]"
+```
+
+## Casos de borda
+
+- **Hook de pre-commit falhou:** leia a saída, corrija a causa e commite de novo. `--no-verify` continua proibido mesmo "só desta vez".
+- **Percebeu erro no último commit (ainda local):** prefira um commit `fix:` por cima; amend apenas se o commit é comprovadamente local (`git log origin/{branch}..HEAD` o inclui) e ninguém mais o consumiu.
+- **Working tree com mudanças de outra story misturadas:** stage seletivo resolve; se os arquivos se sobrepõem, use `git stash` da parte alheia ou escale — nunca commite mistura com um `[Story X.Y]` só.
+- **Segredo commitado por acidente (ainda local):** remova do stage/commit imediatamente, confirme com `git log -p -1`, e avise o humano — se já houver push envolvido, a rotação do segredo é decisão dele, não sua.
+
+## Saída esperada
+
+Resposta final contém: branch, lista de arquivos staged (e o que foi deliberadamente deixado de fora), mensagem do commit criado, hash curto (`git log --oneline -1`), e o lembrete de que a publicação aguarda o papel devops com aprovação humana.

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

@@ -0,0 +1,116 @@
+---
+name: pc-develop-story
+description: "Implementa uma story validada (Ready → InProgress → InReview) com branch guard, gates verdes e rastreabilidade total. Use para: implementar story, codar os ACs de uma story Ready, desenvolver feature do ciclo, retomar implementação em andamento."
+---
+
+# pc-develop-story — Implementação de Story (papel Dev)
+
+Protocolo completo e autocontido. Nenhuma engine externa é necessária.
+
+## Quando usar
+
+Story com Status **Ready** (veredito GO registrado por `pc-validate-story`). Se o Status for `Draft`, pare e rode a validação primeiro. Se for `InProgress`, retome do último checkbox aberto.
+
+## Passo 0 — Branch guard (obrigatório, antes de qualquer edição)
+
+1. `git branch --show-current`.
+2. Se estiver em `main` (ou `master`): **PARE**. Crie a branch antes de tocar em qualquer arquivo:
+   ```bash
+   git checkout -b feat/{epic}.{n}-{slug-curto}
+   ```
+3. Nunca, em nenhuma circunstância, commitar em `main`. Este guard não tem exceção.
+
+## Passo 1 — Preparação
+
+1. Leia a story inteira: ACs, escopo IN/OUT, dependências, critério de Done, seção de Validação.
+2. Atualize `Status: Ready` → `Status: InProgress`.
+3. Mapeie cada AC para os arquivos que serão tocados. Antes de criar qualquer arquivo novo, procure componente/utilitário existente que resolva (**reusar antes de criar**).
+
+## Passo 2 — Implementação (No Invention)
+
+- Implemente **SOMENTE** o que os ACs pedem. Nada de features extras, refactors oportunistas ou "melhorias enquanto estou aqui". Se detectar algo fora de escopo que valha a pena, registre como sugestão no Dev Agent Record — não implemente.
+- Siga os padrões existentes do código (imports, naming, estrutura de testes).
+- Cada AC ganha teste correspondente. Trate casos de borda declarados nos ACs.
+- **Assert contra a SPEC, não contra a implementação:** rótulos, mensagens e listas de UI se afirmam com o valor literal da SPEC (`.toEqual` da lista completa), nunca `toContain` do que o código já produz — senão o teste passa verde mascarando divergência (o "fake green" que o QA pega).
+- **Parser de texto de usuário testa NFC E NFD:** iPhone/macOS enviam Unicode decomposto (NFD); suíte que só cobre NFC quebra no dispositivo real. Cubra combining marks nas duas formas.
+- Trabalhe AC por AC; mantenha o loop curto: implementar → testar o teste único relevante → próximo.
+
+## Passo 3 — Gates antes de marcar [x]
+
+Um checkbox de task/AC só vira `[x]` quando os três gates estão **verdes na sua execução local**:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+```
+
+(Adapte aos comandos reais do projeto.) Cole a saída relevante — resumo de pass/fail — no Dev Agent Record. **Relato sem saída de gate não é evidência.** Se um gate falhar, corrija a causa-raiz; nunca suprima o erro (skip de teste, `// @ts-ignore`, desligar regra de lint) para "passar".
+
+## Passo 4 — Rastreabilidade na story
+
+Mantenha na story, atualizados a cada bloco de trabalho:
+
+1. **Checkboxes:** `[ ]` → `[x]` imediatamente após cada task concluída com gates verdes.
+2. **File List:** TODOS os arquivos criados/modificados/removidos — fiel ao `git diff --stat`, sem omissões. Antes de concluir, confira: `git diff --stat` deve bater 1:1 com a File List.
+3. **Dev Agent Record:** seção na story com:
+   - Decisões técnicas tomadas e por quê (inclusive `[AUTO-DECISION]` quando decidiu sem consultar o humano). Declare cada **desvio** de escopo/design com `[AUTO-DECISION]` + racional — o QA julga um a um; desvio contrabandeado sem registro é finding.
+   - Saídas resumidas dos gates (lint/typecheck/test) da execução final.
+   - Débitos ou sugestões fora de escopo (não implementados).
+
+## Passo 5 — Commits locais
+
+Use `pc-commit` (ou o protocolo equivalente): commits convencionais, atômicos, com referência à story:
+
+```
+feat: implementa detecção de sessão [Story 2.1]
+```
+
+- **NUNCA `git push`.** Publicação é do papel devops, com aprovação humana — o hook do ambiente bloqueia/pergunta de qualquer forma, mas a regra é sua, não do hook.
+- Nunca `--force`, nunca `--no-verify`.
+
+## Passo 6 — Conclusão (handoff para QA)
+
+Quando todos os ACs estiverem `[x]` com gates verdes:
+
+1. Rode a suíte completa de gates uma última vez; registre a saída no Dev Agent Record.
+2. Confirme File List == diff real.
+3. Atualize `Status: InProgress` → `Status: InReview`.
+4. Informe que a story está pronta para `pc-review-story` (papel QA).
+
+## Proibições absolutas
+
+- **NUNCA se auto-aprovar:** não sete `Done`, não escreva na seção QA Results, não emita veredito de gate. Isso é exclusivo do papel QA (`.claude/rules/authority.md`).
+- **NUNCA push** nem `gh pr create`/`gh pr merge`.
+- Nunca marcar `[x]` com gate vermelho ou não executado.
+- Nunca alterar ACs, escopo ou título da story — se um AC se provou impossível/ambíguo, pare e escale ao humano com o problema descrito.
+
+## Retomada de trabalho interrompido
+
+Ao retomar uma story `InProgress`:
+
+1. `git branch --show-current` e `git log --oneline -5` — confirme que está na branch certa e veja onde parou.
+2. `git status` e `git diff --stat` — identifique trabalho não commitado.
+3. Compare os checkboxes da story com o diff real: checkbox `[x]` sem código correspondente indica registro otimista — rebaixe para `[ ]` e registre a correção no Dev Agent Record.
+4. Continue do primeiro checkbox aberto. Não re-implemente o que os gates já provaram verde.
+
+## Casos de borda
+
+- **AC ambíguo ou impossível descoberto no meio:** PARE nesse AC, registre o problema no Dev Agent Record e escale ao humano. Continue nos ACs independentes enquanto espera, se houver.
+- **Dependência de story não-Done:** não "adiante" a dependência dentro desta branch. Escale — a ordem de stories é decisão de quem prioriza.
+- **Gate quebrado já em `main` (pré-existente):** registre como pré-existente no Dev Agent Record e reporte; conserte apenas se for pré-requisito direto dos seus ACs.
+- **Conflito ao rebase/merge local com `main`:** resolva preservando a intenção dos dois lados; se a resolução alterar comportamento coberto por AC, re-rode os gates.
+
+## Referência rápida
+
+| Momento | Ação |
+|---|---|
+| Antes de editar | Branch guard (`feat/{epic}.{n}-{slug}`) |
+| Antes de codar um AC | Procurar código existente para reusar |
+| Antes de marcar `[x]` | lint + typecheck + test verdes, saída registrada |
+| Antes de concluir | File List == `git diff --stat`; suíte completa verde |
+| Ao concluir | Status → `InReview`; handoff para `pc-review-story` |
+
+## Saída esperada
+
+Resposta final contém: branch usada, ACs implementados, File List, resumo das saídas de gates, decisões registradas e o Status final (`InReview`).

package/template/.claude/skills/pc-full-cycle/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: pc-full-cycle
+description: "Orquestra o ciclo completo de UMA story (validate → develop → review → fixes → close) com Sequence Lock, estado durável e retomável, e verificação independente do QA. Use para: rodar uma story de ponta a ponta, ciclo completo de story, retomar um ciclo interrompido, full cycle."
+---
+
+# pc-full-cycle — Ciclo Completo de Uma Story (orquestrador)
+
+Protocolo completo e autocontido. Nenhuma engine externa é necessária: o estado vive em arquivo JSON escrito/lido por ferramentas nativas (Read/Write/Edit).
+
+## Invocação
+
+```
+/pc-full-cycle {story-path} [yolo|interactive]
+```
+
+Default: `interactive`. As fases são executadas pelas skills atômicas do ciclo — esta skill nunca faz o trabalho de fase inline quando um subagente de papel está disponível.
+
+## Estado durável (retomável)
+
+Arquivo: `.power-claude/cycle/{story-id}/state.json` (`story-id` = `{epic}.{n}`, ex.: `2.1`). Crie o diretório se não existir. Schema:
+
+```json
+{
+  "story_id": "2.1",
+  "story_path": "docs/stories/2.1.story.md",
+  "mode": "interactive",
+  "branch": "feat/2.1-slug",
+  "qg_iteration": 0,
+  "max_qg_iterations": 3,
+  "verdict": null,
+  "phases": {
+    "validate":      { "status": "pending", "started_at": null, "verified_at": null },
+    "develop":       { "status": "pending", "started_at": null, "verified_at": null },
+    "review":        { "status": "pending", "started_at": null, "verified_at": null },
+    "apply_qa_fixes":{ "status": "n/a",     "started_at": null, "verified_at": null },
+    "close":         { "status": "pending", "started_at": null, "verified_at": null }
+  },
+  "updated_at": "ISO-8601"
+}
+```
+
+**Retomada:** ao ser invocada, a skill SEMPRE lê o state.json primeiro. Se existe, continue da primeira fase não-`done` (respeitando o Sequence Lock); se não existe, crie-o e comece por `validate`. Atualize `status` → `running` antes de cada fase e → `done` **somente após a verificação pós-fase em disco** (nunca pelo relato do subagente). Timestamps em ISO-8601 a cada escrita.
+
+## Mapa de fases
+
+**O núcleo de papéis e a lista de especialistas por gatilho são definidos em `.claude/rules/orchestration.md`** (fonte única, `DF-SF12.3-3`) — esta skill não reafirma um mapa de papéis próprio, divergente daquele núcleo. Esta skill cobre a granularidade das **5 fases de UMA story já em `Draft`** (criada pelo papel Planner — precondição fora do escopo desta skill) até o handoff ao papel DevOps:
+
+| # | Fase | Skill | Papel (subagente preferencial) | Transição esperada |
+|---|------|-------|-------------------------------|--------------------|
+| 1 | validate | `pc-validate-story` | `pc-po` | Draft → Ready (GO) |
+| 2 | develop | `pc-develop-story` | `pc-dev` | Ready → InProgress → InReview |
+| 3 | review | `pc-review-story` | `pc-qa` | InReview → Done (PASS/CONCERNS/WAIVED) ou → InProgress (FAIL) |
+| 3b | apply_qa_fixes | `pc-apply-qa-fixes` | `pc-dev` | InProgress → InReview (volta ao 3) |
+| 4 | close | `pc-close-story` | `pc-po` | bookkeeping (story já Done) |
+
+**Inserção dinâmica de especialista (capacidade, não exceção):** fases de especialista (`architect`/`db-architect`/`ux-architect`/`analyst`, listados com seus gatilhos em `orchestration.md`) podem ser inseridas dinamicamente em **qualquer ponto** do ciclo, condicionadas ao gatilho registrado na story — não é um desvio do protocolo, é capacidade prevista. Exemplo real: o `*design` de `pc-architect` inserido pelo `@dev` durante a SF12.2, no meio da fase `develop` (`docs/stories/sf12.2.story.md:628`), para resolver um bloqueio de arquitetura sem esperar um ciclo à parte. A ordem fixa das 5 fases do Sequence Lock (abaixo) vale **só entre elas** — não impede essa inserção.
+
+Dispatch preferencial: spawn do subagente de papel correspondente (`.claude/agents/pc-po.md`, `pc-dev.md`, `pc-qa.md`) com prompt: `Execute a skill {skill} na story {story-path}; mode={mode}. Não faça git push.` Fallback: executar a skill inline, mantendo a separação de papéis por fase.
+
+**Contrato de brief:** o prompt de cada subagente inclui paths exatos, ACs, limites de autoridade, e a instrução explícita: "relatório final ≤15 linhas; detalhes vão na story".
+
+**Agente fresco por story:** papéis de execução recebem agente FRESCO a cada story — nunca reaproveite um agente vindo de outra story. Dentro do MESMO ciclo, fixes (`apply_qa_fixes`) retomam o MESMO agente Dev via SendMessage, para preservar o contexto da implementação.
+
+**Worktree:** despache o papel Dev com `isolation: worktree` quando houver risco de colisão com outra frente ativa no repositório.
+
+## Preflight antes de CADA spawn (gate de escopo)
+
+Verifique mecanicamente antes de invocar qualquer subagente; qualquer falha = NÃO despache, reporte e pare:
+
+1. **Story existe e está no status de entrada da fase** (tabela acima). Ex.: nunca despache `develop` com story `Draft`.
+2. **Branch correta:** para develop/fixes, working tree sem alterações não relacionadas à story (`git status`); nunca em `main`/`master`.
+3. **Gates configurados:** os comandos de lint/typecheck/test do projeto existem e são executáveis (ex.: scripts no `package.json`). Sem gates configurados, o veredito do QA não teria base — pare e reporte.
+4. **Escopo íntegro:** o prompt do child referencia exatamente a story do ciclo (path idêntico ao do state.json) e nada além dela.
+5. **Gatilhos de especialista (fase validate):** se a story declara dependência de analyst/architect/db/ux não satisfeita, o PO deve tratá-la — NO-GO até resolver.
+
+> Nota: o controle de orçamento do ciclo é este preflight de escopo + limite duro de iterações; um teto de custo em moeda pode ser introduzido via hook de plataforma quando disponível.
+
+## Sequence Lock — disciplina do ciclo, estatuto por item
+
+Cada item abaixo tem um **estatuto** declarado — o texto não afirma mais garantia do que o mecanismo real entrega: **ENFORCEMENT** (hook `PreToolUse`, verificável em código, `.claude/hooks/enforce-cycle-authority.cjs`) ou **ADVISORY** (disciplina do orquestrador e dos papéis, sem trava de plataforma).
+
+1. **[ADVISORY]** Fases **em ordem**. Nenhuma fase N+1 antes da verificação pós-fase de N passar.
+2. **[ENFORCEMENT]** **Só o papel QA (fase review) seta `Status: Done`.** Nenhum outro papel, nem este orquestrador — hook nega/pergunta conforme a identidade do agente (`agent_type`).
+3. **[ADVISORY]** `close` exige story já `Done` + gate file com veredito não-FAIL. É só bookkeeping.
+4. **[ADVISORY]** Loop de QG limitado a **3 iterações** (`max_qg_iterations`). Na 3ª re-review com FAIL → HALT e escale ao humano com o histórico completo. Nunca afrouxe o gate para fechar.
+5. **[ADVISORY]** **Anti-self-validation:** quem implementa (papel Dev) nunca revisa; quem revisa (papel QA) nunca implementa fixes. Papéis em subagentes distintos.
+
+## Loop de execução (o orquestrador DEVE seguir)
+
+```
+0. Ler/criar state.json (retomada)
+1. LOOP:
+   a. Próxima fase = primeira não-done na ordem do Sequence Lock
+   b. Se nenhuma → ciclo completo; ir para o passo 2
+   c. Preflight de escopo; falhou → HALT com motivo
+   d. Marcar fase running; despachar subagente de papel (ou inline)
+   e. Verificação pós-fase EM DISCO (tabela abaixo); falhou → HALT (não avance, não "conserte" o status)
+   f. Marcar fase done; atualizar state.json
+   g. Se fase = review:
+        - Ler o gate file real (docs/qa/gates/{story}.yaml) — não o relato do subagente
+        - PASS/CONCERNS/WAIVED → verdict no state; seguir para close
+        - FAIL:
+            interactive sem aprovação explícita de fix → reportar e PAUSAR
+            yolo ou aprovação dada → qg_iteration += 1;
+              se qg_iteration > max → HALT + escalar humano
+              senão → rodar apply_qa_fixes → verificar → voltar à review
+   h. interactive: reportar entre fases e pausar em decisões; yolo: autônomo
+2. Registrar aprendizados (seção abaixo)
+3. Push/PR: NUNCA daqui — handoff ao papel devops com branch + story + veredito
+```
+
+## Verificação pós-fase (independente, em disco)
+
+O relato de um subagente **não é evidência**. Após cada retorno, o orquestrador confere o disco:
+
+| Fase | Evidência exigida em disco |
+|------|----------------------------|
+| validate | Story `Status: Ready`; seção de validação com veredito GO |
+| develop | Story `Status: InReview` (nunca Done); Dev Agent Record + File List preenchidos; commits na branch da story |
+| review | Gate file existe em `docs/qa/gates/`; veredito coerente com o Status (aprovado → Done; FAIL → InProgress); QA Results na story |
+| apply_qa_fixes | Story `Status: InReview` (nunca Done); findings do gate marcados com decisão |
+| close | Índice do epic atualizado; status intacto (`Done`) |
+
+A verificação independente pesada (re-executar lint/typecheck/test e rastrear AC → código) vive dentro de `pc-review-story` — este orquestrador garante que ela **aconteceu de fato**, checando o gate file e o diff, e jamais aceita "verde relatado" como verde ("do not fake green").
+
+## Modos
+
+| Modo | Comportamento |
+|------|---------------|
+| `interactive` | Reporta entre fases; pausa em FAIL, NO-GO e decisões |
+| `yolo` | Autônomo entre fases; para somente em HALT (preflight, verificação, circuit breaker de QG) |
+
+## Aprendizados (obrigatório ao fim de cada ciclo)
+
+Ao concluir (ou em HALT), faça **append** — nunca sobrescreva — em `.power-claude/cycle/learnings.md`:
+
+```markdown
+## {data ISO} — Story {id} — {resultado: DONE | HALT:motivo}
+- Iterações de QG: {n}/3 | Veredito final: {verdict}
+- O que o QA pegou que o Dev relatou verde: {…ou "nada"}
+- Padrão/armadilha para os próximos ciclos: {1-3 bullets}
+```
+
+Este arquivo é a memória do ciclo entre sessões; consulte-o no início de cada novo ciclo.
+
+## Fronteiras
+
+- Nunca `git push` / `gh pr create` / merge — exclusivo do papel devops, com aprovação humana.
+- Nunca criar stories (isso é papel de planejamento, fora deste ciclo).
+- Nunca editar o state.json para "pular" fase ou fabricar verificação.

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

@@ -0,0 +1,63 @@
+---
+name: pc-pipeline
+description: "Opera um pipeline cross-pod (pipelines/pipeline-*.yaml) pelo motor supervisor pc-run-pipeline.cjs: aprova o manifesto de fases, encarna os agentes de cada fase via pc-run-pod, decide os portões GO/NO-GO. Use para: rodar um pipeline entre pods, encadear o output de um pod como insumo de outro, retomar um pipeline interrompido, decidir um portão de fase."
+---
+
+# pc-pipeline — Operação de Pipeline Cross-Pod (maestro sequencial)
+
+Protocolo completo e autocontido da coordenadora sobre o motor `scripts/pc-run-pipeline.cjs` (ADR-017). **Fronteira inegociável:** o motor é SUPERVISOR — start do run-filho, detecção de `done` lendo o state, baseline em disco, portão, avanço. Quem EXECUTA cada fase (encarna os agentes, escreve os artefatos) é VOCÊ, dirigindo o `pc-run-pod` da fase exatamente como num run de pod normal. O motor nunca chama LLM; se você pedir que ele "rode a fase", está usando errado.
+
+## Invocação
+
+```
+/pc-pipeline pipelines/pipeline-{id}.yaml [--pods-root pods] [--state-root .power-claude]
+```
+
+## Estado durável (retomável)
+
+`.power-claude/pipeline/{id}/state.json` — status por fase (`pending|running|blocked|completed|failed`), `run_id`/`run_dir` do filho, outputs resolvidos, ressalvas de GO. Runs-filhos vivem em `.power-claude/pipeline/{id}/runs/`. **Retomada:** `status` mostra onde parou; `advance` continua do ponto — fase `completed` nunca repete.
+
+## Stage 0 — Autorar o contrato (se ainda não existe)
+
+`pipelines/pipeline-<id>.yaml`: `{id, deliverable, phases[]}`; cada fase `{id, pod, workflow, outputs: {nome: artifacts/<step>.md}}` (+ `inputs: {local: "<- fase.output"}` da fase 2 em diante; `gate` opcional com `veto` de máquina e/ou `checkpoint` humano). Regras de autoria:
+1. **Compatibilidade real primeiro:** o output REAL de uma fase precisa servir de insumo REAL da próxima — leia os templates/knowledge dos dois pods antes de comprometer o par; não force um encadeamento que não existe.
+2. Outputs apontam os artefatos do runner (`artifacts/<step-id>.md`). O PRIMEIRO output declarado é o que o `gate.veto` avalia — ordene com intenção.
+3. `gate` é camada ADITIVA sobre o baseline (run done + artefato em disco, sempre imposto). Critérios de portão reutilizáveis: `references/gate-templates.md` (universais + por tipo de entregável) — instancie o checkpoint `criteria` a partir de lá, não invente ad hoc.
+4. Valide: `node scripts/validate-pipeline.cjs pipelines/pipeline-<id>.yaml [--pods-root <dir>]` — exit 0 antes de qualquer init.
+
+## Stage 1 — Aprovação do manifesto (humano)
+
+Apresente ao humano: fases na ordem, pod/workflow de cada uma, o que encadeia com o quê (inputs←outputs), e onde há portão (veto/checkpoint). Prossiga só com OK explícito — mesmo espírito do Stage 2 do `pc-wave`.
+
+## Stage 2 — Init
+
+`node scripts/pc-run-pipeline.cjs init pipelines/pipeline-<id>.yaml [--pods-root d] [--state-root d]` — valida o contrato e cria o state (todas as fases `pending`). State já existente = retomada: pule para Stage 3 com `status`.
+
+## Stage 3 — Loop por fase (o coração do protocolo)
+
+Para cada fase, na ordem:
+
+1. **`advance <id>`** → o motor inicia o run-filho (`started`) e devolve o `run_dir` + task-ref (com os paths dos inputs cross-pod resolvidos e verificados em disco, quando houver).
+2. **OPERE o run-filho como um `pc-run-pod` normal** — este é o seu trabalho, não do motor:
+   - `node scripts/pc-run-pod.cjs next --state <run_dir>/state.json --workflow-file <pod>/workflows/<wf>.yaml --pod-root <pod>` despacha a etapa e devolve o BRIEF;
+   - **encarne o agente** da etapa (leia o entry point do agente + knowledge referenciado; inputs cross-pod estão no brief como "Tarefa:") e escreva o artefato REAL em `<run_dir>/artifacts/<step>.md`, conforme o template da etapa;
+   - `next` de novo verifica em disco (conformidade + vetos) e marca `done`; checkpoints bloqueantes internos do pod: `approve`/`revise` como sempre;
+   - repita até o run-filho ficar `done` (todos os steps).
+3. **`advance <id>`** de novo → o motor aplica baseline (outputs em disco) + `gate.veto` (GO/NO-GO de máquina):
+   - `phase-complete` → próxima fase (volte ao passo 1);
+   - `blocked` → portão HUMANO: julgue pelos critérios do checkpoint (instanciados de `references/gate-templates.md`), então `approve <id> [--note "ressalva"]` (GO — ressalva é texto livre, não 3º estado) ou `reject <id>` (NO-GO, trava);
+   - exit 1 com NO-GO de veto → a fase fica `failed`; v1 não tem re-exec parcial: corrija OPERANDO um novo run da fase (remova/reinicie o state da fase conforme o motor instruir) — nunca edite o artefato de uma fase já aprovada.
+4. `advance` com tudo concluído → `pipeline COMPLETO`. Reporte o artefato final ao humano.
+
+## Condições de HALT (pare e reporte — nunca contorne)
+
+- `validate-pipeline` ou `init` falhou → contrato inválido; corrija o YAML, nunca o motor.
+- `advance` fail-loud com run-filho não-done → complete o run (passo 2); NUNCA marque steps por relato.
+- NO-GO (veto ou humano) → fase `failed`/travada; a fase seguinte NUNCA dispara. Recuperação = re-rodar a fase inteira (v1).
+- Input cross-pod ausente em disco → não recrie o artefato "de memória"; investigue o run da fase anterior.
+- Gap genuíno de CONTRATO/MOTOR (não de conteúdo) → PARE e escale `pc-architect *review` — a skill nunca corrige o motor por conta própria.
+- Merge/push do resultado → `pc-devops`, como sempre. Aprovação humana nos checkpoints de portão é indelegável.
+
+## Fronteiras (herdadas de ADR-017)
+
+Motor supervisiona; operador executa; `squad-io.yaml` e `pc-run-pod` intocados; artefato cross-pod viaja por REFERÊNCIA verificada em disco (sem cópia); portão binário GO/NO-GO. "Sem deriva" = sem cópia divergente — mutação de conteúdo de um output APÓS o gate não é re-verificada (limite v1; não edite outputs de fases aprovadas).

package/template/.claude/skills/pc-pipeline/references/gate-templates.md

@@ -0,0 +1,46 @@
+# Gate-templates — critérios de portão reutilizáveis para pipelines cross-pod
+
+> Fonte: `multi-squad-orchestrator` (skill de origem do Daniel, `~/projetos/skills/multi-squad-orchestrator.zip`), `references/quality-gate-templates.md` — absorção-leve decidida em `docs/research/2026-07-29-avaliacao-multi-squad-orchestrator.md` (SF8.2) e ADR-017. Destilação: critérios viram INSUMO do `gate` do pipeline (checkpoint `criteria` e, quando machine-redutível, `veto`); o protocolo de 3 estados e a re-exec parcial da origem NÃO foram absorvidos (v1 é GO/NO-GO binário, ressalva = texto livre num GO — ADR-017 Decisão 5).
+
+## Como usar
+
+Ao autorar um `pipelines/pipeline-*.yaml`, instancie o portão de cada transição a partir daqui: escolha o gate da transição (abaixo), aplique os critérios UNIVERSAIS sempre, some os critérios do TIPO de entregável quando houver. Critério machine-redutível (campo/threshold contável no artefato) vira `gate.veto`; critério de julgamento vira o `criteria` do `gate.checkpoint` (decisão humana GO/NO-GO). BLOCKING = entra no portão; WARNING = ressalva registrável no GO (`--note`), nunca bloqueio.
+
+## QG Research → Narrativa (fase de pesquisa alimentando fase autoral)
+
+**Universais (sempre):**
+- U1 BLOCKING — fontes verificáveis com data e autor ≥ 3.
+- U2 BLOCKING — dados factuais (não opinião) sustentando os claims ≥ 3.
+- U3 BLOCKING — conexão explícita entre findings e público-alvo.
+- U4 WARNING — índice de fontes presente.
+
+**Por tipo (somar ao universal):** keynote/evento executivo — fontes tier-1 ≥ 5, cases com ROI ≥ 2, tendências ≥ 3 · workshop/treinamento — ferramentas/frameworks mapeados ≥ 3, exercícios viáveis ≥ 2 · proposta comercial — intelligence do cliente + benchmarks do setor ≥ 2 · campanha de conteúdo — persona definida, trending topics ≥ 3, concorrentes ≥ 2 · estratégia de produto — TAM/SAM/SOM, análise competitiva ≥ 3, JTBD · ebook/educacional — fontes primárias por capítulo ≥ 2, lacuna do público definida · customizado — ≥ 2 BLOCKING + 1 WARNING definidos na autoria.
+
+## QG Narrativa → Design (fase autoral alimentando fase visual/material)
+
+**Universais:**
+- U1 BLOCKING — argumento central identificável em 1 frase.
+- U2 BLOCKING — dados do research integrados organicamente (não colados).
+- U3 BLOCKING — estrutura com início, desenvolvimento e fechamento.
+- U4 WARNING — público-alvo refletido no tom e vocabulário.
+
+**Por tipo:** keynote — hook com tensão cognitiva, framework reusável ≥ 1, timing por seção · workshop — objetivos de aprendizagem mensuráveis ≥ 3, sequência didática progressiva, exercícios por módulo · proposta — recomendação antes dos argumentos (Minto), ROI projetado, diferenciação · campanha — calendário com datas, ≥ 2 formatos, mensagem-chave consistente · produto — visão em 1 parágrafo, roadmap com fases, métricas por fase · ebook — outline completo, progressão de complexidade, exercícios por capítulo.
+
+## QG Design → Entrega (fase visual/material alimentando fechamento)
+
+**Universais:**
+- U1 BLOCKING — consistência visual (paleta, tipografia, tom) em todo o material.
+- U2 BLOCKING — hierarquia de informação clara (leitor entende a estrutura em 10s).
+- U3 BLOCKING — conteúdo alinhado com a narrativa da fase anterior, sem contradições.
+- U4 WARNING — especificação executável por terceiro.
+
+**Por tipo:** keynote — STAR moment posicionado, zero bullets, ≤ 25 palavras/slide · workshop — slides didáticos, workbook/handout especificado · proposta — deck ≤ 15 slides, executive summary na 1ª página, pricing visual · campanha — assets por canal com tamanhos/formatos, brand guidelines · produto — roadmap visual, one-pager por fase · ebook — diagramação por capítulo, capa e TOC.
+
+## QG Entrega final (última fase antes de reportar ao humano)
+
+**Universais:**
+- U1 BLOCKING — estratégia de ação pós-entrega (≥ 1 next step claro).
+- U2 BLOCKING — todos os deliverables persistidos e verificáveis em disco.
+- U3 WARNING — estado do pipeline atualizado (todas as fases com status final).
+
+**Por tipo:** keynote — playbook pré/durante/pós, follow-up · workshop — logística + avaliação · proposta — objeções preparadas, 2-3 opções de pricing · campanha — calendário de publicação, métricas por canal, plano de iteração · produto — go-to-market, métricas por fase, stakeholder map · ebook — distribuição, canal, métricas de alcance.

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

@@ -0,0 +1,129 @@
+---
+name: pc-review-story
+description: "QA gate independente de uma story em InReview: re-executa gates, rastreia ACs ao código real e emite veredito PASS/CONCERNS/FAIL/WAIVED. Use para: revisar story implementada, rodar QA gate, aprovar/reprovar implementação, setar story para Done."
+---
+
+# pc-review-story — QA Gate Independente (papel QA)
+
+Protocolo completo e autocontido. Nenhuma engine externa é necessária.
+
+## Quando usar
+
+Story com Status **InReview**. Se estiver `InProgress`, devolva ao Dev — não revise trabalho declaradamente incompleto.
+
+## Princípio central: verificação INDEPENDENTE
+
+O relato do implementador **não é evidência**. O ciclo que validou este protocolo pegou um "fake green" real: Dev reportou sucesso, e os gates re-executados desmentiram. Portanto:
+
+1. **Re-execute os gates você mesmo** (lint, typecheck, test). Não aceite saída colada no Dev Agent Record como prova — ela é contexto, não veredito.
+2. **Rastreie cada AC ao código real.** Abra os arquivos da File List e aponte, AC por AC, ONDE ele está implementado (arquivo:linha ou função). AC sem código rastreável = FAIL desse AC.
+3. **Teste pela rota real, não só em teste isolado.** Lição registrada do ciclo: teste de componente verde NÃO prova o wiring da rota. Se o entregável é um endpoint, chame o endpoint; se é uma página, carregue a página; se é um CLI, execute o comando. Exercite o caminho que o usuário final percorre.
+
+## Protocolo
+
+### Passo 1 — Contexto
+
+Leia a story completa (ACs, escopo, Validação do PO, Dev Agent Record, File List) e o diff da branch (`git diff main...HEAD --stat` e os arquivos relevantes).
+
+### Passo 2 — Os 3 eixos de verificação
+
+| Eixo | Como verificar | Falha ⇒ |
+|---|---|---|
+| Gates | Rodar `npm run lint`, `npm run typecheck`, `npm test` do zero | FAIL |
+| Rastreabilidade de ACs | Cada AC apontado a código real; escopo OUT não implementado (No Invention) | FAIL no AC ausente; CONCERNS em invenção menor |
+| Funcionamento real | Executar o entregável pela rota real (endpoint/página/CLI) | FAIL |
+
+Verifique também: File List fiel ao diff; testes novos cobrem os ACs; nenhum erro suprimido (skip, ts-ignore, regra desligada) sem justificativa.
+
+**Arsenal adversarial (aplique o que a story pedir):**
+
+- **Verifique contra o ARTEFATO real, não contra a suíte:** faça seu próprio parse do output (jsdom no HTML gerado). Para exercitar a rota real, gere **credenciais próprias na hora** (bcrypt/JWT) — nunca leia `.env`.
+- **Regressão por byte-identidade:** hash `sha256` do artefato entre a versão nova e o checkout anterior prova ausência de regressão — barato e à prova de discussão.
+- **Teste as falhas que o Dev NÃO testou** (os ramos/chamadas que ele pulou) e **plante um segredo no erro** para provar que log/mensagem não vaza.
+- **Hipóteses adversariais do CONTEXTO DE USO real** (dispositivo, encoding — ex.: iPhone envia NFD) valem mais que fuzzing genérico.
+- **`git diff --stat` com "Bin"** = byte NUL cegando o diff; investigue o arquivo em vez de confiar no review de diff.
+- **Conformidade com ADR por DIFF dirigido** (ex.: arquivo que deveria estar vazio está vazio), não releitura do código inteiro.
+
+### Protocolos aprofundados (carregue sob demanda)
+
+Quando um eixo pedir profundidade, leia o reference correspondente — o checklist/regex/fórmula completo está lá, não inline:
+
+| Situação | Reference |
+|---|---|
+| Story com superfície de risco (auth/dados/dinheiro/integração) | `references/risk-profile.md` (score prob×impacto → gate) |
+| Requisito não-funcional relevante | `references/nfr-assess.md` (4 NFRs, status determinístico) |
+| Conferir cobertura AC→teste | `references/trace-requirements.md` (GWT, full/partial/none) |
+| Planejar/avaliar a suíte | `references/test-design.md` (níveis + P0-P3) |
+| Story toca input/query/superfície externa | `references/security-checklist.md` (8 checks com regex) |
+| Story é bug fix (fix real ou falso positivo?) | `references/false-positive-detection.md` (teste de causação + confidence score) |
+
+### Passo 3 — Veredito
+
+| Veredito | Significado | Efeito |
+|---|---|---|
+| **PASS** | Todos os ACs verificados, gates verdes, rota real funciona | Story → `Done` |
+| **CONCERNS** | Funciona e ACs atendidos, mas há débitos não-bloqueantes nomeados | Story → `Done` com débitos registrados, OU devolve — julgamento explícito |
+| **FAIL** | Qualquer AC não atendido, gate vermelho ou rota real quebrada | Story volta ao Dev → `pc-apply-qa-fixes` |
+| **WAIVED** | Falha conhecida, aceita conscientemente pelo humano | Só com justificativa + ciência humana registradas no gate file |
+
+### Passo 4 — Gate file (obrigatório, qualquer veredito)
+
+Escreva `docs/qa/gates/{epic}.{n}-{slug}.yaml`:
+
+```yaml
+story: "{epic}.{n}"
+date: "{YYYY-MM-DD}"
+reviewer: "pc-qa"
+verdict: PASS | CONCERNS | FAIL | WAIVED
+gates_reexecuted:
+  lint: pass | fail
+  typecheck: pass | fail
+  test: "pass (N testes)" | fail
+real_route_check: "{o que foi executado e o resultado}"
+ac_trace:
+  - ac: 1
+    evidence: "{arquivo:linha ou função}"
+    status: verified | missing
+findings: []        # obrigatório preencher se CONCERNS/FAIL
+waiver_reason: null # obrigatório se WAIVED
+```
+
+### Passo 5 — Atualizar a story
+
+1. Escreva a seção **QA Results** na story: veredito, resumo por eixo, findings numerados (se houver).
+2. **PASS/CONCERNS aceito:** `Status: InReview` → `Status: Done`. **Só o papel QA faz esta transição.**
+3. **FAIL:** Status volta para `InProgress`; liste os findings que o Dev deve tratar via `pc-apply-qa-fixes`.
+
+## Limites do papel
+
+- **Só edita a seção QA Results** da story (e o gate file). Não toca em ACs, escopo, checkboxes, File List nem Dev Agent Record.
+- **Não implementa correções.** Achou problema → finding no gate file → devolve ao Dev. QA que corrige código vira implementador e perde a independência.
+- **Anti-self-review:** se você implementou esta story (mesma sessão/contexto), recuse a revisão e exija um contexto limpo (subagente QA ou outra sessão). Ver `.claude/rules/authority.md`.
+- Máximo 3 iterações de FAIL → fix → re-review; na terceira sem PASS, escale ao humano com o histórico.
+
+## Casos de borda
+
+- **Gates verdes mas rota real quebrada:** FAIL. Este é exatamente o cenário que a verificação em 3 eixos existe para pegar — registre o finding com o comando executado e a saída.
+- **File List não bate com o diff:** CONCERNS no mínimo; se arquivos materiais foram omitidos (código de produção fora da lista), FAIL — rastreabilidade é parte do contrato.
+- **Implementação além do escopo (invenção):** código fora dos ACs e do escopo IN. Menor e inofensivo → CONCERNS com finding pedindo remoção ou story própria. Material → FAIL.
+- **Teste que "passa" porque foi enfraquecido:** compare os testes do diff com os ACs. Assert removido, skip ou mock que engole a rota real = FAIL com finding específico.
+- **Ambiente local impede re-execução de um gate** (ex.: dependência de serviço externo): NÃO assuma verde. Registre o gate como não-verificável, rebaixe o teto do veredito para CONCERNS e escale a decisão ao humano.
+- **Re-review (iteração 2 ou 3):** verifique primeiro a tabela de inventário do `pc-apply-qa-fixes` — cada finding anterior precisa de decisão (FIXED/WON'T_FIX/DEFERRED). Finding sem decisão = FAIL imediato. Depois re-rode os 3 eixos normalmente.
+
+## Como registrar um finding (formato)
+
+```yaml
+findings:
+  - id: 1
+    severity: bloqueante | menor
+    ac_afetado: 2            # ou null
+    descricao: "POST /session retorna 500 com payload válido"
+    evidencia: "curl -X POST ... → HTTP 500 (log anexo)"
+    acao_sugerida: "tratar null em session.ts:42"
+```
+
+Finding sem evidência executável é opinião — não entra no gate file.
+
+## Saída esperada
+
+Resposta final contém: veredito, caminho do gate file criado, tabela de rastreamento dos ACs, saídas resumidas dos gates re-executados, resultado do teste de rota real e o Status final da story.