dd-harness 0.4.0 → 0.5.0

package/dist/brain.d.ts

@@ -47,4 +47,9 @@ export type Brain = {
      * sem embedding — somem da busca semantica — e so este numero denuncia.
      */
     travadas_na_fila?: number;
+    /**
+     * Memorias que so esperam o worker rodar. Voltam sozinhas assim que alguem o sobe —
+     * por isso o cliente age em cima deste numero, em vez de so avisar.
+     */
+    esperando_indexacao?: number;
 };

package/dist/buscar.d.ts

@@ -5,16 +5,23 @@
  * esta responde "o que ja aprendemos sobre isto?", que e a pergunta de quem ainda esta
  * entendendo o problema e nem sabe qual arquivo abrir.
  *
- * Devolve endereco, nao conteudo: quem quiser o corpo abre o arquivo que o `sync` ja
- * materializou. Assim a busca continua barata e o Brain em disco continua sendo a fonte.
+ * Devolve endereco, nao conteudo: quem quiser o corpo chama `ler`. Assim a busca continua
+ * barata, e quem so queria saber "existe algo sobre isto?" nao paga por N corpos.
  */
 export type Achado = {
     endereco: string;
     titulo: string;
     resumo: string;
 };
-export declare function busca(raiz: string, consulta: string, limite?: number): Promise<{
+export type Resultado = {
     semantica: boolean;
     provedor: string | null;
     achados: Achado[];
-}>;
+    /**
+     * Memorias sem vetor no momento da busca. Maior que zero significa que PODE existir
+     * resposta melhor que nao apareceu — e quem chamou nao teria como saber, porque o
+     * resultado parece completo de qualquer forma.
+     */
+    esperandoIndexacao: number;
+};
+export declare function busca(raiz: string, consulta: string, limite?: number): Promise<Resultado>;

package/dist/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/check.d.ts

@@ -1,4 +1,4 @@
-import { type Tocada } from "./diff.js";
+import { type Reancoragem, type Tocada } from "./diff.js";
 import type { Brain } from "./brain.js";
 /**
  * `dd-harness check` — resolve as âncoras contra a árvore de trabalho.
@@ -24,6 +24,11 @@ export type ResultadoDoCheck = {
     fechadas: number;
     /** Memorias que falam do que o commit mudou. Vazio quando nao ha `--commit`. */
     tocadas: Tocada[];
