@fontdata/ai-harness 2.0.0 → 2.1.0

package/templates/commands/configurar-comentarios.md

@@ -1,543 +0,0 @@
----
-description: Instala o padrão de comentários do projeto (comentar o "porquê" com orçamento duro, em qualquer linguagem inclusive Delphi/Pascal) — rule, bloco no CLAUDE.md e hook bloqueante com catraca sobre o legado.
----
-
-# /configurar-comentarios — Padrão de comentários (porquê, com orçamento)
-
-Você vai **instalar o padrão de comentários** deste projeto, em três camadas que se reforçam:
-
-1. **A rule** `.claude/rules/comentarios.md` — o guia completo, com orçamento e contra-exemplos.
-2. **O bloco no `CLAUDE.md`** da raiz — **autossuficiente** (não é um ponteiro), com `@import` da rule.
-3. **O hook** `.claude/hooks/comentarios/check.mjs` — `PostToolUse` bloqueante, com **catraca** sobre o
-   código legado.
-
-Como tudo fica **versionado no projeto**, qualquer clone já vem com o padrão configurado — sem depender de
-configuração global de cada máquina.
-
-> **Por que três camadas.** A versão anterior deste comando só instalava a rule e um ponteiro no fim do
-> `CLAUDE.md`. Em produção isso falhou: a rule mandava "comentar o porquê" **sem nenhum teto**, e os
-> sub-agents produziram arquivos com 38% a 59% de linhas de comentário — blocos de 10 a 25 linhas narrando
-> investigação, medição e histórico de task. Formalmente era "o porquê"; na prática era ilegível. Regra sem
-> orçamento, sem contra-exemplo e sem enforcement não segura nada.
-
-> **🚦 Há um GATE de aprovação obrigatório** antes de gravar qualquer arquivo. Este comando **não faz commit
-> nem push**.
-
-## Uso
-
-- `/configurar-comentarios` — instala/atualiza as três camadas neste projeto.
-
-## Passo 0 — Pré-checagem (somente leitura)
-
-1. Alvos deste comando (escopo **projeto**):
-   - rule → `.claude/rules/comentarios.md`
-   - context file → `CLAUDE.md` na raiz
-   - hook → `.claude/hooks/comentarios/check.mjs`
-   - registro do hook → `.claude/settings.json`
-   - catraca → `.claude/hooks/comentarios/baseline.json` (gerado no Passo 6)
-2. Verifique o que **já existe**. Se houver rule ou bloco antigos, trate como **atualização** (reconcilie
-   no lugar), nunca como duplicação.
-3. Verifique se `.claude/settings.json` já existe e **quais hooks ele já registra** — o Passo 5 faz *merge*,
-   nunca sobrescreve.
-4. Detecte se o projeto usa Prettier/formatador em `.md`. Não é bloqueante: o conteúdo da rule abaixo já
-   vem com os exemplos dentro de code fences justamente para sobreviver à formatação.
-
-## Passo 1 — Rascunhar a rule (sem gravar ainda)
-
-Prepare o conteúdo de `.claude/rules/comentarios.md` exatamente como abaixo:
-
-````markdown
-# Estilo de comentários (todas as linguagens)
-
-IMPORTANT: o padrão é **não comentar**. Comentário é exceção que precisa se justificar.
-
-Antes de escrever qualquer comentário, responda:
-**"quem editar esta linha daqui a 6 meses quebra o sistema sem esta informação?"**
-Se a resposta não for um "sim" claro, **não comente**.
-
-## Orçamento (limites duros)
-
-| Item | Limite |
-|---|---|
-| Bloco de comentário interno | **3 linhas** |
-| Docstring de função/método público | **5 linhas** |
-| Cabeçalho de arquivo | **proibido** |
-| Comentários internos por função | **1** |
-| Densidade do arquivo | **<= 10%** das linhas |
-
-Se o porquê não cabe em 3 linhas, **ele não pertence ao código**.
-
-## Proibido
-
-1. **Banner/separador de seção** — `// ─── X ───`, `// ==== SEÇÃO ====`, `// ---- X ----`.
-   Arquivo que precisa de seções precisa ser **dividido**, não decorado.
-2. **Rastreabilidade de processo** — `Task 4.2.1`, `Fase 2`, `Plano 006`, `T2.1`, `SPEC 001`,
-   `docs/plans/...`, `achado do @code-reviewer`, `commit c83bb4e0`, `bug de 2026-07-16`.
-   O git e `docs/` já guardam isso; no código vira lixo em três meses.
-3. **Narração do passo a passo** — `// Carrega o usuário`, `// Verifica se existe`, `// Monta o payload`.
-4. **Redundância com o identificador** — `// Mapa de nó por id` acima de `const nodeMap = new Map()`.
-5. **Ensaio/investigação** — medição, histórico do bug, o que foi tentado, o que foi rejeitado.
-   Isso vive em `docs/investigacoes/`, não no código.
-6. **Ênfase tipográfica** — CAPS-LOCK (`NUNCA`, `IMPOSSÍVEL`), emoji, `⚠️ REGRA DE OURO`.
-7. **Código comentado** — apague; o git guarda.
-
-## Permitido (lista fechada)
-
-- **Contrato não óbvio** de função/método público — docstring de até 5 linhas.
-- **Armadilha real**: por que a abordagem óbvia quebra — até 3 linhas, **no presente**, sem contar a história.
-- **`TODO:` / `FIXME:`** com o motivo real — 1 linha.
-- **Referência externa** (RFC, issue da lib, doc de API) que justifica um workaround — 1 linha.
-
-## Para onde vai cada informação
-
-| Informação | Onde mora | Nunca em |
-|---|---|---|
-| Por que a mudança foi feita | mensagem de commit | comentário |
-| Task / fase / plano / spec | `docs/plans/`, `docs/specs/` | comentário |
-| Diagnóstico e correção de um defeito | `docs/bugs/` | comentário |
-| Investigação, medição, auditoria, paridade, comparação | `docs/investigacoes/` | comentário, `docs/bugs/` |
-| Achado de review | resposta do review, commit | comentário |
-| Decisão de arquitetura | `SPEC.md` | comentário |
-| Armadilha ao editar **aquela linha** | comentário de até 3 linhas | — |
-
-**Bug ou investigação?** Só vai para `docs/bugs/` o que tem os três: sintoma reproduzível,
-causa-raiz identificada e correção aplicada no código. Se falta qualquer um — é auditoria,
-paridade com legado, medição, comparação, levantamento, handoff ou follow-up — vai para
-`docs/investigacoes/`. Se o documento descreve trabalho a fazer em vez de defeito apurado,
-vai para `docs/plans/`.
-
-Convenção de nome em ambas: `<yyyy-mm-dd>-<slug>.md`.
-
-## Antes e depois
-
-**1. Ensaio de investigação → armadilha objetiva**
-
-```ts
-// ANTES (7 linhas: medição, histórico e ênfase)
-// Timeout PRÓPRIO (independente do timeout global de query do Baileys) para a busca
-// da foto de perfil no recebimento. Medição real: com o timeout global em 60000ms,
-// todo recebimento de contato LID (que não responde à query w:profile:picture)
-// travava por ~60s; baixando para 15000ms o atraso caiu para 15.001ms — proporcional
-// ao milissegundo. A foto é cosmética e NUNCA pode bloquear o recebimento; default
-// SEGURO e curto, sem depender de NODE_ENV.
-PROFILE_PIC_TIMEOUT_MS: z.coerce.number().default(3000),
-
-// DEPOIS (2 linhas: só o que quebra ao editar esta linha)
-// Contato LID nunca responde a essa query e a foto é cosmética — subir este timeout
-// volta a travar o recebimento de mensagem.
-PROFILE_PIC_TIMEOUT_MS: z.coerce.number().default(3000),
-```
-
-**2. Cabeçalho de arquivo → nada**
-
-```ts
-// ANTES (49 linhas antes do primeiro import)
-/**
- * Task 1.3.4 / Task 2.3.7 — AgentFlowExecutor
- *
- * Orquestra a execução de um AgentRun:
- *   1. Carrega AgentRun escopado por id + companyId (multi-tenant)
- *   2. Adquire lock por ticket
- *   ...
- * GRAFO DINÂMICO (Fase 2):
- * ROTEAMENTO POR builderMode (Plano 006 — modo simples, T2.1):
- */
-import { ... }
-
-// DEPOIS
-import { ... }
-```
-
-O nome do arquivo, os exports e a assinatura pública já dizem o que ele é. A ordem dos passos está no
-código; a história está no git.
-
-**3. Banner + narração → código legível**
-
-```ts
-// ANTES
-// ── 1. Carrega AgentRun escopado por id + companyId ─────────────────
-const run = await AgentRun.findOne({ where: { id, companyId } });
-// ── 2. Adquire lock por ticket ──────────────────────────────────────
-const lock = await acquireTicketLock(companyId, ticketId);
-
-// DEPOIS
-const run = await AgentRun.findOne({ where: { id, companyId } });
-const lock = await acquireTicketLock(companyId, ticketId);
-```
-
-**4. Docstring inflada → contrato**
-
-```ts
-// ANTES (12 linhas)
-/**
- * Gera um novo par de chaves de API para a empresa.
- * Task 7.3.1. Esta função foi criada no plano de 2026-07-28 depois que o
- * @code-reviewer apontou que a chave estava sendo salva em texto puro.
- * Primeiro gera bytes aleatórios, depois deriva o hash SHA-256, e por fim
- * ...
- */
-
-// DEPOIS (4 linhas)
-/**
- * Gera um par (plainKey, keyHash).
- * - plainKey: devolvido UMA única vez ao chamador, nunca persistido
- * - keyHash: o que vai para o banco
- */
-```
-
-## Sintaxe por linguagem
-
-```ts
-/**
- * Uma linha de propósito; entradas/saídas só quando não são óbvias.
- */
-export function hashApiKey(plainKey: string): string {}
-```
-
-```pascal
-/// <summary>
-///   Gera o hash SHA-256 de uma API Key.
-/// </summary>
-function HashApiKey(const APlainKey: string): string;
-```
-
-- **TypeScript/JavaScript/Java/C#/C++/Go/Rust/PHP:** `/** ... */` no topo do símbolo **público**.
-- **Python:** docstring `"""..."""` curta logo abaixo da assinatura.
-- **Delphi/Pascal:** `///` (XMLDoc) nas rotinas públicas da `interface`; nunca repetir na `implementation`.
-- **SQL/Shell/YAML:** somente regra de negócio ou pegadinha não evidente.
-
-## Enforcement
-
-O hook `.claude/hooks/comentarios/check.mjs` roda a cada `Write`/`Edit` e **bloqueia** banner, rastreabilidade
-de processo, data, cabeçalho de arquivo, código comentado e bloco acima do teto.
-
-Arquivos que já existiam quando o padrão foi instalado estão em
-`.claude/hooks/comentarios/baseline.json` (catraca): eles **não precisam ser limpos de uma vez**, só não
-podem piorar. Quando melhoram, a catraca desce e não volta.
-````
-
-## Passo 2 — Rascunhar o bloco do CLAUDE.md (sem gravar ainda)
-
-O bloco é **autossuficiente** — quem só ler o `CLAUDE.md` já sabe o que fazer sem abrir a rule. Ele vai
-logo **após a seção "Padrões de código"** (ou, se ela não existir, após "Stack"). **Não** no fim do arquivo.
-
-````markdown
-## Comentários em código
-
-IMPORTANT: o padrão é **não comentar**. Comentário é exceção que precisa se justificar — em qualquer
-linguagem, incluindo Delphi/Pascal. Antes de comentar: *"quem editar esta linha daqui a 6 meses quebra o
-sistema sem esta informação?"* Se não for um "sim" claro, não comente.
-
-**Orçamento:** bloco interno <= 3 linhas · docstring pública <= 5 linhas · cabeçalho de arquivo proibido ·
-1 comentário interno por função · densidade <= 10% do arquivo.
-Se o porquê não cabe em 3 linhas, ele não pertence ao código.
-
-**Proibido:** banner/separador (`// ─── X ───`) · task/fase/plano/spec/data/hash de commit/achado de review
-· narração do passo a passo · redundância com o nome do identificador · ensaio de investigação · CAPS-LOCK
-e emoji · código comentado.
-
-**Onde a informação mora:** por que a mudança foi feita → mensagem de commit · task/plano → `docs/plans/` ·
-correção de defeito → `docs/bugs/` · investigação, medição e auditoria → `docs/investigacoes/` ·
-decisão de arquitetura → `SPEC.md`. No código, só a armadilha que quebra ao editar aquela linha.
-
-Enforcement: `.claude/hooks/comentarios/check.mjs` bloqueia no `Write`/`Edit`. Legado tem catraca em
-`.claude/hooks/comentarios/baseline.json` — não precisa ser limpo de uma vez, mas não pode piorar.
-
-@.claude/rules/comentarios.md
-````
-
-Se o `CLAUDE.md` não existir na raiz, avise que ele será **criado** só com esse bloco — e confirme se é isso
-que o usuário quer, ou se prefere rodar antes o `/gerar-claude-md`.
-
-## Passo 3 — Rascunhar o hook (sem gravar ainda)
-
-Conteúdo de `.claude/hooks/comentarios/check.mjs`:
-
-```js
-#!/usr/bin/env node
-import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
-import { extname, relative, join, dirname } from 'node:path';
-
-const MAX_BLOCO = Number(process.env.COMENTARIOS_MAX_BLOCO ?? 3);
-const MAX_DOCSTRING = Number(process.env.COMENTARIOS_MAX_DOCSTRING ?? 5);
-const DENSIDADE_ALVO = 0.1;
-
-const EXTENSOES = new Set([
-  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
-  '.py', '.go', '.rs', '.java', '.cs', '.php',
-  '.pas', '.dpr', '.sql', '.sh',
-]);
-
-const IGNORAR = [
-  /node_modules/,
-  /[\\/]\.git[\\/]/,
-  /[\\/](dist|build|coverage|out|\.next|\.nuxt|vendor|migrations|generated|__generated__)[\\/]/,
-  /\.d\.ts$/,
-  /\.(test|spec)\.[jt]sx?$/,
-];
-
-const CABECALHO_PERMITIDO =
-  /eslint|ts-nocheck|ts-ignore|prettier|@license|copyright|spdx|jshint|globals|^#!|use (strict|client|server)/i;
-
-const BANNER = /^[-=─-╿_*#~+]{3,}|[-=─-╿_*#~+]{3,}$/;
-
-const RASTREIO = [
-  [/\b(task|tarefa|fase|etapa|plano|spec|sprint|epico|épico)\s*[\dIVX]/i, 'referência a task/fase/plano/spec'],
-  [/\bT\d+(\.\d+)+\b/, 'referência a task (T0.0)'],
-  [/docs\/(plans|specs|bugs|investigacoes)\//i, 'caminho de docs/ dentro do código'],
-  [/\bachado d[oe]\b/i, 'achado de review no código'],
-  [/@[\w-]*(reviewer|auditor|orquestrador|agent)\b/i, 'menção a agent no código'],
-  [/\b(commit|sha|hash)\s+[0-9a-f]{7,40}\b/i, 'hash de commit'],
-];
-
-const DATA = /(^|[^"'\w])20\d{2}-\d{2}-\d{2}([^"'\w]|$)/;
-const CODIGO_TOKEN = /(^|\s)(const|let|var|function|return|if|for|while|await|import|export|def|class)\b/;
-const CODIGO_FIM = /[;{}]\s*$/;
-
-function comentario(linha, ext) {
-  const t = linha.trim();
-  if (!t) return null;
-  if (ext === '.py' || ext === '.sh') return t.startsWith('#') ? t.replace(/^#+/, '').trim() : null;
-  if (ext === '.sql') {
-    if (t.startsWith('--')) return t.replace(/^-+/, '').trim();
-    if (t.startsWith('/*') || t.startsWith('*')) return t.replace(/^[/*]+/, '').trim();
-    return null;
-  }
-  if (ext === '.pas' || ext === '.dpr') {
-    if (t.startsWith('//')) return t.replace(/^\/+/, '').trim();
-    if (t.startsWith('(*')) return t.replace(/^\(\*/, '').trim();
-    if (t.startsWith('{') && !t.startsWith('{$')) return t.replace(/^\{/, '').trim();
-    return null;
-  }
-  if (t.startsWith('//')) return t.replace(/^\/+/, '').trim();
-  if (t.startsWith('/*')) return t.replace(/^\/\*+/, '').trim();
-  if (t.startsWith('*')) return t.replace(/^\*+\/?/, '').trim();
-  return null;
-}
-
-function analisar(caminho, fonte) {
-  const ext = extname(caminho);
-  const linhas = fonte.split('\n');
-  const achados = [];
-  const marca = (linha, msg) => achados.push({ linha, msg });
-  const ehComentario = linhas.map((l) => comentario(l, ext));
-
-  let primeiroCodigo = -1;
-  for (let i = 0; i < linhas.length; i++) {
-    if (ehComentario[i] === null && linhas[i].trim()) { primeiroCodigo = i; break; }
-  }
-
-  let i = 0;
-  while (i < linhas.length) {
-    if (ehComentario[i] === null) { i++; continue; }
-    const inicio = i;
-    const conteudo = [];
-    while (i < linhas.length && ehComentario[i] !== null) { conteudo.push(ehComentario[i]); i++; }
-    const fim = i - 1;
-    const corpo = conteudo.filter(Boolean);
-    const texto = corpo.join(' ');
-
-    for (let k = 0; k < conteudo.length; k++) {
-      if (conteudo[k] && BANNER.test(conteudo[k])) {
-        marca(inicio + k + 1, 'separador/banner decorativo — divida o arquivo em vez de decorá-lo');
-        break;
-      }
-    }
-    for (const [re, motivo] of RASTREIO) {
-      if (re.test(texto)) { marca(inicio + 1, `${motivo} — isso mora no commit ou em docs/, não no código`); break; }
-    }
-    if (DATA.test(texto)) marca(inicio + 1, 'data de mudança no comentário — o git já registra isso');
-    for (let k = 0; k < conteudo.length; k++) {
-      if (conteudo[k] && CODIGO_TOKEN.test(conteudo[k]) && CODIGO_FIM.test(conteudo[k])) {
-        marca(inicio + k + 1, 'código comentado — apague, o git guarda');
-        break;
-      }
-    }
-
-    let proxima = fim + 1;
-    while (proxima < linhas.length && !linhas[proxima].trim()) proxima++;
-    const ehDocstring =
-      /^(\/\*\*|"""|'''|\/\/\/)/.test(linhas[inicio].trim()) &&
-      proxima < linhas.length &&
-      ehComentario[proxima] === null;
-    const teto = ehDocstring ? MAX_DOCSTRING : MAX_BLOCO;
-    if (corpo.length > teto) {
-      marca(inicio + 1, `bloco de ${corpo.length} linhas (teto ${teto}) — mova o rationale para o commit ou docs/`);
-    }
-
-    // `ehDocstring` exclui o caso do primeiro símbolo do arquivo já vir documentado:
-    // isso é docstring do símbolo, não cabeçalho.
-    if (primeiroCodigo !== -1 && inicio < primeiroCodigo && !ehDocstring && !CABECALHO_PERMITIDO.test(texto)) {
-      marca(inicio + 1, 'cabeçalho de arquivo — proibido; o nome do arquivo e os exports já dizem o que ele é');
-    }
-  }
-
-  const comentadas = ehComentario.filter((c) => c !== null).length;
-  const uteis = linhas.filter((l) => l.trim()).length;
-  return { achados, comentadas, uteis, densidade: uteis ? comentadas / uteis : 0 };
-}
-
-function elegivel(caminho) {
-  return EXTENSOES.has(extname(caminho)) && !IGNORAR.some((re) => re.test(caminho));
-}
-
-const raiz = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const BASELINE = join(raiz, '.claude', 'hooks', 'comentarios', 'baseline.json');
-
-function varrer(dir, saida = []) {
-  let itens;
-  try { itens = readdirSync(dir, { withFileTypes: true }); } catch { return saida; }
-  for (const item of itens) {
-    const cheio = join(dir, item.name);
-    if (item.isDirectory()) {
-      if (item.name === 'node_modules' || item.name === '.git') continue;
-      if (IGNORAR.some((re) => re.test(`${cheio}/`))) continue;
-      varrer(cheio, saida);
-    } else if (elegivel(cheio)) saida.push(cheio);
-  }
-  return saida;
-}
-
-if (process.argv.includes('--gerar-baseline')) {
-  const mapa = {};
-  let arquivos = 0;
-  let violacoes = 0;
-  for (const f of varrer(raiz)) {
-    let fonte;
-    try { fonte = readFileSync(f, 'utf8'); } catch { continue; }
-    const { achados } = analisar(f, fonte);
-    if (achados.length > 0) { mapa[relative(raiz, f)] = achados.length; arquivos++; violacoes += achados.length; }
-  }
-  if (!existsSync(dirname(BASELINE))) mkdirSync(dirname(BASELINE), { recursive: true });
-  writeFileSync(BASELINE, `${JSON.stringify(mapa, null, 2)}\n`);
-  console.log(`[comentarios] baseline gravado: ${arquivos} arquivos legados, ${violacoes} violações toleradas.`);
-  console.log('[comentarios] arquivo novo responde ao padrão cheio; legado só não pode piorar.');
-  process.exit(0);
-}
-
-if (process.env.COMENTARIOS_CHECK === 'off') process.exit(0);
-
-let payload = null;
-try { payload = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
-const caminho = payload?.tool_input?.file_path;
-if (!caminho || !elegivel(caminho)) process.exit(0);
-
-let fonte;
-try { fonte = readFileSync(caminho, 'utf8'); } catch { process.exit(0); }
-
-const { achados, comentadas, uteis, densidade } = analisar(caminho, fonte);
-const chave = relative(raiz, caminho);
-const rel = !chave || chave.startsWith('..') ? caminho : chave;
-
-let baseline = null;
-try { baseline = JSON.parse(readFileSync(BASELINE, 'utf8')); } catch {}
-const tolerado = baseline?.[chave] ?? 0;
-
-if (achados.length <= tolerado) {
-  if (baseline && tolerado > 0 && achados.length < tolerado) {
-    if (achados.length === 0) delete baseline[chave];
-    else baseline[chave] = achados.length;
-    try { writeFileSync(BASELINE, `${JSON.stringify(baseline, null, 2)}\n`); } catch {}
-    console.error(`[comentarios] ${rel}: ${tolerado} → ${achados.length} violações. Catraca desceu — não pode mais subir.`);
-  } else if (achados.length === 0 && densidade > DENSIDADE_ALVO) {
-    console.error(`[comentarios] aviso: ${rel} tem ${(densidade * 100).toFixed(0)}% de linhas de comentário (${comentadas}/${uteis}), alvo <= ${DENSIDADE_ALVO * 100}%.`);
-  }
-  process.exit(0);
-}
-
-const lista = achados.sort((a, b) => a.linha - b.linha).map((a) => `  ${rel}:${a.linha}  ${a.msg}`);
-const contexto =
-  tolerado > 0
-    ? `Este arquivo é legado: a baseline tolera ${tolerado} violação(ões) e agora há ${achados.length}. Não é preciso limpar o arquivo inteiro — basta não piorá-lo.`
-    : 'Este arquivo não tem tolerância na baseline: vale o padrão cheio.';
-
-console.error(
-  [
-    `[comentarios] ${rel} viola a rule .claude/rules/comentarios.md:`,
-    '',
-    ...lista,
-    '',
-    contexto,
-    'Tetos: bloco interno <= 3 linhas, docstring pública <= 5, cabeçalho de arquivo proibido.',
-    'Task/plano/data/achado de review e rationale longo vão para a mensagem de commit ou docs/ — nunca para o código.',
-    'Corrija no próprio arquivo antes de continuar a task.',
-  ].join('\n'),
-);
-process.exit(2);
-```
-
-E o registro em `.claude/settings.json` (**merge**, preservando o que já existir):
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit",
-        "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/comentarios/check.mjs\"" }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Passo 4 — 🚦 GATE de aprovação (obrigatório)
-
-Antes de escrever qualquer arquivo, mostre ao usuário:
-
-- os **caminhos exatos** que serão tocados (rule, `CLAUDE.md`, hook, `settings.json`);
-- o **conteúdo completo** da rule e do bloco do `CLAUDE.md`;
-- o `settings.json` **resultante do merge** (não só o trecho novo), se o arquivo já existia;
-- o que **já existia** (portanto é atualização, não criação).
-
-**Peça aprovação explícita.** Não grave nada sem o "ok".
-
-## Passo 5 — Gravar os artefatos (somente após aprovação)
-
-1. `.claude/rules/comentarios.md` (criando `.claude/rules/` se necessário).
-2. Bloco "Comentários em código" no `CLAUDE.md`, **após "Padrões de código"** — sem duplicar: se já houver
-   um bloco equivalente (inclusive o formato antigo, que terminava em `Ver detalhes em ...`), **substitua-o
-   no lugar**.
-3. `.claude/hooks/comentarios/check.mjs`.
-4. `.claude/settings.json` — **merge**: se já existir `hooks.PostToolUse`, acrescente uma entrada ao array
-   em vez de substituí-lo; se já houver uma entrada para este mesmo `check.mjs`, não duplique.
-
-## Passo 6 — Gerar a catraca do legado (obrigatório)
-
-Rode, a partir da raiz do projeto:
-
-```bash
-CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/comentarios/check.mjs --gerar-baseline
-```
-
-Isso grava `.claude/hooks/comentarios/baseline.json` com a contagem de violações por arquivo **no estado
-atual**. A partir daí:
-
-- **arquivo novo ou já limpo** → padrão cheio, qualquer violação bloqueia;
-- **arquivo legado** → só bloqueia se o número **subir**;
-- **arquivo legado que melhora** → a catraca desce sozinha e não volta.
-
-Informe ao usuário quantos arquivos entraram na catraca. Se forem muitos, deixe claro que **não é dívida a
-pagar de uma vez** — o legado se limpa por contato.
-
-> Sem este passo o hook cobraria o padrão cheio de todo o código existente e travaria o projeto. Não pule.
-
-## Passo 7 — Finalizar (sem commit)
-
-- **Não** rode `git add/commit/push`. Deixe tudo no working tree e informe o usuário.
-- Sugira comitar para que outros clones já venham configurados — por exemplo
-  `chore: Configura padrão de comentários (rule + hook + catraca)`.
-- Lembre que `baseline.json` **deve ser versionado**: é o contrato do que é legado.
-
-## Guardrails
-
-- **NUNCA** gravar antes do GATE; **NUNCA** commitar ou dar push por conta própria.
-- **NUNCA** pular o Passo 6 — hook sem catraca trava o projeto inteiro.
-- **Escopo projeto apenas**: não tocar em `~/.claude` nem em configuração global da máquina.
-- **Idempotência**: não duplicar a rule, o bloco do `CLAUDE.md`, o hook nem a entrada no `settings.json`.
-- **Merge, não sobrescrita**, em `CLAUDE.md` e `settings.json` — outros hooks já registrados devem continuar
-  funcionando.
-- **Não** editar código-fonte do projeto neste comando — ele instala o padrão, não faz a limpeza.
-- Conteúdo em **pt-BR**.

