dd-harness-mcp 0.1.2 → 0.3.0

package/dist/cli/src/brain.js

@@ -0,0 +1,9 @@
+/**
+ * A forma do Brain no contrato `/api/v1`.
+ *
+ * So os tipos: o que o servico devolve, e o que o CLI le. Ate a fase 0 este modulo
+ * tambem transformava o payload em arquivos de disco — o `sync` materializava politica,
+ * briefing e o Brain inteiro no repositorio consumidor. Isso acabou: a politica chega
+ * pelo hook de sessao, e a memoria pela busca, na hora. Nada do dd-harness vive em disco.
+ */
+export {};

package/dist/cli/src/buscar.js

@@ -11,5 +11,10 @@ export async function busca(raiz, consulta, limite) {
     if (!resposta.ok)
         await recusa(resposta);
     const lido = (await resposta.json());
-    return { semantica: lido.semantica, provedor: lido.provedor, achados: lido.resultados };
+    return {
+        semantica: lido.semantica,
+        provedor: lido.provedor,
+        achados: lido.resultados,
+        esperandoIndexacao: lido.esperando_indexacao ?? 0,
+    };
 }

package/dist/cli/src/check.js

@@ -1,6 +1,6 @@
 import { pede } from "./api.js";
 import { leConfigDoRepo, leToken } from "./config.js";