+    /**
+     * Para onde o git sugere que cada alvo ausente foi. So com `--commit`: sem diff nao ha
+     * rename a cruzar, e a lista de ausentes continua sendo tudo o que se pode dizer.
+     */
+    reancoragens: Reancoragem[];
 };
 export type ResultadoDoStatus = {
     /**

package/dist/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/diff.d.ts

@@ -10,14 +10,71 @@ import type { Brain } from "./brain.js";
  * "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.
  */
-/** Caminhos alterados num commit. Vazio quando o git nao responde — nunca quebra. */
-export declare function caminhosDoCommit(raiz: string, commit: string): Promise<string[]>;
+/** Um arquivo que saiu de um caminho e chegou noutro, com a confianca que o git deu. */
+export type Rename = {
+    de: string;
+    para: string;
+    similaridade: number;
+};
+export type MudancasDoCommit = {
+    caminhos: string[];
+    renames: Rename[];
+};
+/**
+ * O que um commit mudou: caminhos tocados e renames detectados.
+ *
+ * `-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.
+ *
+ * Vazio quando o git nao responde — nunca quebra: um aviso que nao pode ser dado nao vira
+ * erro que atrapalha o commit.
+ */
+export declare function caminhosDoCommit(raiz: string, commit: string): Promise<MudancasDoCommit>;
+/**
+ * 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 declare function interpretaNameStatus(stdout: string): MudancasDoCommit;
 export type Tocada = {
     pasta: string;
     memoria: string;
     titulo: string;
     ancora: string;
 };
+/**
+ * Uma ancora cujo alvo sumiu, e para onde o git sugere que ele foi.
+ *
+ * A sugestao e heuristica: o git compara conteudo e da um percentual. Por isso ela e
+ * SUGERIDA e nunca aplicada sozinha — reancorar em silencio moveria a memoria para o
+ * lugar errado sem ninguem ver, que e pior que o alvo ausente que se queria resolver.
+ */
+export type Reancoragem = {
+    pasta: string;
+    memoria: string;
+    ancora: string;
+    sugestao: string;
+    similaridade: number;
+};
+/**
+ * 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 declare function sugereReancoragem(ausentes: {
+    pasta: string;
+    memoria: string;
+    valor: string;
+}[], renames: Rename[]): Reancoragem[];
 /**
  * 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/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/index.js

@@ -3,12 +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_HOOK, SUGESTAO_MCP } from "./init.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, le } from "./curar.js";
 import { criaPasta } from "./pasta.js";
 import { criaProjeto } from "./projeto.js";
+import { reancora } from "./reancorar.js";
+import { subiuOWorker } from "./worker.js";
 /**
  * `dd-harness` — o cliente que materializa os artefatos no repositorio.
  *
@@ -34,6 +36,8 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
                                      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
@@ -93,12 +97,24 @@ async function comandoInit(argv) {
     }
     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
@@ -170,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
@@ -179,6 +196,32 @@ async function comandoBuscar(argv) {
         console.log(`  ${a.endereco} — ${a.titulo}`);
         console.log(`    ${a.resumo}`);
     }
+    avisaSobreAFila(r.esperandoIndexacao);
+}
+/**
+ * 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>"');
+    }
+    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"));
@@ -195,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("");
@@ -239,7 +298,11 @@ async function comandoPolitica(argv) {
     // 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")) {
-        console.log(JSON.stringify({ hookSpecificOutput: contextoDaSessao(r) }));
+        // 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") {
@@ -261,14 +324,16 @@ async function comandoPolitica(argv) {
  * 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) {
+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,
+                r.conteudo +
+                fila,
         };
     }
     if (r.estado === "sem-politica") {
@@ -276,7 +341,8 @@ function contextoDaSessao(r) {
             ...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`.",
+                "implementar qualquer coisa, diga isso ao usuário e proponha rodar `/briefar`." +
+                fila,
         };
     }
     return {
@@ -290,6 +356,33 @@ function contextoDaSessao(r) {
             "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?",
@@ -397,6 +490,8 @@ async function principal() {
             return comandoLer(resto);
         case "buscar":
             return comandoBuscar(resto);
+        case "reancorar":
+            return comandoReancorar(resto);
         case "check":
             return comandoCheck(resto);
         case "status":

package/dist/init.d.ts

@@ -12,6 +12,8 @@ export type ResultadoDoInit = {
     config: "criada" | "ja-existia";
     mcp: "ja-declarado" | "a-declarar";
     hook: "ja-declarado" | "a-declarar";
+    /** O `AGENTS.md` manda o agente de fora do Claude Code buscar a política? */
+    agents: "ja-aponta" | "a-apontar";
 };
 /**
  * O `.mcp.json` e sugerido, nunca escrito.
@@ -32,6 +34,19 @@ export declare const SUGESTAO_MCP = "{\n  \"mcpServers\": {\n    \"dd-harness\":
  * Sugerido e nao escrito, pelo mesmo motivo do `.mcp.json`.
  */
 export declare const SUGESTAO_HOOK = "{\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"dd-harness politica --hook\",\n            \"statusMessage\": \"Carregando a pol\u00EDtica do dd-harness...\"\n          }\n        ]\n      }\n    ]\n  }\n}";
