dd-harness-mcp 0.11.0 → 0.13.0

package/dist/cli/src/cinto.js

@@ -0,0 +1,178 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { memoriasNoConteudo } from "./diff.js";
+/**
+ * O cinto de seguranca: a memoria chega ANTES da edicao, sem ninguem ter pedido.
+ *
+ * O Brain ate aqui e PULL — o agente precisa lembrar de chamar `buscar_memoria`. Isso
+ * falha exatamente onde mais custa: o agente nao busca quando *acha que sabe*. Ninguem
+ * consulta memoria antes de trocar um `SECURITY DEFINER` por `INVOKER` para silenciar um
+ * advisor; a tarefa parece trivial, e a melhor pratica da internet diz para fazer isso.
+ * A memoria existe justamente porque, neste projeto, isso quebrou a RLS inteira.
+ *
+ * O PUSH inverte: o hook `PreToolUse` cruza o arquivo que o agente esta editando contra
+ * as ancoras e injeta a memoria como `additionalContext`. AVISA, NUNCA BLOQUEIA — mesma
+ * regra da deriva e dos ganchos. Bloquear antes de o mecanismo ter reputacao ensina o
+ * reflexo do `--no-verify`, e ai nao ha cinto nenhum.
+ *
+ * Tudo local, de proposito. O hook e SINCRONO: cada `Edit` espera ele terminar. Medido
+ * contra producao, a rede custa ~250ms quente e ate 1,9s no cold start — por edicao. O
+ * cruzamento local custa ~100ms, quase tudo boot do Node. Por isso o cache: o payload do
+ * `SessionStart` ja traz ancoras, resumo e corpo, entao ele sai de graca, sem endpoint
+ * novo e sem uma segunda chamada.
+ */
+/** Onde o cache vive. Fora do repositorio: nada do dd-harness volta a morar em disco versionado. */
+export function caminhoDoCache(raiz) {
+    return join(raiz, ".claude", "dd-harness-ancoras.json");
+}
+/** Guarda as ancoras do Brain para o hook consultar sem rede. Falha em silencio: cache e otimizacao, nao contrato. */
+export async function guardaCache(raiz, brain) {
+    const cache = {
+        gravado_em: new Date().toISOString(),
+        memorias: brain.memorias
+            .filter((m) => m.status === "ativa" && m.ancoras.length > 0)
+            .map(({ pasta, slug, titulo, resumo, status, ancoras }) => ({
+            pasta,
+            slug,
+            titulo,
+            resumo,
+            status,
+            ancoras,
+        })),
+    };
+    try {
+        const caminho = caminhoDoCache(raiz);
+        await mkdir(dirname(caminho), { recursive: true });
+        await writeFile(caminho, `${JSON.stringify(cache)}\n`, "utf8");
+    }
+    catch {
+        // Sem cache o hook cala, e o PULL continua funcionando. Nao vale falhar a sessao.
+    }
+}
+export async function leCache(raiz) {
+    try {
+        return JSON.parse(await readFile(caminhoDoCache(raiz), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Um alerta por memoria por sessao. Sem isto, o agente que edita o mesmo arquivo dez
+ * vezes ate o teste passar recebe o mesmo texto dez vezes — e aviso repetido nao reforca,
+ * anestesia: na terceira repeticao ele vira ruido de fundo, e a memoria perde justamente
+ * a autoridade que o PUSH existe para dar.
+ *
+ * A chave e a MEMORIA, nao o arquivo: duas memorias no mesmo arquivo sao dois avisos
+ * diferentes, e calar a segunda porque a primeira ja falou esconderia a que importava.
+ *
+ * Por sessao, nao para sempre: sessao nova e contexto novo, e o agente que abre amanha
+ * nao viu o aviso de hoje.
+ */
+async function jaAvisou(raiz, sessao, enderecos) {
+    const caminho = join(raiz, ".claude", `dd-harness-avisos-${sessao.replace(/[^\w-]/g, "")}.json`);
+    let vistos = [];
+    try {
+        vistos = JSON.parse(await readFile(caminho, "utf8"));
+    }
+    catch {
+        // Primeira edicao da sessao: nada visto ainda.
+    }
+    const novos = enderecos.filter((e) => !vistos.includes(e));
+    if (novos.length === 0)
+        return [];
+    try {
+        await mkdir(dirname(caminho), { recursive: true });
+        await writeFile(caminho, JSON.stringify([...vistos, ...novos]), "utf8");
+    }
+    catch {
+        // Sem registro, o alerta repete — degrada para barulhento, nunca para calado.
+    }
+    return novos;
+}
+/**
+ * O caminho do arquivo relativo a raiz, no formato das ancoras (barras normais).
+ *
+ * `null` quando a edicao e fora do repositorio: `..` no relativo. Ancora nunca aponta
+ * para fora — o CHECK do banco recusa — entao nao ha o que cruzar, e avisar seria ruido.
+ */
+export function caminhoRelativo(raiz, arquivo) {
+    const rel = relative(resolve(raiz), resolve(arquivo));
+    if (!rel || rel.startsWith(".."))
+        return null;
+    return rel.split(sep).join("/");
+}
+/**
+ * A memoria que o agente precisa ver ANTES de escrever — ou `""` quando nao ha nenhuma.
+ *
+ * Vazio e o caso comum e tem que sair barato: a maioria das edicoes nao toca ancora
+ * alguma, e o silencio ai nao e falta de aviso, e a ausencia de motivo para avisar.
+ */
+export function alerta(tocadas, resumos) {
+    if (tocadas.length === 0)
+        return "";
+    const linhas = [
+        "ALERTA DE CICATRIZ (dd-harness) — este arquivo tem memória do projeto.",
+        "",
+    ];
+    for (const t of tocadas) {
+        const endereco = `${t.pasta}/${t.memoria}`;
+        linhas.push(`## ${t.titulo}`, `\`${endereco}\` — âncora: \`${t.ancora}\``, "");
+        const resumo = resumos.get(endereco);
+        if (resumo)
+            linhas.push(resumo, "");
+    }
+    linhas.push("Isto não bloqueia nada: siga se a mudança for deliberada. Mas se ela contradiz a " +
+        "memória acima, pare e diga isso ao usuário antes de escrever — é para este " +
+        "momento que a memória foi gravada. `ler_memoria` traz o texto inteiro, com o porquê.");
+    return linhas.join("\n");
+}
+/**
+ * O hook inteiro: le a entrada, cruza, devolve o JSON que o Claude Code espera.
+ *
+ * SEMPRE `permissionDecision: "allow"` — provado no runtime que `additionalContext`
+ * chega ao agente junto com `allow`, sem bloquear a edicao. Esse par e o que torna o
+ * "avisa, nao impede" possivel aqui; com `deny` o aviso existiria so as custas de
+ * recusar a edicao.
+ */
+export async function decideDoHook(entrada) {
+    const permitir = JSON.stringify({
+        hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow" },
+    });
+    const arquivo = entrada.tool_input?.file_path;
+    const raiz = entrada.cwd;
+    if (!arquivo || !raiz)
+        return permitir;
+    const relativo = caminhoRelativo(raiz, arquivo);
+    if (!relativo)
+        return permitir;
+    const cache = await leCache(raiz);
+    if (!cache || cache.memorias.length === 0)
+        return permitir;
+    // `Edit` manda o trecho trocado; `Write` manda o arquivo inteiro. Nos dois casos o que
+    // interessa e o texto que existe agora e o que vai existir — e a ancora de trecho casa
+    // com qualquer um dos dois lados.
+    const { old_string, new_string, content } = entrada.tool_input ?? {};
+    const antes = old_string ?? (await readFile(arquivo, "utf8").catch(() => null));
+    const depois = new_string ?? content ?? null;
+    const brain = { memorias: cache.memorias };
+    const tocadas = memoriasNoConteudo(brain, relativo, antes, depois);
+    if (tocadas.length === 0)
+        return permitir;
+    // Sem `session_id` nao ha como separar uma sessao da outra; avisa sempre, que e o lado
+    // seguro de errar: repetir cansa, calar deixa passar.
+    const inedito = entrada.session_id
+        ? await jaAvisou(raiz, entrada.session_id, tocadas.map((t) => `${t.pasta}/${t.memoria}`))
+        : tocadas.map((t) => `${t.pasta}/${t.memoria}`);
+    const novas = tocadas.filter((t) => inedito.includes(`${t.pasta}/${t.memoria}`));
+    if (novas.length === 0)
+        return permitir;
+    const resumos = new Map(cache.memorias.map((m) => [`${m.pasta}/${m.slug}`, m.resumo]));
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            additionalContext: alerta(novas, resumos),
+        },
+    });
+}

package/dist/cli/src/diff.js

@@ -138,3 +138,106 @@ export function memoriasTocadas(brain, caminhos) {
     }
     return tocadas;
 }
