dd-harness 0.3.0 → 0.5.0

package/dist/index.js

@@ -3,14 +3,14 @@ import { termosDaConsulta } from "./argv.js";
 import { check, status } from "./check.js";
 import { leConfigDoRepo, guardaToken } from "./config.js";
 import { grava } from "./gravar.js";
-import { init, SUGESTAO_MCP } from "./init.js";
-import { LINHA_DE_IMPORT } from "./materializa.js";
+import { init, SUGESTAO_AGENTS, SUGESTAO_HOOK, SUGESTAO_MCP } from "./init.js";
 import { buscaPolitica } from "./politica.js";
 import { busca } from "./buscar.js";
-import { arquiva, edita } from "./curar.js";
+import { arquiva, edita, le } from "./curar.js";
 import { criaPasta } from "./pasta.js";
 import { criaProjeto } from "./projeto.js";
-import { sync } from "./sync.js";
+import { reancora } from "./reancorar.js";
+import { subiuOWorker } from "./worker.js";
 /**
  * `dd-harness` — o cliente que materializa os artefatos no repositorio.
  *
@@ -19,80 +19,53 @@ import { sync } from "./sync.js";
  * em repositorio alheio tem que envelhecer bem, e cada dependencia e uma chance de nao
  * envelhecer.
  */
-const AJUDA = `dd-harness — materializa política, briefing e Brain no repositório
-
-  dd-harness login --token <token> [--api <url>]
-                                     guarda a credencial desta máquina
-  dd-harness projeto <slug> --nome "<nome>" [--tenant <t>] [--api <url>]
-                                     cria o projeto no serviço (antes do init)
-  dd-harness init --tenant <t> --projeto <p> [--api <url>]
-                                     prepara o repositório (config + CLAUDE.md)
-  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
-                                     cria a pasta que o gravar exige
-  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
-  dd-harness editar <arquivo.md>     corrige o que já está gravado
-  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
-                     [--substituida-por <pasta>/<slug>]
-                                     tira de circulação sem apagar
-  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
-  dd-harness sync                    escreve os artefatos em disco
-  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
-  dd-harness status                  só lê: o tamanho do Brain e o que espera julgamento
-  dd-harness politica                imprime a política do serviço (para o hook de sessão)
-                                     saída 0 = veio; 3 = projeto sem política;
-                                     1 = não consegui buscar
-  dd-harness --help
-
-O gerado vive em dd-harness/. Na raiz fica só o seu CLAUDE.md, que importa a
-política com a linha ${LINHA_DE_IMPORT}
+const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
+
+  dd-harness login --token <token> [--api <url>]
+                                     guarda a credencial desta máquina
+  dd-harness projeto <slug> --nome "<nome>" [--tenant <t>] [--api <url>]
+                                     cria o projeto no serviço (antes do init)
+  dd-harness init --tenant <t> --projeto <p> [--api <url>]
+                                     prepara o repositório (config + CLAUDE.md)
+  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
+                                     cria a pasta que o gravar exige
+  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
+  dd-harness editar <arquivo.md>     corrige o que já está gravado
+  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
+                     [--substituida-por <pasta>/<slug>]
+                                     tira de circulação sem apagar
+  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
+  dd-harness ler <pasta>/<slug>      imprime a memória inteira, no formato de gravar
+  dd-harness reancorar <pasta>/<slug> --de "<alvo>" --para "<alvo>"
+                                     troca o alvo de uma âncora que mudou de lugar
+  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
+  dd-harness status                  só lê: o tamanho do Brain e o que espera julgamento
+  dd-harness politica [--hook]       imprime a política do serviço
+                                     saída 0 = veio; 3 = projeto sem política;
+                                     1 = não consegui buscar
+                                     --hook: fala o protocolo do SessionStart do
+                                     Claude Code, para pôr a política no contexto
+  dd-harness --help
+
+Nada do dd-harness fica em disco: a política chega pelo hook de sessão, e a
+memória pela busca, na hora.
 `;