-import { caminhosDoCommit, memoriasTocadas } from "./diff.js";
+import { caminhosDoCommit, memoriasTocadas, sugereReancoragem, } from "./diff.js";
 import { mede } from "./medir.js";
 /** Separado do IO para poder ser testado sem rede: dado um Brain, o que se mede. */
 export async function medeAsAncoras(raiz, brain) {
@@ -80,11 +80,26 @@ export async function check(raiz, commit) {
     const cabecalhos = { Authorization: `Bearer ${token}` };
     const medicoes = await medeAsAncoras(raiz, brain);
     // O cruzamento com o diff so faz sentido quando ha um commit para olhar.
-    const tocadas = commit
-        ? memoriasTocadas(brain, await caminhosDoCommit(raiz, commit))
-        : [];
+    const mudancas = commit
+        ? await caminhosDoCommit(raiz, commit)
+        : { caminhos: [], renames: [] };
+    const tocadas = commit ? memoriasTocadas(brain, mudancas.caminhos) : [];
+    // Para onde o alvo ausente foi. Sem `--commit` a lista de renames e vazia, entao isto
+    // devolve vazio sozinho — nao ha caso especial a escrever.
+    const reancoragens = sugereReancoragem(medicoes
+        .filter((m) => m.sha === null)
+        .map((m) => ({ pasta: m.pasta, memoria: m.memoria, valor: m.valor })), mudancas.renames);
     if (medicoes.length === 0) {
-        return { medidas: 0, ausentes: [], novas: 0, base: 0, jaAbertas: 0, fechadas: 0, tocadas };
+        return {
+            medidas: 0,
+            ausentes: [],
+            novas: 0,
+            base: 0,
+            jaAbertas: 0,
+            fechadas: 0,
+            tocadas,
+            reancoragens,
+        };
     }
     const envio = await pede(`${config.api}/api/v1/deriva`, {
         method: "POST",
@@ -111,5 +126,6 @@ export async function check(raiz, commit) {
         jaAbertas: julgamento.ja_abertas,
         fechadas: julgamento.fechadas ?? 0,
         tocadas,
+        reancoragens,
     };
 }

package/dist/cli/src/curar.js

@@ -1,37 +1,48 @@
 import { readFile } from "node:fs/promises";
-import { relative } from "node:path";
 import { cabecalhos, credencial, pede, recusa } from "./api.js";
-import { gravaManifesto, hashDe, leManifesto } from "./config.js";
 import { interpreta } from "./gravar.js";
 /**
- * Curadoria pelo agente: editar e arquivar.
+ * A memoria inteira, no markdown que `gravar` e `editar` consomem.
  *
- * `gravar` sabia criar e mais nada. Uma memoria errada ficava errada, porque corrigir
- * exigia abrir a interface — e o `CLAUDE.md` trata curadoria como obrigacao ("se
- * encontrar uma memoria obsoleta ou errada, corrija").
- *
- * Editar reaproveita o mesmo markdown de `gravar`, de proposito: o agente edita o arquivo
- * que o `sync` materializou e manda de volta. Um formato so para as duas operacoes, e o
- * que ele ja sabe ler.
- */
-/**
- * Depois que o servico aceita, o arquivo em disco deixa de ser "edicao nao enviada" — e o
- * manifesto tem que saber, senao o `sync` seguinte para com "editado a mao" e a unica saida
- * que resta e descartar o arquivo. O ciclo materializa-corrige-envia travava justamente
- * aqui, com o servico ja atualizado.
- *
- * Guarda o hash do que foi enviado, nao do que o servico devolveria: o `sync` seguinte
- * reescreve o arquivo na forma canonica quando o ETag mudar.
+ * Sem materializacao, esta e a unica forma de ler o corpo: a busca devolve so endereco,
+ * titulo e resumo, e o disco nao tem mais nada. Tambem e o ponto de partida de qualquer
+ * edicao — corrigir exige ver o que esta la.
  */
-async function marcaComoEnviado(raiz, caminho, conteudo) {
-    const chave = relative(raiz, caminho).split("\\").join("/");
-    const manifesto = await leManifesto(raiz);
-    // Arquivo de fora do repositorio (um rascunho em /tmp, por exemplo) nao esta no
-    // manifesto e nao deve entrar: o manifesto descreve o que o `sync` materializou.
-    if (!manifesto.arquivos[chave])
-        return;
-    manifesto.arquivos[chave] = hashDe(conteudo);
-    await gravaManifesto(raiz, manifesto);
+export async function le(raiz, endereco) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/memorias/${endereco}`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return comoMarkdown((await resposta.json()));
+}
+/** O formato canonico: o mesmo que `interpreta` le, para o ciclo fechar sem conversao. */
+export function comoMarkdown(m) {
+    const ancoras = m.ancoras.length
+        ? `\n## Âncoras\n\n${m.ancoras.map((a) => `- \`${a.valor}\``).join("\n")}\n`
+        : "";
+    return [
+        "---",
+        `name: ${m.slug}`,
+        `titulo: ${m.titulo}`,
+        `description: ${m.resumo}`,
+        `pasta: ${m.pasta}`,
+        ...(m.revisar_ate ? [`revisar-ate: ${m.revisar_ate.slice(0, 10)}`] : []),
+        "---",
+        "",
+        m.corpo.trim(),
+        "",
+        "## Os três filtros",
+        "",
+        `**Dano:** ${m.dano}`,
+        "",
+        `**Invisibilidade:** ${m.invisibilidade}`,
+        "",
+        `**Externalidade:** ${m.externalidade}`,
+        ancoras,
+    ].join("\n");
 }
 export async function edita(raiz, caminho) {
     const { config, token } = await credencial(raiz);
@@ -55,7 +66,6 @@ export async function edita(raiz, caminho) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    await marcaComoEnviado(raiz, caminho, cru);
     return { endereco, ancoras: memoria.ancoras.length };
 }
 export async function arquiva(raiz, endereco, opcoes) {

package/dist/cli/src/diff.js

@@ -2,31 +2,89 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const roda = promisify(execFile);
 /**
- * Quais memorias falam do que este commit mudou.
+ * O que um commit mudou: caminhos tocados e renames detectados.
  *
- * E a peca que devolve a memoria ao code review. Tirar o Brain do repositorio tirou o
- * revisor que o diff dava de graca — no modelo file-based a memoria estava ali, no
- * caminho de quem mexia. Aqui ela volta pelo cruzamento: caminho do diff contra ancora.
+ * `-M` liga a deteccao de rename por similaridade, e e o que torna a reancoragem
+ * possivel: sem ela, mover um arquivo aparece como um apagado mais um criado, e a ancora
+ * que apontava para o antigo so tem "alvo ausente" a dizer. Com ela, o git responde para
+ * ONDE o conteudo foi, com um percentual de confianca.
  *
- * Repare que isto NAO e deriva. Deriva e "o alvo mudou desde a linha de base"; isto e
- * "voce acabou de mexer no que esta memoria guarda" — util mesmo quando a base ainda
- * nem foi medida, e util mesmo que a memoria continue valendo.
+ * Vazio quando o git nao responde — nunca quebra: um aviso que nao pode ser dado nao vira
+ * erro que atrapalha o commit.
  */
-/** Caminhos alterados num commit. Vazio quando o git nao responde — nunca quebra. */
 export async function caminhosDoCommit(raiz, commit) {
     try {
-        const { stdout } = await roda("git", ["diff-tree", "--no-commit-id", "--name-only", "-r", commit], { cwd: raiz });
-        return stdout
-            .split(/\r?\n/)
-            .map((l) => l.trim())
-            .filter(Boolean);
+        const { stdout } = await roda("git", ["diff-tree", "--no-commit-id", "-r", "-M", "--name-status", commit], { cwd: raiz });
+        return interpretaNameStatus(stdout);
     }
     catch {
-        // Sem git, commit inexistente, repositorio raso: o cruzamento simplesmente nao
-        // acontece. Um aviso que nao pode ser dado nao vira erro que atrapalha o commit.
-        return [];
+        return { caminhos: [], renames: [] };
     }
 }
+/**
+ * Le a saida de `--name-status`: uma letra de status, TAB, e um ou dois caminhos.
+ *
+ * Rename vem como `R<similaridade>\t<de>\t<para>` (ex: `R094`), e conta como mudanca nos
+ * DOIS caminhos: quem tinha ancora no antigo precisa saber, e quem tem ancora no novo
+ * tambem — o conteudo chegou la.
+ */
+export function interpretaNameStatus(stdout) {
+    const caminhos = [];
+    const renames = [];
+    for (const linha of stdout.split(/\r?\n/)) {
+        if (!linha.trim())
+            continue;
+        const [status, primeiro, segundo] = linha.split("\t");
+        if (!status || !primeiro)
+            continue;
+        if (status.startsWith("R") && segundo) {
+            caminhos.push(primeiro, segundo);
+            renames.push({
+                de: primeiro,
+                para: segundo,
+                // `R094` -> 94. Sem numero (formatos antigos do git), 0 diz "nao sei o quanto".
+                similaridade: Number(status.slice(1)) || 0,
+            });
+            continue;
+        }
+        caminhos.push(primeiro);
+    }
+    return { caminhos, renames };
+}
+/**
+ * Cruza ancoras ausentes com os renames do commit.
+ *
+ * O caso que isto resolve: uma refatoracao move um arquivo (ou uma pasta inteira) e toda
+ * memoria ancorada ali passa a acusar "alvo ausente" de uma vez. A lista sozinha nao
+ * ajuda — o git sabe para onde o conteudo foi, e e essa a resposta que faltava.
+ *
+ * Ancora de trecho (`arquivo#alvo`) mantem o alvo na sugestao: o arquivo mudou de lugar,
+ * o trecho dentro dele provavelmente nao.
+ */
+export function sugereReancoragem(ausentes, renames) {
+    const sugestoes = [];
+    for (const ausente of ausentes) {
+        const corte = ausente.valor.indexOf("#");
+        const arquivo = corte === -1 ? ausente.valor : ausente.valor.slice(0, corte);
+        const trecho = corte === -1 ? "" : ausente.valor.slice(corte);
+        // Casa o arquivo exato ou um diretorio que o continha: mover `src/db/` inteiro
+        // renomeia cada arquivo dentro, e a ancora de diretorio precisa achar isso.
+        const rename = renames.find((r) => r.de === arquivo || arquivo.startsWith(`${r.de}/`));
+        if (!rename)
+            continue;
+        const destino = rename.de === arquivo
+            ? rename.para
+            : `${rename.para}${arquivo.slice(rename.de.length)}`;
+        sugestoes.push({
+            pasta: ausente.pasta,
+            memoria: ausente.memoria,
+            ancora: ausente.valor,
+            sugestao: `${destino}${trecho}`,
+            similaridade: rename.similaridade,
+        });
+    }
+    return sugestoes;
+}
 /**
  * Cruza caminhos com ancoras. A ancora casa quando e o proprio caminho ou quando e um
  * diretorio que o contem — `supabase/migrations` tem que casar com a migration nova.

package/dist/cli/src/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/cli/src/init.js

@@ -1,37 +1,72 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CAMINHO_CONFIG } from "./config.js";
-import { LINHA_DE_IMPORT } from "./materializa.js";
 /**
- * Prepara um repositorio para o dd-harness.
+ * O `.mcp.json` e sugerido, nunca escrito.
  *
- * Funciona nos dois casos, e o segundo e o que importa para a ambicao de adotar projeto
- * que ja existe: se nao ha `CLAUDE.md`, cria um com a linha de import; se **ja ha**,
- * acrescenta a linha ao que voce escreveu, sem tocar no resto. Adotar um projeto vira
- * uma linha, e nao um ritual de mover arquivo.
+ * 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.
  */
-const CABECALHO = `# CLAUDE.md
-
-Este arquivo é seu: escreva aqui o que for específico deste repositório.
-
-A linha abaixo importa a política gerenciada pelo dd-harness. **Não a remova** — sem
-ela a sessão abre sem protocolo, e nada avisa.
-`;
+export const SUGESTAO_MCP = `{
+  "mcpServers": {
+    "dd-harness": {
+      "command": "npx",
+      "args": ["-y", "dd-harness-mcp"]
+    }
+  }
+}`;
 /**
- * O `.mcp.json` e sugerido, nunca escrito.
+ * 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.
  *
- * 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.
+ * Sugerido e nao escrito, pelo mesmo motivo do `.mcp.json`.
  */
-export const SUGESTAO_MCP = `{
-  "mcpServers": {
-    "dd-harness": {
-      "command": "npx",
-      "args": ["-y", "dd-harness-mcp"]
-    }
-  }
+export const SUGESTAO_HOOK = `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dd-harness politica --hook",
+            "statusMessage": "Carregando a política do dd-harness..."
+          }
+        ]
+      }
+    ]
+  }
 }`;
+/**
+ * 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 const SUGESTAO_AGENTS = `# AGENTS.md
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  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.
+
+O Claude Code carrega a política sozinho, por hook. Nas outras ferramentas, a
+chamada acima é o que substitui esse hook.`;
 async function declaraMcp(raiz) {
     try {
         const cru = await readFile(join(raiz, ".mcp.json"), "utf8");
@@ -43,6 +78,26 @@ async function declaraMcp(raiz) {
         return "a-declarar";
     }
 }
+/**
+ * O hook ja esta declarado?
+ *
+ * Procura pelo COMANDO, nao pela forma: `settings.json` aceita varios formatos de
+ * matcher, e quem ja tem o hook pode te-lo escrito de outro jeito. O que importa e se
+ * `dd-harness politica` roda no inicio da sessao.
+ */
+async function declaraHook(raiz) {
+    for (const arquivo of [".claude/settings.json", ".claude/settings.local.json"]) {
+        try {
+            const cru = await readFile(join(raiz, arquivo), "utf8");
+            if (cru.includes("dd-harness politica"))
+                return "ja-declarado";
+        }
+        catch {
+            // Sem arquivo: segue para o proximo.
+        }
+    }
+    return "a-declarar";
+}
 export async function init(raiz, dados) {
     const caminhoConfig = join(raiz, CAMINHO_CONFIG);
     let config = "ja-existia";
@@ -58,27 +113,26 @@ export async function init(raiz, dados) {
         await writeFile(caminhoConfig, `${JSON.stringify(conteudo, null, 2)}\n`, "utf8");
         config = "criada";
     }
-    const caminhoClaude = join(raiz, "CLAUDE.md");
-    let claudeMd;
-    let atual = null;
+    return {
+        config,
+        mcp: await declaraMcp(raiz),
+        hook: await declaraHook(raiz),
+        agents: await apontaNoAgents(raiz),
+    };
+}
+/**
+ * O `AGENTS.md` ja manda buscar a politica?
+ *
+ * Procura pela CHAMADA (`ler_artefato`), nao por uma frase exata: quem ja escreveu a
+ * instrucao pode te-la redigido de outro jeito, e sugerir de novo por causa de palavra
+ * diferente e ruido.
+ */
+async function apontaNoAgents(raiz) {
     try {
-        atual = await readFile(caminhoClaude, "utf8");
+        const cru = await readFile(join(raiz, "AGENTS.md"), "utf8");
+        return cru.includes("ler_artefato") ? "ja-aponta" : "a-apontar";
     }
     catch {
-        atual = null;
-    }
-    if (atual === null) {
-        await writeFile(caminhoClaude, `${CABECALHO}\n${LINHA_DE_IMPORT}\n`, "utf8");
-        claudeMd = "criado";
-    }
-    else if (atual.includes(LINHA_DE_IMPORT)) {
-        claudeMd = "ja-tinha-a-linha";
-    }
-    else {
-        // Acrescenta no fim, sem reescrever nada do que ja estava la.
-        const separador = atual.endsWith("\n") ? "\n" : "\n\n";
-        await writeFile(caminhoClaude, `${atual}${separador}${LINHA_DE_IMPORT}\n`, "utf8");
-        claudeMd = "linha-acrescentada";
+        return "a-apontar";
     }
-    return { config, claudeMd, mcp: await declaraMcp(raiz) };
 }

package/dist/cli/src/politica.js

@@ -23,10 +23,11 @@ export async function buscaPolitica(raiz) {
         }
         const payload = (await resposta.json());
         const conteudo = payload.politica?.trim();
+        const esperandoIndexacao = payload.esperando_indexacao ?? 0;
         // Vazio e nulo sao a mesma coisa aqui, e os dois significam "nunca foi escrita".
         if (!conteudo)
-            return { estado: "sem-politica" };
-        return { estado: "ok", conteudo };
+            return { estado: "sem-politica", esperandoIndexacao };
+        return { estado: "ok", conteudo, esperandoIndexacao };
     }
     catch (erro) {
         return { estado: "inalcancavel", motivo: mensagem(erro) };

package/dist/cli/src/reancorar.js

@@ -0,0 +1,48 @@
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import {} from "./curar.js";
+/**
+ * Trocar o alvo de uma ancora, sem reescrever a memoria.
+ *
+ * O caso: uma refatoracao move um arquivo, e toda memoria ancorada nele passa a acusar
+ * "alvo ausente". O `check --commit` cruza isso com os renames do git e diz para onde o
+ * conteudo foi; este comando aplica a troca.
+ *
+ * Separado de `editar` de proposito: editar exige o markdown inteiro e mexe no conteudo,
+ * que nao e o que mudou aqui. Reancorar troca um endereco e mais nada — misturar as duas
+ * coisas convidaria a reescrever o corpo de memoria enquanto se conserta um caminho.
+ */
+export async function reancora(raiz, endereco, de, para) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/memorias/${endereco}`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    const leitura = await pede(url, { headers: cabecalhos(token) });
+    if (!leitura.ok)
+        await recusa(leitura);
+    const memoria = (await leitura.json());
+    if (!memoria.ancoras.some((a) => a.valor === de)) {
+        throw new Error(`${endereco} não tem âncora em "${de}". Âncoras atuais: ` +
+            (memoria.ancoras.map((a) => a.valor).join(", ") || "nenhuma"));
+    }
+    const novas = memoria.ancoras.map((a) => (a.valor === de ? { ...a, valor: para } : a));
+    // Reaproveita o PATCH de edicao: ele recebe a memoria inteira, entao mandamos o que ja
+    // estava la com a ancora trocada. Uma porta so para escrever memoria, e nao duas.
+    const envio = await pede(`${config.api}/api/v1/memorias/${endereco}`, {
+        method: "PATCH",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            titulo: memoria.titulo,
+            resumo: memoria.resumo,
+            corpo: memoria.corpo,
+            dano: memoria.dano,
+            invisibilidade: memoria.invisibilidade,
+            externalidade: memoria.externalidade,
+            ancoras: novas.map((a) => a.valor),
+        }),
+    });
+    if (!envio.ok)
+        await recusa(envio);
+    return { endereco, de, para };
+}

