dd-harness 0.18.0 → 0.20.0

package/dist/cinto.d.ts

@@ -0,0 +1,75 @@
+import type { Brain, Memoria } from "./brain.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 declare function caminhoDoCache(raiz: string): string;
+/**
+ * So o que o cruzamento precisa. O payload inteiro tem briefing, politica e o corpo de
+ * toda memoria — carregar isso a cada `Edit` seria pagar leitura de disco grande para,
+ * quase sempre, nao casar com nada.
+ */
+export type CacheDeAncoras = {
+    gravado_em: string;
+    memorias: Pick<Memoria, "pasta" | "slug" | "titulo" | "resumo" | "status" | "ancoras">[];
+};
+/** Guarda as ancoras do Brain para o hook consultar sem rede. Falha em silencio: cache e otimizacao, nao contrato. */
+export declare function guardaCache(raiz: string, brain: Brain): Promise<void>;
+export declare function leCache(raiz: string): Promise<CacheDeAncoras | null>;
+/** O que o hook recebe do Claude Code no stdin. So os campos que usamos. */
+export type EntradaDoHook = {
+    cwd?: string;
+    session_id?: string;
+    tool_name?: string;
+    tool_input?: {
+        file_path?: string;
+        old_string?: string;
+        new_string?: string;
+        content?: string;
+    };
+};
+/**
+ * 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 declare function caminhoRelativo(raiz: string, arquivo: string): string | null;
+/**
+ * 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 declare function alerta(tocadas: {
+    titulo: string;
+    pasta: string;
+    memoria: string;
+    ancora: string;
+}[], resumos: Map<string, string>): string;
+/**
+ * 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 declare function decideDoHook(entrada: EntradaDoHook): Promise<string>;

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

@@ -95,3 +95,39 @@ export declare function sugereReancoragem(ausentes: {
  * e o que a mensagem mostra: quem le precisa saber qual trecho a memoria guarda.
  */
 export declare function memoriasTocadas(brain: Brain, caminhos: string[]): Tocada[];
+/**
+ * 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 declare function caminhosDaArvore(raiz: string): Promise<string[]>;
+/**
+ * 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 declare function memoriasNoConteudo(brain: Brain, caminho: string, antes: string | null, depois: string | null): Tocada[];

package/dist/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/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" };

package/dist/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;
     }
@@ -926,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/politica.d.ts

@@ -1,3 +1,4 @@
+import type { Memoria } from "./brain.js";
 import type { RoadmapDaSessao } from "./roadmap.js";
 /**
  * A politica do projeto, buscada no servico na hora.
@@ -37,5 +38,11 @@ export type ResultadoDaPolitica = ({
      * nao imprime nada.
      */
     roadmap?: RoadmapDaSessao;
+    /**
+     * As memorias, de carona no mesmo payload. Servem para o cache de ancoras que o
+     * interceptador pre-voo consulta a cada edicao: o hook ja paga esta requisicao, e o
+     * cruzamento local nao pode pagar outra — ele e sincrono e roda a cada `Edit`.
+     */
+    memorias?: Memoria[];
 };
 export declare function buscaPolitica(raiz: string): Promise<ResultadoDaPolitica>;

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

@@ -62,8 +62,17 @@ export declare function criaFase(raiz: string, dados: NovaFase): Promise<{
     fase: Fase;
     criou: boolean;
 }>;
+/**
+ * A fase aberta imediatamente a frente, quando `ordem` foi pedida — `null` se a editada
+ * ficou na frente de todas, e ausente quando `ordem` nem foi mencionada.
+ */
+export type AtrasDe = {
+    slug: string;
+    titulo: string;
+} | null;
 export declare function editaFase(raiz: string, slug: string, dados: EdicaoDeFase): Promise<{
     fase: Fase;
+    atras_de: AtrasDe;
 }>;
 /** Rotulo do grupo de fases concluidas sem versao: o "Unreleased" do Keep a Changelog. */
 export declare const SEM_VERSAO = "Sem vers\u00E3o (ainda n\u00E3o lan\u00E7ado)";
@@ -82,6 +91,19 @@ export declare function blocoDeSessao(r: RoadmapDaSessao | null | undefined): st
  * separa por status. Concluidas nao aparecem aqui — sao changelog.
  */
 export declare function formataRoadmap(fases: Fase[]): string;
+/**
+ * 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 declare function avisoDeOrdem(fase: Pick<Fase, "ordem" | "status">, atrasDe: AtrasDe, pediuOrdem: boolean): string;
 /**
  * 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-harness",
-  "version": "0.18.0",
+  "version": "0.20.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",