package/templates/commands/configurar-orquestrador.md

@@ -1,13 +0,0 @@
----
-description: Configura o agente orquestrador de sub-agents, persistindo a orientação no CLAUDE.md.
----
-
-# Configuração do orquestrador de agentes
-
-Configure-se para ser um **agente orquestrador de subagentes**.
-
-- Salve esta orientação no `CLAUDE.md` (ou em outro arquivo que será lido e entendido em toda nova sessão), para que o comportamento persista.
-- Você irá **delegar** o trabalho para os outros agentes do projeto, em vez de implementar diretamente.
-- Oriente o agente orquestrador **e todos os outros agentes** a sempre relatar no chat qual agente está sendo usado no momento — principalmente quando fizerem gates entre eles.
-
-Ao terminar, mostre o trecho exato que foi adicionado ao `CLAUDE.md`.

package/templates/commands/corrigir-review.md

@@ -1,11 +0,0 @@
----
-description: Organiza as correções do code-review em sprints/fases/tasks com TDD e delega ao orquestrador.
----
-
-# Execução de correções levantadas pelo code-review
-
-Vamos realizar as correções necessárias. Organize-as em **Sprints, Fases e Tasks**, com critérios de aceite em cada uma e **testes (TDD) obrigatórios** para cada implementação e correção, de modo que esses tipos de problema não voltem a ocorrer. O que por ventura não estiver mapeado nas nossas rules, incremente também (`.claude/rules/`).
-
-Grave o(s) arquivo(s) de Sprint na convenção do projeto: `docs/plans/AAAA-MM-DD-correcoes-breve-descricao.md` (e, se fizer sentido, a spec correspondente em `docs/specs/`).
-
-Após a criação dos arquivos das Sprints, **chame o Agente Orquestrador** (`/executar-plan`) para delegar as implementações utilizando sub-agents em paralelo.

