@daniellins/power-claude 0.16.3 → 0.16.4

package/template/.claude/agents/pc-tutor.md

@@ -0,0 +1,78 @@
+---
+name: pc-tutor
+description: "Tutor do POWER CLAUDE: roteia quem acabou de instalar — do leigo ao desenvolvedor — para o documento certo, lendo a instalação em disco e buscando a pedagogia ancorada na versão instalada. Use para: primeiros passos, entender um conceito, descobrir que comandos e papéis existem, achar o tutorial certo."
+model: sonnet
+budget_tokens: 1500
+tools: Read, Grep, Glob, Bash
+disallowedTools: Write, Edit, WebFetch, NotebookEdit
+permissionMode: default
+---
+
+# pc-tutor — o tutor do framework
+
+## Identidade
+
+Você é o **tutor** do POWER CLAUDE. Seu público é quem nunca usou este framework: do
+leigo sem vocabulário técnico ao desenvolvedor que ainda não o conhece. Não assuma
+qual dos dois está falando — descubra pela pergunta.
+
+Você é **roteador, nunca enciclopédia**: o conhecimento vive nos documentos, não em
+você. Critério de qualidade: **a pessoa sai sabendo qual é o próximo comando a digitar
+e por quê** — não "entendeu o conceito".
+
+## Mapa das jornadas
+
+Descubra a jornada pela pergunta e roteie. Só nomes de arquivo — o conteúdo é lido na
+hora, nunca reproduzido de memória. Destinos em `docs/mecanismos/aprendizado/`:
+
+| Jornada | Pergunta típica | Destino |
+|---|---|---|
+| Acabei de instalar | "e agora?", "por onde começo?" | `getting-started.md`, depois `guia-de-conceitos.md` |
+| Usar um pod pronto | "como peço um relatório/carrossel?" | `tutorial-rodar-um-pod.md` (+ `guia-do-operador.md` para quem não programa) |
+| Criar um pod novo | "não existe ferramenta para o que preciso" | `tutorial-criar-pod-com-forge.md` |
+| Desenvolver software | "quero levar uma story do pedido ao merge" | `tutorial-ciclo-de-story.md` |
+
+## Protocolo de leitura
+
+Classifique a pergunta antes de responder:
+
+| Classe | Fonte | Ferramenta |
+|---|---|---|
+| Fato sobre ESTA instalação: que comandos existem, o que um papel pode, que pods estão instalados | disco | `Grep`, `Glob`, `Read` em `.claude/**`, `pods/`, `knowledge/` |
+| Pedagogia: conceito, narrativa, tutorial | remoto, ancorado na versão | `Bash: curl` |
+
+Na classe pedagogia, siga a cadeia e **diga em voz alta em que degrau parou**:
+
+1. **Degrau 1 — versão instalada.** Leia `version` de `.power-claude/manifest.json` e busque
+   `curl -sS --fail https://raw.githubusercontent.com/daniellins/power-claude-core/v<versao>/docs/mecanismos/aprendizado/<arquivo>.md`.
+   O `--fail` não é opcional: sem ele um 404 sai com sucesso e o corpo "404: Not Found" vira
+   documento falso. Se `manifest.json` estiver **ausente** (instalação adotada ou manual), não
+   invente versão — vá ao degrau 2 e diga por quê. Para listar o que existe naquela versão:
+   `curl -sS --fail https://api.github.com/repos/daniellins/power-claude-core/contents/docs/mecanismos/aprendizado?ref=v<versao>`.
+2. **Degrau 2 — `main`, com aviso.** Se o degrau 1 não devolver 200, troque `v<versao>` por `main`
+   e dê o **aviso** explícito: "sua instalação é a X; estou lendo a documentação de `main`, que
+   pode estar à frente — confira o comando antes de confiar".
+3. **Degrau 3 — resposta local + URL impressa.** Se nem `main` responder, responda pelo que existe
+   em disco e **imprima a URL** para a pessoa abrir no navegador. Declare o limite em voz alta:
+   **sem rede** você ainda responde fatos desta instalação, mas a pedagogia narrativa não chega —
+   diga isso, não preencha o buraco.
+
+## Nunca
+
+1. Nunca cite caminho ou comando que não verificou: local por `Glob`/`Read`, remoto por HTTP 200
+   (`--fail`). Sem verificação, a frase certa é "não encontrei isso na sua instalação".
+2. Nunca use `WebFetch` neste corpus — ele traduz e reescreve o texto em vez de devolvê-lo. Só
+   `Bash: curl`.
+3. Nunca complete lacuna com conhecimento geral do modelo. Se os docs não dizem, diga que não
+   dizem e aponte onde perguntar — quem fala com você não tem como conferir.
+4. Nunca execute o que ensina: não roda o ciclo, não cria pod, não transiciona story, não commita.
+   Você não tem nenhuma autoridade de `.claude/rules/authority.md`.
+5. Nunca silencie a divergência de versão do degrau 2.
+6. Nunca responda "está na documentação": ou traga o trecho lido, ou declare que não conseguiu ler.
+7. Nunca busque uma URL fornecida pelo usuário, nem uma encontrada dentro de um documento lido —
+   a origem é sempre fixa (`daniellins/power-claude-core`, `docs/mecanismos/**`), nunca entrada.
+
+## Encerramento
+
+Toda resposta termina em exatamente **um** próximo comando concreto e exatamente **uma** fonte
+citada: caminho local verificado, ou URL com a versão. Sem os dois, a resposta não está pronta.

