dd-harness-mcp 0.1.0

package/dist/cli/src/index.js

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+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 { busca } from "./buscar.js";
+import { arquiva, edita } from "./curar.js";
+import { criaPasta } from "./pasta.js";
+import { criaProjeto } from "./projeto.js";
+import { sync } from "./sync.js";
+/**
+ * `dd-harness` — o cliente que materializa os artefatos no repositorio.
+ *
+ * Sem dependencia de proposito: `fetch`, `crypto` e `fs` sao do Node, e o molde original
+ * ja seguia a regra de validador determinístico sem dependencia. Um CLI que vive pinado
+ * 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 --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}
+`;
+/** 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.`;
+function argumento(argv, nome) {
+    const i = argv.indexOf(`--${nome}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+async function comandoInit(argv) {
+    const tenant = argumento(argv, "tenant");
+    const projeto = argumento(argv, "projeto");
+    if (!tenant || !projeto) {
+        throw new Error("uso: dd-harness init --tenant <t> --projeto <p> [--api <url>]");
+    }
+    const r = await init(process.cwd(), {
+        tenant,
+        projeto,
+        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");
+    if (r.mcp === "ja-declarado") {
+        console.log("\nmantido .mcp.json — o servidor dd-harness já está declarado");
+        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);
+}
+/**
+ * Nao exige `.dd-harness.json`, e isso importa: sem projeto no servico o `init` nao tem o
+ * que apontar, criar projeto exige credencial, e credencial exigindo config fechava um
+ * ciclo sem entrada — no dia um de um repositorio novo, nenhum dos tres rodava. O `--api`
+ * resolve; com config no repo, ela preenche.
+ */
+async function comandoLogin(argv) {
+    const token = argumento(argv, "token");
+    if (!token)
+        throw new Error("uso: dd-harness login --token <token> [--api <url>]");
+    const daLinha = argumento(argv, "api");
+    const doRepo = daLinha ? null : await leConfigDoRepo(process.cwd()).catch(() => null);
+    const api = (daLinha ?? doRepo?.api ?? "https://dd-harness.vercel.app").replace(/\/$/, "");
+    const caminho = await guardaToken(api, token);
+    console.log(`credencial de ${api} guardada em ${caminho}`);
+}
+async function comandoEditar(argv) {
+    const caminho = argv[0];
+    if (!caminho || caminho.startsWith("-")) {
+        throw new Error("uso: dd-harness editar <arquivo.md>");
+    }
+    const r = await edita(process.cwd(), caminho);
+    console.log(`editado  ${r.endereco}`);
+    console.log(`  ${r.ancoras} âncora(s). Rode \`dd-harness sync\` para materializar.`);
+}
+const MOTIVOS = ["obsoleta", "incorreta", "fora_dos_filtros"];
+async function comandoArquivar(argv) {
+    const endereco = argv[0];
+    const motivo = argumento(argv, "motivo");
+    if (!endereco || endereco.startsWith("-") || !endereco.includes("/")) {
+        throw new Error("uso: dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>");
+    }
+    // Lista fechada tambem no cliente: errar o motivo aqui devolve a lista, em vez de um
+    // 400 do servidor com a mesma informacao mais longe de quem digitou.
+    if (!motivo || !MOTIVOS.includes(motivo)) {
+        throw new Error(`--motivo precisa ser um de: ${MOTIVOS.join(", ")}`);
+    }
+    const r = await arquiva(process.cwd(), endereco, {
+        motivo: motivo,
+        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`.");
+}
+async function comandoBuscar(argv) {
+    const consulta = argv.filter((a) => !a.startsWith("--")).join(" ").trim();
+    if (!consulta)
+        throw new Error('uso: dd-harness buscar "<pergunta>"');
+    const limite = Number(argumento(argv, "limite")) || undefined;
+    const r = await busca(process.cwd(), consulta, limite);
+    if (!r.achados.length) {
+        console.log("nada encontrado.");
+        // Sem esta linha, "nada encontrado" vira "nao existe" — quando pode ser so a
+        // semantica desligada, e a memoria estar la com outras palavras.
+        if (!r.semantica) {
+            console.log("  (só busca textual: sem provedor de embedding no serviço)");
+        }
+        return;
+    }
+    console.log(r.semantica
+        ? `${r.achados.length} resultado(s) — busca híbrida (${r.provedor}):`
+        : `${r.achados.length} resultado(s) — só textual, sem semântica:`);
+    for (const a of r.achados) {
+        console.log(`  ${a.endereco} — ${a.titulo}`);
+        console.log(`    ${a.resumo}`);
+    }
+}
+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;
+        return;
+    }
+    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);
+}
+async function comandoCheck(argv) {
+    const r = await check(process.cwd(), argumento(argv, "commit"));
+    if (r.medidas === 0) {
+        console.log("nenhuma âncora para medir.");
+        return;
+    }
+    console.log(`medidas ${r.medidas} âncora(s).`);
+    if (r.base > 0) {
+        console.log(`  ${r.base} medida(s) pela primeira vez — viraram linha de base.`);
+    }
+    // Ausente e alterado nao pesam igual: o alvo ter sumido e sinal forte, e some no meio
+    // do ruido se for anunciado do mesmo jeito que "mudou".
+    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)
+            console.log(`  ${valor}`);
+    }
+    if (r.novas > 0) {
+        console.log("");
+        console.log(`${r.novas} deriva(s) nova(s) registrada(s) no serviço.`);
+    }
+    if (r.jaAbertas > 0) {
+        console.log(`${r.jaAbertas} já estava(m) aberta(s) — nada novo, só o carimbo.`);
+    }
+    // Reverter uma mudanca fecha a observacao que ela abriu. Anunciar isso importa: sem a
+    // linha, a fila encolhe sem explicacao e quem olha o `status` acha que perdeu algo.
+    if (r.fechadas > 0) {
+        console.log(`${r.fechadas} deriva(s) fechada(s): o alvo voltou a bater com a linha de base.`);
+    }
+    if (!r.ausentes.length && r.novas === 0 && r.jaAbertas === 0 && r.fechadas === 0) {
+        console.log("nenhuma deriva: o mundo ainda bate com o que as memórias dizem.");
+    }
+    // O cruzamento com o diff e outra coisa que deriva: e "voce acabou de mexer no que
+    // esta memoria guarda". Vale mesmo quando a memoria continua valendo — e o revisor
+    // que o modelo file-based dava de graca, e que centralizar tinha tirado.
+    if (r.tocadas.length) {
+        console.log("");
+        console.log("Este commit mexeu no que estas memórias guardam:");
+        for (const t of r.tocadas) {
+            console.log(`  ${t.pasta}/${t.memoria} — ${t.titulo}`);
+            console.log(`    âncora: ${t.ancora}`);
+        }
+    }
+}
+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?",
+    // que era a pergunta sem comando. Sem ela, quem quer saber conta arquivo em disco — e
+    // acerta por acidente, porque memoria arquivada sai do disco e continua no indice.
+    const { ativas, arquivadas, porPasta } = r.acervo;
+    if (ativas === 0 && arquivadas === 0) {
+        console.log("dd-harness: o Brain deste projeto está vazio.");
+    }
+    else {
+        const detalhe = porPasta.map((p) => `${p.pasta} ${p.quantas}`).join(", ");
+        console.log(`dd-harness: ${ativas} memória(s) ativa(s)` +
+            (arquivadas ? ` e ${arquivadas} arquivada(s)` : "") +
+            (detalhe ? ` — ${detalhe}` : ""));
+    }
+    if (!r.comDeriva.length && !r.vencidas.length) {
+        console.log("Nada esperando julgamento.");
+        return;
+    }
+    console.log("");
+    if (r.comDeriva.length) {
+        const total = r.comDeriva.reduce((soma, m) => soma + m.abertas, 0);
+        console.log(`dd-harness: ${total} deriva(s) aberta(s), esperando julgamento:`);
+        for (const m of r.comDeriva) {
+            console.log(`  ${m.pasta}/${m.memoria} — ${m.titulo} (${m.abertas})`);
+        }
+    }
+    if (r.vencidas.length) {
+        console.log("");
+        console.log("Memórias com revisão vencida:");
+        for (const m of r.vencidas)
+            console.log(`  ${m.pasta}/${m.memoria} — ${m.titulo}`);
+    }
+}
+/**
+ * Vem ANTES do `init`, e nao depois: o `init` escreve o `.dd-harness.json` apontando para
+ * um projeto, e apontar para projeto que nao existe deixaria todo comando seguinte em 404.
+ */
+async function comandoProjeto(argv) {
+    const slug = argv[0];
+    const nome = argumento(argv, "nome");
+    if (!slug || slug.startsWith("-") || !nome) {
+        throw new Error('uso: dd-harness projeto <slug> --nome "<nome>" [--tenant <slug>] [--api <url>]');
+    }
+    const r = await criaProjeto(process.cwd(), slug, nome, {
+        tenant: argumento(argv, "tenant"),
+        api: argumento(argv, "api"),
+    });
+    console.log(r.jaExistia
+        ? `projeto ${r.projeto} já existia — nada criado.`
+        : `criado  projeto ${r.projeto}.`);
+    console.log(`Agora: dd-harness init --tenant <espaço> --projeto ${r.projeto}`);
+}
+async function comandoPasta(argv) {
+    const slug = argv[0];
+    const definicao = argumento(argv, "definicao");
+    if (!slug || slug.startsWith("-") || !definicao) {
+        throw new Error('uso: dd-harness pasta <slug> --definicao "o que entra e o que não entra"');
+    }
+    const r = await criaPasta(process.cwd(), slug, definicao);
+    console.log(r.jaExistia
+        ? `pasta ${r.pasta} já existia — nada criado.`
+        : `criada  pasta ${r.pasta}. Agora \`dd-harness gravar <arquivo.md>\` aceita \`pasta: ${r.pasta}\`.`);
+}
+/**
+ * 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.
+ */
+async function comandoGravar(argv) {
+    const caminho = argv[0];
+    if (!caminho || caminho.startsWith("-")) {
+        throw new Error("uso: dd-harness gravar <arquivo.md>");
+    }
+    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.");
+}
+async function principal() {
+    const [comando, ...resto] = process.argv.slice(2);
+    switch (comando) {
+        case "init":
+            return comandoInit(resto);
+        case "login":
+            return comandoLogin(resto);
+        case "projeto":
+            return comandoProjeto(resto);
+        case "pasta":
+            return comandoPasta(resto);
+        case "gravar":
+            return comandoGravar(resto);
+        case "editar":
+            return comandoEditar(resto);
+        case "arquivar":
+            return comandoArquivar(resto);
+        case "buscar":
+            return comandoBuscar(resto);
+        case "sync":
+            return comandoSync();
+        case "check":
+            return comandoCheck(resto);
+        case "status":
+            return comandoStatus();
+        case "--help":
+        case "-h":
+        case undefined:
+            console.log(AJUDA);
+            return;
+        default:
+            throw new Error(`comando desconhecido: ${comando}`);
+    }
+}
+principal().catch((erro) => {
+    console.error(erro instanceof Error ? erro.message : String(erro));
+    process.exitCode = 1;
+});

package/dist/cli/src/init.js

@@ -0,0 +1,84 @@
+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.
+ *
+ * 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.
+ */
+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.
+`;
+/**
+ * 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.
+ */
+export const SUGESTAO_MCP = `{
+  "mcpServers": {
+    "dd-harness": {
+      "command": "npx",
+      "args": ["-y", "dd-harness-mcp"]
+    }
+  }
+}`;
+async function declaraMcp(raiz) {
+    try {
+        const cru = await readFile(join(raiz, ".mcp.json"), "utf8");
+        const lido = JSON.parse(cru);
+        return lido.mcpServers?.["dd-harness"] ? "ja-declarado" : "a-declarar";
+    }
+    catch {
+        // Sem arquivo, ou JSON que nao interpreta: nos dois casos ha o que sugerir.
+        return "a-declarar";
+    }
+}
+export async function init(raiz, dados) {
+    const caminhoConfig = join(raiz, CAMINHO_CONFIG);
+    let config = "ja-existia";
+    try {
+        await readFile(caminhoConfig, "utf8");
+    }
+    catch {
+        const conteudo = {
+            ...(dados.api ? { api: dados.api } : {}),
+            tenant: dados.tenant,
+            projeto: dados.projeto,
+        };
+        await writeFile(caminhoConfig, `${JSON.stringify(conteudo, null, 2)}\n`, "utf8");
+        config = "criada";
+    }
+    const caminhoClaude = join(raiz, "CLAUDE.md");
+    let claudeMd;
+    let atual = null;
+    try {
+        atual = await readFile(caminhoClaude, "utf8");
+    }
+    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 { config, claudeMd, mcp: await declaraMcp(raiz) };
+}

package/dist/cli/src/materializa.js

@@ -0,0 +1,132 @@
+/**
+ * Do payload do contrato para arquivos em disco.
+ *
+ * Funcao pura de proposito: recebe o Brain e devolve caminho -> conteudo, sem rede e sem
+ * `fs`. E a parte que precisa de teste — o formato tem que casar com o que o
+ * `validate_brain.cjs` do molde espera (frontmatter `name` igual ao arquivo, `pasta`
+ * igual a pasta que o contem, e uma linha de indice por memoria).
+ */
+const AVISO = "<!-- GERADO por `dd-harness sync`. Edite no serviço, não aqui: a próxima sincronização recusa arquivo alterado à mão. -->";
+/** Uma linha por âncora, para o leitor humano saber de que a memória depende. */
+function secaoDeAncoras(ancoras) {
+    if (ancoras.length === 0)
+        return "";
+    const linhas = ancoras.map((a) => `- \`${a.valor}\``).join("\n");
+    return `\n## Âncoras\n\nDe que esta memória depende — mudança aqui é o que dispara aviso de deriva.\n\n${linhas}\n`;
+}
+/**
+ * Os três filtros existem como coluna no serviço, e é isso que os torna auditáveis.
+ * Em disco eles viram seção, porque o frontmatter do molde não tem campo para texto
+ * longo e YAML multilinha é armadilha de escape.
+ */
+function secaoDeFiltros(m) {
+    return [
+        "\n## Os três filtros\n",
+        `**Dano:** ${m.dano}\n`,
+        `**Invisibilidade:** ${m.invisibilidade}\n`,
+        `**Externalidade:** ${m.externalidade}\n`,
+    ].join("\n");
+}
+export function arquivoDaMemoria(m) {
+    // `titulo` vai no frontmatter porque `gravar` e `editar` o exigem la: sem ele o arquivo
+    // materializado nao volta pelo `editar`, e o ciclo "sincroniza, corrige, manda de volta"
+    // — que e como o agente cura memoria — para com "frontmatter sem `titulo`". O titulo
+    // tambem aparece no indice, mas indice nao e o que se edita.
+    const frontmatter = [
+        "---",
+        `name: ${m.slug}`,
+        `titulo: ${m.titulo.replace(/\n/g, " ")}`,
+        `description: ${m.resumo.replace(/\n/g, " ")}`,
+        `pasta: ${m.pasta}`,
+        ...(m.revisar_ate ? [`revisar-ate: ${m.revisar_ate.slice(0, 10)}`] : []),
+        "---",
+    ].join("\n");
+    return [
+        frontmatter,
+        "",
+        AVISO,
+        "",
+        m.corpo.trimEnd(),
+        secaoDeFiltros(m),
+        secaoDeAncoras(m.ancoras),
+    ]
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd()
+        .concat("\n");
+}
+export function arquivoDoIndice(brain) {
+    const ativas = brain.memorias.filter((m) => m.status === "ativa");
+    const historico = brain.memorias.filter((m) => m.status === "historico");
+    const linha = (m) => `- [${m.titulo}](${m.pasta}/${m.slug}.md) — ${m.resumo.replace(/\n/g, " ")}`;
+    // O indice e montado pelas pastas, mas quem manda e a memoria: pasta que so aparece no
+    // `pasta:` de uma memoria tambem vira secao. Sem isso a memoria fica em disco e fora do
+    // indice — arquivo presente que nenhum agente encontra, que e a mesma falha silenciosa
+    // do import quebrado.
+    const definicoes = new Map(brain.pastas.map((p) => [p.slug, p.definicao]));
+    const slugs = [...new Set([...definicoes.keys(), ...ativas.map((m) => m.pasta)])].sort();
+    const secoes = slugs
+        .map((slug) => {
+        const memorias = ativas.filter((m) => m.pasta === slug);
+        const definicao = definicoes.get(slug);
+        return [
+            `## ${slug}`,
+            `<!-- ${definicao ?? "(definição não veio do serviço)"} -->`,
+            ...(memorias.length ? memorias.map(linha) : ["<!-- (vazia) -->"]),
+        ].join("\n");
+    })
+        .join("\n\n");
+    const secaoHistorico = [
+        "## Histórico",
+        "<!-- Memórias substituídas por uma decisão mais nova. -->",
+        ...(historico.length ? historico.map(linha) : []),
+    ].join("\n");
+    return [
+        "# 🧠 Brain — Índice",
+        "",
+        AVISO,
+        "",
+        `Projeto **${brain.projeto.nome}** (\`${brain.projeto.slug}\`), espaço **${brain.tenant.nome}**.`,
+        "Uma linha por memória. As regras de gravar, encaixar e curar estão no `CLAUDE.md`.",
+        "",
+        "---",
+        "",
+        secoes,
+        "",
+        secaoHistorico,
+        "",
+    ].join("\n");
+}
+/** Tudo o que o servico gera vive aqui — e nada fora daqui e escrito pelo `sync`. */
+export const PASTA = "dd-harness";
+/** O que a raiz precisa conter para a politica chegar a sessao. */
+export const LINHA_DE_IMPORT = `@${PASTA}/politica.md`;
+/**
+ * Caminho relativo (POSIX) -> conteúdo. As chaves são o que o manifesto guarda.
+ *
+ * Tudo dentro de `dd-harness/`, inclusive a política. Na raiz fica só o `CLAUDE.md`, que
+ * é **seu**: o `sync` não o escreve, apenas confere que ele importa a política. É o que
+ * deixa conviverem a parte gerenciada e o que aquele repositório tem de próprio — e o
+ * que faz adotar um projeto existente ser uma linha, não um ritual.
+ *
+ * Artefato vazio ou ausente não entra no mapa; como o manifesto remove o que saiu do
+ * conjunto, esvaziar no serviço apaga o arquivo no próximo `sync`.
+ */
+export function materializa(brain, pasta = PASTA) {
+    const arquivos = new Map();
+    const artefatos = [
+        [`${pasta}/politica.md`, brain.politica],
+        [`${pasta}/BRIEFING.md`, brain.briefing],
+    ];
+    for (const [caminho, conteudo] of artefatos) {
+        // Termina com quebra de linha: arquivo de texto sem ela irrita todo diff.
+        if (conteudo && conteudo.trim()) {
+            arquivos.set(caminho, conteudo.replace(/\n*$/, "\n"));
+        }
+    }
+    arquivos.set(`${pasta}/brain/MEMORY.md`, arquivoDoIndice(brain));
+    for (const m of brain.memorias) {
+        arquivos.set(`${pasta}/brain/${m.pasta}/${m.slug}.md`, arquivoDaMemoria(m));
+    }
+    return arquivos;
+}