-/** O aviso existe porque o import falha em silêncio — foi medido, não suposto. */
-function avisaSobreOPonteiro(ponteiro) {
-    if (ponteiro === "ok" || ponteiro === "sem-politica")
-        return;
-    // O import pendurado e o inverso dos outros dois: a linha esta la, o alvo e que nao
-    // existe. Dizer "acrescente a linha" aqui mandaria a pessoa para o lugar errado.
-    if (ponteiro === "aponta-para-o-vazio") {
-        console.error([
-            "",
-            `AVISO: o CLAUDE.md importa ${LINHA_DE_IMPORT}, mas não há política no serviço.`,
-            "O arquivo apontado não existe, e import quebrado falha em silêncio: a sessão abre",
-            "sem protocolo e nada avisa.",
-            "",
-            "Escreva a política do projeto no serviço, ou tire a linha do CLAUDE.md.",
-        ].join("\n"));
-        return;
-    }
-    const motivo = ponteiro === "sem-claude-md"
-        ? "não há CLAUDE.md na raiz"
-        : "o CLAUDE.md da raiz não importa a política";
-    console.error([
-        "",
-        `AVISO: ${motivo}.`,
-        "A política existe no serviço e está em disco, mas não chega à sessão: o import",
-        "ausente falha em silêncio, e a sessão abre sem protocolo sem avisar ninguém.",
-        "",
-        `Acrescente esta linha ao CLAUDE.md da raiz:  ${LINHA_DE_IMPORT}`,
-        "Ou rode: dd-harness init --tenant <t> --projeto <p>",
-    ].join("\n"));
-}
 /**
  * Os ganchos sao IMPRESSOS, nunca instalados. `.git/hooks` nao e versionado e nao e
  * nosso: escrever la dentro sem a pessoa pedir e o mesmo tipo de invasao que
  * sobrescrever o CLAUDE.md dela. Quem cola, decide.
  */
-const GANCHOS = `
-Opcional — dois ganchos que valem a pena:
-
-  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
-    #!/bin/sh
-    dd-harness check --commit "$(git rev-parse HEAD)" || true
-
-  .claude/settings.json    (na abertura da sessão, o que espera julgamento)
-    "hooks": { "SessionStart": [{ "hooks": [{ "type": "command",
-      "command": "dd-harness status" }] }] }
-
-Os dois terminam em sucesso mesmo com deriva: avisam, não bloqueiam.`;
+const GANCHOS = `
+Opcional — o gancho que devolve a memória ao code review:
+
+  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
+    #!/bin/sh
+    dd-harness check --commit "$(git rev-parse HEAD)" || true
+
+Termina em sucesso mesmo com deriva: avisa, não bloqueia.
+
+O hook da política (\`dd-harness politica --hook\`) é outra coisa, e não é
+opcional — \`dd-harness init\` imprime a linha para o \`.claude/settings.json\`.`;
 function argumento(argv, nome) {
     const i = argv.indexOf(`--${nome}`);
     return i >= 0 ? argv[i + 1] : undefined;
@@ -109,20 +82,39 @@ async function comandoInit(argv) {
         api: argumento(argv, "api"),
     });
     console.log(r.config === "criada" ? "criado  .dd-harness.json" : "mantido .dd-harness.json");