package/templates/commands/criar-agents.md

@@ -1,42 +0,0 @@
----
-description: Cria agents especializados em .claude/agents/ a partir do plano, SPEC e CLAUDE.md.
----
-
-# Criação dos agents do projeto
-
-Leia o `CLAUDE.md` e o `SPEC.md` na raiz e o **plano mais recente em `docs/plans/`**.
-
-Com base nos módulos e tasks definidos, crie os **agents especializados** para este projeto.
-
-Para cada agent, defina:
-1. Nome e descrição clara de quando usar
-2. Tools necessárias — apenas o mínimo para a task (não dê `Write` se o agent só precisa de `Read`)
-3. Model adequado — **Haiku** para tasks simples, **Sonnet** para implementação, **Opus** para arquitetura
-4. Skills do projeto que o agent deve carregar
-5. System prompt com:
-   - Papel e responsabilidades
-   - Restrições explícitas (o que nunca fazer)
-   - Padrões do projeto que deve seguir
-
-**Obrigatório em todo agent que escreve código** (implementação, testes, refactor, design system): incluir
-no system prompt, literalmente, o bloco abaixo. Rule referenciada só por caminho não é lida — precisa estar
-no prompt.
-
-```markdown
-## Comentários
-
-@.claude/rules/comentarios.md
-
-O padrão é **não comentar**. Orçamento: bloco interno <= 3 linhas · docstring pública <= 5 · cabeçalho de
-arquivo proibido · densidade <= 10%.
-Nunca colocar no código: banner/separador de seção, task/fase/plano/spec, data, hash de commit, achado de
-review, narração do passo a passo, código comentado.
-Isso mora na mensagem de commit e em `docs/` — nunca em comentário.
-```
-
-> Este ponto é onde o padrão falhou antes: os agents eram instruídos a rastrear plano/SPEC/task e
-> despejavam essa rastreabilidade em comentário, porque nada dizia **onde** ela deveria morar.
-
-Crie os arquivos em `.claude/agents/`.
-
-Ao terminar, mostre como invocar cada agent manualmente e como o agent primário (orquestrador) pode delegar para eles automaticamente.