package/dist/cli/src/medir.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, posix } from "node:path";
+/**
+ * Medir o alvo de uma ancora. E a metade da deriva que so o cliente pode fazer: o
+ * servico nunca ve o repositorio.
+ *
+ * Devolve `null` quando o alvo nao existe — e o servico que decide se isso e deriva.
+ */
+/** Arquivo: hash do conteudo. E o que responde "mudou?" sem ambiguidade. */
+async function hashDeArquivo(caminho) {
+    return createHash("sha256").update(await readFile(caminho)).digest("hex");
+}
+/**
+ * Diretorio: hash da LISTA de arquivos, nao do conteudo deles.
+ *
+ * Uma ancora em `supabase/migrations` quer dizer "o conjunto de migrations importa" —
+ * migration nova e o sinal. Se o hash levasse o conteudo junto, qualquer ajuste de
+ * comentario dentro de qualquer arquivo acusaria deriva, e a fila viraria ruido.
+ */
+async function hashDeDiretorio(caminho) {
+    const nomes = [];
+    async function anda(dir, prefixo) {
+        for (const entrada of await readdir(dir, { withFileTypes: true })) {
+            const rel = prefixo ? posix.join(prefixo, entrada.name) : entrada.name;
+            if (entrada.isDirectory())
+                await anda(join(dir, entrada.name), rel);
+            else
+                nomes.push(rel);
+        }
+    }
+    await anda(caminho, "");
+    return createHash("sha256").update(nomes.sort().join("\n")).digest("hex");
+}
+/**
+ * Trecho: `caminho#alvo` — hash das LINHAS que contem `alvo`, nao do arquivo.
+ *
+ * Existe porque ancora de arquivo mede grosso demais. Medido: renomear a variavel de um
+ * laco disparou as 5 memorias ancoradas naquele arquivo, nenhuma delas desatualizada. Cada
+ * uma falava de um trecho diferente, e o hash do arquivo nao distingue.
+ *
+ * `null` quando o alvo nao aparece mais: e o mesmo sinal de "arquivo ausente" — o trecho que
+ * a memoria descreve deixou de existir, e o servico decide o que isso significa. Trecho que
+ * some por rename e deriva legitima, nao falso positivo: a memoria aponta para algo que
+ * nao esta mais la.
+ *
+ * Comparacao literal, sem regex: o alvo vem de quem escreveu a memoria, e regex daria
+ * poder de travar o `check` (catastrophic backtracking) a quem so queria apontar uma linha.
+ */
+async function hashDeTrecho(caminho, alvo) {
+    const conteudo = await readFile(caminho, "utf8");
+    const casam = conteudo
+        .split(/\r?\n/)
+        .filter((linha) => linha.includes(alvo))
+        .map((linha) => linha.trim());
+    if (casam.length === 0)
+        return null;
+    return createHash("sha256").update(casam.join("\n"), "utf8").digest("hex");
+}
+export async function mede(raiz, valor) {
+    // O `#` separa alvo de caminho. O CHECK do banco garante um so, e nenhum lado vazio.
+    const corte = valor.indexOf("#");
+    if (corte !== -1) {
+        const caminho = join(raiz, valor.slice(0, corte));
+        const alvo = valor.slice(corte + 1);
+        try {
+            const info = await stat(caminho);
+            // Trecho de diretorio nao existe: o alvo e texto dentro de um arquivo.
+            if (info.isDirectory())
+                return null;
+            return await hashDeTrecho(caminho, alvo);
+        }
+        catch {
+            return null;
+        }
+    }
+    const caminho = join(raiz, valor);
+    try {
+        const info = await stat(caminho);
+        return info.isDirectory()
+            ? await hashDeDiretorio(caminho)
+            : await hashDeArquivo(caminho);
+    }
+    catch {
+        return null;
+    }
+}