@daniellins/power-claude 0.16.3 → 0.16.4

package/README.md

@@ -2,47 +2,67 @@
 
 Framework enxuto de agentes para Claude Code — **pods por job-to-be-done**, com budget de tokens como gate de qualidade.
 
-## Princípios
+Você o instala dentro de um projeto seu, e ele acrescenta ali agentes, regras, skills e verificações
+automáticas que o Claude Code passa a usar. Não substitui o Claude Code: dá forma ao que ele faz, e
+verifica o resultado em disco antes de você confiar nele.
 
-1. **Pods por job-to-be-done** — em vez de dezenas de agentes genéricos, cada pod resolve um trabalho concreto (criar conteúdo com autoridade, montar aulas, automatizar processos, desenvolver com IA, forjar novos pods). Você instala só o que usa.
-2. **Budget de tokens como gate** — todo agente declara `budget_tokens` no frontmatter e um validador determinístico (`scripts/validate-budgets.js`) bloqueia qualquer agente que estoure o próprio budget, o teto global (1.500 tokens) ou 150 linhas. Contexto enxuto não é convenção: é gate.
-3. **Enforcement determinístico** — regras críticas viram hooks e scripts, não pedidos educados no prompt. Exemplo: o hook `enforce-git-push-authority.cjs` bloqueia `git push` fora do fluxo autorizado, direto no `PreToolUse`.
-4. **Verificação adversarial embutida** — os pods incluem agentes críticos (red-team) que revisam o próprio output antes de você confiar nele.
-5. **Garantia por código, não por prosa** — um pod é dado declarativo (`workflows/wf-*.yaml` + templates de etapa + `squad-io.yaml`), executado por um runner determinístico (`scripts/pc-run-pod.cjs`, skill `pc-run-pod`) que verifica o artefato EM DISCO — existe, casa com o template, todas as `veto.assertions` passam — antes de liberar a etapa seguinte. A garantia de processo é código, não prosa no prompt do agente.
+## Para quem chega agora
 
-Documentação operacional de cada mecanismo (uso, não só decisão): `docs/mecanismos/`.
+Se esta é a sua primeira vez, o caminho mais curto é este, nesta ordem:
 
-## O que mudou na v0.3 (runner, memória evolutiva, migração)
+1. **[Comece aqui](docs/mecanismos/aprendizado/getting-started.md)** — instalar, conferir a instalação
+   com o `doctor` e rodar o primeiro comando. Poucos minutos, sem pré-requisito de leitura.
+2. **[Guia de conceitos](docs/mecanismos/aprendizado/guia-de-conceitos.md)** — os termos que o framework
+   usa o tempo todo (pod, workflow, etapa, veto, checkpoint, budget, skill), um parágrafo cada.
+3. **Um tutorial de ponta a ponta**, conforme o que você quer fazer primeiro:
+   - [rodar um pod do começo ao fim](docs/mecanismos/aprendizado/tutorial-rodar-um-pod.md);
+   - [levar uma story do pedido ao merge](docs/mecanismos/aprendizado/tutorial-ciclo-de-story.md);
+   - [criar um pod novo com o forge](docs/mecanismos/aprendizado/tutorial-criar-pod-com-forge.md).
 
-**Runner determinístico.** Todo workflow de pod roda por um contrato `wf-*.yaml` validado estaticamente (`scripts/validate-pod-workflow.cjs` — ciclos, handoffs abertos, vetos malformados, templates ausentes) e provado em runtime pelo smoke dinâmico (`scripts/smoke-pod-workflow.cjs`). O runner (`scripts/pc-run-pod.cjs`, skill `pc-run-pod`) despacha um subagente fresco por etapa, aplica checkpoints bloqueantes e retoma por run-id.
+Prefere perguntar a ler? Depois de instalar, digite `/power:tutor` no Claude Code — ele aponta o
+próximo passo certo para o seu caso, sem você ter que escolher sozinho por qual destes documentos
+começar.
 
-**Memória evolutiva dos pods.** Um pod aprende do próprio uso, sem virar ruído: log cru append-only + consolidado podado por budget de tokens (`scripts/pod-memory.cjs`), watcher heurístico que audita aderência ao consolidado (`scripts/watcher-audit.cjs`) e ingest inicial de memória com dedupe (`scripts/forge-ingest-memory.cjs`). O runner injeta só o consolidado no brief do agente — nunca o log cru.
+Se você prefere instalar antes de ler, vá direto para a seção **Instalação**, logo abaixo — o
+getting-started continua valendo depois.
 
-**`*migrate-squad` — migração squad legado → pod com gates completos.** Comando do `forge-chief` que leva um squad inteiro pelas fases F0 (inventário) → F1 (triagem, para no humano) → F2 (geração + gates por workflow) → F3 (fechamento), com raiz de confiança em código no manifest de migração (`scripts/migration-manifest.cjs`) e paridade decidida pela máquina entre G5-LITE (2 runs) e G5-FULL (5 runs) via `scripts/harness-g5-lite.cjs`.
+## Princípios
+
+1. **Pods por job-to-be-done** — em vez de dezenas de agentes genéricos, cada pod resolve um trabalho concreto (criar conteúdo com autoridade, montar aulas, automatizar processos, desenvolver com IA, forjar novos pods). Você instala só o que usa.
+2. **Budget de tokens como gate** — todo agente declara `budget_tokens` no frontmatter e um validador determinístico ([`scripts/validate-budgets.js`](scripts/validate-budgets.js)) bloqueia qualquer agente que estoure o próprio budget, o teto global (1.500 tokens) ou 150 linhas. Contexto enxuto não é convenção: é gate.
+3. **Enforcement determinístico** — regras críticas viram hooks e scripts, não pedidos educados no prompt. Exemplo: o hook [`enforce-git-push-authority.cjs`](template/.claude/hooks/enforce-git-push-authority.cjs) bloqueia `git push` fora do fluxo autorizado, direto no `PreToolUse`.
+4. **Verificação adversarial embutida** — os pods incluem agentes críticos (red-team) que revisam o próprio output antes de você confiar nele.
+5. **Garantia por código, não por prosa** — um pod é dado declarativo (`workflows/wf-*.yaml` + templates de etapa + `squad-io.yaml`), executado por um runner determinístico ([`scripts/pc-run-pod.cjs`](scripts/pc-run-pod.cjs), skill `pc-run-pod`) que verifica o artefato EM DISCO — existe, casa com o template, todas as `veto.assertions` passam — antes de liberar a etapa seguinte. A garantia de processo é código, não prosa no prompt do agente.
 
 ## Instalação
 
