dd-harness-mcp 0.16.0 → 0.17.0

package/dist/cli/src/api.js

@@ -20,44 +20,39 @@ export function cabecalhos(token, comCorpo = false) {
         ? { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }
         : { Authorization: `Bearer ${token}` };
 }
-/**
- * `fetch` com nova tentativa para falha transitoria.
- *
- * Medido em uso real: um `ECONNRESET` de conexao ociosa derrubou um `arquivar` que
- * funcionou na segunda tentativa manual. Sem retry, falha de rede de um segundo vira erro
- * final — e para um agente isso e a diferenca entre seguir sozinho e parar para pedir
- * ajuda. Com varios agentes concorrendo, transitorio deixa de ser raro.
- *
- * O que NAO e repetido, e o cuidado que importa:
- *
- * - Erro de aplicacao (4xx). Token invalido ou memoria fora dos filtros nao melhora na
- *   segunda tentativa; repetir so atrasa a mensagem que o agente precisa ler.
- * - 5xx em requisicao que ESCREVE. `POST /memorias` pode ter gravado antes de a resposta
- *   se perder, e repetir criaria duas. Perder a resposta de uma escrita que funcionou e
- *   ruim; gravar duas vezes e pior.
- *
- * Entao: repete falha de REDE (o `fetch` nem chegou a receber resposta) sempre, e 5xx
- * apenas quando o metodo e seguro de repetir.
- */
-const IDEMPOTENTES = new Set(["GET", "HEAD", "PUT", "DELETE"]);
+/** Retry limitado a leituras; erro de transporte em escrita deixa resultado incerto. */
+// Mesmo PUT/DELETE podem ter auditoria, triggers ou conflito após a primeira aplicação.
+// Só leituras são repetidas automaticamente; erro de transporte não prova ausência de commit.
+const LEITURAS = new Set(["GET", "HEAD"]);
 const espera = (ms) => new Promise((r) => setTimeout(r, ms));
 export async function pede(url, init = {}, tentativas = 3) {
     const metodo = (init.method ?? "GET").toUpperCase();
-    const podeRepetirErroDoServidor = IDEMPOTENTES.has(metodo);
+    const podeRepetirErroDoServidor = LEITURAS.has(metodo);
+    if (!Number.isInteger(tentativas) || tentativas < 1)
+        throw new Error("tentativas deve ser inteiro positivo");
     let ultimoErro;
     for (let tentativa = 1; tentativa <= tentativas; tentativa += 1) {
         try {
-            const resposta = await fetch(url, init);
+            const timeout = AbortSignal.timeout(10000);
+            const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+            const resposta = await fetch(url, { ...init, signal });
+            if (resposta.status >= 500 && !podeRepetirErroDoServidor) {
+                await resposta.body?.cancel();
+                throw new Error(`HTTP ${resposta.status}: o servidor pode ter aplicado a escrita antes de falhar`);
+            }
             if (resposta.status >= 500 && podeRepetirErroDoServidor && tentativa < tentativas) {
+                await resposta.body?.cancel();
                 await espera(tentativa * 400);
                 continue;
             }
             return resposta;
         }
         catch (erro) {
-            // Aqui o `fetch` falhou antes de qualquer resposta: DNS, conexao recusada,
-            // ECONNRESET. Nada foi processado do outro lado, entao repetir e seguro mesmo
-            // para POST.
+            if (!podeRepetirErroDoServidor) {
+                throw new Error(`resultado incerto de ${metodo}: não houve confirmação confiável e a escrita pode ter sido aplicada. Consulte o estado antes de tentar novamente.`, { cause: erro });
+            }
+            if (init.signal?.aborted)
+                throw erro;
             ultimoErro = erro;
             if (tentativa === tentativas)
                 break;
@@ -67,3 +62,12 @@ export async function pede(url, init = {}, tentativas = 3) {
     const detalhe = ultimoErro instanceof Error ? ultimoErro.message : String(ultimoErro);
     throw new Error(`não consegui falar com o serviço depois de ${tentativas} tentativas: ${detalhe}`);
 }
+/** A conexão também pode cair depois dos headers, enquanto o corpo é consumido. */
+export async function jsonDaEscrita(resposta) {
+    try {
+        return await resposta.json();
+    }
+    catch (cause) {
+        throw new Error("resultado incerto: a resposta da escrita ficou incompleta. Consulte o estado antes de tentar novamente.", { cause });
+    }
+}

package/dist/cli/src/artefato.js

@@ -1,4 +1,5 @@
-import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { jsonDaEscrita, cabecalhos, credencial, pede, recusa } from "./api.js";
+import { invalidaContexto } from "./estado-local.js";
 /**
  * O `GET` devolve o payload inteiro (politica, briefing, pastas e memorias); aqui so o
  * artefato pedido interessa.
@@ -38,5 +39,8 @@ export async function escreveArtefato(raiz, tipo, conteudo) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    await invalidaContexto(raiz).catch(() => {
+        throw new Error("Artefato aceito pela API, mas a sessão local não pôde ser invalidada. Reabra a sessão antes de trabalhar.");
+    });
+    return (await jsonDaEscrita(resposta));
 }

package/dist/cli/src/cinto.js

@@ -1,4 +1,7 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { estadoDoRepo, escreveAtomico } from "./estado-local.js";
+import { leConfigDoRepo, leToken } from "./config.js";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { memoriasNoConteudo } from "./diff.js";
 /**
@@ -23,7 +26,16 @@ import { memoriasNoConteudo } from "./diff.js";
  */
 /** Onde o cache vive. Fora do repositorio: nada do dd-harness volta a morar em disco versionado. */
 export function caminhoDoCache(raiz) {
-    return join(raiz, ".claude", "dd-harness-ancoras.json");
+    return join(estadoDoRepo(raiz), "ancoras.json");
+}
+async function identidade(raiz) {
+    const config = await leConfigDoRepo(raiz).catch(() => null);
+    return createHash("sha256").update(JSON.stringify([config, config ? await leToken(config.api) : null])).digest("hex");
+}
+export async function invalidaCache(raiz) {
+    await rm(caminhoDoCache(raiz), { force: true }).catch(() => {
+        throw new Error("Gravação aceita pela API, mas o cache local não pôde ser invalidado. Reabra a sessão para reconstruí-lo.");
+    });
 }
 /**
  * Acrescenta UMA memoria ao cache, sem esperar a proxima sessao.
@@ -40,21 +52,23 @@ export function caminhoDoCache(raiz) {
  * Idempotente pelo endereco: regravar a mesma memoria substitui a entrada, nunca duplica.
  */
 export async function acrescentaAoCache(raiz, memoria) {
-    if (memoria.ancoras.length === 0)
+    const existente = await leCache(raiz);
+    if (!existente && memoria.ancoras.length === 0)
         return;
-    const atual = (await leCache(raiz)) ?? { gravado_em: "", memorias: [] };
+    const atual = existente ?? { gravado_em: "", memorias: [] };
     const endereco = `${memoria.pasta}/${memoria.slug}`;
     const cache = {
+        projeto: await identidade(raiz),
         gravado_em: new Date().toISOString(),
         memorias: [
             ...atual.memorias.filter((m) => `${m.pasta}/${m.slug}` !== endereco),
-            memoria,
+            ...(memoria.status === "ativa" && memoria.ancoras.length ? [memoria] : []),
         ],
     };
     try {
         const caminho = caminhoDoCache(raiz);
         await mkdir(dirname(caminho), { recursive: true });
-        await writeFile(caminho, `${JSON.stringify(cache)}\n`, "utf8");
+        await escreveAtomico(caminho, `${JSON.stringify(cache)}\n`);
     }
     catch {
         // Mesmo motivo do `guardaCache`: cache e otimizacao, nao contrato.
@@ -63,6 +77,7 @@ export async function acrescentaAoCache(raiz, memoria) {
 /** Guarda as ancoras do Brain para o hook consultar sem rede. Falha em silencio: cache e otimizacao, nao contrato. */
 export async function guardaCache(raiz, brain) {
     const cache = {
+        projeto: await identidade(raiz),
         gravado_em: new Date().toISOString(),
         memorias: brain.memorias
             .filter((m) => m.status === "ativa" && m.ancoras.length > 0)
@@ -79,7 +94,7 @@ export async function guardaCache(raiz, brain) {
     try {
         const caminho = caminhoDoCache(raiz);
         await mkdir(dirname(caminho), { recursive: true });
-        await writeFile(caminho, `${JSON.stringify(cache)}\n`, "utf8");
+        await escreveAtomico(caminho, `${JSON.stringify(cache)}\n`);
     }
     catch {
         // Sem cache o hook cala, e o PULL continua funcionando. Nao vale falhar a sessao.
@@ -87,7 +102,10 @@ export async function guardaCache(raiz, brain) {
 }
 export async function leCache(raiz) {
     try {
-        return JSON.parse(await readFile(caminhoDoCache(raiz), "utf8"));
+        const cache = JSON.parse(await readFile(caminhoDoCache(raiz), "utf8"));
+        if (cache.projeto !== await identidade(raiz) || !Array.isArray(cache.memorias))
+            return null;
+        return cache;
     }
     catch {
         return null;
@@ -106,7 +124,8 @@ export async function leCache(raiz) {
  * nao viu o aviso de hoje.
  */
 async function jaAvisou(raiz, sessao, enderecos) {
-    const caminho = join(raiz, ".claude", `dd-harness-avisos-${sessao.replace(/[^\w-]/g, "")}.json`);
+    const chave = createHash("sha256").update(sessao + await identidade(raiz)).digest("hex");
+    const caminho = join(estadoDoRepo(raiz), `avisos-${chave}.json`);
     let vistos = [];
     try {
         vistos = JSON.parse(await readFile(caminho, "utf8"));
@@ -134,7 +153,7 @@ async function jaAvisou(raiz, sessao, enderecos) {
  */
 export function caminhoRelativo(raiz, arquivo) {
     const rel = relative(resolve(raiz), resolve(arquivo));
-    if (!rel || rel.startsWith(".."))
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || /^[A-Za-z]:/.test(rel))
         return null;
     return rel.split(sep).join("/");
 }

package/dist/cli/src/config.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { diretorioDoUsuario } from "./estado-local.js";
 /**
  * O servico publicado e o padrao: um repositorio que so declara `tenant` e `projeto` ja
  * fala com quem existe. Para desenvolver contra a maquina local, ponha `api` explicito no
@@ -30,8 +30,37 @@ export async function leConfigDoRepo(raiz) {
         pasta: lido.pasta ?? PADRAO.pasta,
     };
 }
-const arquivoDeCredenciais = () => join(homedir(), ".dd-harness", "credentials.json");
-const arquivoDeConfigDaMaquina = () => join(homedir(), ".dd-harness", "config.json");
+/** Sobe apenas até a raiz git; não herda outro projeto acima de um worktree. */
+export async function achaRaiz(inicio = process.env.DD_HARNESS_ROOT ?? process.cwd()) {
+    let atual = resolve(inicio);
+    const { access } = await import("node:fs/promises");
+    for (;;) {
+        if (await access(join(atual, CAMINHO_CONFIG)).then(() => true, () => false))
+            return atual;
+        if (await access(join(atual, ".git")).then(() => true, () => false))
+            break;
+        const pai = dirname(atual);
+        if (pai === atual)
+            break;
+        atual = pai;
+    }
+    throw new Error(`não encontrei ${CAMINHO_CONFIG} a partir de ${resolve(inicio)}. Configure este projeto com dd-harness start.`);
+}
+/** Uma configuração copiada de outro checkout nunca pode direcionar operações silenciosamente. */
+export async function raizDoMcp() {
+    const explicita = process.env.DD_HARNESS_ROOT;
+    const atual = await achaRaiz(process.cwd()).catch(() => null);
+    if (!explicita)
+        return atual ?? process.cwd();
+    const raiz = await achaRaiz(explicita);
+    const normaliza = (p) => process.platform === "win32" ? resolve(p).toLowerCase() : resolve(p);
+    if (atual && normaliza(atual) !== normaliza(raiz)) {
+        throw new Error("DD_HARNESS_ROOT aponta para outro checkout/projeto. Corrija a raiz na configuração MCP deste host e reinicie-o.");
+    }
+    return raiz;
+}
+const arquivoDeCredenciais = () => join(diretorioDoUsuario(), "credentials.json");
+const arquivoDeConfigDaMaquina = () => join(diretorioDoUsuario(), "config.json");
 export async function leConfigDaMaquina() {
     try {
         const cru = await readFile(arquivoDeConfigDaMaquina(), "utf8");
@@ -43,7 +72,7 @@ export async function leConfigDaMaquina() {
 }
 export async function guardaConfigDaMaquina(parcial) {
     const caminho = arquivoDeConfigDaMaquina();
-    await mkdir(join(homedir(), ".dd-harness"), { recursive: true });
+    await mkdir(diretorioDoUsuario(), { recursive: true });
     const atual = await leConfigDaMaquina();
     const mesclado = { ...atual, ...parcial };
     await writeFile(caminho, `${JSON.stringify(mesclado, null, 2)}\n`, "utf8");
@@ -65,7 +94,7 @@ export async function leToken(api) {
 }
 export async function guardaToken(api, token) {
     const caminho = arquivoDeCredenciais();
-    await mkdir(join(homedir(), ".dd-harness"), { recursive: true });
+    await mkdir(diretorioDoUsuario(), { recursive: true });
     let mapa = {};
     try {
         mapa = JSON.parse(await readFile(caminho, "utf8"));

package/dist/cli/src/curar.js

@@ -1,5 +1,6 @@
+import { invalidaCache } from "./cinto.js";
 import { readFile } from "node:fs/promises";
-import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { jsonDaEscrita, cabecalhos, credencial, pede, recusa } from "./api.js";
 import { interpreta } from "./gravar.js";
 /**
  * A memoria inteira, no markdown que `gravar` e `editar` consomem.
@@ -73,6 +74,7 @@ export async function edita(raiz, caminho) {
     });
     if (!resposta.ok)
         await recusa(resposta);
+    await invalidaCache(raiz);
     return { endereco, ancoras: memoria.ancoras.length };
 }
 export async function arquiva(raiz, endereco, opcoes) {
@@ -89,7 +91,8 @@ export async function arquiva(raiz, endereco, opcoes) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    const lido = (await resposta.json());
+    await invalidaCache(raiz);
+    const lido = (await jsonDaEscrita(resposta));
     return lido;
 }
 /**
@@ -108,7 +111,8 @@ export async function promove(raiz, endereco, global) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    await invalidaCache(raiz);
+    return (await jsonDaEscrita(resposta));
 }
 /**
  * Apaga de verdade, em cascata — ancoras, deriva medida, vinculos, tudo.
@@ -140,5 +144,6 @@ export async function apaga(raiz, endereco, confirmacao) {
     }
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    await invalidaCache(raiz);
+    return (await jsonDaEscrita(resposta));
 }

package/dist/cli/src/diagnostico.js

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { achaRaiz, leConfigDoRepo, leToken } from "./config.js";
+import { buscaPolitica } from "./politica.js";
+export async function handshakeMcp(raiz, comando = "npx", args = ["-y", "dd-harness-mcp@latest"]) {
+    return new Promise((resolve, reject) => {
+        const filho = spawn(comando, args, { cwd: raiz, windowsHide: true,
+            shell: process.platform === "win32" && comando === "npx", stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, DD_HARNESS_ROOT: raiz } });
+        let buffer = "", terminou = false, versao = "desconhecida";
+        const fim = (erro, resultado) => {
+            if (terminou)
+                return;
+            terminou = true;
+            clearTimeout(timer);
+            filho.stdin.end();
+            filho.kill();
+            if (erro)
+                reject(erro);
+            else
+                resolve(resultado);
+        };
+        const timer = setTimeout(() => fim(new Error("MCP não completou initialize/tools/list em 30 segundos")), 30000);
+        filho.once("error", () => fim(new Error("Não foi possível iniciar o executável MCP")));
+        filho.once("exit", () => { if (!terminou)
+            fim(new Error("MCP encerrou antes de listar ferramentas")); });
+        filho.stdin.on("error", () => fim(new Error("MCP fechou stdin antes do handshake")));
+        filho.stderr.resume(); // Saída do subprocesso pode conter ambiente; não a ecoar.
+        const envia = (v) => filho.stdin.write(JSON.stringify(v) + "\n");
+        filho.stdout.on("data", chunk => {
+            buffer += chunk;
+            if (buffer.length > 2000000)
+                return fim(new Error("Resposta MCP excedeu o limite do diagnóstico"));
+            for (;;) {
+                const pos = buffer.indexOf("\n");
+                if (pos < 0)
+                    break;
+                const linha = buffer.slice(0, pos);
+                buffer = buffer.slice(pos + 1);
+                let msg;
+                try {
+                    msg = JSON.parse(linha);
+                }
+                catch {
+                    return fim(new Error("MCP imprimiu texto fora do protocolo em stdout"));
+                }
+                if (msg.error)
+                    return fim(new Error("MCP recusou initialize/tools/list"));
+                if (msg.id === 1) {
+                    versao = msg.result?.serverInfo?.version ?? versao;
+                    envia({ jsonrpc: "2.0", method: "notifications/initialized" });
+                    envia({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+                }
+                else if (msg.id === 2) {
+                    const ferramentas = msg.result?.tools?.map((t) => t.name);
+                    if (!Array.isArray(ferramentas))
+                        return fim(new Error("tools/list não devolveu ferramentas"));
+                    fim(undefined, { versao, ferramentas });
+                }
+            }
+        });
+        envia({ jsonrpc: "2.0", id: 1, method: "initialize", params: {
+                protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "dd-harness-diagnostico", version: "1.0.0" },
+            } });
+    });
+}
+export async function diagnostico(inicio, testarMcp = false) {
+    const raiz = await achaRaiz(inicio);
+    const c = await leConfigDoRepo(raiz);
+    const linhas = [`Raiz: ${raiz}`, `Projeto: ${c.tenant}/${c.projeto}`, `Node: ${process.version}`,
+        `Credencial: ${await leToken(c.api) ? "presente (valor omitido)" : "ausente"}`];
+    for (const [host, config, hook] of [
+        ["Claude Code", ".mcp.json", ".claude/settings.json"],
+        ["Codex", ".codex/config.toml", ".codex/hooks.json"],
+        ["Antigravity", ".agents/mcp_config.json", ".agents/hooks.json"],
+    ]) {
+        const m = await readFile(join(raiz, config), "utf8").catch(() => "");
+        const h = await readFile(join(raiz, hook), "utf8").catch(() => "");
+        linhas.push(`${host}: MCP ${m.includes("dd-harness") ? "declarado" : "ausente"}; ` +
+            `hooks ${h.includes("dd-harness guarda") && h.includes("dd-harness sessao") ? "declarados" : "ausentes/legados"}; ativação no host requer verificação.`);
+        if (m.includes("dd-harness") && !m.includes(JSON.stringify(raiz)))
+            linhas.push(`${host}: confira DD_HARNESS_ROOT; a raiz explícita atual não foi reconhecida.`);
+    }
+    const politica = await buscaPolitica(raiz);
+    linhas.push(`Contexto: ${politica.estado}${politica.estado === "inalcancavel" ? " — " + politica.motivo : ""}`);
+    if (testarMcp) {
+        const m = await handshakeMcp(raiz);
+        linhas.push(`MCP ${m.versao}: initialize/tools/list concluídos; ${m.ferramentas.length} ferramentas. Isto não comprova hooks ativos.`);
+    }
+    return linhas;
+}

package/dist/cli/src/edicoes.js

@@ -0,0 +1,52 @@
+import { resolve } from "node:path";
+const texto = (v) => typeof v === "string" ? v : undefined;
+export function normalizaEntrada(host, entrada) {
+    if (host === "antigravity") {
+        const roots = entrada.workspacePaths;
+        if (!Array.isArray(roots) || roots.length !== 1 || typeof roots[0] !== "string") {
+            throw new Error("dd-harness exige um workspace inequívoco por sessão; selecione um projeto.");
+        }
+        const chamada = entrada.toolCall;
+        return { raiz: roots[0], sessao: texto(entrada.conversationId) ?? "", ferramenta: chamada?.name ?? "",
+            args: chamada?.args ?? {} };
+    }
+    return { raiz: texto(entrada.cwd) ?? process.cwd(), sessao: texto(entrada.session_id) ?? "",
+        ferramenta: texto(entrada.tool_name) ?? "", args: (entrada.tool_input ?? {}) };
+}
+export function edicoesDaChamada(c) {
+    const a = c.args;
+    if (c.ferramenta === "apply_patch") {
+        const patch = texto(a.command) ?? texto(a.patch) ?? "";
+        const edicoes = [];
+        let atual;
+        for (const linha of patch.split(/\r?\n/)) {
+            const inicio = /^\*\*\* (Update|Add|Delete) File: (.+)$/.exec(linha);
+            if (inicio) {
+                atual = { arquivo: resolve(c.raiz, inicio[2]), antes: inicio[1] === "Delete" ? undefined : "", depois: "" };
+                edicoes.push(atual);
+            }
+            else if (atual && linha.startsWith("*** Move to: ")) {
+                // Renomear afeta o arquivo inteiro, inclusive trechos fora dos hunks.
+                atual.antes = undefined;
+                edicoes.push({ arquivo: resolve(c.raiz, linha.slice(13)), origem: atual.arquivo });
+            }
+            else if (atual && !linha.startsWith("***")) {
+                if (atual.antes !== undefined && (linha.startsWith("-") || linha.startsWith(" ")))
+                    atual.antes += linha.slice(1) + "\n";
+                if (linha.startsWith("+") || linha.startsWith(" "))
+                    atual.depois += linha.slice(1) + "\n";
+            }
+        }
+        return edicoes;
+    }
+    const arquivo = texto(a.file_path) ?? texto(a.TargetFile) ?? texto(a.Path);
+    if (!arquivo)
+        return [];
+    const chunks = a.ReplacementChunks ?? a.edits;
+    if (Array.isArray(chunks))
+        return chunks.map(chunk => ({ arquivo: resolve(c.raiz, arquivo),
+            antes: texto(chunk.TargetContent ?? chunk.old_string), depois: texto(chunk.ReplacementContent ?? chunk.new_string) }));
+    return [{ arquivo: resolve(c.raiz, arquivo),
+            antes: texto(a.old_string) ?? texto(a.TargetContent),
+            depois: texto(a.new_string) ?? texto(a.content) ?? texto(a.ReplacementContent) ?? texto(a.CodeContent) }];
+}

package/dist/cli/src/escreve-config.js

@@ -112,7 +112,7 @@ export async function escrevePonteiro(raiz, arquivo) {
 }
 /** Compatibilidade: `init` ainda chama pelo nome antigo. */
 export const escreveAgents = (raiz) => escrevePonteiro(raiz, "AGENTS.md");
-const SUGESTAO_AGENTS = `## Protocolo do dd-harness
+export const SUGESTAO_AGENTS = `## Protocolo do dd-harness
 
 Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
 
@@ -124,6 +124,16 @@ de ler código, responder ou planejar.
   avise o usuário e **não modifique nada** até ele resolver.
 - Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
 
-Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
+Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
+
+Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
 desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
-válido — não crie fase sem o usuário pedir.`;
+válido — não crie fase sem o usuário pedir.
+
+E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
+ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
+já saiu errado, e é tarde.
+
+Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
+frase que antecede pular o procedimento. A política diz quais são obrigatórias
+e quando.`;

package/dist/cli/src/estado-local.js

@@ -0,0 +1,33 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, rename, writeFile, rm, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+/** Override explícito para testes e instalações isoladas; nunca troca HOME do processo. */
+export const diretorioDoUsuario = () => process.env.DD_HARNESS_HOME ?? join(homedir(), ".dd-harness");
+export function estadoDoRepo(raiz) {
+    const caminho = resolve(raiz);
+    const chave = createHash("sha256").update(process.platform === "win32" ? caminho.toLowerCase() : caminho).digest("hex");
+    return join(diretorioDoUsuario(), "repos", chave);
+}
+export async function revisaoDoContexto(raiz) {
+    return readFile(join(estadoDoRepo(raiz), "contexto-revisao"), "utf8").catch((e) => {
+        if (e.code === "ENOENT")
+            return "";
+        throw e;
+    });
+}
+export async function invalidaContexto(raiz) {
+    await escreveAtomico(join(estadoDoRepo(raiz), "contexto-revisao"), randomUUID());
+}
+/** Leitores veem o JSON anterior ou o novo, nunca um arquivo parcialmente escrito. */
+export async function escreveAtomico(caminho, conteudo) {
+    await mkdir(dirname(caminho), { recursive: true });
+    const temporario = `${caminho}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporario, conteudo, { encoding: "utf8", mode: 0o600 });
+        await rename(temporario, caminho);
+    }
+    finally {
+        await rm(temporario, { force: true });
+    }
+}

package/dist/cli/src/git.js

@@ -0,0 +1,67 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const roda = promisify(execFile);
+/** Ja e um repositorio? Responde pelo proprio git, nao pela existencia de `.git` — submodulo e worktree tem `.git` como ARQUIVO, e checar a pasta erraria nos dois. */
+export async function ehRepositorio(raiz) {
+    try {
+        const { stdout } = await roda("git", ["rev-parse", "--is-inside-work-tree"], { cwd: raiz });
+        return stdout.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Cria o repositorio, se ainda nao houver.
+ *
+ * Nao faz commit inicial: o que commitar e decisao de quem esta comecando o projeto, e um
+ * commit automatico com os arquivos que o `start` acabou de escrever criaria uma historia
+ * que ninguem pediu — inclusive num repositorio que a pessoa talvez queira que comece
+ * vazio.
+ *
+ * Nunca lanca. `start` nao pode falhar porque o git nao esta instalado.
+ */
+export async function iniciaRepositorio(raiz) {
+    if (await ehRepositorio(raiz))
+        return "ja-era";
+    try {
+        await roda("git", ["init"], { cwd: raiz });
+        return "criado";
+    }
+    catch (erro) {
+        return erro.code === "ENOENT" ? "git-indisponivel" : "falhou";
+    }
+}
+/**
+ * Escreve o gancho `post-commit`, que devolve a memoria ao code review.
+ *
+ * Ate aqui ele era IMPRESSO para a pessoa colar, pela regra de que `.git/hooks` nao e
+ * nosso. A regra continua valendo para repositorio que ja existia — mas num que o
+ * proprio `start` acabou de criar nao ha nada de ninguem para preservar, e imprimir
+ * instrucao que so vale se alguem copiar e colar e o mesmo "rode X depois" que a rodada
+ * 006 mostrou que ninguem segue.
+ *
+ * Nunca sobrescreve um gancho existente: ali ha trabalho de outra pessoa.
+ */
+export async function escreveGanchoDeCommit(raiz) {
+    const { join } = await import("node:path");
+    const { readFile, writeFile, chmod } = await import("node:fs/promises");
+    const caminho = join(raiz, ".git", "hooks", "post-commit");
+    try {
+        await readFile(caminho, "utf8");
+        return "ja-tinha";
+    }
+    catch {
+        // Sem gancho: escreve.
+    }
+    try {
+        // `|| true` porque aviso nao pode falhar um commit que ja aconteceu — o gancho roda
+        // DEPOIS, e sair diferente de zero aqui so polui a saida de quem commitou.
+        await writeFile(caminho, '#!/bin/sh\n# dd-harness: avisa quais memórias falam do que este commit mudou.\ndd-harness check --commit "$(git rev-parse HEAD)" || true\n', "utf8");
+        await chmod(caminho, 0o755);
+        return "criado";
+    }
+    catch {
+        return "falhou";
+    }
+}

package/dist/cli/src/gravar.js

@@ -1,7 +1,7 @@
+import { invalidaCache } from "./cinto.js";
 import { readFile } from "node:fs/promises";
 import { recusaPorAcentuacao } from "./acentuacao.js";
-import { cabecalhos, credencial, pede, recusa } from "./api.js";
-import { acrescentaAoCache } from "./cinto.js";
+import { jsonDaEscrita, cabecalhos, credencial, pede, recusa } from "./api.js";
 const OBRIGATORIOS = ["name", "titulo", "description", "pasta"];
 /**
  * Frontmatter simples: `chave: valor` por linha. Sem lib de YAML — nao ha aninhamento.
@@ -188,19 +188,9 @@ export async function grava(raiz, caminho) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    const { endereco } = (await resposta.json());
-    // O cinto passa a enxergar esta memoria AGORA, nao na proxima sessao. Sem isto, a
-    // memoria recem-gravada nao protegia nada ate a sessao seguinte — medido na rodada 006,
-    // e justamente no fluxo mais comum: gravar a decisao e, minutos depois, alguem tentar
-    // desfazer o que ela guarda.
-    await acrescentaAoCache(raiz, {
-        pasta: memoria.pasta,
-        slug: memoria.slug,
-        titulo: memoria.titulo,
-        resumo: memoria.resumo,
-        status: "ativa",
-        ancoras: memoria.ancoras.map((valor) => ({ tipo: "caminho", valor, sha: null })),
-    });
+    await invalidaCache(raiz);
+    const { endereco } = (await jsonDaEscrita(resposta));
+    // A próxima edição atualiza o cache inteiro, incluindo outras memórias e globais.
     return {
         endereco,
         ancoras: memoria.ancoras.length,