package/dist/cli/src/worker.js

@@ -0,0 +1,65 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Subir o worker de embeddings quando ha fila esperando.
+ *
+ * O worker nao esta hospedado (decisao de custo, registrada no ROADMAP): roda local, a
+ * mao. O problema disso e a degradacao SILENCIOSA — a memoria e gravada, a busca responde
+ * `semantica: true` porque a CONSULTA foi vetorizada, e mesmo assim nao acha nada, porque
+ * a BASE ainda nao tem vetor. Quem procura conclui "nao existe" quando o certo era
+ * "ainda nao indexei".
+ *
+ * Por isso o hook de sessao sobe o worker sozinho. Duas travas, e as duas importam:
+ *
+ * - **So sobe quando ha fila.** O hook roda em TODA sessao, inclusive nas que so leem
+ *   codigo. Subir com a fila vazia gastaria chamada de embedding sem ninguem ter pedido.
+ * - **So no repositorio que TEM o worker.** Ele vive neste monorepo, nao no repositorio
+ *   consumidor: la o `pnpm worker` nao existe, e tentar rodar daria erro a cada sessao.
+ */
+/** O worker vive aqui dentro. Noutro repositorio, nao ha o que subir. */
+export async function temWorkerLocal(raiz) {
+    try {
+        await access(join(raiz, "src", "worker", "indexador.ts"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Dispara um lote e devolve na hora — nao espera terminar.
+ *
+ * `--uma-vez` e nao o modo continuo: o hook de sessao nao pode deixar processo de pe que
+ * ninguem mandou subir, e um lote basta para o caso comum (as memorias gravadas na sessao
+ * anterior). Fila grande volta a aparecer na proxima sessao, e ai o numero cresce em vez
+ * de sumir — que e o sinal de que esta na hora de hospedar de verdade.
+ *
+ * `unref()` solta o processo do pai: sem isso o hook so retornaria quando o worker
+ * terminasse, e a sessao ficaria esperando embedding para abrir.
+ */
+export async function subiuOWorker(raiz, esperando) {
+    if (esperando <= 0)
+        return { subiu: false, motivo: "sem-fila" };
+    if (!(await temWorkerLocal(raiz))) {
+        return { subiu: false, motivo: "sem-worker" };
+    }
+    try {
+        const filho = spawn("npx", ["pnpm@latest", "worker", "--uma-vez"], {
+            cwd: raiz,
+            detached: true,
+            stdio: "ignore",
+            shell: process.platform === "win32",
+            windowsHide: true,
+        });
+        filho.unref();
+        return { subiu: true };
+    }
+    catch (erro) {
+        return {
+            subiu: false,
+            motivo: "falhou",
+            detalhe: erro instanceof Error ? erro.message : String(erro),
+        };
+    }
+}

package/dist/mcp/src/index.js

@@ -5,7 +5,7 @@ import * as z from "zod/v4";
 // que e gerado por build e nao vai no git — num checkout limpo (a Vercel) a resolucao
 // falharia, e foi assim que o build de producao caiu uma vez. Aqui o compilador segue o
 // fonte, e o `dist` deste pacote sai com o codigo do CLI embutido.
-import { arquiva, edita } from "../../cli/src/curar.js";
+import { arquiva, edita, le } from "../../cli/src/curar.js";
 import { busca } from "../../cli/src/buscar.js";
 import { criaPasta } from "../../cli/src/pasta.js";
 import { criaProjeto } from "../../cli/src/projeto.js";
@@ -22,8 +22,8 @@ import { grava } from "../../cli/src/gravar.js";
  * na skill: quem nunca leu a skill descobre a regra por 422. Aqui eles vao na descricao da
  * ferramenta, que e onde o agente olha antes de tentar.
  *
- * `init`, `sync`, `login` e `check` ficam de fora de proposito: sao bootstrap e fluxo de
- * quem esta no terminal, e materializar arquivo nao e trabalho de ferramenta de sessao.
+ * `init`, `login` e `check` ficam de fora de proposito: sao bootstrap e fluxo de quem
+ * esta no terminal, nao trabalho de ferramenta de sessao.
  */
 /** Tudo roda contra o repositorio de onde o host lancou o servidor. */
 const raiz = process.cwd();
@@ -34,20 +34,20 @@ const falha = (erro) => ({
     ],
     isError: true,
 });
-const FILTROS = `Os três filtros são CONJUNTIVOS: a memória só nasce se os três valerem, e o banco recusa quem não passa.
-- dano: se ninguém souber disto, alguém desfaz e QUEBRA algo? "é interessante de saber" não é dano.
-- invisibilidade: o próprio repositório já conta (um config, uma dependência, um teste, um nome bem escolhido)? Se conta, NÃO grave. "eu explico melhor que o código" não é invisibilidade.
-- externalidade: a razão vem de FORA do código — sistema legado, compliance, limite de fornecedor, número mágico, bug de terceiro? "foi uma decisão difícil" não é externalidade.
+const FILTROS = `Os três filtros são CONJUNTIVOS: a memória só nasce se os três valerem, e o banco recusa quem não passa.
+- dano: se ninguém souber disto, alguém desfaz e QUEBRA algo? "é interessante de saber" não é dano.
+- invisibilidade: o próprio repositório já conta (um config, uma dependência, um teste, um nome bem escolhido)? Se conta, NÃO grave. "eu explico melhor que o código" não é invisibilidade.
+- externalidade: a razão vem de FORA do código — sistema legado, compliance, limite de fornecedor, número mágico, bug de terceiro? "foi uma decisão difícil" não é externalidade.
 Decisão difícil e reversível não vira memória — vira commit. Cada campo exige no mínimo 10 caracteres de justificativa real.`;
 function criaServidor() {
     const server = new McpServer({ name: "dd-harness", version: "0.1.0" });
     server.registerTool("buscar_memoria", {
-        description: `Procura no Brain do projeto por relevância e devolve endereço, título e resumo — não o corpo. Use quando estiver entendendo um problema e ainda não souber que arquivo abrir ("o que já aprendemos sobre isto?").
-
-Para ler o corpo de um achado, abra o arquivo que o \`dd-harness sync\` materializou em \`dd-harness/brain/<endereço>.md\`.
-
-A busca combina semântica e lexical e tem piso de similaridade: quando nada é pertinente ela devolve lista vazia em vez de inventar o vizinho mais próximo. Lista vazia é resposta, não falha.
-
+        description: `Procura no Brain do projeto por relevância e devolve endereço, título e resumo — não o corpo. Use quando estiver entendendo um problema e ainda não souber que arquivo abrir ("o que já aprendemos sobre isto?").
+
+Para ler o corpo de um achado, use \`ler_memoria\` com o endereço. O Brain não existe em disco: nada de procurar arquivo.
+
+A busca combina semântica e lexical e tem piso de similaridade: quando nada é pertinente ela devolve lista vazia em vez de inventar o vizinho mais próximo. Lista vazia é resposta, não falha.
+
 Os primeiros achados são os que valem: o piso barra tema alheio, mas num Brain temático a relevância decai de forma contínua, sem corte óbvio. Leia de cima para baixo e pare quando deixar de fazer sentido.`,
         inputSchema: z.object({
             consulta: z
@@ -81,41 +81,63 @@ Os primeiros achados são os que valem: o piso barra tema alheio, mas num Brain
         }
     });
     server.registerTool("gravar_memoria", {
-        description: `Registra uma memória nova no Brain do projeto. O default é NÃO gravar: proponha ao humano antes, e grave o que ele aprovar.
-
-${FILTROS}
-
-A pasta precisa existir antes — use \`criar_pasta\`. Essa recusa é deliberada: ela impede um typo virar pasta nova em silêncio.
-
-Âncoras (opcional) amarram a memória ao código, e são o que faz a memória ser recuperada quando alguém mexe naquele ponto. Caminho relativo à raiz, sem \`..\` e sem separador do Windows. Duas formas:
-
-- \`src/api/encurtar.js\` — o arquivo inteiro. Use quando a memória fala do arquivo como um todo.
+        description: `Registra uma memória nova no Brain do projeto. O default é NÃO gravar: proponha ao humano antes, e grave o que ele aprovar.
+
+${FILTROS}
+
+A pasta precisa existir antes — use \`criar_pasta\`. Essa recusa é deliberada: ela impede um typo virar pasta nova em silêncio.
+
+Âncoras (opcional) amarram a memória ao código, e são o que faz a memória ser recuperada quando alguém mexe naquele ponto. Caminho relativo à raiz, sem \`..\` e sem separador do Windows. Duas formas:
+
+- \`src/api/encurtar.js\` — o arquivo inteiro. Use quando a memória fala do arquivo como um todo.
 - \`src/api/encurtar.js#readFileSync\` — só as linhas que contêm \`readFileSync\`. PREFIRA esta: quando várias memórias dividem um arquivo, a âncora de arquivo acusa todas a cada mudança em qualquer parte dele, e o aviso perde valor. Escolha um texto estável e específico do que a memória descreve (um nome de função, uma constante, uma chave de config) — não um trecho que a próxima refatoração reescreve à toa.`,
         inputSchema: z.object({
             arquivo: z
                 .string()
                 .min(1)
-                .describe("Caminho de um .md no formato que o sync materializa: frontmatter com name/titulo/description/pasta, corpo, e a seção `## Os três filtros` com **Dano:**, **Invisibilidade:** e **Externalidade:**. Âncoras vão numa seção `## Âncoras` como itens de lista."),
+                .describe("Caminho de um .md neste formato: frontmatter com name/titulo/description/pasta, corpo, e a seção `## Os três filtros` com **Dano:**, **Invisibilidade:** e **Externalidade:**. Âncoras vão numa seção `## Âncoras` como itens de lista."),
         }),
     }, async ({ arquivo }) => {
         try {
             const r = await grava(raiz, arquivo);
             return texto(`Gravado ${r.endereco} — ${r.ancoras} âncora(s), valendo para ${r.projetos} projeto(s).\n` +
-                "Rode `dd-harness sync` para materializar, e `pnpm worker --uma-vez` para entrar na busca semântica.");
+                "Rode `pnpm worker --uma-vez` para ela entrar na busca semântica.");
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
+    server.registerTool("ler_memoria", {
+        description: `Devolve uma memória inteira — corpo, filtros e âncoras — pelo endereço \`<pasta>/<slug>\`.
+
+Use depois de \`buscar_memoria\`, que devolve só título e resumo: é aqui que está o conteúdo. O Brain não vive em disco, então este é o único caminho para o corpo — não procure arquivo.
+
+Também é o ponto de partida obrigatório de \`editar_memoria\`: o formato devolvido é o mesmo que ela consome.`,
+        inputSchema: z.object({
+            endereco: z
+                .string()
+                .min(1)
+                .describe("`<pasta>/<slug>`, como `buscar_memoria` devolveu."),
+        }),
+    }, async ({ endereco }) => {
+        try {
+            return texto(await le(raiz, endereco));
         }
         catch (erro) {
             return falha(erro);
         }
     });
     server.registerTool("editar_memoria", {
-        description: `Corrige uma memória que já existe, pelo mesmo formato markdown de \`gravar_memoria\`. O endereço sai do frontmatter (pasta + name), então edite o arquivo que o \`sync\` materializou.
-
+        description: `Corrige uma memória que já existe, pelo mesmo formato markdown de \`gravar_memoria\`. O endereço sai do frontmatter (pasta + name).
+
+Comece por \`ler_memoria\`: ela devolve exatamente este formato, e o Brain não existe em disco — sem ler antes, você estaria reescrevendo de memória e apagaria o que não lembrasse. Salve o resultado num arquivo, edite, e passe o caminho aqui.
+
 Os três filtros continuam valendo na edição — o banco recusa igual. ${FILTROS}`,
         inputSchema: z.object({
             arquivo: z
                 .string()
                 .min(1)
-                .describe("Caminho do .md da memória, normalmente `dd-harness/brain/<pasta>/<slug>.md`."),
+                .describe("Caminho do .md com a memória corrigida (um arquivo temporário serve)."),
         }),
     }, async ({ arquivo }) => {
         try {
@@ -127,8 +149,8 @@ Os três filtros continuam valendo na edição — o banco recusa igual. ${FILTR
         }
     });
     server.registerTool("arquivar_memoria", {
-        description: `Arquiva uma memória. Nunca apaga: ela sai do Brain ativo e migra para a seção \`## Histórico\` do índice, com o motivo registrado.
-
+        description: `Arquiva uma memória. Nunca apaga: ela sai do Brain ativo e migra para a seção \`## Histórico\` do índice, com o motivo registrado.
+
 Use \`substituida_por\` quando outra memória toma o lugar desta — a troca acontece numa transação só, e o histórico aponta para a sucessora.`,
         inputSchema: z.object({
             endereco: z
@@ -154,12 +176,12 @@ Use \`substituida_por\` quando outra memória toma o lugar desta — a troca aco
         }
     });
     server.registerTool("criar_projeto", {
-        description: `Cria um projeto no serviço — o espaço onde as pastas e memórias deste repositório vão morar.
-
-Use quando estiver começando num repositório que ainda não tem \`.dd-harness.json\`, ANTES de \`dd-harness init\`: o init escreve a configuração apontando para um projeto, e apontar para um que não existe deixa todo comando seguinte em 404.
-
-O \`slug\` é a chave que o repositório guarda, e é único por espaço — renomear depois quebraria o ponteiro, então escolha pensando nisso. O \`nome\` é livre e editável, é o que aparece na interface.
-
+        description: `Cria um projeto no serviço — o espaço onde as pastas e memórias deste repositório vão morar.
+
+Use quando estiver começando num repositório que ainda não tem \`.dd-harness.json\`, ANTES de \`dd-harness init\`: o init escreve a configuração apontando para um projeto, e apontar para um que não existe deixa todo comando seguinte em 404.
+
+O \`slug\` é a chave que o repositório guarda, e é único por espaço — renomear depois quebraria o ponteiro, então escolha pensando nisso. O \`nome\` é livre e editável, é o que aparece na interface.
+
 O ESPAÇO (tenant) não se cria por aqui, de propósito: ele é a fronteira de isolamento entre pessoas, e isso é decisão do dono. Se não houver espaço nenhum, pare e peça que ele crie pela interface.`,
         inputSchema: z.object({
             slug: z
@@ -184,10 +206,10 @@ O ESPAÇO (tenant) não se cria por aqui, de propósito: ele é a fronteira de i
         }
     });
     server.registerTool("criar_pasta", {
-        description: `Cria uma pasta temática no Brain. \`gravar_memoria\` recusa quando a pasta não existe, e esta é a saída.
-
-A pasta é deste projeto, nomeada pelo domínio dele. Antes de criar uma nova, prefira ENCAIXAR numa que já existe (leia as definições das atuais): pasta de um arquivo só fragmenta o índice e sai do radar. Pasta nova exige que a memória não caiba em nenhuma existente E que você consiga nomear outra memória futura plausível que cairia nela.
-
+        description: `Cria uma pasta temática no Brain. \`gravar_memoria\` recusa quando a pasta não existe, e esta é a saída.
+
+A pasta é deste projeto, nomeada pelo domínio dele. Antes de criar uma nova, prefira ENCAIXAR numa que já existe (leia as definições das atuais): pasta de um arquivo só fragmenta o índice e sai do radar. Pasta nova exige que a memória não caiba em nenhuma existente E que você consiga nomear outra memória futura plausível que cairia nela.
+
 Criar uma que já existe não é erro: devolve que já existia, sem alterar a definição.`,
         inputSchema: z.object({
             slug: z
@@ -211,11 +233,11 @@ Criar uma que já existe não é erro: devolve que já existia, sem alterar a de
         }
     });
     server.registerTool("ler_artefato", {
-        description: `Lê a política ou o briefing do projeto direto do serviço.
-
-- \`politica\`: as regras que valem neste projeto — proibições, o protocolo antes de implementar, o que exige autorização. É o que o \`CLAUDE.md\` do repositório importa.
-- \`briefing\`: o retrato estável do projeto — stack, objetivo, restrições.
-
+        description: `Lê a política ou o briefing do projeto direto do serviço.
+
+- \`politica\`: as regras que valem neste projeto — proibições, o protocolo antes de implementar, o que exige autorização. É o que o \`CLAUDE.md\` do repositório importa.
+- \`briefing\`: o retrato estável do projeto — stack, objetivo, restrições.
+
 Devolve vazio quando o artefato ainda não existe. Vazio não é erro: projeto novo nasce assim, e a saída é escrever o primeiro conteúdo, não investigar falha.`,
         inputSchema: z.object({
             tipo: z
@@ -235,10 +257,10 @@ Devolve vazio quando o artefato ainda não existe. Vazio não é erro: projeto n
         }
     });
     server.registerTool("escrever_artefato", {
-        description: `Substitui a política ou o briefing do projeto. Proponha ao humano antes: a política é a regra que governa as próprias sessões, e trocá-la sem combinar muda o que vale para todo mundo que abrir este repositório.
-
-SUBSTITUIÇÃO TOTAL, não acréscimo. O conteúdo enviado passa a ser o artefato inteiro — para acrescentar um parágrafo, use \`ler_artefato\` primeiro, junte o que falta e mande o texto completo. Mandar só o trecho novo APAGA o resto.
-
+        description: `Substitui a política ou o briefing do projeto. Proponha ao humano antes: a política é a regra que governa as próprias sessões, e trocá-la sem combinar muda o que vale para todo mundo que abrir este repositório.
+
+SUBSTITUIÇÃO TOTAL, não acréscimo. O conteúdo enviado passa a ser o artefato inteiro — para acrescentar um parágrafo, use \`ler_artefato\` primeiro, junte o que falta e mande o texto completo. Mandar só o trecho novo APAGA o resto.
+
 Conteúdo vazio é válido e significa apagar o artefato.`,
         inputSchema: z.object({
             tipo: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-harness-mcp",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Servidor MCP do dd-harness: o agente consulta e grava memoria como ferramenta, sem passar por arquivo.",
   "license": "UNLICENSED",