-Enquanto o pacote não está publicado no npm, instale direto do GitHub:
+O framework é distribuído pelo npm. Dentro do projeto onde você quer usá-lo:
 
 ```bash
 cd seu-projeto
-npx github:daniellins/power-claude install
+npx @daniellins/power-claude install --yes
 ```
 
-Quando publicado no npm:
+`--yes` é o modo não-interativo: instala todos os pods, assume os padrões e **nunca** sobrescreve nem
+remove arquivo seu. Para escolher quais pods entram e decidir sobre o `git init` com commit inicial,
+rode a forma interativa:
 
 ```bash
 npx @daniellins/power-claude install
 ```
 
-O instalador pergunta quais pods instalar, se deve inicializar git e registra tudo em `.power-claude/manifest.json`. Em modo não-interativo:
+Em qualquer um dos dois, o instalador registra o que colocou em `.power-claude/manifest.json` — é esse
+manifesto que dá base ao `update` e ao `uninstall`. Logo depois de instalar, confira a instalação:
 
 ```bash
-npx @daniellins/power-claude install --yes
+npx @daniellins/power-claude doctor
 ```
 
 O instalador **nunca sobrescreve** arquivos seus: conflitos são perguntados (interativo) ou preservados (`--yes`). O `.claude/settings.json` recebe merge aditivo em `hooks`/`permissions` (a entrada nova do template é acrescentada sem remover nem alterar o que você já tem); nas demais chaves, suas chaves vencem, as do template entram só onde faltam.
 
+O npm é o caminho de instalação — não `git clone`. Um clone do repositório serve para ler e auditar o
+código, nunca para instalar; o que o instalador copia é o que o pacote publica.
+
 ## Comandos do CLI
 
 | Comando | O que faz |