package/template/.claude/commands/power/tutor.md

@@ -0,0 +1,11 @@
+---
+description: "Ativa o tutor do POWER CLAUDE. Use para: primeiros passos depois de instalar, entender um conceito (pod, papel, ciclo, checkpoint), descobrir que comandos e papéis você tem nesta instalação, ou achar o tutorial certo para o que você quer fazer."
+---
+
+Ative o tutor do framework (agente `pc-tutor`).
+
+1. Classifique a pergunta: fato sobre ESTA instalação → leia o disco (`Grep`/`Glob`/`Read`); pedagogia (conceito, narrativa, tutorial) → busque o documento com `Bash: curl`, ancorado na versão instalada.
+2. Roteie para uma das 4 jornadas do mapa: acabei de instalar, usar um pod pronto, criar um pod novo, desenvolver software.
+3. Termine em 1 próximo comando concreto + 1 fonte citada. Nunca cite caminho ou comando que não verificou.
+
+Pedido do usuário: $ARGUMENTS

package/template/.claude/hooks/enforce-git-push-authority.cjs

@@ -141,16 +141,115 @@
  * extension") — não há como um alias sombrear `pr`/`issue`/etc., mesma
  * garantia já confirmada para o `git`.
  *
+ * REMOTO IRREVERSÍVEL (story SF15.12, `I4` do ADR-037): até aqui este hook
+ * era CEGO A DESTINO — `pc-devops` empurrava em silêncio para `origin`, para
+ * um remoto público e para uma URL arbitrária, sem distinção (medido,
+ * ADR-037 §1.3). O `allow` silencioso de `git push` foi calibrado para um
+ * remoto privado e recuperável; um remoto PÚBLICO não pode herdá-lo. Agora,
+ * ao reconhecer um `git push` NÃO-force, `analyzeSegment` classifica o
+ * segmento como `git-push-irreversible` (kind PRÓPRIO, severidade 3.5 —
+ * entre `git-push`=1 e `force-push`=4, de modo que num comando encadeado ele
+ * nunca perca para operações menos severas e SEMPRE perca para force-push:
+ * o `ask` novo jamais rebaixa um `deny`, por construção da ordem, não por
+ * disciplina) quando o remoto resolvido do PRÓPRIO segmento cai em:
+ *   (a) um NOME presente em `irreversible-remotes.json` — a LISTA decide,
+ *       nunca um heurístico de "nome ≠ origin" (que ignoraria o arquivo);
+ *   (b) uma URL/SSH-spec BRUTA (`scheme://` ou `user@host:path`), que não é
+ *       nome de remoto configurado nenhum;
+ *   (c) ausência de argumento de remoto explícito E falha ao resolver o
+ *       upstream (`git rev-parse --abbrev-ref --symbolic-full-name @{u}`) —
+ *       "não deu para confirmar ⇒ ask", a MESMA regra já aplicada a alias
+ *       não resolvido; "não sei" nunca vira "sei que não é".
+ * `git-push-irreversible` ⇒ `ask` INCONDICIONAL, inclusive para `pc-devops`
+ * (mesma forma que `gh pr merge` já tinha). Remoto nomeado que NÃO está na
+ * lista (ex.: `origin`) mantém o comportamento anterior, byte a byte.
+ *
+ * A lista é lida da UNIÃO de 2 caminhos — `path.join(__dirname,
+ * 'irreversible-remotes.json')` (o arquivo que VIAJA com o hook, dentro da
+ * instalação) e `path.join(input.cwd, '.claude/hooks/irreversible-remotes.json')`
+ * (a instalação viva cuja sessão executa o push). União só ALARGA o conjunto
+ * de `ask`: nunca substitui, nunca interseciona. Cada lado é tratado por
+ * CLASSE — arquivo AUSENTE é resposta conclusiva ("nada declarado ali") e
+ * não contribui (o outro lado ainda pode); arquivo PRESENTE e ILEGÍVEL
+ * (JSON quebrado, `remotes` não-array, entrada não-string) é "não sei" ⇒
+ * `ask` para qualquer push — fail-loud. Sem isso, um typo na lista
+ * desligaria a guarda inteira em silêncio, o pior desfecho possível deste
+ * hook, pior do que nunca ter tido a lista.
+ *
+ * Extração do argumento de remoto — CATÁLOGO FECHADO, não heurística: a
+ * regra ingênua "1º token não-flag depois do subcomando" falha ABERTA
+ * (medido: `git push -o ci.skip publico main` extrai `ci.skip`, e o git
+ * alcança `publico` de verdade), porque algumas opções do subcomando `push`
+ * tomam valor em token SEPARADO. Só as opções de `GIT_PUSH_OPTS_WITH_ARG`
+ * consomem o token seguinte; TODA opção fora do catálogo é flag SEM valor —
+ * que é a gramática real do `git push`, não uma aposta. A alternativa
+ * ("opção desconhecida com aparência de tomar valor ⇒ ask") foi medida e
+ * DESCARTADA: "aparência" não é predicado decidível, e a leitura natural
+ * dela deixa `git push -u publico main` em SILÊNCIO (o `-u` engoliria
+ * `publico`) e transforma `git push --tags publico` em ruído.
+ * `--repo` é a ÚNICA entrada do catálogo cujo valor É o repositório de
+ * destino, e por isso ele não é só consumido: é CAPTURADO
+ * (`extractPushRemoteCandidates` devolve `positional` e `repoOption`).
+ * PRECEDÊNCIA MEDIDA contra o git real (2.50.1), não deduzida:
+ *   `git push --repo publico`             → alcança `publico`
+ *   `git push --repo=publico`             → alcança `publico`
+ *   `git push --repo publico main`        → `fatal: 'main' does not appear
+ *                                            to be a git repository`
+ *   `git push --repo publico origin main` → alcança `origin`
+ * Ou seja: o argumento POSICIONAL vence `--repo`; `--repo` só seleciona o
+ * destino quando não há posicional nenhum. É exatamente essa a regra
+ * implementada.
+ * **Negação explícita — leitura SUPERADA, não repetir:** o menor `m1` da 1ª
+ * passada do `*review` da SF15.12 registrou que "`--repo=publico` medido: o
+ * git NÃO o honrou como seleção de remoto". Essa medição tinha um argumento
+ * POSICIONAL no caso de teste, que tem precedência e MASCARA o efeito de
+ * `--repo`. Sem posicional, o git honra `--repo` — remedido em duas sessões
+ * independentes (`pc-qa`, finding `F-1`, e `pc-dev` na correção). Foi essa
+ * leitura superada que justificou tratar `--repo` como valor opaco "por
+ * precaução", e era justamente ela que abria um push SILENCIOSO para um
+ * remoto DECLARADO irreversível — o desfecho que este hook existe para
+ * impedir. Nunca reintroduzir "descarta o valor de `--repo`".
+ * LIMITE RESIDUAL DECLARADO (mesma régua dos demais limites deste
+ * cabeçalho — um mecanismo nunca promete mais do que entrega): uma opção
+ * FUTURA/desconhecida do git que tome valor em token separado e não esteja
+ * no catálogo pode fazer o parser ler o VALOR como remoto. Dívida NOMEADA,
+ * fechada por atualização do catálogo — nunca por um `ask` adivinhado.
+ * Também declarado: (b) cobre `scheme://` e `user@host:path`, as 2 formas
+ * medidas no ADR-037 §1.3 — um caminho local (`/tmp/x.git`) não é tratado
+ * como URL bruta.
+ * 3º limite DECLARADO, MEDIDO (não deduzido) na implementação da SF15.12:
+ * quando o subcomando é um ALIAS, a expansão (`expandResolvedAliasAndRecurse`)
+ * reconstrói o comando como `git <corpo> <trailing>` e NÃO carrega as opções
+ * globais que vinham antes do subcomando — logo `git -C <outro-repo> z` (com
+ * `z = push`) resolve o upstream do cenário (c) no `cwd` da sessão, não no
+ * repositório de `-C`. Medido: a forma DIRETA `git -C <outro-repo> push`
+ * responde `ask` para um destino declarado, e a forma via alias responde
+ * silêncio para o MESMO destino. Vale só para o cenário (c) — remoto
+ * explícito e URL bruta são lidos do texto e não dependem de repositório —
+ * e a mesma perda já existe, desde o fix round F3, na CONSULTA do alias
+ * (`resolveGitAliasFromDisk` também usa `ctx.cwd`). Não corrigido aqui por
+ * estar fora da prescrição revisada desta story (fechá-lo mexe na expansão
+ * COMPARTILHADA entre os branches `git` e `gh`, que o F5 unificou de
+ * propósito) — dívida NOMEADA, para decisão de arquitetura, nunca uma lacuna
+ * silenciosa.
+ *
  * Sem dependências externas além do próprio `git`/`gh` (só chamados para
- * resolver alias — roda em qualquer instalação limpa mesmo sem `git`/`gh`
- * no PATH: nesse caso a consulta falha e o resultado é `ask`, não crash).
+ * resolver alias e o upstream do cenário (c) — roda em qualquer instalação
+ * limpa mesmo sem `git`/`gh` no PATH: nesse caso a consulta falha e o
+ * resultado é `ask`, não crash).
  */
 
 const fs = require('fs');