package/templates/commands/criar-code-reviewer.md

@@ -1,30 +0,0 @@
----
-description: Cria o agent code-reviewer (somente leitura) em .claude/agents/code-reviewer.md.
----
-
-# Criação do code-reviewer
-
-Leia o `CLAUDE.md` e o `SPEC.md` na raiz do projeto.
-
-Crie um agent de review em `.claude/agents/code-reviewer.md` com:
-
-- **Somente ferramentas de leitura** — nunca escrita ou execução.
-- System prompt focado em revisar contra o `SPEC.md` e o plano mais recente em `docs/plans/`.
-- Hook que **bloqueia** qualquer tentativa de modificar arquivos (`PreToolUse` bloqueando `Write`/`Edit`).
-- Critérios de classificação: **BLOQUEANTE**, **IMPORTANTE**, **SUGESTÃO**.
-
-Inclua no system prompt um **checklist explícito** do que revisar (sem isso o agent revisa o que lhe parecer
-relevante e ignora o resto):
-
-1. Correção — bugs, casos de borda, erros silenciados.
-2. Aderência ao `SPEC.md` e ao plano em `docs/plans/`.
-3. Testes — existem e cobrem o crítico da task?
-4. Segurança e isolamento de dados (multi-tenant, autorização, segredos).
-5. Rules do projeto em `.claude/rules/`.
-6. **Comentários** — classificar como **IMPORTANTE** (nunca SUGESTÃO): bloco interno acima de 3 linhas,
-   docstring pública acima de 5, cabeçalho de arquivo, banner/separador de seção, task/fase/plano/data/hash
-   de commit/achado de review dentro do código, narração do passo a passo, código comentado.
-   Ver `.claude/rules/comentarios.md`.
-7. Legibilidade e simplicidade.
-
-O agent não deve corrigir nada — apenas identificar e reportar problemas.