-    console.log({
-        criado: "criado  CLAUDE.md com a linha de import",
-        "linha-acrescentada": "ajustado CLAUDE.md — linha de import acrescentada ao seu",
-        "ja-tinha-a-linha": "mantido CLAUDE.md — já importava a política",
-    }[r.claudeMd]);
-    console.log("\nAgora: dd-harness login --token <token> && dd-harness sync");
+    console.log("\nAgora: dd-harness login --token <token>");
+    // O hook vem primeiro e nao e opcional: sem ele a sessao abre sem politica, que e a
+    // falha que este projeto existe para combater. O MCP e conveniencia; este, nao.
+    if (r.hook === "ja-declarado") {
+        console.log("\nmantido .claude/settings.json — o hook da política já está declarado");
+    }
+    else {
+        console.log("\nOBRIGATÓRIO: o hook que carrega a política no início de cada sessão." +
+            "\nSem ele a sessão abre sem protocolo, e nada avisa. Acrescente ao" +
+            "\n`.claude/settings.json` (não escrevo nele: o arquivo é seu e pode já" +
+            "\nter hooks e permissões):\n");
+        console.log(SUGESTAO_HOOK);
+    }
     if (r.mcp === "ja-declarado") {
         console.log("\nmantido .mcp.json — o servidor dd-harness já está declarado");
+    }
+    else {
+        console.log("\nOpcional: as memórias como ferramenta, para o agente buscar e gravar sem" +
+            "\nescrever arquivo. Acrescente ao `.mcp.json` da raiz (não escrevo nele: o" +
+            "\narquivo é seu e pode declarar outros servidores):\n");
+        console.log(SUGESTAO_MCP);
+    }
+    // Fora do Claude Code o hook nao roda, e ai o MCP deixa de ser conveniencia: e o unico
+    // caminho da politica. Mas ferramenta disponivel nao e ferramenta chamada — sem esta
+    // instrucao, o agente pode nunca perguntar.
+    if (r.agents === "ja-aponta") {
+        console.log("\nmantido AGENTS.md — já manda buscar a política pelo MCP");
         return;
     }