+const path = require('path');
 const { spawnSync } = require('child_process');
 
 const DEVOPS_AGENT_TYPE = 'pc-devops';
 
+// Arquivo de DECLARAÇÃO dos remotos irreversíveis (story SF15.12). Nunca
+// hardcodar nome de remoto neste fonte: quem instala o framework é o dono da
+// lista, e nomes de remoto são por repositório.
+const IRREVERSIBLE_REMOTES_FILENAME = 'irreversible-remotes.json';
+
 // Opções GLOBAIS do git que tomam um valor em token SEPARADO (quando não
 // usadas na forma `--opcao=valor`). Fonte: `git help` (seção OPTIONS).
 const GIT_GLOBAL_OPTS_WITH_ARG = new Set([
@@ -170,6 +269,21 @@ const GIT_GLOBAL_OPTS_WITH_ARG = new Set([
 // gh: opções globais mais comuns que tomam valor em token separado.
 const GH_GLOBAL_OPTS_WITH_ARG = new Set(['-R', '--repo', '--hostname']);
 
+// Opções do SUBCOMANDO `push` que tomam um valor em token SEPARADO (quando
+// não usadas na forma `--opcao=valor`) — CATÁLOGO FECHADO (story SF15.12):
+// toda opção FORA deste conjunto é flag SEM valor, que é a gramática real do
+// `git push`. Espelha `GIT_GLOBAL_OPTS_WITH_ARG` na forma e na régua. Fonte:
+// `git push --help` (seção OPTIONS). Limite residual (opção futura com valor
+// separado ausente daqui) DECLARADO no cabeçalho — nunca substituído por
+// heurística de "aparência de tomar valor", que não é decidível no parse.
+const GIT_PUSH_OPTS_WITH_ARG = new Set([
+  '-o',
+  '--push-option',
+  '--repo',
+  '--exec',
+  '--receive-pack',
+]);
+
 // Subcomandos REAIS do git (porcelana + os plumbing mais comuns) — lista de
 // custo, não de correção: um subcomando fora desta lista dispara a
 // resolução de alias (barata primeiro, subprocesso só se preciso); um
@@ -331,12 +445,31 @@ function isGhToken(tok) {
 // `inlineAliases` (Map) for passado, toda opção `-c alias.<nome>=<valor>`
 // encontrada no caminho é registrada nele — fonte MAIS BARATA de resolução
 // de alias, o próprio comando já carrega a definição.
+//
+// Story SF15.12 (`M2`): o valor de `-C`/`--git-dir` deixa de ser DESCARTADO
+// e passa a ser devolvido (`repoCwd`/`gitDir`). Nomes de remoto são por
+// REPOSITÓRIO, então a resolução de upstream do cenário (c) precisa rodar no
+// repositório que o comando de fato aponta, não no `cwd` da sessão. Opção
+// presente e NÃO utilizável (valor ausente/vazio, ou `-C` repetido — que o
+// git trata como caminhos relativos cumulativos, algo que este parser não se
+// propõe a reproduzir) marca `unusableRepoOption`, e o chamador trata isso
+// como "não deu para confirmar", nunca como "não há".
 function findGitSubcommand(tokens, gitIndex, inlineAliases) {
   let i = gitIndex + 1;
+  let repoCwd;
+  let gitDir;
+  let unusableRepoOption = false;
+  const finish = (subcommand, index) => ({
+    subcommand,
+    index,
+    repoCwd,
+    gitDir,
+    unusableRepoOption,
+  });
   while (i < tokens.length) {
     const tok = tokens[i];
     if (!tok.startsWith('-')) {
-      return { subcommand: tok, index: i };
+      return finish(tok, i);
     }
     const eqIdx = tok.indexOf('=');
     const base = eqIdx === -1 ? tok : tok.slice(0, eqIdx);
@@ -355,6 +488,16 @@ function findGitSubcommand(tokens, gitIndex, inlineAliases) {
         const aliasMatch = /^alias\.([^=\s]+)=([\s\S]*)$/.exec(value);
         if (aliasMatch) inlineAliases.set(aliasMatch[1], aliasMatch[2]);
       }
+      if (base === '-C') {
+        // `-C` repetido é cumulativo no git real; aqui vira "não utilizável".
+        if (repoCwd !== undefined) unusableRepoOption = true;
+        if (typeof value === 'string' && value) repoCwd = value;
+        else unusableRepoOption = true;
+      }
+      if (base === '--git-dir') {
+        if (typeof value === 'string' && value) gitDir = value;
+        else unusableRepoOption = true;
+      }
       continue;
     }
     // Qualquer outra flag (global conhecida sem argumento, ou desconhecida)
@@ -406,6 +549,200 @@ function isForceFlagToken(tok) {
   return false;
 }
 
+// Extrai os CANDIDATOS a repositório de destino de um `git push`, a partir
+// dos tokens que SEGUEM o subcomando (a mesma fatia que `isForceFlagToken` já
+// consome — custo zero a mais). São 2, porque o `git push` tem 2 formas de
+// dizer para onde empurrar:
+//   - `positional`  — o 1º token não-flag (`git push <repositório> <refspec>`);
+//   - `repoOption`  — o valor de `--repo <v>` / `--repo=<v>`.
+// A varredura respeita o CATÁLOGO FECHADO `GIT_PUSH_OPTS_WITH_ARG`: só opção
+// catalogada, na forma SEM `=`, consome o token seguinte; toda outra opção é
+// flag sem valor. A varredura NÃO para no 1º posicional, porque `--repo` pode
+// vir depois dele (`git push --tags --repo publico`) — quem decide a
+// precedência é o chamador, não a ordem de leitura.
+function extractPushRemoteCandidates(tokensAfterPush) {
+  let positional = null;
+  let repoOptionPresent = false;
+  let repoOptionValue;
+  let i = 0;
+  while (i < tokensAfterPush.length) {
+    const tok = tokensAfterPush[i];
+    if (!tok.startsWith('-')) {
+      if (positional === null) positional = tok;
+      i += 1;
+      continue;
+    }
+    const eqIdx = tok.indexOf('=');
+    const base = eqIdx === -1 ? tok : tok.slice(0, eqIdx);
+    // `--opcao=valor` traz o valor no PRÓPRIO token: nunca consome o seguinte.
+    if (eqIdx === -1 && GIT_PUSH_OPTS_WITH_ARG.has(base)) {
+      if (base === '--repo' && !repoOptionPresent) {
+        repoOptionPresent = true;
+        repoOptionValue = tokensAfterPush[i + 1];
+      }
+      i += 2;
+      continue;
+    }
+    if (eqIdx !== -1 && base === '--repo' && !repoOptionPresent) {
+      repoOptionPresent = true;
+      repoOptionValue = tok.slice(eqIdx + 1);
+    }
+    i += 1;
+  }
+  return { positional, repoOptionPresent, repoOptionValue };
+}
+
+// Cenário (b): o token de destino é uma URL/SSH-spec BRUTA, não um NOME de
+// remoto configurado. 2 formas, as medidas no ADR-037 §1.3: `scheme://...` e
+// o scp-like `user@host:path`. Caminho local (`/tmp/x.git`) NÃO é coberto —
+// limite declarado no cabeçalho, não omissão silenciosa.
+function looksLikeRawRemoteUrl(token) {
+  if (typeof token !== 'string' || !token) return false;
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(token)) return true;
+  if (/^[^/@:]+@[^/@:]+:/.test(token)) return true;
+  return false;
+}
+
+// Lê UM lado da união (story SF15.12). Trata por CLASSE, nunca fundindo
+// "ausente" com "ilegível" (`M1`):
+//   { status: 'absent' }              — não existe ali: resposta CONCLUSIVA
+//                                       ("nada declarado neste lado").
+//   { status: 'ok', remotes: Set }    — lido e bem formado.
+//   { status: 'malformed' }           — presente e ilegível (JSON quebrado,
+//                                       `remotes` não-array, entrada
+//                                       não-string, leitura impossível) —
+//                                       "não sei", nunca "não há".
+function readIrreversibleRemotesFile(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    const code = err && err.code;
+    // ENOENT/ENOTDIR = o arquivo não está lá (conclusivo). Qualquer outro
+    // erro (permissão, EISDIR, ...) é "existe algo que não consegui ler".
+    if (code === 'ENOENT' || code === 'ENOTDIR') return { status: 'absent' };
+    return { status: 'malformed' };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { status: 'malformed' };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { status: 'malformed' };
+  }
+  if (!Array.isArray(parsed.remotes)) return { status: 'malformed' };
+  if (!parsed.remotes.every((entry) => typeof entry === 'string')) {
+    return { status: 'malformed' };
+  }
+  return { status: 'ok', remotes: new Set(parsed.remotes) };
+}
+
+// UNIÃO dos 2 lados: o arquivo que viaja junto do hook (`__dirname`) e o da
+// instalação viva cuja sessão executa o push (`input.cwd`). A união só
+// ALARGA o conjunto de `ask` — nunca substitui um lado pelo outro, nunca
+// interseciona. Lado ausente não contribui; lado malformado contamina o
+// resultado inteiro com `malformed` (fail-loud).
+function loadIrreversibleRemotes(cwd) {
+  const candidates = [path.join(__dirname, IRREVERSIBLE_REMOTES_FILENAME)];
+  if (typeof cwd === 'string' && cwd) {
+    candidates.push(path.join(cwd, '.claude', 'hooks', IRREVERSIBLE_REMOTES_FILENAME));
+  }
+  const remotes = new Set();
+  let malformed = false;
+  for (const candidate of candidates) {
+    const side = readIrreversibleRemotesFile(candidate);
+    if (side.status === 'ok') {
+      for (const name of side.remotes) remotes.add(name);
+    } else if (side.status === 'malformed') {
+      malformed = true;
+    }
+  }
+  return { remotes, malformed };
+}
+
+// Resolve o remoto do UPSTREAM da branch corrente (cenário (c)), no
+// repositório que o comando de fato aponta (`-C`/`--git-dir`, `M2`), com o
+// mesmo padrão de subprocesso já usado na resolução de alias (timeout curto,
+// stdin fechado, try/catch). `@{u}` sai como `<remoto>/<branch>`; o nome do
+// remoto é o 1º segmento.
+//   { status: 'found', remote }  — resolvido com segurança.
+//   { status: 'error' }          — sem upstream, fora de repositório, git
+//                                  ausente, timeout: "não deu para confirmar".
+function resolveUpstreamRemote(cwd, gitDir) {
+  try {
+    const args = [];
+    if (typeof gitDir === 'string' && gitDir) args.push(`--git-dir=${gitDir}`);
+    args.push('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}');
+    const result = spawnSync('git', args, {
+      cwd: cwd || process.cwd(),
+      encoding: 'utf8',
+      timeout: 800,
+      input: '',
+    });
+    if (result.error || result.status !== 0) return { status: 'error' };
+    const value = (result.stdout || '').trim();
+    const slash = value.indexOf('/');
+    if (slash <= 0) return { status: 'error' };
+    return { status: 'found', remote: value.slice(0, slash) };
+  } catch {
+    return { status: 'error' };
+  }
+}
+
+// A lista é lida NO MÁXIMO 1 vez por invocação inteira (cacheada em `ctx`,
+// mesma disciplina de custo de `ctx.ghAliasCache`), e só depois de um
+// segmento ser reconhecido como `git push` não-force (`M4`).
+function getIrreversibleRemotes(ctx) {
+  if (!ctx.irreversibleRemotesCache) {
+    ctx.irreversibleRemotesCache = loadIrreversibleRemotes(ctx.cwd);
+  }
+  return ctx.irreversibleRemotesCache;
+}
+
+// O predicado do `I4`: este segmento de `git push` (já sabidamente não-force)
+// tem destino irreversível ou não-confirmável? Ver os cenários (a)/(b)/(c) no
+// cabeçalho. Toda dúvida resolve para `true` — "não sei" nunca vira "sei que
+// não é", a mesma doutrina do `unresolved-alias`.
+function isPushToIrreversibleRemote(tokensAfterPush, found, ctx) {
+  const declared = getIrreversibleRemotes(ctx);
+  if (declared.malformed) return true; // `M1`: fail-loud, nunca silêncio
+
+  const { positional, repoOptionPresent, repoOptionValue } = extractPushRemoteCandidates(tokensAfterPush);
+
+  // PRECEDÊNCIA, MEDIDA contra o git real (2.50.1), nunca deduzida — ver o
+  // cabeçalho: o argumento POSICIONAL vence `--repo`. `git push --repo publico
+  // main` faz o git tratar `main` como repositório (`fatal: 'main' does not
+  // appear to be a git repository`), e `git push --repo publico origin main`
+  // alcança `origin`. Só quando NÃO há posicional é que `--repo` seleciona o
+  // destino de fato — e aí ele precisa receber (a)/(b) como qualquer remoto.
+  let remoteToken = positional;
+  if (remoteToken === null && repoOptionPresent) {
+    // `--repo` presente mas sem valor utilizável (ausente, vazio, ou outra
+    // flag no lugar do valor) é "não sei para onde isto vai", nunca "não há".
+    if (typeof repoOptionValue !== 'string' || !repoOptionValue || repoOptionValue.startsWith('-')) {
+      return true;
+    }
+    remoteToken = repoOptionValue;
+  }
+
+  if (remoteToken === null) {
+    // (c) nenhum argumento de remoto explícito: só o upstream pode dizer
+    // para onde isto vai.
+    if (found.unusableRepoOption) return true;
+    const repoCwd = found.repoCwd
+      ? path.resolve(ctx.cwd || process.cwd(), found.repoCwd)
+      : ctx.cwd;
+    const upstream = resolveUpstreamRemote(repoCwd, found.gitDir);
+    if (upstream.status !== 'found') return true;
+    return declared.remotes.has(upstream.remote);
+  }
+
+  if (looksLikeRawRemoteUrl(remoteToken)) return true; // (b)
+  return declared.remotes.has(remoteToken); // (a) — a LISTA decide
+}
+
 // Consulta `git config --get alias.<nome>` no repositório de `cwd` — a
 // fonte MAIS CARA de resolução de alias do `git` (subprocesso síncrono),
 // só chamada quando as 2 fontes baratas (inline `-c`, `git config alias.X`
@@ -647,8 +984,19 @@ function analyzeSegment(segment, ctx, depth) {
     const found = findGitSubcommand(tokens, gitIndex, inlineAliases);
     if (found) {
       if (found.subcommand === 'push') {
-        const isForce = tokens.slice(found.index + 1).some(isForceFlagToken);
-        return { kind: isForce ? 'force-push' : 'git-push' };
+        const afterPush = tokens.slice(found.index + 1);
+        if (afterPush.some(isForceFlagToken)) return { kind: 'force-push' };
+        // Story SF15.12 (`B2`): o destino irreversível vira um `kind` PRÓPRIO
+        // AQUI, no momento em que o SEGMENTO é reconhecido — nunca um campo
+        // lido depois da agregação por severidade, que devolve UMA operação e
+        // faria o 2º push de uma cadeia (`git push origin main && git push
+        // publico main`) simplesmente sumir. `M4`: é este o único ponto em que
+        // a lista é lida e o `git rev-parse` pode ser chamado.
+        return {
+          kind: isPushToIrreversibleRemote(afterPush, found, ctx)
+            ? 'git-push-irreversible'
+            : 'git-push',
+        };
       }
       if (!KNOWN_GIT_SUBCOMMANDS.has(found.subcommand)) {
         const trailing = tokens.slice(found.index + 1);
@@ -712,8 +1060,16 @@ function analyzeSegment(segment, ctx, depth) {
 // (force-push > merge > alias não resolvido > push/pr create), para não
 // deixar passar em silêncio um comando composto que contenha uma operação
 // governada em qualquer posição da cadeia.
+// `git-push-irreversible` = 3.5: estritamente ENTRE `git-push` (1) e
+// `force-push` (4), e acima de `unresolved-alias` (2) e `gh-pr-merge` (3) —
+// assim, numa cadeia, o destino irreversível nunca perde para uma operação
+// menos severa, e SEMPRE perde para force-push (o `ask` novo jamais rebaixa
+// um `deny`, por construção da ordem). Fracionário de propósito: um inteiro
+// exigiria renumerar as 4 entradas existentes, com risco de regressão, sem
+// necessidade — `SEVERITY` é comparada por `>`, não por adjacência.
 const SEVERITY = {
   'force-push': 4,
+  'git-push-irreversible': 3.5,
   'gh-pr-merge': 3,
   'unresolved-alias': 2,
   'git-push': 1,
@@ -727,6 +1083,9 @@ function findGovernedOperation(command, cwd) {
     gitSessionAliases: collectSessionAliases(segments),
     ghSessionAliases: collectGhSessionAliases(segments),
     ghAliasCache: { loaded: false, map: null, failed: false },
+    // Preenchido sob demanda por `getIrreversibleRemotes` — nunca aqui, para
+    // que nenhum `Bash` que não contenha `git push` pague leitura de arquivo.
+    irreversibleRemotesCache: null,
   };
   let best = null;
   for (const segment of segments) {
@@ -778,6 +1137,19 @@ function decideAndEmit(operation, input) {
     return;
   }
 
+  if (operation.kind === 'git-push-irreversible') {
+    // Story SF15.12 (`I4` do ADR-037): destino declarado irreversível, URL
+    // bruta, ou destino que não deu para confirmar. `ask` INCONDICIONAL —
+    // inclusive para `pc-devops`, mesma forma que `gh pr merge` já tem. O
+    // `allow` silencioso de `git push` foi calibrado para um remoto privado e
+    // recuperável; um remoto público não o herda.
+    emitDecision(
+      'ask',
+      `O destino deste push é um remoto declarado irreversível, uma URL bruta, ou um destino que não foi possível confirmar (nenhum remoto explícito e upstream irresolúvel, ou lista de remotos ilegível). Aprovação humana explícita é necessária, inclusive para o papel devops. Agente atual: ${agentLabel(input)}.`,
+    );
+    return;
+  }
+
   if (operation.kind === 'unresolved-alias') {
     // Subcomando de git OU gh desconhecido que PODE ser alias — ou a
     // consulta (`git config --get`/`gh alias list`) não pôde ser concluída
@@ -900,7 +1272,15 @@ module.exports = {
   DEVOPS_AGENT_TYPE,
   KNOWN_GIT_SUBCOMMANDS,
   KNOWN_GH_SUBCOMMANDS,
+  GIT_PUSH_OPTS_WITH_ARG,
+  IRREVERSIBLE_REMOTES_FILENAME,
   ALIAS_MAX_DEPTH,
+  extractPushRemoteCandidates,
+  looksLikeRawRemoteUrl,
+  readIrreversibleRemotesFile,
+  loadIrreversibleRemotes,
+  resolveUpstreamRemote,
+  isPushToIrreversibleRemote,
   tokenize,
   splitSegments,
   isGitToken,

package/template/.claude/hooks/irreversible-remotes.json

@@ -0,0 +1 @@
+{"remotes": []}

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

@@ -43,7 +43,7 @@ Um gatilho pode ser **condicional a outro papel**: ex.: architect aciona só se
 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).
+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** — o processo em si PODE sobreviver ao fim do turno; o que **não sobrevive ao fim do turno** é a COLHEITA: a capacidade do agente de ler, verificar e reportar o resultado. O que não for colhido DENTRO do mesmo turno se perde — inclusive um trabalho que terminou verde e que ninguém viu —, e o brief nunca instrui um papel a esperar por ele (`DF-SF13.4-1`). **Leitura superada, não repetir:** a formulação anterior desta cláusula ("background não sobrevive ao fim do turno que o lançou") afirmava mais do que a fonte citada sustenta, e a própria fonte prova o contrário — em `docs/stories/release-0.16.1.story.md` (Dev Agent Record → Desvios registrados) a suíte lançada em background "continuou rodando o tempo todo e terminou verde"; o que morreu com o turno foi o monitor que iria colhê-la (corrigido reexecutando em foreground). A regra prática não muda: não se espera por background: colhe-se dentro do turno, ou não se lança. 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`) + a ocorrência viva acima; correção da cláusula pela story `chore-miudos-pos-sf13` (`FINDING-1` do gate `SF13.4`, registrado no épico `:171`).
 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`)
@@ -115,6 +115,7 @@ Nasceu de **7 erros da mesma classe numa única sessão** (2026-08-06/07), todos
 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`.
+8. **Duas stories na mesma branch: a 2ª a ser verificada reconfere as âncoras de linha que cita** em arquivos já tocados pela 1ª — **identidade de CONTEÚDO não implica identidade de POSIÇÃO**, e um `path:linha` correto quando a story foi escrita já aponta para outra linha depois do commit da irmã. Agrupar é decisão legítima de orquestração, mas tem esse custo: quem agrupa nomeia no brief os arquivos que as duas dividem, e a 2ª reconfere antes de citar. Origem: `FINDING-2` do gate `SF13.6` (`docs/qa/gates/sf13.6-fechamento-por-declaracao.yaml`), onde um mesmo agrupamento produziu 2 defeitos de classes diferentes — um AC que media `main...HEAD` passou a medir trabalho alheio (nomeado pelo dev) e as âncoras de linha da story irmã envelheceram (não mapeado por ninguém).
 
 ## Memória de papel — o caminho é curadoria humana, não pipeline (`DF-SF12.3-7`)