@@ -50,11 +70,12 @@ O instalador **nunca sobrescreve** arquivos seus: conflitos são perguntados (in
 | `power-claude install` | Instala o framework no diretório atual (default) |
 | `power-claude adopt` | Adota uma instalação montada à mão (sem manifest): classifica o disco contra o template (idêntico / modificado / ausente), gera o `.power-claude/manifest.json` sem sobrescrever nada e coloca a instalação ao alcance do `update` |
 | `power-claude update` | Atualiza; arquivos que você modificou são preservados (com diff resumido no modo interativo) |
-| `power-claude doctor` | Diagnóstico: integridade do manifest, hooks, `.gitignore`, gate de budgets, tamanho do CLAUDE.md |
+| `power-claude doctor` | Diagnóstico: integridade do manifest, hooks, `.gitignore`, gate de budgets, tamanho do CLAUDE.md e execução dos workflows dos pods instalados |
 | `power-claude uninstall` | Remove apenas o que o instalador colocou e continua intacto; o que você modificou fica |
 | `power-claude --help` / `--version` | Ajuda / versão |
 
-Flag global: `--yes` (`-y`) para modo não-interativo.
+Flags globais: `--yes` (`-y`) para modo não-interativo; `--scope motor`, só em `update`, restringe a
+atualização aos scripts do motor (ver a nota da próxima seção).
 
 ## Estrutura instalada
 
@@ -63,30 +84,50 @@ seu-projeto/
 ├── .claude/
 │   ├── CLAUDE.md                  # instruções enxutas (budget ~2.000 tokens)
 │   ├── settings.json              # hooks + permissions (merge com o seu)
+│   ├── agents/                    # papéis do ciclo (pc-planner, pc-dev, pc-qa, pc-devops, ...)
+│   ├── commands/                  # comandos /power:*
+│   ├── rules/                     # autoridade, orquestração, matriz de modelos, curadoria
+│   ├── skills/                    # pc-run-pod, pc-full-cycle, pc-pipeline, pc-arena, ...
 │   └── hooks/
-│       └── enforce-git-push-authority.cjs
+│       ├── enforce-git-push-authority.cjs
+│       ├── enforce-cycle-authority.cjs
+│       ├── enforce-ready-oracles.cjs
+│       └── context-budget.cjs
 ├── pods/
 │   ├── academy/                   # aulas, palestras, treinamentos
 │   ├── authority-content/         # conteúdo com voz própria e fact-check
 │   ├── automation/                # N8N + Langgraph
+│   ├── content-carousel/          # carrosséis a partir de uma fonte, com fact-check
 │   ├── dev-ia/                    # ciclo de desenvolvimento com IA
+│   ├── hormozi-method/            # oferta, aquisição e diagnóstico de escala
 │   └── squad-forge/               # cria novos agentes e pods
 ├── knowledge/
-│   └── voice-dna/                 # DNA de voz para conteúdo autoral
-├── scripts/
-│   └── validate-budgets.js        # gate de budget dos agentes
+│   ├── voice-dna/                 # DNA de voz para conteúdo autoral (opcional)
+│   └── analyst/                   # base de pesquisa compartilhada
+├── scripts/                       # motor: runner, memória, validadores, vetos
 └── .power-claude/
     └── manifest.json              # estado da instalação (base do update/uninstall)
 ```
 
-**Nota honesta sobre o runner/memória/migração:** `power-claude install` copia `template/` inteiro (inclui a skill `pc-run-pod` em `.claude/skills/`) mais `scripts/validate-budgets.js` avulso — **só isso é distribuído automaticamente** (`installer/install.js`/`copy.js`). Os scripts que o runner, a memória e o `*migrate-squad` invocam (`pc-run-pod.cjs`, `pod-memory.cjs`, `migration-manifest.cjs`, `validate-pod-workflow.cjs`, `smoke-pod-workflow.cjs`, `harness-g5-lite.cjs`, `watcher-audit.cjs`, `forge-*.cjs`, `validate-no-clone.cjs`) vivem só em `scripts/` na raiz deste repositório e **não são copiados para o projeto instalado**. Hoje essas capacidades operam via o próprio repositório do framework (dogfooding) ou por sync manual dos scripts para o projeto consumidor — gap registrado em `BACKLOG.md`.
+O catálogo dos pods, com o job-to-be-done de cada um, está em [`template/pods/README.md`](template/pods/README.md).
+
+**O que viaja para a sua instalação, e o que não viaja.** `install` copia o `template/` inteiro (o
+`.claude/` acima, com agentes, regras, skills, comandos e hooks, mais os pods que você escolheu) **e**
+os scripts do motor declarados em [`installer/motor-scripts.json`](installer/motor-scripts.json) — o
+runner, a memória evolutiva dos pods, os validadores de workflow e os vetos vão junto, em `scripts/`,
+com o mesmo contrato de preservação do template (o que você modificar não é sobrescrito; `update
+--scope motor` é a via explícita para atualizar só esses scripts). O que **não** viaja é o que só faz
+sentido no repositório do framework: testes, fixtures e um punhado de scripts nomeados na lista
+`exclude` do mesmo manifesto. A documentação também não entra no pacote npm (`package.json` →
+`files: ["bin","installer","template","scripts"]`) — ela vive neste repositório, que é o que você está
+lendo agora.
 
-## Personalização — opcional, em três degraus
+## Personalização
 
-**Nenhum pod exige que você construa um DNA de voz.** Os pods que assinam peças **em seu nome**
-perguntam quem é você — **uma vez, três campos** (nome, handle, uma linha de autoridade). Tudo o
-mais — voz, tom, léxico, objetivos — é opcional, tem default funcional, e vai se ajustando com o
-seu feedback durante o uso.
+Opcional, em três degraus — e **nenhum pod exige que você construa um DNA de voz.** Os pods que assinam
+peças **em seu nome** perguntam quem é você — **uma vez, três campos** (nome, handle, uma linha de
+autoridade). Tudo o mais — voz, tom, léxico, objetivos — é opcional, tem default funcional, e vai se
+ajustando com o seu feedback durante o uso.
 
 | Degrau | O que você fornece | Onde mora | O que muda |
 |---|---|---|---|
@@ -107,6 +148,29 @@ template distribui só os `*.example.*`, e um oráculo (`scripts/owner-layer.cjs
 ser um placeholder marcado. Passo a passo de instanciação: `knowledge/voice-dna/README.md` na sua
 instalação.
 
+## Para quem avalia o framework
+
+Se você já conhece o terreno e quer julgar profundidade em vez de aprender do zero:
+
+- **[Índice dos mecanismos](docs/mecanismos/README.md)** — a referência densa: uma página por
+  mecanismo entregue, agrupada por área funcional, com comandos reais e ligação para o "porquê".
+  É o melhor lugar para medir o que o framework realmente faz.
+- **[Releases do GitHub](../../releases)** — o histórico versão a versão, com o que entrou em cada
+  release; o corpo de cada Release deriva do `CHANGELOG.md` do repositório de desenvolvimento (privado
+  por decisão). Este README não mantém vitrine de novidades: quem responde por "o que mudou desde a
+  última vez que olhei" são as Releases.
+- **[Decisões arquiteturais (ADR)](docs/adr)** — cada decisão não trivial com alternativas
+  consideradas, o que foi medido e o que foi recusado. É onde ver o critério, não só o resultado.
+- **[Pesquisa e registros de investigação](docs/research)** — o que foi medido antes de decidir,
+  inclusive quando a medição derrubou a hipótese.
+
+**Sobre as referências a `docs/stories` e `docs/qa` que você vai encontrar nos ADRs e na pesquisa.** Elas
+apontam para o registro de execução do framework — as stories de desenvolvimento e os gates de qualidade que
+as aprovam. Esse registro é **privado por decisão explícita, não por descuido**: o que se publica aqui é o
+critério (o porquê e o que foi medido), enquanto o diário de execução, que carrega contexto operacional e
+pessoal de quem trabalha nele, fica fora. Um link quebrado para `docs/stories/...` ou `docs/qa/...` num ADR
+é, portanto, o comportamento esperado desta fronteira — não um arquivo perdido.
+
 ## Validação no repositório do framework
 
 ```bash
@@ -116,6 +180,6 @@ npm run validate   # budgets + branding + validate-no-clone
 
 ## Licença
 
-[MIT](./LICENSE) — Copyright (c) 2026 **Daniel Lins**.
+[MIT](LICENSE) — Copyright (c) 2026 **Daniel Lins**.
 
 Use, copie e adapte à vontade, mantendo a atribuição a Daniel Lins conforme a licença.

package/installer/motor-scripts.json

@@ -35,5 +35,5 @@
     { "path": "scripts/pod-export-ui.cjs",        "owner": "skill:pc-export", "reason": "referenced", "requiredBy": "skill:pc-export" },
     { "path": "scripts/validate-story-acs.cjs",   "owner": "skill:pc-validate-story", "reason": "referenced" }
   ],
-  "exclude": ["*.test.cjs", "__tests__/", "__fixtures__/", "validate-install.js", "validate-adopt.js", "validate-update-scope-motor.js", "owner-layer.cjs", "derive-ready-transitions.cjs"]
+  "exclude": ["*.test.cjs", "__tests__/", "__fixtures__/", "validate-install.js", "validate-adopt.js", "validate-update-scope-motor.js", "owner-layer.cjs", "derive-ready-transitions.cjs", "validate-git-vetor.cjs", "build-public-tree.cjs"]
 }

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@daniellins/power-claude",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "description": "Lean, budget-gated agent framework for Claude Code — pods by job-to-be-done",
   "author": "Daniel Lins",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daniellins/power-claude-core.git"
+  },
+  "homepage": "https://github.com/daniellins/power-claude-core#readme",
+  "bugs": {
+    "url": "https://github.com/daniellins/power-claude-core/issues"
+  },
   "bin": {
     "power-claude": "bin/cli.js"
   },
@@ -21,6 +29,6 @@
   ],
   "scripts": {
     "test": "node scripts/validate-install.js && node scripts/validate-adopt.js && node scripts/validate-update-scope-motor.js && node scripts/__tests__/validate-pod-workflow.test.cjs && node scripts/__tests__/pc-run-pod.test.cjs && node scripts/__tests__/pc-run-pod-counter.test.cjs && node scripts/pc-run-pod-countgte.test.cjs && node scripts/forge.test.cjs && node scripts/forge-assess-tier.test.cjs && node scripts/forge-additive.test.cjs && node scripts/forge-canonical.test.cjs && node scripts/migration-manifest.test.cjs && node scripts/migration-manifest-sf3.2.test.cjs && node scripts/migration-manifest-sf3.3.test.cjs && node scripts/migration-manifest-sf5.5.test.cjs && node scripts/validate-no-clone.test.cjs && node scripts/migrate-squad-orchestration.test.cjs && node scripts/pod-memory.test.cjs && node scripts/pod-memory-budget.test.cjs && node scripts/pod-memory-note.test.cjs && node scripts/forge-harden-learning.test.cjs && node scripts/harden-knowledge.test.cjs && node scripts/consolidate-knowledge-runner.test.cjs && node scripts/smoke-pod-workflow.cjs scripts/__fixtures__/smoke-canary/workflows/wf-canary.yaml && node scripts/smoke-sweep.test.cjs && node scripts/smoke-isolation.test.cjs && node scripts/harness-g5-lite.test.cjs && node scripts/__tests__/motor-scripts.test.cjs && node scripts/validate-fidelity-output.test.cjs && node scripts/validate-source-audit.test.cjs && node scripts/arena.test.cjs && node scripts/veto-checks.test.cjs && node scripts/phash-gate.test.cjs && node scripts/render-png.test.cjs && node scripts/hn-carousel-contrato-entrada.test.cjs && node scripts/anti-path.test.cjs && node scripts/brief-leitura-obrigatoria.test.cjs && node scripts/pc-run-pipeline.test.cjs && node scripts/pod-export-compile.test.cjs && node scripts/pod-export-executor.test.cjs && node scripts/pod-export-postprocess.test.cjs && node scripts/pod-export-release.test.cjs && node scripts/pod-export-service.test.cjs && node scripts/pod-export-ui.test.cjs && node scripts/pod-export-hardening.test.cjs && node scripts/pod-export-queue-race.test.cjs && node scripts/npm-scope-invocation.test.cjs && node scripts/default-funcional.test.cjs && node scripts/owner-layer.test.cjs && node scripts/__tests__/enforce-cycle-authority.test.cjs && node scripts/__tests__/enforce-git-push-authority.test.cjs && node scripts/__tests__/validate-story-acs.test.cjs && node scripts/__tests__/enforce-ready-oracles.test.cjs && node scripts/__tests__/derive-ready-transitions.test.cjs && node installer/__tests__/doctor-ready-oracles.test.cjs && node installer/__tests__/merge-settings.test.cjs",
-    "validate": "node scripts/validate-budgets.js template/pods template/.claude/agents && node scripts/validate-branding.js && node scripts/validate-no-clone.cjs template"
+    "validate": "node scripts/validate-budgets.js template/pods template/.claude/agents && node scripts/validate-branding.js && node scripts/validate-no-clone.cjs template && node scripts/validate-git-vetor.cjs"
   }
 }

package/scripts/__tests__/enforce-git-push-authority.test.cjs

@@ -72,6 +72,23 @@
  * desconhecido que não é alias; subcomando real do gh), `gh` inacessível,
  * e a prova final de que `gh pr merge` não é alcançável sem `ask` por
  * nenhuma forma testada, nem para pc-devops.
+ *
+ * Story SF15.12 (`I4` do ADR-037): até então NENHUMA asserção deste arquivo
+ * distinguia DESTINO — `pc-devops` empurrava em silêncio para `origin`, para
+ * um remoto público e para uma URL arbitrária, indistintamente.
+ * `testStorySF15_12()` cobre os 3 cenários do predicado de remoto (nome
+ * declarado na lista; URL/SSH bruta; destino não confirmável) e, sobretudo,
+ * as CONTRAPROVAS sem as quais o predicado passaria com uma implementação
+ * errada: o par que mata o cheat "tudo que não é `origin` pede confirmação"
+ * (`B5` — remoto não declarado com nome ≠ origin → silêncio; lista contendo
+ * `["origin"]` → ask), o catálogo FECHADO de opções com valor separado
+ * (`B1`/`B6` — `-o ci.skip` não vira remoto, `-u`/`--tags` não engolem o
+ * remoto), o encadeamento (`B2` — o 2º push da cadeia não some na agregação,
+ * e o `ask` novo nunca rebaixa um `deny`), malformado ≠ ausente (`M1`), o
+ * `-C` que passa a ser usado em vez de descartado (`M2`) e a UNIÃO dos 2
+ * lados de leitura da lista (`B4`). Os cenários vivem AQUI, na suíte que
+ * `npm test` roda, e não só no oráculo da story — sem isso o próximo refactor
+ * do hook regride o `I4` em silêncio.
  */
 
 const fs = require('node:fs');
@@ -641,6 +658,264 @@ function testFixRoundF5() {
   }
 }
 
+// Cria um repositório temporário real com (opcionalmente) uma DECLARAÇÃO de
+// remotos irreversíveis em `.claude/hooks/irreversible-remotes.json` — o lado
+// `input.cwd` da união (a instalação viva cuja sessão executa o push).
+function initTmpRepoComDeclaracao(prefix, conteudoJson) {
+  const dir = initTmpGitRepo(prefix);
+  if (conteudoJson !== undefined) {
+    fs.mkdirSync(path.join(dir, '.claude', 'hooks'), { recursive: true });
+    fs.writeFileSync(path.join(dir, '.claude', 'hooks', 'irreversible-remotes.json'), conteudoJson);
+  }
+  return dir;
+}
+
+function declara(remotes) {
+  return JSON.stringify({ remotes });
+}
+
+// Configura um upstream RESOLVÍVEL offline (sem rede, sem push real): o
+// `git rev-parse --abbrev-ref --symbolic-full-name @{u}` só responde quando
+// existem as 3 peças — remote com refspec de fetch, `branch.<b>.remote`/
+// `.merge`, e a ref de rastreamento `refs/remotes/<remoto>/<branch>` (medido:
+// sem a ref, sai `exit 128`, "not stored as a remote-tracking branch").
+function configuraUpstream(repo, remoteName) {
+  spawnSync('git', ['commit', '-q', '--allow-empty', '-m', 'base'], { cwd: repo });
+  const branch = (spawnSync('git', ['branch', '--show-current'], { cwd: repo, encoding: 'utf8' }).stdout || '').trim();
+  const head = (spawnSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).stdout || '').trim();
+  spawnSync('git', ['remote', 'add', remoteName, `/tmp/repositorio-inexistente-${remoteName}.git`], { cwd: repo });
+  spawnSync('git', ['config', `branch.${branch}.remote`, remoteName], { cwd: repo });
+  spawnSync('git', ['config', `branch.${branch}.merge`, `refs/heads/${branch}`], { cwd: repo });
+  spawnSync('git', ['update-ref', `refs/remotes/${remoteName}/${branch}`, head], { cwd: repo });
+  return branch;
+}
+
+function testStorySF15_12() {
+  console.log('\n-- Story SF15.12 (`I4` do ADR-037): o hook deixa de ser cego a REMOTO --');
+
+  // Toda asserção usa `pc-devops` de propósito: é a identidade MAIS permissiva
+  // do hook (a única que hoje empurra em silêncio), então é nela que a
+  // regressão dói e é nela que o `ask` novo precisa valer — "inclusive para
+  // devops" não é retórica do desenho, é o caso testado.
+  const declarado = initTmpRepoComDeclaracao('egpa-i4-decl-', declara(['publico']));
+  try {
+    const push = (command) => runHook(payloadCmd({ agentType: 'pc-devops', command, cwd: declarado })).decision;
+
+    // (a) NOME declarado na lista → ask incondicional.
+    assert(push('git push publico main') === 'ask', 'I4 (a): remoto DECLARADO irreversível, pc-devops → ask (o allow silencioso não é herdado pelo remoto público)');
+
+    // Regressão: remoto nomeado NÃO declarado — comportamento idêntico ao de
+    // antes desta story. É o push do próprio ciclo do framework.
+    assert(push('git push origin main') === null, 'I4 regressão: `origin` (não declarado), pc-devops → silêncio (comportamento inalterado)');
+
+    // `B5`, metade 1: o cheat `remote !== "origin" ⇒ ask` morre aqui.
+    assert(push('git push upstream main') === null, 'I4 (`B5` metade 1): remoto NÃO declarado com nome ≠ origin (`upstream`) → silêncio (não é o nome que decide)');
+
+    // `B1`: opção do subcomando que toma valor em token SEPARADO não pode
+    // fazer o parser ler o VALOR como remoto.
+    assert(push('git push -o ci.skip publico main') === 'ask', 'I4 (`B1`): `-o ci.skip publico main` → ask (a opção catalogada consome `ci.skip`, o remoto extraído é `publico`)');
+    assert(push('git push --push-option ci.skip publico main') === 'ask', 'I4 (`B1`): `--push-option ci.skip publico main` → ask (forma longa da mesma opção)');
+    assert(push('git push --push-option=ci.skip publico main') === 'ask', 'I4 (`B1`): `--push-option=ci.skip publico main` → ask (forma com `=` não consome o token seguinte)');
+
+    // `B6`: catálogo FECHADO — toda opção FORA dele é flag SEM valor.
+    assert(push('git push -u publico main') === 'ask', 'I4 (`B6` fail-open): `-u publico main` → ask (`-u`, fora do catálogo, NÃO engole o remoto — a flag de push mais usada do ciclo)');
+    assert(push('git push --tags origin main') === null, 'I4 (`B6` ruído): `--tags origin main` → silêncio (`--tags` não engole o remoto nem vira "destino não resolvido")');
+    assert(push('git push --tags publico main') === 'ask', 'I4 (`B6`): `--tags publico main` → ask (a mesma flag sem valor, com remoto declarado, continua mordendo)');
+
+    // (b) URL/SSH-spec BRUTA — o vetor medido no ADR-037 §1.3.
+    assert(push('git push git@github.com:qualquer/outro.git HEAD:main') === 'ask', 'I4 (b): URL SSH bruta (`git@github.com:...`), pc-devops → ask (vetor medido no ADR-037 §1.3)');
+    assert(push('git push https://github.com/qualquer/outro.git main') === 'ask', 'I4 (b): URL `https://` bruta → ask');
+
+    // (c) nenhum remoto explícito e upstream irresolúvel.
+    assert(push('git push') === 'ask', 'I4 (c): `git push` pelado em repositório SEM upstream → ask ("não deu para confirmar" nunca vira "sei que não é")');
+
+    // `B2`: o 2º segmento da cadeia não pode SUMIR na agregação por severidade.
+    assert(push('git push origin main && git push publico main') === 'ask', 'I4 (`B2`): cadeia `origin && publico` → ask (o 2º segmento não some na agregação)');
+
+    // `B2`, invariante inegociável: o `ask` novo NUNCA rebaixa um `deny`.
+    assert(push('git push && git push --force origin main') === 'deny', 'I4 (`B2` invariante): cadeia com force-push → deny (severidade 3.5 < 4: o `ask` novo nunca rebaixa o `deny`)');
+    assert(push('git push publico main && git push --force origin main') === 'deny', 'I4 (`B2` invariante): remoto declarado + force-push na mesma cadeia → deny (não `ask`)');
+  } finally {
+    fs.rmSync(declarado, { recursive: true, force: true });
+  }
+
+  // `F-1` (gate FAIL do `pc-qa`, `b5b0d84`): `--repo` é a ÚNICA entrada do
+  // catálogo cujo valor É o repositório de destino. Consumi-lo como valor
+  // opaco (o que a leitura SUPERADA do menor `m1` justificou "por precaução")
+  // fazia `git push --repo publico` cair no cenário (c) e concluir SILÊNCIO,
+  // enquanto o git empurrava para `publico`, um remoto DECLARADO irreversível.
+  //
+  // ATENÇÃO ao ambiente destas asserções — elas SÓ discriminam num repositório
+  // cujo upstream RESOLVE para um remoto NÃO declarado. Medido: num repositório
+  // sem upstream, a versão com o defeito também responde `ask` (cai em (c) e
+  // não consegue confirmar), e o par inteiro passaria com o furo VIVO. É a
+  // condição exata em que o `pc-qa` mediu o `F-1`, e é por isso que este bloco
+  // monta `origin` como upstream real em vez de reusar o repositório acima.
+  const repoRepoOpt = initTmpRepoComDeclaracao('egpa-i4-repoopt-', declara(['publico']));
+  try {
+    configuraUpstream(repoRepoOpt, 'origin');
+    const p = (command) => runHook(payloadCmd({ agentType: 'pc-devops', command, cwd: repoRepoOpt })).decision;
+
+    // Pré-condição do instrumento: sem ela, o par abaixo não prova nada.
+    assert(p('git push') === null, 'I4 (`F-1`) pré-condição: neste repositório o upstream RESOLVE para `origin` (não declarado) ⇒ `git push` pelado é silêncio — é o que dá poder de discriminação ao par abaixo');
+
+    // Matam o fail-open: as 2 formas que o git HONRA quando não há posicional.
+    assert(p('git push --repo publico') === 'ask', 'I4 (`F-1`): `--repo publico` sem posicional → ask (o git alcança `publico`, medido contra o git real 2.50.1 — antes era SILÊNCIO)');
+    assert(p('git push --repo=publico') === 'ask', 'I4 (`F-1`): `--repo=publico` sem posicional → ask (a forma com `=` também é honrada pelo git)');
+    assert(p('git push --tags --repo publico') === 'ask', 'I4 (`F-1`): `--repo` DEPOIS de outra flag, sem posicional → ask (a varredura não para no 1º token)');
+
+    // Matam o ruído: a PRECEDÊNCIA do posicional, medida contra o git real.
+    assert(p('git push --repo publico main') === null, 'I4 (`F-1` precedência): `--repo publico main` → silêncio (o POSICIONAL vence — o git trata `main` como repositório: `fatal: \'main\' does not appear to be a git repository`)');
+    assert(p('git push --repo publico origin main') === null, 'I4 (`F-1` precedência): `--repo publico origin main` → silêncio (o git alcança `origin`, o posicional, não `publico`)');
+    assert(p('git push --repo origin') === null, 'I4 (`F-1` regressão): `--repo origin` (não declarado) → silêncio (capturar `--repo` não virou `ask` genérico)');
+
+    // Dúvida e invariantes.
+    assert(p('git push --repo') === 'ask', 'I4 (`F-1`): `--repo` sem valor utilizável → ask ("não sei para onde isto vai" nunca vira "não há")');
+    assert(p('git push --force --repo publico') === 'deny', 'I4 (`F-1` invariante): `--force --repo publico` → deny (o `ask` do destino nunca rebaixa o force-push)');
+
+    // Contraprova: as OUTRAS opções do catálogo continuam com valor opaco —
+    // o fix não transformou todo valor catalogado em candidato a remoto.
+    assert(p('git push --exec /bin/true publico') === 'ask', 'I4 (`F-1` contraprova): o valor de `--exec` NÃO é remoto — quem decide é `publico`, o posicional → ask');
+    assert(p('git push --exec /bin/true origin') === null, 'I4 (`F-1` contraprova): a mesma forma com `origin` → silêncio (o catálogo segue consumindo o valor das demais opções)');
+    assert(p('git push -o ci.skip publico') === 'ask', 'I4 (`F-1` contraprova): `-o ci.skip publico` → ask (o `B1` segue intacto: `ci.skip` não é remoto, `publico` é)');
+  } finally {
+    fs.rmSync(repoRepoOpt, { recursive: true, force: true });
+  }
+
+  // `B5`, metade 2: com `["origin"]` na lista, `git push origin main` — o
+  // comando mais comum do ciclo, silencioso em TODA outra asserção deste
+  // arquivo — passa a pedir confirmação. As 2 metades juntas provam que é a
+  // LISTA que decide, não o nome do remoto.
+  const originDeclarado = initTmpRepoComDeclaracao('egpa-i4-origin-', declara(['origin']));
+  try {
+    assert(
+      runHook(payloadCmd({ agentType: 'pc-devops', command: 'git push origin main', cwd: originDeclarado })).decision === 'ask',
+      'I4 (`B5` metade 2): lista contendo `["origin"]` → `git push origin main` → ask (é a LISTA que decide, não o nome)',
+    );
+  } finally {
+    fs.rmSync(originDeclarado, { recursive: true, force: true });
+  }
+
+  // `M1` — malformado ≠ ausente. Um typo na lista NUNCA pode desligar a
+  // guarda em silêncio: o desfecho é o oposto, `ask` até para o que hoje é
+  // silencioso.
+  const ausente = initTmpRepoComDeclaracao('egpa-i4-ausente-', undefined);
+  try {
+    assert(
+      runHook(payloadCmd({ agentType: 'pc-devops', command: 'git push origin main', cwd: ausente })).decision === null,
+      'I4 (`M1` controle): arquivo AUSENTE é resposta conclusiva ("nada declarado") → silêncio (não quebra instalação que nunca ouviu falar desta story)',
+    );
+  } finally {
+    fs.rmSync(ausente, { recursive: true, force: true });
+  }
+
+  const malformados = [
+    ['{ isto nao e json valido', 'JSON com erro de SINTAXE'],
+    [JSON.stringify({ remotes: 'publico' }), 'FORMA errada (`remotes` string, não array)'],
+    [JSON.stringify({ remotes: ['publico', 42] }), 'FORMA errada (entrada não-string dentro do array)'],
+    [JSON.stringify({ semChaveRemotes: [] }), 'FORMA errada (sem a chave `remotes`)'],
+  ];
+  for (const [conteudo, rotulo] of malformados) {
+    const repo = initTmpRepoComDeclaracao('egpa-i4-malformado-', conteudo);
+    try {
+      assert(
+        runHook(payloadCmd({ agentType: 'pc-devops', command: 'git push origin main', cwd: repo })).decision === 'ask',
+        `I4 (\`M1\` fail-loud): lista ilegível — ${rotulo} — → ask até para \`origin\` (um typo NUNCA desliga a guarda em silêncio)`,
+      );
+    } finally {
+      fs.rmSync(repo, { recursive: true, force: true });
+    }
+  }
+
+  // (c) quando o upstream RESOLVE: o predicado usa o remoto resolvido contra a
+  // lista, em vez de perguntar sempre. Sem estas 2, "(c) ⇒ ask" passaria por
+  // um `ask` cego que quebraria todo push do próprio ciclo.
+  const upstreamDeclarado = initTmpRepoComDeclaracao('egpa-i4-up-decl-', declara(['publico']));
+  try {
+    configuraUpstream(upstreamDeclarado, 'publico');
+    assert(
+      runHook(payloadCmd({ agentType: 'pc-devops', command: 'git push', cwd: upstreamDeclarado })).decision === 'ask',
+      'I4 (c): `git push` pelado com upstream que resolve para remoto DECLARADO → ask (o destino real é alcançado mesmo sem token de remoto)',
+    );
+  } finally {
+    fs.rmSync(upstreamDeclarado, { recursive: true, force: true });
+  }
+
+  const upstreamNaoDeclarado = initTmpRepoComDeclaracao('egpa-i4-up-ndecl-', declara(['publico']));
+  try {
+    configuraUpstream(upstreamNaoDeclarado, 'origin');
+    assert(
+      runHook(payloadCmd({ agentType: 'pc-devops', command: 'git push', cwd: upstreamNaoDeclarado })).decision === null,
+      'I4 (c) contraprova: `git push` pelado com upstream que resolve para remoto NÃO declarado → silêncio (o cenário (c) não é um `ask` cego)',
+    );
+  } finally {
+    fs.rmSync(upstreamNaoDeclarado, { recursive: true, force: true });
+  }
+
+  // `M2` — `git -C <outro-repo> push` resolve o upstream no repositório que o
+  // comando aponta, não no `cwd` da sessão (nomes de remoto são POR
+  // repositório). Discrimina: se `-C` fosse descartado (como antes desta
+  // story), a resolução cairia no `cwd`, que não tem upstream, e o desfecho
+  // seria `ask` — o oposto do esperado aqui.
+  const cwdSemUpstream = initTmpRepoComDeclaracao('egpa-i4-c-cwd-', declara(['publico']));
+  const alvoComUpstream = initTmpGitRepo('egpa-i4-c-alvo-');
+  try {
+    configuraUpstream(alvoComUpstream, 'origin');
+    assert(
+      runHook(payloadCmd({ agentType: 'pc-devops', command: `git -C ${alvoComUpstream} push`, cwd: cwdSemUpstream })).decision === null,
+      'I4 (`M2`): `git -C <repo-com-upstream-não-declarado> push` → silêncio (o valor de `-C` é usado como repositório da resolução, não descartado)',
+    );
+    assert(
+      runHook(payloadCmd({ agentType: 'pc-devops', command: `git -C ${alvoComUpstream} -C ${cwdSemUpstream} push`, cwd: cwdSemUpstream })).decision === 'ask',
+      'I4 (`M2`): `-C` repetido (cumulativo no git real, não reproduzido por este parser) → ask ("presente e não utilizável" é dúvida, nunca silêncio)',
+    );
+  } finally {
+    fs.rmSync(cwdSemUpstream, { recursive: true, force: true });
+    fs.rmSync(alvoComUpstream, { recursive: true, force: true });
+  }
+
+  // `B4` — a UNIÃO dos 2 lados. O lado `__dirname` (o arquivo que VIAJA com o
+  // hook, dentro da instalação) precisa contribuir SOZINHO, sem depender de
+  // `cwd`: é ele que morde quando a sessão roda de um diretório sem `.claude/`
+  // nenhum. E os 2 lados juntos ALARGAM o conjunto — nunca se substituem.
+  const hookHome = fs.mkdtempSync(path.join(os.tmpdir(), 'egpa-i4-dirname-'));
+  const repoSemClaude = initTmpGitRepo('egpa-i4-sem-claude-');
+  const repoOutraLista = initTmpRepoComDeclaracao('egpa-i4-uniao-', declara(['soNoCwd']));
+  try {
+    const hookCopiado = path.join(hookHome, 'enforce-git-push-authority.cjs');
+    fs.copyFileSync(HOOK_PATH, hookCopiado);
+    fs.writeFileSync(path.join(hookHome, 'irreversible-remotes.json'), declara(['soNoDirname']));
+    const viaCopia = (command, cwd) => runHookAtPath(hookCopiado, payloadCmd({ agentType: 'pc-devops', command, cwd })).decision;
+
+    assert(!fs.existsSync(path.join(repoSemClaude, '.claude')), 'I4 (`B4`) pré-condição: o `cwd` do caso `__dirname` não tem `.claude/` nenhum');
+    assert(viaCopia('git push soNoDirname main', repoSemClaude) === 'ask', 'I4 (`B4`): o lado `__dirname` da união morde SOZINHO, com `cwd` sem `.claude/` (o hook não lia arquivo nenhum antes desta story)');
+    assert(viaCopia('git push origin main', repoSemClaude) === null, 'I4 (`B4`) controle: remoto não declarado em lado nenhum → silêncio');
+    assert(viaCopia('git push soNoDirname main', repoOutraLista) === 'ask', 'I4 (`B4`) união: o lado `__dirname` continua valendo mesmo quando o `cwd` declara OUTRA lista (união não é substituição)');
+    assert(viaCopia('git push soNoCwd main', repoOutraLista) === 'ask', 'I4 (`B4`) união: o lado `input.cwd` também morde na mesma invocação (união ALARGA os dois lados, nunca interseciona)');
+  } finally {
+    fs.rmSync(hookHome, { recursive: true, force: true });
+    fs.rmSync(repoSemClaude, { recursive: true, force: true });
+    fs.rmSync(repoOutraLista, { recursive: true, force: true });
+  }
+
+  // O arquivo que VIAJA no template nasce vazio e assim precisa permanecer:
+  // hardcodar o nome do remoto deste projeto no framework distribuído é
+  // exatamente o que o ADR-037 §8.1.1 (b) proíbe — a lista é do dono de cada
+  // instalação. Guarda permanente contra essa regressão.
+  const templateDecl = path.join(REPO_ROOT, 'template', '.claude', 'hooks', 'irreversible-remotes.json');
+  assert(fs.existsSync(templateDecl), 'I4: `template/.claude/hooks/irreversible-remotes.json` existe e viaja com o hook para toda instalação');
+  let templateParsed = null;
+  try {
+    templateParsed = JSON.parse(fs.readFileSync(templateDecl, 'utf8'));
+  } catch {
+    templateParsed = null;
+  }
+  assert(
+    templateParsed && Array.isArray(templateParsed.remotes) && templateParsed.remotes.length === 0,
+    'I4: o arquivo do template é `{"remotes": []}` — nenhum nome de remoto hardcodado no framework distribuído (ADR-037 §8.1.1 b)',
+  );
+}
+
 function buildMutant(tmpDir) {
   const source = fs.readFileSync(HOOK_PATH, 'utf8');
   const target = `function isDevOpsAgent(input) {\n  return typeof input?.agent_type === 'string' && input.agent_type === DEVOPS_AGENT_TYPE;\n}`;
@@ -670,7 +945,18 @@ function testMutacao() {
 
     // A mutante deveria, no entanto, mudar o resultado do controle 4 (não-force):
     // prova que a mutação realmente afeta a checagem de identidade (mutante viva).
-    const nonForcePayload = payloadCmd({ agentType: 'pc-dev', command: 'git push' });
+    //
+    // Story SF15.12 (`B3`, remediação prescrita ANTES da implementação): o
+    // payload deste instrumento era `git push` PELADO. Com o cenário (c) do
+    // `I4` (sem argumento de remoto + upstream irresolúvel ⇒ `ask`), esse
+    // comando passa a ser `ask` por razão INDEPENDENTE da identidade — a
+    // branch de trabalho não tem upstream (medido: `git rev-parse @{u}` sai
+    // exit 128) — e o instrumento perderia o poder de discriminar mutante ×
+    // hook real, que é a única coisa que ele existe para fazer. `git push
+    // origin main` (remoto EXPLÍCITO e NÃO-declarado) restaura essa
+    // discriminação: `origin` não participa da checagem de identidade que o
+    // AC43 testa, e o desfecho volta a depender só dela.
+    const nonForcePayload = payloadCmd({ agentType: 'pc-dev', command: 'git push origin main' });
     assert(runHook(nonForcePayload).decision === 'ask', 'controle: hook REAL pergunta pc-dev + push (não-force) (pré-condição)');
     assert(
       runHookAtPath(mutantPath, nonForcePayload).decision === null,
@@ -682,12 +968,13 @@ function testMutacao() {
 }
 
 function main() {
-  console.log('POWER CLAUDE — suíte do hook enforce-git-push-authority.cjs (SF12.3, Bloco M, AC42-43 + fix rounds F1/F3/F4/F5)\n');
+  console.log('POWER CLAUDE — suíte do hook enforce-git-push-authority.cjs (SF12.3, Bloco M, AC42-43 + fix rounds F1/F3/F4/F5 + SF15.12/`I4`)\n');
   testControlesAC43();
   testFixRoundF1();
   testFixRoundF3();
   testFixRoundF4();
   testFixRoundF5();
+  testStorySF15_12();
   testMutacao();
 
   if (failures > 0) {