-    console.log("\nOpcional: as memórias como ferramenta, para o agente buscar e gravar sem" +
-        "\nescrever arquivo. Acrescente ao `.mcp.json` da raiz (não escrevo nele: o" +
-        "\narquivo é seu e pode declarar outros servidores):\n");
-    console.log(SUGESTAO_MCP);
+    console.log("\nUsa Codex, Cursor, Gemini CLI ou Windsurf? Eles NÃO rodam o hook do" +
+        "\nClaude Code, e sem isto a sessão abre sem política. Crie um `AGENTS.md`" +
+        "\nna raiz (ou acrescente ao seu) com:\n");
+    console.log(SUGESTAO_AGENTS);
 }
 /**
  * Nao exige `.dd-harness.json`, e isso importa: sem projeto no servico o `init` nao tem o
@@ -147,7 +139,7 @@ async function comandoEditar(argv) {
     }
     const r = await edita(process.cwd(), caminho);
     console.log(`editado  ${r.endereco}`);
-    console.log(`  ${r.ancoras} âncora(s). Rode \`dd-harness sync\` para materializar.`);
+    console.log(`  ${r.ancoras} âncora(s).`);
 }
 const MOTIVOS = ["obsoleta", "incorreta", "fora_dos_filtros"];
 async function comandoArquivar(argv) {
@@ -166,7 +158,20 @@ async function comandoArquivar(argv) {
         substituidaPor: argumento(argv, "substituida-por"),
     });
     console.log(`arquivado  ${r.endereco} (${r.motivo})`);
-    console.log("  foi para o histórico, não foi apagada. Rode `dd-harness sync`.");
+    console.log("  foi para o histórico, não foi apagada.");
+}
+/**
+ * A memoria inteira no stdout, no mesmo markdown que `gravar` e `editar` consomem.
+ *
+ * Sem materializacao este e o unico caminho para o corpo: a busca devolve so endereco,
+ * titulo e resumo. Tambem e o ponto de partida de toda edicao — corrigir exige ver.
+ */
+async function comandoLer(argv) {
+    const endereco = argv[0];
+    if (!endereco || endereco.startsWith("-")) {
+        throw new Error("uso: dd-harness ler <pasta>/<slug>");
+    }
+    console.log(await le(process.cwd(), endereco));
 }
 async function comandoBuscar(argv) {
     const consulta = termosDaConsulta(argv);
@@ -181,6 +186,7 @@ async function comandoBuscar(argv) {
         if (!r.semantica) {
             console.log("  (só busca textual: sem provedor de embedding no serviço)");
         }
+        avisaSobreAFila(r.esperandoIndexacao);
         return;
     }
     console.log(r.semantica
@@ -190,36 +196,32 @@ async function comandoBuscar(argv) {
         console.log(`  ${a.endereco} — ${a.titulo}`);
         console.log(`    ${a.resumo}`);
     }
+    avisaSobreAFila(r.esperandoIndexacao);
 }
-async function comandoSync() {
-    const resultado = await sync(process.cwd());
-    if (resultado.tipo === "editado-a-mao") {
-        console.error([
-            "parei sem escrever nada: estes arquivos foram editados à mão.",
-            ...resultado.arquivos.map((a) => `  ${a}`),
-            "",
-            "O disco é projeção do serviço, uma direção só. Duas saídas:",
-            "",
-            "  1. Leve a edição para o serviço — `dd-harness editar <arquivo>` para cada um",
-            "     acima. É o caminho normal de corrigir memória, e destrava o sync.",
-            "  2. Descarte a edição local (git checkout / apague o arquivo) e sincronize.",
-        ].join("\n"));
-        process.exitCode = 1;
+/**
+ * Memoria sem vetor nao aparece na busca semantica, e a resposta parece completa do
+ * mesmo jeito. `semantica: true` diz so que a CONSULTA foi vetorizada — a base pode
+ * estar inteira na fila, e ai a busca responde lexical com cara de semantica.
+ */
+function avisaSobreAFila(esperando) {
+    if (esperando <= 0)
         return;
+    console.log("");
+    console.log(`ATENÇÃO: ${esperando} memória(s) ainda sem vetor — podem existir respostas`);
+    console.log("  melhores que não apareceram aqui. Rode `start-worker.bat`.");
+}
+async function comandoReancorar(argv) {
+    const endereco = argv[0];
+    const de = argumento(argv, "de");
+    const para = argumento(argv, "para");
+    if (!endereco || endereco.startsWith("-") || !endereco.includes("/") || !de || !para) {
+        throw new Error('uso: dd-harness reancorar <pasta>/<slug> --de "<alvo>" --para "<alvo>"');
     }
-    if (resultado.tipo === "sem-mudanca") {
-        console.log("nada mudou no serviço — disco já está em dia.");
-    }
-    else {
-        for (const a of resultado.escritos)
-            console.log(`escrito  ${a}`);
-        for (const a of resultado.removidos)
-            console.log(`removido ${a}`);
-        if (!resultado.escritos.length && !resultado.removidos.length) {
-            console.log("conteúdo novo do serviço, sem diferença em disco.");
-        }
-    }
-    avisaSobreOPonteiro(resultado.ponteiro);
+    const r = await reancora(process.cwd(), endereco, de, para);
+    console.log(`reancorado  ${r.endereco}`);
+    console.log(`  de   ${r.de}`);
+    console.log(`  para ${r.para}`);
+    console.log("  Rode `dd-harness check --commit <sha>` para medir a base nova.");
 }
 async function comandoCheck(argv) {
     const r = await check(process.cwd(), argumento(argv, "commit"));
@@ -236,8 +238,24 @@ async function comandoCheck(argv) {
     if (r.ausentes.length) {
         console.log("");
         console.log("ALVO AUSENTE — alguém apagou ou moveu o que uma memória guarda:");
-        for (const valor of r.ausentes)
+        for (const valor of r.ausentes) {
             console.log(`  ${valor}`);
+            // Quando o git achou para onde o conteúdo foi, a saída deixa de ser só um
+            // diagnóstico e passa a ter uma ação — que é o que faltava numa refatoração
+            // grande, onde a lista de ausentes vira uma parede sem resposta.
+            const sugerida = r.reancoragens.find((s) => s.ancora === valor);
+            if (sugerida) {
+                console.log(`    → provavelmente virou ${sugerida.sugestao}` +
+                    (sugerida.similaridade ? ` (git: ${sugerida.similaridade}% similar)` : ""));
+                console.log(`      dd-harness reancorar ${sugerida.pasta}/${sugerida.memoria}` +
+                    ` --de "${valor}" --para "${sugerida.sugestao}"`);
+            }
+        }
+        if (r.reancoragens.length) {
+            console.log("");
+            console.log("  A sugestão vem da detecção de rename do git, por similaridade de");
+            console.log("  conteúdo — confira antes de aplicar. Nada é reancorado sozinho.");
+        }
     }
     if (r.novas > 0) {
         console.log("");
@@ -273,8 +291,20 @@ async function comandoCheck(argv) {
  * um "falhou" generico colapsaria: projeto novo (que precisa de briefing) de politica
  * inalcancavel (que precisa PARAR a sessao). Mudar estes numeros quebra o hook.
  */
-async function comandoPolitica() {
+async function comandoPolitica(argv) {
     const r = await buscaPolitica(process.cwd());
+    // `--hook`: fala o protocolo do SessionStart do Claude Code, que injeta
+    // `additionalContext` no contexto da sessao. Sem a flag, saida legivel para quem roda
+    // no terminal. A diferenca importa: o hook precisa que o AVISO chegue ao modelo, e
+    // stderr so chega ao transcript — aviso que o modelo nao le e o mesmo que silencio.
+    if (argv.includes("--hook")) {
+        // A abertura da sessao e o momento certo de esvaziar a fila: o worker nao esta
+        // hospedado, e memoria sem vetor some da busca sem nada denunciar. Sobe so quando ha
+        // fila de verdade — o hook roda ate nas sessoes que so leem codigo.
+        const worker = await subiuOWorker(process.cwd(), r.esperandoIndexacao ?? 0);
+        console.log(JSON.stringify({ hookSpecificOutput: contextoDaSessao(r, worker) }));
+        return;
+    }
     if (r.estado === "ok") {
         console.log(r.conteudo);
         return;
@@ -287,6 +317,72 @@ async function comandoPolitica() {
     console.error(`não consegui buscar a política: ${r.motivo}`);
     process.exitCode = 1;
 }
+/**
+ * O que o hook injeta no contexto, por estado.
+ *
+ * Sai sempre com codigo 0: o que precisa chegar ao modelo e o TEXTO, e um codigo de erro
+ * so faria o Claude Code registrar falha no transcript — que ninguem le — enquanto a
+ * sessao seguiria sem saber que esta sem protocolo.
+ */
+function contextoDaSessao(r, worker) {
+    const base = { hookEventName: "SessionStart" };
+    const fila = avisoDaFila(r.esperandoIndexacao ?? 0, worker);
+    if (r.estado === "ok") {
+        return {
+            ...base,
+            additionalContext: "# Política deste projeto (carregada do dd-harness)\n\n" +
+                "As regras abaixo valem para esta sessão inteira.\n\n" +
+                r.conteudo +
+                fila,
+        };
+    }
+    if (r.estado === "sem-politica") {
+        return {
+            ...base,
+            additionalContext: "AVISO DO DD-HARNESS: este projeto existe no serviço mas **nunca foi briefado** " +
+                "— não há política.\n\nIsto não é uma falha: é um projeto novo. Antes de " +
+                "implementar qualquer coisa, diga isso ao usuário e proponha rodar `/briefar`." +
+                fila,
+        };
+    }
+    return {
+        ...base,
+        additionalContext: "PARE: NÃO FOI POSSÍVEL CARREGAR A POLÍTICA DESTE PROJETO.\n\n" +
+            `Motivo: ${r.motivo}\n\n` +
+            "A política pode existir no serviço e não ter chegado até aqui, então esta sessão " +
+            "está **sem protocolo** — as proibições e a regra do OK não foram carregadas.\n\n" +
+            "Antes de qualquer outra coisa: avise o usuário com estas palavras e **não " +
+            "modifique nenhum arquivo** até ele decidir como prosseguir. Seguir como se nada " +
+            "tivesse acontecido é exatamente a falha que este projeto combate.",
+    };
+}
+/**
+ * O estado da fila de indexacao, para ir junto da politica no contexto.
+ *
+ * Fila vazia nao gera linha nenhuma: aviso sem motivo em toda sessao e o que ensina a
+ * ignorar aviso. O texto muda conforme o worker subiu ou nao, porque a acao que se espera
+ * do agente e diferente em cada caso.
+ */
+function avisoDaFila(esperando, worker) {
+    if (esperando <= 0)
+        return "";
+    if (worker.subiu) {
+        return (`\n\n---\n\nNOTA DO DD-HARNESS: ${esperando} memória(s) estavam sem vetor, e o ` +
+            "worker de indexação foi iniciado automaticamente agora. Até ele terminar, " +
+            "`buscar_memoria` pode não encontrar o que foi gravado recentemente — se uma " +
+            "busca vier vazia nos próximos minutos, tente de novo antes de concluir que a " +
+            "memória não existe.");
+    }
+    // Sem worker local (o caso do repositorio consumidor) ou falha ao subir: so avisar.
+    const comoResolver = worker.motivo === "sem-worker"
+        ? "O worker não roda a partir deste repositório — ele vive no monorepo do " +
+            "dd-harness. Avise o usuário que a indexação está pendente lá."
+        : `Não consegui iniciar o worker${worker.detalhe ? ` (${worker.detalhe})` : ""}. ` +
+            "Peça ao usuário para rodar `start-worker.bat`.";
+    return (`\n\n---\n\nAVISO DO DD-HARNESS: ${esperando} memória(s) estão sem vetor e **não ` +
+        "aparecem na busca semântica**. A busca vai responder mesmo assim, o que a faz " +
+        `parecer completa quando não está.\n\n${comoResolver}`);
+}
 async function comandoStatus() {
     const r = await status(process.cwd());
     // O acervo vem primeiro, e sempre: e a resposta para "o que ha no Brain deste projeto?",
@@ -361,9 +457,8 @@ async function comandoPasta(argv) {
 }
 /**
  * O agente escreve o arquivo — que e o que ele ja fazia no modelo file-based — e este
- * comando o transforma em requisicao. O arquivo nao fica no repositorio: quem
- * materializa e o `sync`, a partir do servico, para nao existir copia escrita a mao ao
- * lado da copia gerada.
+ * comando o transforma em requisicao. O arquivo e so o veiculo: depois de gravado, a
+ * memoria vive no servico, e quem quiser le-la usa a busca. Nada fica em disco.
  */
 async function comandoGravar(argv) {
     const caminho = argv[0];
@@ -372,8 +467,7 @@ async function comandoGravar(argv) {
     }
     const r = await grava(process.cwd(), caminho);
     console.log(`gravado  ${r.endereco}`);
-    console.log(`  ${r.ancoras} âncora(s), valendo para ${r.projetos} projeto(s).` +
-        " Rode `dd-harness sync` para materializar.");
+    console.log(`  ${r.ancoras} âncora(s), valendo para ${r.projetos} projeto(s).`);
 }
 async function principal() {
     const [comando, ...resto] = process.argv.slice(2);
@@ -392,16 +486,18 @@ async function principal() {
             return comandoEditar(resto);
         case "arquivar":
             return comandoArquivar(resto);
+        case "ler":
+            return comandoLer(resto);
         case "buscar":
             return comandoBuscar(resto);
-        case "sync":
-            return comandoSync();
+        case "reancorar":
+            return comandoReancorar(resto);
         case "check":
             return comandoCheck(resto);
         case "status":
             return comandoStatus();
         case "politica":
-            return comandoPolitica();
+            return comandoPolitica(resto);
         case "--help":
         case "-h":
         case undefined:

package/dist/init.d.ts

@@ -1,16 +1,52 @@
+/**
+ * Prepara um repositorio para o dd-harness.
+ *
+ * Escreve UM arquivo: o `.dd-harness.json`, que diz a que projeto este repositorio
+ * pertence. Todo o resto e sugestao impressa, para quem cola decidir.
+ *
+ * Ate a fase 0 este comando tambem escrevia uma linha de import no `CLAUDE.md`, que
+ * apontava para a politica materializada em disco. Isso acabou: a politica chega pelo
+ * hook de sessao, e nada do dd-harness fica em disco.
+ */
 export type ResultadoDoInit = {
     config: "criada" | "ja-existia";
-    claudeMd: "criado" | "linha-acrescentada" | "ja-tinha-a-linha";
     mcp: "ja-declarado" | "a-declarar";
+    hook: "ja-declarado" | "a-declarar";
+    /** O `AGENTS.md` manda o agente de fora do Claude Code buscar a política? */
+    agents: "ja-aponta" | "a-apontar";
 };
 /**
  * O `.mcp.json` e sugerido, nunca escrito.
  *
- * Pelo mesmo motivo do `CLAUDE.md` da raiz: o arquivo e do repositorio, pode ja declarar
- * outros servidores, e mesclar JSON alheio e onde falha silenciosa nasce — entrada errada
- * nao da erro, a ferramenta so nao aparece. Quem cola sabe o que colou.
+ * O arquivo e do repositorio, pode ja declarar outros servidores, e mesclar JSON alheio e
+ * onde falha silenciosa nasce — entrada errada nao da erro, a ferramenta so nao aparece.
+ * Quem cola sabe o que colou.
  */
 export declare const SUGESTAO_MCP = "{\n  \"mcpServers\": {\n    \"dd-harness\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"dd-harness-mcp\"]\n    }\n  }\n}";
+/**
+ * O hook que carrega a politica no inicio de cada sessao.
+ *
+ * E a garantia de que nenhuma sessao abre sem protocolo — o papel que antes era do
+ * arquivo materializado mais a linha de import. Vive num hook, e nao numa instrucao no
+ * `CLAUDE.md`, porque instrucao o modelo pode pular: o import quebrado falhava em
+ * silencio, e isso foi medido.
+ *
+ * Sugerido e nao escrito, pelo mesmo motivo do `.mcp.json`.
+ */
+export declare const SUGESTAO_HOOK = "{\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"dd-harness politica --hook\",\n            \"statusMessage\": \"Carregando a pol\u00EDtica do dd-harness...\"\n          }\n        ]\n      }\n    ]\n  }\n}";
+/**
+ * O que escrever num `AGENTS.md`, para agente que NAO e o Claude Code.
+ *
+ * O hook de `SessionStart` e um mecanismo do Claude Code: Codex, Cursor, Gemini CLI e
+ * Windsurf nao o executam. Nessas ferramentas nada carrega a politica sozinho — e o
+ * resultado e a mesma falha de sempre, a sessao abrindo sem protocolo sem avisar.
+ *
+ * O que resta la e o servidor MCP, que essas ferramentas suportam. Mas ferramenta
+ * disponivel nao e ferramenta chamada: sem uma instrucao explicita, o agente pode
+ * simplesmente nunca perguntar pela politica. Dai esta linha, que e curta de proposito —
+ * ela manda buscar a regra, nao repete a regra.
+ */
+export declare const SUGESTAO_AGENTS = "# AGENTS.md\n\nEste projeto tem um protocolo de trabalho que **n\u00E3o est\u00E1 neste arquivo**.\n\n**ANTES de qualquer outra coisa**, chame a ferramenta MCP `ler_artefato` com\n`tipo: \"politica\"` e siga o que ela devolver. \u00C9 a primeira a\u00E7\u00E3o da sess\u00E3o, antes\nde ler c\u00F3digo, responder ou planejar.\n\n- Se a ferramenta n\u00E3o existir, o servidor MCP do dd-harness n\u00E3o est\u00E1 declarado:\n  avise o usu\u00E1rio e **n\u00E3o modifique nada** at\u00E9 ele resolver.\n- Se ela devolver vazio, este projeto nunca foi briefado \u2014 diga isso ao usu\u00E1rio.\n\nO Claude Code carrega a pol\u00EDtica sozinho, por hook. Nas outras ferramentas, a\nchamada acima \u00E9 o que substitui esse hook.";
 export declare function init(raiz: string, dados: {
     tenant: string;
     projeto: string;