package/templates/commands/criar-hooks.md

@@ -1,32 +0,0 @@
----
-description: Cria hooks por agent em .claude/hooks/ conforme o escopo (leitura, implementação, QA).
----
-
-# Geração de hooks para os agents
-
-Leia os agents criados em `.claude/agents/` e o **plano mais recente em `docs/plans/`**.
-
-Para cada agent, crie os hooks específicos que façam sentido para o seu domínio e escopo. Siga estas regras por tipo de agent:
-
-**AGENT SOMENTE LEITURA (revisor, auditor):**
-- `PreToolUse` que bloqueia `Write`, `Edit` e `Bash` com mensagem clara de por que está bloqueando.
-
-**AGENT DE IMPLEMENTAÇÃO (backend, frontend, parser):**
-- `PostToolUse` que roda os testes do módulo após qualquer edição de arquivo.
-- `PreToolUse` que bloqueia comandos fora do escopo (ex: backend não faz `git push`, parser não acessa banco de dados).
-- `Stop` que verifica se os testes passam antes de encerrar.
-
-**AGENT DE QA/TESTES:**
-- `PreToolUse` que permite apenas comandos de execução de testes (`pytest`, `vitest`, `jest`) e bloqueia qualquer outra coisa.
-
-**Hook já existente — não recrie nem remova:** se `.claude/hooks/comentarios/check.mjs` existir, ele é do
-`/configurar-comentarios` (valida comentários no `PostToolUse` de `Write|Edit`, com catraca em
-`baseline.json`). Preserve-o e preserve o registro dele no `.claude/settings.json` ao fazer merge dos
-hooks novos.
-
-Para o Claude Code:
-- Adicione a seção `hooks` no frontmatter de cada arquivo em `.claude/agents/`.
-- Crie os scripts em `.claude/hooks/nome-do-agent/`.
-- Scripts devem usar `exit 2` para bloquear e `exit 0` para permitir.
-
-Ao terminar, demonstre um caso de uso real: um agent tentando fazer algo fora do seu escopo e sendo bloqueado pelo hook.