+/**
+ * O que a arvore de trabalho tem de modificado AGORA — sem commit nenhum.
+ *
+ * `caminhosDoCommit` responde "o que aquele commit mudou"; esta responde "o que esta
+ * mudado neste instante". E a diferenca entre o code review (depois) e a sessao em
+ * andamento (durante), e e o que permite propor ancora no momento em que a memoria nasce:
+ * quem grava uma memoria acabou de mexer no que ela descreve.
+ *
+ * Inclui nao rastreados (`--others`): arquivo novo e exatamente onde a decisao recem
+ * tomada costuma morar, e exclui-lo deixaria de fora o caso mais comum.
+ *
+ * Lista vazia quando nao ha git — sem lancar. Propor ancora e um extra; um projeto sem
+ * repositorio continua gravando memoria normalmente, so sem a sugestao.
+ */
+export async function caminhosDaArvore(raiz) {
+    try {
+        const { stdout } = await roda("git", ["status", "--porcelain=v1", "--untracked-files=all", "--no-renames"], { cwd: raiz });
+        const caminhos = [];
+        for (const linha of stdout.split(/\r?\n/)) {
+            if (!linha.trim())
+                continue;
+            // `XY caminho` — os dois primeiros caracteres sao o estado no indice e na arvore.
+            const caminho = linha.slice(3).trim();
+            if (caminho)
+                caminhos.push(descitado(caminho));
+        }
+        return caminhos;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * O git cita caminhos com caractere especial (`"src/caf\303\251.ts"`). Sem desfazer isso,
+ * a ancora proposta nasce com aspas no valor e nunca casa com arquivo nenhum.
+ */
+function descitado(caminho) {
+    if (!caminho.startsWith('"') || !caminho.endsWith('"'))
+        return caminho;
+    const cru = caminho.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < cru.length; i++) {
+        if (cru[i] === "\\" && /[0-7]/.test(cru[i + 1] ?? "")) {
+            bytes.push(parseInt(cru.slice(i + 1, i + 4), 8));
+            i += 3;
+        }
+        else if (cru[i] === "\\") {
+            bytes.push(cru.charCodeAt(++i));
+        }
+        else {
+            bytes.push(...new TextEncoder().encode(cru[i]));
+        }
+    }
+    return new TextDecoder().decode(new Uint8Array(bytes));
+}
+/**
+ * Cruza ancoras com o CONTEUDO de uma edicao, nao so com o nome do arquivo.
+ *
+ * `memoriasTocadas` casa por arquivo porque e tudo que o `git diff-tree` permite — ele
+ * devolve caminho puro, nunca o trecho. Aqui e diferente: quem chama tem o texto que vai
+ * ser escrito, entao a ancora de trecho pode ser verificada de verdade.
+ *
+ * A diferenca importa porque e o que separa aviso de ruido. Medido neste projeto: duas
+ * memorias ancoradas no mesmo `config/limites.json` eram as duas sinalizadas quando so
+ * uma das chaves mudava. Numa interrupcao nao solicitada — que e o que o interceptador
+ * faz — errar assim ensina a ignorar o aviso, e um aviso ignorado e pior que nenhum.
+ *
+ * A regra, por tipo de ancora:
+ * - `arquivo`        -> casa sempre que o arquivo casa. A memoria fala do todo.
+ * - `arquivo#trecho` -> casa so se o trecho aparecer no texto ANTES ou DEPOIS da edicao.
+ *   Antes: a edicao esta mexendo onde a memoria guarda. Depois: esta mexendo para la.
+ *
+ * `antes` ausente (arquivo novo, ou `Write` que nao le o original) cai so no `depois` —
+ * sem inventar casamento por falta de dado.
+ */
+export function memoriasNoConteudo(brain, caminho, antes, depois) {
+    const tocadas = [];
+    for (const memoria of brain.memorias) {
+        if (memoria.status !== "ativa")
+            continue;
+        for (const ancora of memoria.ancoras) {
+            const corte = ancora.valor.indexOf("#");
+            const alvo = corte === -1 ? ancora.valor : ancora.valor.slice(0, corte);
+            const arquivoCasa = caminho === alvo || caminho.startsWith(`${alvo}/`);
+            if (!arquivoCasa)
+                continue;
+            if (corte !== -1) {
+                const trecho = ancora.valor.slice(corte + 1);
+                const apareceAntes = antes?.includes(trecho) ?? false;
+                const apareceDepois = depois?.includes(trecho) ?? false;
+                if (!apareceAntes && !apareceDepois)
+                    continue;
+            }
+            tocadas.push({
+                pasta: memoria.pasta,
+                memoria: memoria.slug,
+                titulo: memoria.titulo,
+                ancora: ancora.valor,
+            });
+        }
+    }
+    return tocadas;
+}

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

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 const COMANDO_DO_HOOK = "dd-harness politica --hook";
+const COMANDO_DO_CINTO = "dd-harness cinto";
 /**
  * Acrescenta o hook do dd-harness a `.claude/settings.json`, sem tocar em outros hooks.
  *
@@ -23,19 +24,33 @@ export async function escreveHook(raiz) {
     }
     const hooks = (doc.hooks ??= {});
     const sessionStart = (hooks.SessionStart ??= []);
-    const jaTemONosso = JSON.stringify(sessionStart).includes(COMANDO_DO_HOOK);
-    if (jaTemONosso)
+    const preToolUse = (hooks.PreToolUse ??= []);
+    const temSessionStart = JSON.stringify(sessionStart).includes(COMANDO_DO_HOOK);
+    // O interceptador pre-voo e checado SEPARADAMENTE do SessionStart, e nao junto: quem
+    // instalou o dd-harness antes desta versao ja tem o SessionStart e nao tem o cinto. Um
+    // `return` antecipado por "ja tinha" deixaria esses repositorios sem o cinto para
+    // sempre, calados — que e a classe de defeito que este projeto mais persegue.
+    const temCinto = JSON.stringify(preToolUse).includes(COMANDO_DO_CINTO);
+    if (temSessionStart && temCinto)
         return { ok: true, estado: "ja-tinha" };
-    const eraVazio = sessionStart.length === 0;
-    sessionStart.push({
-        hooks: [
-            {
-                type: "command",
-                command: COMANDO_DO_HOOK,
-                statusMessage: "Carregando a política do dd-harness...",
-            },
-        ],
-    });
+    const eraVazio = sessionStart.length === 0 && preToolUse.length === 0;
+    if (!temSessionStart) {
+        sessionStart.push({
+            hooks: [
+                {
+                    type: "command",
+                    command: COMANDO_DO_HOOK,
+                    statusMessage: "Carregando a política do dd-harness...",
+                },
+            ],
+        });
+    }
+    if (!temCinto) {
+        preToolUse.push({
+            matcher: "Edit|Write|MultiEdit",
+            hooks: [{ type: "command", command: COMANDO_DO_CINTO }],
+        });
+    }
     await mkdir(dirname(caminho), { recursive: true });
     await writeFile(caminho, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
     return { ok: true, estado: eraVazio ? "criado" : "acrescentado" };
@@ -107,4 +122,8 @@ 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.`;
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
+desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
+válido — não crie fase sem o usuário pedir.`;

package/dist/cli/src/index.js

@@ -19,7 +19,8 @@ import { grava } from "./gravar.js";
 import { init, SUGESTAO_AGENTS, SUGESTAO_HOOK, SUGESTAO_MCP } from "./init.js";
 import { pergunta, escolha, fechaPerguntas } from "./pergunta.js";
 import { buscaPolitica } from "./politica.js";
-import { blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
+import { avisoDeOrdem, blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
+import { decideDoHook, guardaCache } from "./cinto.js";
 import { busca } from "./buscar.js";
 import { arquiva, edita, le } from "./curar.js";
 import { criaPasta } from "./pasta.js";
@@ -62,6 +63,9 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
                                      1 = não consegui buscar
                                      --hook: fala o protocolo do SessionStart do
                                      Claude Code, para pôr a política no contexto
+  dd-harness cinto                  o interceptador pré-voo: lê a edição no stdin
+                                     e devolve a memória que fala daquele trecho.
+                                     Quem chama é o hook PreToolUse, não você
   dd-harness roadmap                as fases abertas: a atual inteira, as próximas
                                      por título (opcional — projeto sem fase não tem)
   dd-harness changelog [--versao <v>]
@@ -155,7 +159,7 @@ async function comandoFase(argv) {
             throw new Error("fase editar exige o slug da fase.");
         const ordemBruta = argumento(opcoes, "ordem");
         const status = statusDoArgv(opcoes);
-        const { fase } = await editaFase(process.cwd(), slug, {
+        const { fase, atras_de } = await editaFase(process.cwd(), slug, {
             titulo: argumento(opcoes, "titulo"),
             conteudo: await conteudoDoArgv(opcoes),
             versao: opcoes.includes("--sem-versao") ? null : argumento(opcoes, "versao"),
@@ -165,7 +169,8 @@ async function comandoFase(argv) {
         console.log(`Fase ${fase.slug} atualizada — ${fase.status}` +
             (fase.versao ? `, versão ${fase.versao}` : "") +
             (status === "concluida" ? " (saiu do roadmap, entrou no changelog)" : "") +
-            ".");
+            "." +
+            avisoDeOrdem(fase, atras_de, ordemBruta !== undefined));
         return;
     }
     throw new Error('uso: dd-harness fase criar --titulo "<t>" [...]  |  dd-harness fase editar <slug> [...]');
@@ -647,6 +652,34 @@ 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.
  */
+/**
+ * `dd-harness cinto` — o interceptador pre-voo, chamado pelo hook `PreToolUse`.
+ *
+ * Le a chamada de ferramenta no stdin e devolve o JSON que o Claude Code espera. SEMPRE
+ * permite: o alerta viaja em `additionalContext`, que chega ao agente antes da edicao
+ * sem recusa-la (provado no runtime, nao inferido da documentacao).
+ *
+ * Nunca falha o processo. Este comando roda ANTES de cada `Edit`, e um hook que quebra
+ * bloquearia o trabalho por causa de um aviso — exatamente o contrario do que ele existe
+ * para fazer. Qualquer erro vira "permitir e calar".
+ */
+async function comandoCinto() {
+    const permitir = JSON.stringify({
+        hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow" },
+    });
+    try {
+        const pedacos = [];
+        for await (const p of process.stdin)
+            pedacos.push(p);
+        const cru = Buffer.concat(pedacos).toString("utf8").trim();
+        if (!cru)
+            return console.log(permitir);
+        console.log(await decideDoHook(JSON.parse(cru)));
+    }
+    catch {
+        console.log(permitir);
+    }
+}
 async function comandoPolitica(argv) {
     const r = await buscaPolitica(process.cwd());
     // `--hook`: fala o protocolo do SessionStart do Claude Code, que injeta
@@ -658,6 +691,11 @@ async function comandoPolitica(argv) {
         // 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);
+        // O cache que o interceptador pre-voo le a cada edicao. Aqui e o unico lugar onde ele
+        // pode ser escrito sem custo: a requisicao ja foi paga, e as ancoras vieram junto.
+        if (r.memorias) {
+            await guardaCache(process.cwd(), { memorias: r.memorias });
+        }
         console.log(JSON.stringify({ hookSpecificOutput: contextoDaSessao(r, worker) }));
         return;
     }
@@ -714,9 +752,27 @@ function contextoDaSessao(r, worker) {
                 "(`tipo: \"politica\"` e `tipo: \"briefing\"`, uma chamada cada). Se essa " +
                 "ferramenta não estiver disponível nesta sessão, pare e diga ao usuário que " +
                 "o servidor MCP do dd-harness precisa estar conectado para isto.\n" +
+                // A politica e escrita do zero pelo agente, e este texto e o unico lugar que diz o
+                // que ela precisa conter. Sem esta linha, o roadmap chega ao contexto e nao obriga
+                // a nada: informacao passiva, que e como uma feature existe sem ser usada.
+                "   Na política, inclua uma linha sobre o roadmap: a fase **Agora** é o foco da " +
+                "sessão, e ao terminá-la o agente **propõe** concluí-la (`editar_fase` com " +
+                "`status: \"concluida\"`) — nunca conclui por conta própria, porque quem decide " +
+                "que uma fase acabou é o usuário.\n" +
                 "5. Depois de escrever os dois, sobrescreva o `CLAUDE.md` da raiz com um " +
                 "ponteiro curto para a política deste serviço — a verdade passa a morar " +
-                "aqui, e o `CLAUDE.md` local nunca mais precisa ser editado à mão." +
+                "aqui, e o `CLAUDE.md` local nunca mais precisa ser editado à mão. O ponteiro " +
+                "precisa citar `ler_artefato` **e** `ler_roadmap`: quem chega por ele (Codex, " +
+                "Cursor, ou o Claude Code quando o hook não roda) não tem outro jeito de " +
+                "descobrir que há roadmap.\n" +
+                // O momento certo de perguntar: quem acabou de descrever o projeto tem o contexto
+                // fresco para dizer por onde ele vai. Depois disso, ninguem mais pergunta — e uma
+                // feature que so se descobre lendo a lista de ferramentas nao se descobre.
+                "6. Por fim, pergunte se o trabalho deste projeto tem **fases** — algo que " +
+                "atravessa sessões, com ordem entre as partes. Se tiver, proponha as primeiras e " +
+                "crie-as com `criar_fase`; a de menor ordem vira o foco de cada sessão, e " +
+                "concluí-la a move para o changelog sozinha. Se for um projeto pequeno, diga que " +
+                "roadmap é opcional e siga sem ele — não insista." +
                 fila,
         };
     }
@@ -908,6 +964,8 @@ async function principal() {
             return comandoStatus();
         case "politica":
             return comandoPolitica(resto);
+        case "cinto":
+            return comandoCinto();
         case "roadmap":
             return comandoRoadmap();
         case "changelog":

package/dist/cli/src/politica.js

@@ -30,9 +30,9 @@ export async function buscaPolitica(raiz) {
         // existir sem briefing — a sessao seguia como "ok" com metade do briefing faltando,
         // e nada acionava o fluxo que devia completa-lo.
         if (!conteudo || payload.briefado === false) {
-            return { estado: "sem-politica", esperandoIndexacao };
+            return { estado: "sem-politica", esperandoIndexacao, memorias: payload.memorias };
         }
-        return { estado: "ok", conteudo, esperandoIndexacao, roadmap };
+        return { estado: "ok", conteudo, esperandoIndexacao, roadmap, memorias: payload.memorias };
     }
     catch (erro) {
         return { estado: "inalcancavel", motivo: mensagem(erro) };

package/dist/cli/src/roadmap.js

@@ -123,6 +123,27 @@ export function formataRoadmap(fases) {
         : "Nenhuma fase concluída ainda.");
     return linhas.join("\n");
 }
+/**
+ * A frase sobre POSICAO que fecha a resposta de `editar_fase` — vazia quando `ordem` nao
+ * foi pedida, porque quem edita texto nao perguntou nada sobre posicao.
+ *
+ * Existe por um achado medido (rodada 005): pedir `ordem: 1` para promover uma fase a
+ * "Agora" quando outra mais antiga ja tem `ordem: 1` grava o valor, responde sucesso e
+ * nao muda nada visivel — a leitura desempata por `created_at`. O comportamento esta
+ * certo; o silencio e que ensinava o agente a seguir achando que promoveu a fase.
+ *
+ * Confirma a ordem aplicada mesmo sem empate: e o unico jeito de quem pediu saber que o
+ * numero pegou, e custa uma linha.
+ */
+export function avisoDeOrdem(fase, atrasDe, pediuOrdem) {
+    if (!pediuOrdem)
+        return "";
+    if (!atrasDe)
+        return ` Ordem ${fase.ordem}${fase.status === "aberta" ? " — é o \"Agora\"" : ""}.`;
+    return (` Ordem ${fase.ordem}, mas ainda atrás de \`${atrasDe.slug}\` (${atrasDe.titulo}) —` +
+        " fases com a mesma ordem desempatam pela mais antiga. Para passar à frente, use uma" +
+        " ordem menor ou mude a ordem da outra.");
+}
 /**
  * O changelog: fases concluidas agrupadas por versao, na ordem em que a API devolveu (mais
  * recente primeiro). Grupo sem versao recebe `SEM_VERSAO`. A ordem dos grupos e a da

package/dist/mcp/src/index.js

@@ -12,7 +12,8 @@ import { criaPasta } from "../../cli/src/pasta.js";
 import { criaProjeto } from "../../cli/src/projeto.js";
 import { escreveArtefato, leArtefato } from "../../cli/src/artefato.js";
 import { grava } from "../../cli/src/gravar.js";
-import { criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "../../cli/src/roadmap.js";
+import { caminhosDaArvore } from "../../cli/src/diff.js";
+import { avisoDeOrdem, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "../../cli/src/roadmap.js";
 /**
  * O mesmo servico, outra porta.
  *
@@ -87,6 +88,31 @@ Os primeiros achados são os que valem: o piso barra tema alheio, mas num Brain
             return falha(erro);
         }
     });
+    server.registerTool("sugerir_ancoras", {
+        description: `Os arquivos que esta sessão modificou, para escolher a âncora de uma memória que vai ser gravada.
+
+Chame ANTES de \`gravar_memoria\` quando a memória fala de um ponto do código. A âncora é o que faz a memória ser entregue a quem for mexer naquele ponto — sem ela, a memória só aparece se alguém lembrar de buscar, e é justamente quando o agente acha que já sabe que ele não busca.
+
+Isto NÃO escolhe por você: devolve o que mudou, e a âncora certa é a que aponta o trecho de que a memória fala. Prefira \`arquivo#trecho\` a \`arquivo\` inteiro — um texto estável e específico (nome de função, constante, chave de config), não uma linha que a próxima refatoração reescreve.
+
+Lista vazia significa que não há git ou nada foi modificado; nesse caso pergunte ao usuário qual arquivo a memória guarda.`,
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            const caminhos = await caminhosDaArvore(raiz);
+            if (caminhos.length === 0) {
+                return texto("Nada modificado nesta sessão (ou o projeto não tem git). Pergunte ao " +
+                    "usuário qual arquivo a memória guarda — e grave com âncora, não sem.");
+            }
+            return texto(`${caminhos.length} arquivo(s) modificado(s) nesta sessão:\n` +
+                caminhos.map((c) => `- \`${c}\``).join("\n") +
+                "\n\nEscolha o que a memória descreve e ancore no TRECHO (`arquivo#alvo`), " +
+                "não no arquivo inteiro, quando a memória fala de um ponto específico.");
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
     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.
 
@@ -110,6 +136,12 @@ A pasta precisa existir antes — use \`criar_pasta\`. Essa recusa é deliberada
         try {
             const r = await grava(raiz, arquivo);
             return texto(`Gravado ${r.endereco} — ${r.ancoras} âncora(s), valendo para ${r.projetos} projeto(s).\n` +
+                (r.ancoras === 0
+                    ? "SEM ÂNCORA: esta memória só será encontrada por busca, e ninguém será " +
+                        "avisado ao mexer no código que ela guarda — o alerta que chega antes da " +
+                        "edição nasce da âncora. `sugerir_ancoras` mostra o que esta sessão tocou; " +
+                        "proponha uma ao usuário.\n"
+                    : "") +
                 "Rode `pnpm worker --uma-vez` para ela entrar na busca semântica.");
         }
         catch (erro) {
@@ -384,7 +416,7 @@ CONCLUIR uma fase é isto com \`status: "concluida"\`. Proponha ao humano antes
 
 Fase concluída NÃO gera memória no Brain por padrão. O roadmap guarda o quê e quando; o porquê de uma decisão só vira memória se passar nos três filtros — e aí o caminho é \`gravar_memoria\`, não o conteúdo da fase.
 
-\`versao: null\` tira a versão. \`ordem\` reposiciona: a aberta de menor ordem é o "Agora".`,
+\`versao: null\` tira a versão. \`ordem\` reposiciona: a aberta de menor ordem é o "Agora". Duas fases podem ter a mesma ordem — aí a mais antiga vem primeiro, então repetir a ordem da fase atual NÃO promove a sua. A resposta diz em que posição a fase ficou e, se ela seguiu atrás de outra, qual.`,
         inputSchema: z.object({
             slug: z.string().min(1).describe("O endereço da fase, como aparece entre colchetes em `ler_roadmap` e `ler_changelog`."),
             titulo: z.string().min(2).max(120).optional(),
@@ -395,12 +427,13 @@ Fase concluída NÃO gera memória no Brain por padrão. O roadmap guarda o quê
         }),
     }, async ({ slug, ...mudancas }) => {
         try {
-            const { fase } = await editaFase(raiz, slug, mudancas);
+            const { fase, atras_de } = await editaFase(raiz, slug, mudancas);
             // A frase de transicao so quando a conclusao foi o PEDIDO — editar o texto de uma
             // fase ja concluida nao a faz "sair do roadmap" de novo.
             return texto(`Fase \`${fase.slug}\` atualizada — ${fase.status}` +
                 (fase.versao ? `, versão ${fase.versao}` : "") +
-                (mudancas.status === "concluida" ? ". Saiu do roadmap e entrou no changelog." : "."));
+                (mudancas.status === "concluida" ? ". Saiu do roadmap e entrou no changelog." : ".") +
+                avisoDeOrdem(fase, atras_de, mudancas.ordem !== undefined));
         }
         catch (erro) {
             return falha(erro);

package/package.json

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