+/**
+ * O que escrever num `AGENTS.md`, para agente que NAO e o Claude Code.
+ *
+ * O hook de `SessionStart` e um mecanismo do Claude Code: Codex, Cursor, Gemini CLI e
+ * Windsurf nao o executam. Nessas ferramentas nada carrega a politica sozinho — e o
+ * resultado e a mesma falha de sempre, a sessao abrindo sem protocolo sem avisar.
+ *
+ * O que resta la e o servidor MCP, que essas ferramentas suportam. Mas ferramenta
+ * disponivel nao e ferramenta chamada: sem uma instrucao explicita, o agente pode
+ * simplesmente nunca perguntar pela politica. Dai esta linha, que e curta de proposito —
+ * ela manda buscar a regra, nao repete a regra.
+ */
+export declare const SUGESTAO_AGENTS = "# AGENTS.md\n\nEste projeto tem um protocolo de trabalho que **n\u00E3o est\u00E1 neste arquivo**.\n\n**ANTES de qualquer outra coisa**, chame a ferramenta MCP `ler_artefato` com\n`tipo: \"politica\"` e siga o que ela devolver. \u00C9 a primeira a\u00E7\u00E3o da sess\u00E3o, antes\nde ler c\u00F3digo, responder ou planejar.\n\n- Se a ferramenta n\u00E3o existir, o servidor MCP do dd-harness n\u00E3o est\u00E1 declarado:\n  avise o usu\u00E1rio e **n\u00E3o modifique nada** at\u00E9 ele resolver.\n- Se ela devolver vazio, este projeto nunca foi briefado \u2014 diga isso ao usu\u00E1rio.\n\nO Claude Code carrega a pol\u00EDtica sozinho, por hook. Nas outras ferramentas, a\nchamada acima \u00E9 o que substitui esse hook.";
 export declare function init(raiz: string, dados: {
     tenant: string;
     projeto: string;

package/dist/init.js

@@ -41,6 +41,32 @@ export const SUGESTAO_HOOK = `{
     ]
   }
 }`;
+/**
+ * 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");
@@ -91,5 +117,22 @@ export async function init(raiz, dados) {
         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 {
+        const cru = await readFile(join(raiz, "AGENTS.md"), "utf8");
+        return cru.includes("ler_artefato") ? "ja-aponta" : "a-apontar";
+    }
+    catch {
+        return "a-apontar";
+    }
+}

package/dist/politica.d.ts

@@ -15,7 +15,7 @@
  * A diferenca entre as duas ultimas e o que o `GET /api/v1/artefatos` responde: `404` e
  * "nao ha projeto"; `200` com `politica` nula e "existe, nunca briefado".
  */
-export type ResultadoDaPolitica = {
+export type ResultadoDaPolitica = ({
     estado: "ok";
     conteudo: string;
 } | {
@@ -23,5 +23,11 @@ export type ResultadoDaPolitica = {
 } | {
     estado: "inalcancavel";
     motivo: string;
+}) & {
+    /**
+     * Memorias esperando o worker. Vem de carona no mesmo payload da politica — o hook ja
+     * faz esta chamada, entao saber o estado da fila custa zero requisicao.
+     */
+    esperandoIndexacao?: number;
 };
 export declare function buscaPolitica(raiz: string): Promise<ResultadoDaPolitica>;

package/dist/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/reancorar.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function reancora(raiz: string, endereco: string, de: string, para: string): Promise<{
+    endereco: string;
+    de: string;
+    para: string;
+}>;

package/dist/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/worker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare function temWorkerLocal(raiz: string): Promise<boolean>;
+export type Subida = {
+    subiu: true;
+} | {
+    subiu: false;
+    motivo: "sem-fila" | "sem-worker" | "falhou";
+    detalhe?: string;
+};
+/**
+ * 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 declare function subiuOWorker(raiz: string, esperando: number): Promise<Subida>;

package/dist/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-harness",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Cliente do dd-harness: politica no inicio da sessao, e memoria por busca — nada em disco. Sem dependencia: fetch, crypto e fs sao do Node.",
   "license": "UNLICENSED",