dd-harness 0.32.1 → 0.33.0

package/dist/atualizar.d.ts

@@ -0,0 +1,31 @@
+/**
+ * O diagnostico de defasagem de um projeto que consome o dd-harness.
+ *
+ * Existe porque a atualizacao nao era automatica em lugar nenhum: o CLI e pacote global
+ * que fica na versao do dia da instalacao, e o bloco nos pontos de entrada era detectado
+ * de forma binaria — tem ou nao tem —, o que nunca responde "esta na versao atual?".
+ * Projeto em producao ficava para tras sem nada avisar.
+ *
+ * Aqui so DIAGNOSTICA. Aplicar e decisao de quem chama, porque parte do que sai daqui
+ * exige julgamento humano (bloco editado a mao) e parte nao (hook faltando).
+ */
+export type Item = {
+    o_que: string;
+    situacao: string;
+    acao: "aplicar" | "perguntar" | "em-dia" | "manual";
+    detalhe?: string;
+};
+/**
+ * `aplicar` e o que esta funcao pode fazer sozinha com seguranca; `perguntar` exige o dono
+ * do arquivo; `manual` e o que nao se resolve de dentro do repositorio (o CLI global e por
+ * maquina, nao por projeto).
+ */
+export declare function diagnosticaAtualizacao(raiz: string, versaoInstalada: string, versaoPublicada: string | null): Promise<Item[]>;
+/**
+ * Aplica so os itens marcados `aplicar`. Os de `perguntar` ficam intactos de proposito —
+ * quem decide sobre arquivo editado a mao e o dono dele.
+ */
+export declare function aplicaAtualizacao(raiz: string, itens: Item[]): Promise<string[]>;
+/** A versao publicada no npm. Nunca lanca: diagnostico sem rede ainda vale para o resto. */
+export declare function versaoPublicada(signal?: AbortSignal): Promise<string | null>;
+export declare function versaoInstalada(url: string): Promise<string>;

package/dist/atualizar.js

@@ -0,0 +1,103 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { analisa } from "./bloco.js";
+import { MOLDES_HISTORICOS } from "./moldes-historicos.js";
+import { COMANDO_DO_CINTO, COMANDO_DO_HOOK, SUGESTAO_AGENTS, VERSAO_DO_MOLDE, escreveHook, escrevePonteiro } from "./escreve-config.js";
+import { versaoDoPacote } from "./versao.js";
+/**
+ * `aplicar` e o que esta funcao pode fazer sozinha com seguranca; `perguntar` exige o dono
+ * do arquivo; `manual` e o que nao se resolve de dentro do repositorio (o CLI global e por
+ * maquina, nao por projeto).
+ */
+export async function diagnosticaAtualizacao(raiz, versaoInstalada, versaoPublicada) {
+    const itens = [];
+    // 1. O CLI global — por maquina, nao por projeto. Rodar em dez pastas nao muda nada.
+    if (versaoPublicada && versaoPublicada !== versaoInstalada) {
+        itens.push({
+            o_que: "CLI",
+            situacao: `instalado ${versaoInstalada}, publicado ${versaoPublicada}`,
+            acao: "manual",
+            detalhe: "npm i -g dd-harness@latest (por máquina, não por projeto)",
+        });
+    }
+    else {
+        itens.push({ o_que: "CLI", situacao: `${versaoInstalada}`, acao: "em-dia" });
+    }
+    // 2. Os dois pontos de entrada. Espelhos: o mesmo bloco, a mesma versao.
+    for (const arquivo of ["CLAUDE.md", "AGENTS.md"]) {
+        const cru = await readFile(join(raiz, arquivo), "utf8").catch(() => null);
+        if (cru === null) {
+            itens.push({ o_que: arquivo, situacao: "ausente", acao: "aplicar", detalhe: "será criado" });
+            continue;
+        }
+        const a = analisa(cru, [SUGESTAO_AGENTS, ...MOLDES_HISTORICOS]);
+        if (a.caso === "ambiguo") {
+            itens.push({ o_que: arquivo, situacao: "precisa de decisão", acao: "perguntar", detalhe: a.motivo });
+        }
+        else if (a.caso === "ausente") {
+            itens.push({ o_que: arquivo, situacao: "sem o bloco do harness", acao: "aplicar", detalhe: "entra no fim do arquivo" });
+        }
+        else if (a.caso === "migravel") {
+            itens.push({ o_que: arquivo, situacao: "bloco sem carimbo (instalado antes das marcas)", acao: "aplicar",
+                detalhe: `será marcado e carimbado ${VERSAO_DO_MOLDE}` });
+        }
+        else if (a.versao !== VERSAO_DO_MOLDE) {
+            itens.push({ o_que: arquivo, situacao: `bloco em ${a.versao}, atual ${VERSAO_DO_MOLDE}`, acao: "aplicar",
+                detalhe: "troca só o miolo do bloco; o resto do arquivo não é tocado" });
+        }
+        else if (a.corpo !== SUGESTAO_AGENTS.trim()) {
+            // Mesma versao, texto diferente: alguem editou dentro do bloco.
+            itens.push({ o_que: arquivo, situacao: `carimbado ${a.versao}, mas o texto foi editado`, acao: "perguntar",
+                detalhe: "o conteúdo dentro do bloco não é o do molde" });
+        }
+        else {
+            itens.push({ o_que: arquivo, situacao: `${a.versao}`, acao: "em-dia" });
+        }
+    }
+    // 3. Hooks. `escreveHook` ja e idempotente e nao toca em hook alheio.
+    // Pelas constantes, nao por string repetida: o hook do cinto so entrou numa versao
+    // posterior, e um projeto antigo tem o SessionStart sem ele — que e o caso mais comum
+    // de defasagem, e o que mais custa, porque o cinto e o que avisa antes da edicao.
+    const settings = await readFile(join(raiz, ".claude/settings.json"), "utf8").catch(() => "");
+    const temOsDois = settings.includes(COMANDO_DO_HOOK) && settings.includes(COMANDO_DO_CINTO);
+    itens.push(temOsDois
+        ? { o_que: "hooks", situacao: "sessão e cinto declarados", acao: "em-dia" }
+        : { o_que: "hooks", situacao: settings ? "incompletos ou legados" : "ausentes", acao: "aplicar",
+            detalhe: "acrescenta sem duplicar nem tocar em hook de terceiro" });
+    return itens;
+}
+/**
+ * Aplica so os itens marcados `aplicar`. Os de `perguntar` ficam intactos de proposito —
+ * quem decide sobre arquivo editado a mao e o dono dele.
+ */
+export async function aplicaAtualizacao(raiz, itens) {
+    const feitos = [];
+    for (const item of itens.filter(i => i.acao === "aplicar")) {
+        if (item.o_que === "CLAUDE.md" || item.o_que === "AGENTS.md") {
+            const r = await escrevePonteiro(raiz, item.o_que);
+            feitos.push(`${item.o_que}: ${r.estado}${r.de ? ` (de ${r.de} para ${VERSAO_DO_MOLDE})` : ""}`);
+        }
+        else if (item.o_que === "hooks") {
+            const r = await escreveHook(raiz);
+            // `ok: false` e settings.json invalido — nao foi escrito, e dizer "ok" aqui esconderia
+            // um projeto que continua sem o cinto.
+            feitos.push(r.ok ? `hooks: ${r.estado}` : `hooks: NÃO aplicado (${r.motivo})`);
+        }
+    }
+    return feitos;
+}
+/** A versao publicada no npm. Nunca lanca: diagnostico sem rede ainda vale para o resto. */
+export async function versaoPublicada(signal) {
+    try {
+        const r = await fetch("https://registry.npmjs.org/dd-harness/latest", { signal });
+        if (!r.ok)
+            return null;
+        return (await r.json()).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function versaoInstalada(url) {
+    return versaoDoPacote(url, "dd-harness").catch(() => "desconhecida");
+}

package/dist/bloco.d.ts

@@ -0,0 +1,54 @@
+/**
+ * O bloco do harness dentro de um CLAUDE.md/AGENTS.md que pertence ao projeto.
+ *
+ * O arquivo e do repositorio, nao nosso — a decisao esta no Brain
+ * (`import-do-claude-md-falha-calado`): a parte gerenciada CONVIVE com o que o projeto
+ * tem de proprio, em vez de sobrescrever o arquivo de alguem. O que este modulo
+ * acrescenta e a fronteira explicita dessa convivencia: marcas de inicio e fim, com a
+ * versao carimbada.
+ *
+ * Sem a fronteira, atualizar e adivinhacao. A deteccao anterior era binaria — o arquivo
+ * contem `ler_artefato`, sim ou nao —, o que responde "ja foi instalado?" e nunca "esta
+ * na versao atual?". Foi assim que um projeto em producao ficou para tras: tinha o bloco,
+ * entao o init disse "ja-tinha" e nao tocou em nada, enquanto o texto do molde mudava.
+ *
+ * Com a fronteira, trocar o miolo e seguro por CONSTRUCAO: o que esta fora das marcas
+ * nunca e lido para decidir, muito menos reescrito. A regra do dono do projeto — "o
+ * CLAUDE.md e diferente para cada um; edite so a linha que e nossa" — deixa de depender
+ * da atencao de quem roda a atualizacao.
+ */
+export type Analise = {
+    caso: "ausente";
+} | {
+    caso: "marcado";
+    versao: string;
+    corpo: string;
+    antes: string;
+    depois: string;
+} | {
+    caso: "migravel";
+    corpo: string;
+    antes: string;
+    depois: string;
+} | {
+    caso: "ambiguo";
+    motivo: string;
+};
+/** `<!-- dd-harness:inicio v1.3.0 -->` — a versao e o que responde "atualizado ate onde?". */
+export declare function marcaDeInicio(versao: string): string;
+/**
+ * Le o arquivo e diz em que caso ele esta. Nao decide nada e nao escreve: quem chama e
+ * que sabe se pode aplicar sozinho ou se precisa perguntar.
+ *
+ * `textoConhecido` e o molde de uma versao anterior, usado so para reconhecer um bloco
+ * que ainda nao tem marca — o caso de todo projeto instalado antes desta mudanca.
+ */
+export declare function analisa(arquivo: string, textoConhecido: string | string[]): Analise;
+/** Monta o bloco com as marcas. Uma linha em branco de cada lado: markdown gruda. */
+export declare function envolve(corpo: string, versao: string): string;
+/**
+ * Devolve o arquivo com o bloco na versao nova, preservando tudo que esta fora dele.
+ *
+ * Nao decide se DEVE atualizar — so produz o texto. Caso ambiguo nem chega aqui.
+ */
+export declare function aplica(arquivo: string, corpo: string, versao: string, analise: Analise): string;

package/dist/bloco.js

@@ -0,0 +1,100 @@
+/**
+ * O bloco do harness dentro de um CLAUDE.md/AGENTS.md que pertence ao projeto.
+ *
+ * O arquivo e do repositorio, nao nosso — a decisao esta no Brain
+ * (`import-do-claude-md-falha-calado`): a parte gerenciada CONVIVE com o que o projeto
+ * tem de proprio, em vez de sobrescrever o arquivo de alguem. O que este modulo
+ * acrescenta e a fronteira explicita dessa convivencia: marcas de inicio e fim, com a
+ * versao carimbada.
+ *
+ * Sem a fronteira, atualizar e adivinhacao. A deteccao anterior era binaria — o arquivo
+ * contem `ler_artefato`, sim ou nao —, o que responde "ja foi instalado?" e nunca "esta
+ * na versao atual?". Foi assim que um projeto em producao ficou para tras: tinha o bloco,
+ * entao o init disse "ja-tinha" e nao tocou em nada, enquanto o texto do molde mudava.
+ *
+ * Com a fronteira, trocar o miolo e seguro por CONSTRUCAO: o que esta fora das marcas
+ * nunca e lido para decidir, muito menos reescrito. A regra do dono do projeto — "o
+ * CLAUDE.md e diferente para cada um; edite so a linha que e nossa" — deixa de depender
+ * da atencao de quem roda a atualizacao.
+ */
+/** Comentario HTML: invisivel no render, e o modelo que le o arquivo cru ignora sem ruido. */
+const INICIO = "<!-- dd-harness:inicio";
+const FIM = "<!-- dd-harness:fim -->";
+/** `<!-- dd-harness:inicio v1.3.0 -->` — a versao e o que responde "atualizado ate onde?". */
+export function marcaDeInicio(versao) {
+    return `${INICIO} ${versao} -->`;
+}
+/**
+ * Le o arquivo e diz em que caso ele esta. Nao decide nada e nao escreve: quem chama e
+ * que sabe se pode aplicar sozinho ou se precisa perguntar.
+ *
+ * `textoConhecido` e o molde de uma versao anterior, usado so para reconhecer um bloco
+ * que ainda nao tem marca — o caso de todo projeto instalado antes desta mudanca.
+ */
+export function analisa(arquivo, textoConhecido) {
+    const conhecidos = (Array.isArray(textoConhecido) ? textoConhecido : [textoConhecido])
+        .map(t => t.trim()).filter(Boolean);
+    const i = arquivo.indexOf(INICIO);
+    if (i !== -1) {
+        const fimDaMarca = arquivo.indexOf("-->", i);
+        const f = arquivo.indexOf(FIM, i);
+        // Marca de inicio sem fim e arquivo truncado ou editado a mao. Mexer nele as cegas
+        // apagaria conteudo do projeto — exatamente o que este modulo existe para impedir.
+        if (fimDaMarca === -1 || f === -1) {
+            return { caso: "ambiguo", motivo: "marca de início sem marca de fim correspondente" };
+        }
+        if (arquivo.indexOf(INICIO, i + 1) !== -1) {
+            return { caso: "ambiguo", motivo: "mais de um bloco do dd-harness no arquivo" };
+        }
+        const versao = arquivo.slice(i + INICIO.length, fimDaMarca).trim();
+        return {
+            caso: "marcado",
+            versao,
+            corpo: arquivo.slice(fimDaMarca + 3, f).trim(),
+            antes: arquivo.slice(0, i),
+            depois: arquivo.slice(f + FIM.length),
+        };
+    }
+    // Sem marca: procura o bloco pelo texto EXATO de alguma versao que ja existiu. Exato de
+    // proposito — encontrar "parecido" e o comeco de reescrever o que o dono escreveu.
+    //
+    // Varias versoes porque um projeto instalado ha meses tem o molde daquela epoca, e sem
+    // reconhece-lo ele cairia em "editado a mao": o caminho seguro, mas errado, porque
+    // ninguem editou nada. Projeto atrasado e o caso COMUM, e ele tem que se resolver sozinho.
+    for (const conhecido of conhecidos) {
+        const j = arquivo.indexOf(conhecido);
+        if (j !== -1) {
+            return {
+                caso: "migravel",
+                corpo: conhecido,
+                antes: arquivo.slice(0, j),
+                depois: arquivo.slice(j + conhecido.length),
+            };
+        }
+    }
+    // Tem nosso protocolo, mas nao como o molde o escreveu: foi editado. Caso de perguntar,
+    // nunca de sobrescrever.
+    if (arquivo.includes("ler_artefato")) {
+        return { caso: "ambiguo", motivo: "o bloco existe mas foi editado; não bate com nenhum molde conhecido" };
+    }
+    return { caso: "ausente" };
+}
+/** Monta o bloco com as marcas. Uma linha em branco de cada lado: markdown gruda. */
+export function envolve(corpo, versao) {
+    return `${marcaDeInicio(versao)}\n\n${corpo.trim()}\n\n${FIM}`;
+}
+/**
+ * Devolve o arquivo com o bloco na versao nova, preservando tudo que esta fora dele.
+ *
+ * Nao decide se DEVE atualizar — so produz o texto. Caso ambiguo nem chega aqui.
+ */
+export function aplica(arquivo, corpo, versao, analise) {
+    const bloco = envolve(corpo, versao);
+    if (analise.caso === "marcado" || analise.caso === "migravel") {
+        return `${analise.antes}${bloco}${analise.depois}`;
+    }
+    // Ausente: entra no fim, que e onde o molde sempre acrescentou.
+    if (arquivo.trim() === "")
+        return `${bloco}\n`;
+    return `${arquivo}${arquivo.endsWith("\n") ? "\n" : "\n\n"}${bloco}\n`;
+}

package/dist/escreve-config.d.ts

@@ -19,6 +19,8 @@ export type ResultadoDaEscrita<T extends string> = {
     motivo: "json-invalido";
     caminho: string;
 };
+export declare const COMANDO_DO_HOOK = "dd-harness politica --hook";
+export declare const COMANDO_DO_CINTO = "dd-harness cinto";
 /**
  * Acrescenta o hook do dd-harness a `.claude/settings.json`, sem tocar em outros hooks.
  *
@@ -44,10 +46,26 @@ export declare function escreveMcp(raiz: string): Promise<ResultadoDaEscrita<"cr
  * de objeto.
  */
 export declare function escrevePonteiro(raiz: string, arquivo: "AGENTS.md" | "CLAUDE.md"): Promise<{
-    estado: "criado" | "ja-tinha" | "acrescentado";
+    estado: "criado" | "ja-tinha" | "acrescentado" | "atualizado" | "migrado" | "precisa-decisao";
+    de?: string;
+    motivo?: string;
 }>;
 /** Compatibilidade: `init` ainda chama pelo nome antigo. */
 export declare const escreveAgents: (raiz: string) => Promise<{
-    estado: "criado" | "ja-tinha" | "acrescentado";
+    estado: "criado" | "ja-tinha" | "acrescentado" | "atualizado" | "migrado" | "precisa-decisao";
+    de?: string;
+    motivo?: string;
 }>;
+/**
+ * A versao do MOLDE, que nao e a do CLI.
+ *
+ * O CLI publica por correcao — 0.32.1 saiu de um fix que nao mudou uma linha do texto
+ * abaixo. Carimbar a versao do pacote faria todo projeto parecer desatualizado a cada
+ * publicacao, e "desatualizado" que aparece sem nada para fazer e o aviso que ensina a
+ * ignorar aviso.
+ *
+ * Suba este numero SO quando o texto do bloco mudar de fato. E o carimbo que um projeto
+ * em producao compara para saber se precisa de atualizacao.
+ */
+export declare const VERSAO_DO_MOLDE = "v1.3.0";
 export declare const SUGESTAO_AGENTS = "## Protocolo do dd-harness\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\nLeia tamb\u00E9m o briefing com a mesma ferramenta (tipo briefing). Os dois s\u00E3o obrigat\u00F3rios.\n\nDepois, `ler_roadmap`: se houver uma fase **Agora**, \u00E9 dela que saem os passos\ndesta sess\u00E3o. Lista vazia significa que este projeto n\u00E3o usa roadmap, e isso \u00E9\nv\u00E1lido \u2014 n\u00E3o crie fase sem o usu\u00E1rio pedir.\n\nE `listar_skills`: s\u00E3o os procedimentos deste projeto. **Invoque a que couber\nANTES de fazer o trabalho, n\u00E3o depois** \u2014 skill lida no fim vira revis\u00E3o do que\nj\u00E1 saiu errado, e \u00E9 tarde.\n\nVale mesmo quando o pedido parece pequeno: \"\u00E9 s\u00F3 um ajuste\" \u00E9 exatamente a\nfrase que antecede pular o procedimento. A pol\u00EDtica diz quais s\u00E3o obrigat\u00F3rias\ne quando.";

package/dist/escreve-config.js

@@ -1,7 +1,9 @@
 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";
+import { analisa, aplica } from "./bloco.js";
+import { MOLDES_HISTORICOS } from "./moldes-historicos.js";
+export const COMANDO_DO_HOOK = "dd-harness politica --hook";
+export const COMANDO_DO_CINTO = "dd-harness cinto";
 /**
  * Acrescenta o hook do dd-harness a `.claude/settings.json`, sem tocar em outros hooks.
  *
@@ -92,7 +94,6 @@ export async function escreveMcp(raiz) {
  */
 export async function escrevePonteiro(raiz, arquivo) {
     const caminho = join(raiz, arquivo);
-    const instrucao = SUGESTAO_AGENTS;
     let atual = null;
     try {
         atual = await readFile(caminho, "utf8");
@@ -101,39 +102,66 @@ export async function escrevePonteiro(raiz, arquivo) {
         // Sem arquivo: cria do zero.
     }
     if (atual === null) {
-        await writeFile(caminho, `${instrucao}\n`, "utf8");
+        await writeFile(caminho, `${aplica("", SUGESTAO_AGENTS, VERSAO_DO_MOLDE, { caso: "ausente" })}`, "utf8");
         return { estado: "criado" };
     }
-    if (atual.includes("ler_artefato"))
+    const analise = analisa(atual, [SUGESTAO_AGENTS, ...MOLDES_HISTORICOS]);
+    // Bloco editado, truncado ou duplicado: quem decide e o dono do arquivo. Escrever aqui
+    // seria apagar o que alguem escreveu — o unico erro desta funcao que nao da para desfazer
+    // sem o git.
+    if (analise.caso === "ambiguo") {
+        return { estado: "precisa-decisao", motivo: analise.motivo };
+    }
+    // Ja esta na versao atual: nao reescreve, para o `start` nao sujar o git toda vez.
+    if (analise.caso === "marcado" && analise.versao === VERSAO_DO_MOLDE && analise.corpo === SUGESTAO_AGENTS.trim()) {
+        return { estado: "ja-tinha" };
+    }
+    const novo = aplica(atual, SUGESTAO_AGENTS, VERSAO_DO_MOLDE, analise);
+    if (novo === atual)
         return { estado: "ja-tinha" };
-    const separador = atual.endsWith("\n") ? "\n" : "\n\n";
-    await writeFile(caminho, `${atual}${separador}${instrucao}\n`, "utf8");
+    await writeFile(caminho, novo, "utf8");
+    if (analise.caso === "marcado")
+        return { estado: "atualizado", de: analise.versao };
+    if (analise.caso === "migravel")
+        return { estado: "migrado" };
     return { estado: "acrescentado" };
 }
 /** Compatibilidade: `init` ainda chama pelo nome antigo. */
 export const escreveAgents = (raiz) => escrevePonteiro(raiz, "AGENTS.md");
+/**
+ * A versao do MOLDE, que nao e a do CLI.
+ *
+ * O CLI publica por correcao — 0.32.1 saiu de um fix que nao mudou uma linha do texto
+ * abaixo. Carimbar a versao do pacote faria todo projeto parecer desatualizado a cada
+ * publicacao, e "desatualizado" que aparece sem nada para fazer e o aviso que ensina a
+ * ignorar aviso.
+ *
+ * Suba este numero SO quando o texto do bloco mudar de fato. E o carimbo que um projeto
+ * em producao compara para saber se precisa de atualizacao.
+ */
+export const VERSAO_DO_MOLDE = "v1.3.0";
 export const SUGESTAO_AGENTS = `## Protocolo do dd-harness
-
-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.
-
+
+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.
+
 Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
 
 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.
-
-E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
-ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
-já saiu errado, e é tarde.
-
-Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
-frase que antecede pular o procedimento. A política diz quais são obrigatórias
+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.
+
+E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
+ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
+já saiu errado, e é tarde.
+
+Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
+frase que antecede pular o procedimento. A política diz quais são obrigatórias
 e quando.`;

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { diagnostico } from "./diagnostico.js";
+import { aplicaAtualizacao, diagnosticaAtualizacao, versaoInstalada, versaoPublicada } from "./atualizar.js";
 import { instalaHosts, selecionaHosts } from "./hosts.js";
 import { achaRaiz } from "./config.js";
 import { abreSessao, guardaSessao, saidaDaGuarda, saidaDoBoot } from "./sessao.js";
@@ -43,84 +44,89 @@ import { REGRA_DE_COMMITS } from "./regras-de-commit.js";
  * em repositorio alheio tem que envelhecer bem, e cada dependencia e uma chance de nao
  * envelhecer.
  */
-const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
-
+const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
+
   dd-harness diagnostico [--mcp]    confere projeto, contexto e conexão MCP
+  dd-harness atualizar [--aplicar]  diz o que neste projeto ficou para trás do
+                                     harness atual (CLI, hooks, bloco do
+                                     CLAUDE.md/AGENTS.md) e, com --aplicar,
+                                     atualiza o que é seguro. O que está FORA
+                                     do bloco é do projeto e nunca é tocado
   dd-harness integrar --host todos  instala MCP/regras/hooks em projeto existente
   dd-harness sessao --host <host>    hook de boot (stdin JSON)
   dd-harness guarda --host <host>    hook antes de ferramentas (stdin JSON)
-  dd-harness start [--host <host>]   numa pasta vazia: conduz tudo (login,
-                                     espaço, projeto, config) numa tacada
-  dd-harness login --token <token> [--api <url>]
-                                     guarda a credencial desta máquina
-  dd-harness projeto <slug> --nome "<nome>" [--tenant <t>] [--api <url>]
-                                     cria o projeto no serviço (antes do init)
-  dd-harness init --tenant <t> --projeto <p> [--api <url>]
-                                     escreve .dd-harness.json; depois rode integrar
-  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
-                                     cria a pasta que o gravar exige
-  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
-  dd-harness editar <arquivo.md>     corrige o que já está gravado
-  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
-                     [--substituida-por <pasta>/<slug>]
-                                     tira de circulação sem apagar
-  dd-harness promover <pasta>/<slug>
-                                     torna a memória global: vale para TODO
-                                     projeto do espaço, inclusive os futuros
-  dd-harness despromover <pasta>/<slug>
-                                     traz de volta ao alcance dos vínculos
-  dd-harness apagar <pasta>/<slug> [--confirmar <espaço>]
-                                     apaga de vez, em cascata — sem desfazer.
-                                     Para tirar de circulação guardando o
-                                     conteúdo, use "arquivar"
-  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
-  dd-harness ler <pasta>/<slug>      imprime a memória inteira, no formato de gravar
-  dd-harness reancorar <pasta>/<slug> --de "<alvo>" --para "<alvo>"
-                                     troca o alvo de uma âncora que mudou de lugar
-  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
-  dd-harness status                  só lê: o tamanho do Brain e o que espera julgamento
-  dd-harness politica [--hook]       imprime a política do serviço
-                                     saída 0 = veio; 3 = projeto sem política;
-                                     1 = não consegui buscar
-                                     --hook: fala o protocolo do SessionStart do
-                                     Claude Code, para pôr a política no contexto
-  dd-harness 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 skills                 as skills deste projeto e quando cada uma serve
-  dd-harness skill <nome>           o procedimento de uma delas (o mesmo que o
-                                     agente recebe ao invocá-la)
-  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>]
-                                     o que já foi concluído, agrupado por versão
-  dd-harness fase criar --titulo "<t>" [--conteudo <arquivo.md>] [--versao <v>]
-                     [--status ideia|aberta|concluida] [--slug <s>]
-  dd-harness fase editar <slug> [--titulo "<t>"] [--conteudo <arquivo.md>]
-                     [--versao <v> | --sem-versao] [--status <s>] [--ordem <n>]
-                                     concluir = --status concluida: a fase sai do
-                                     roadmap e entra no changelog, nada migra
-  dd-harness --help
-  dd-harness --version              qual binário está instalado nesta máquina
-
+  dd-harness start [--host <host>]   numa pasta vazia: conduz tudo (login,
+                                     espaço, projeto, config) numa tacada
+  dd-harness login --token <token> [--api <url>]
+                                     guarda a credencial desta máquina
+  dd-harness projeto <slug> --nome "<nome>" [--tenant <t>] [--api <url>]
+                                     cria o projeto no serviço (antes do init)
+  dd-harness init --tenant <t> --projeto <p> [--api <url>]
+                                     escreve .dd-harness.json; depois rode integrar
+  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
+                                     cria a pasta que o gravar exige
+  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
+  dd-harness editar <arquivo.md>     corrige o que já está gravado
+  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
+                     [--substituida-por <pasta>/<slug>]
+                                     tira de circulação sem apagar
+  dd-harness promover <pasta>/<slug>
+                                     torna a memória global: vale para TODO
+                                     projeto do espaço, inclusive os futuros
+  dd-harness despromover <pasta>/<slug>
+                                     traz de volta ao alcance dos vínculos
+  dd-harness apagar <pasta>/<slug> [--confirmar <espaço>]
+                                     apaga de vez, em cascata — sem desfazer.
+                                     Para tirar de circulação guardando o
+                                     conteúdo, use "arquivar"
+  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
+  dd-harness ler <pasta>/<slug>      imprime a memória inteira, no formato de gravar
+  dd-harness reancorar <pasta>/<slug> --de "<alvo>" --para "<alvo>"
+                                     troca o alvo de uma âncora que mudou de lugar
+  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
+  dd-harness status                  só lê: o tamanho do Brain e o que espera julgamento
+  dd-harness politica [--hook]       imprime a política do serviço
+                                     saída 0 = veio; 3 = projeto sem política;
+                                     1 = não consegui buscar
+                                     --hook: fala o protocolo do SessionStart do
+                                     Claude Code, para pôr a política no contexto
+  dd-harness 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 skills                 as skills deste projeto e quando cada uma serve
+  dd-harness skill <nome>           o procedimento de uma delas (o mesmo que o
+                                     agente recebe ao invocá-la)
+  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>]
+                                     o que já foi concluído, agrupado por versão
+  dd-harness fase criar --titulo "<t>" [--conteudo <arquivo.md>] [--versao <v>]
+                     [--status ideia|aberta|concluida] [--slug <s>]
+  dd-harness fase editar <slug> [--titulo "<t>"] [--conteudo <arquivo.md>]
+                     [--versao <v> | --sem-versao] [--status <s>] [--ordem <n>]
+                                     concluir = --status concluida: a fase sai do
+                                     roadmap e entra no changelog, nada migra
+  dd-harness --help
+  dd-harness --version              qual binário está instalado nesta máquina
+
 Política e briefing chegam do serviço. O disco guarda configuração, ponteiros
 para skills e estado descartável em ~/.dd-harness. Hosts: claude, codex,
-antigravity, lista separada por vírgulas ou todos.
+antigravity, lista separada por vírgulas ou todos.
 `;
 /**
  * Os ganchos sao IMPRESSOS, nunca instalados. `.git/hooks` nao e versionado e nao e
  * nosso: escrever la dentro sem a pessoa pedir e o mesmo tipo de invasao que
  * sobrescrever o CLAUDE.md dela. Quem cola, decide.
  */
-const GANCHOS = `
-Opcional — o gancho que devolve a memória ao code review:
-
-  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
-    #!/bin/sh
-    dd-harness check --commit "$(git rev-parse HEAD)" || true
-
-Termina em sucesso mesmo com deriva: avisa, não bloqueia.
-
+const GANCHOS = `
+Opcional — o gancho que devolve a memória ao code review:
+
+  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
+    #!/bin/sh
+    dd-harness check --commit "$(git rev-parse HEAD)" || true
+
+Termina em sucesso mesmo com deriva: avisa, não bloqueia.
+
 Instale os hooks de sessão e guarda com \`dd-harness integrar --host <host>\`.`;
 function argumento(argv, nome) {
     const i = argv.indexOf(`--${nome}`);
@@ -155,7 +161,7 @@ async function comandoSkill(argv) {
         throw new Error("uso: dd-harness skill <nome>");
     }
     const s = await leSkill(process.cwd(), slug);
-    console.log(`# ${s.slug}
+    console.log(`# ${s.slug}
 `);
     console.log(s.descricao);
     console.log("");
@@ -516,6 +522,40 @@ async function temWorkerConfigurado() {
     const { workerRepo } = await leConfigDaMaquina();
     return Boolean(workerRepo);
 }
+/**
+ * Diagnostica (e opcionalmente aplica) a defasagem deste projeto.
+ *
+ * O padrao e SO RELATAR: comando que edita `CLAUDE.md` de projeto em producao nao faz isso
+ * por omissao. `--aplicar` escreve o que e seguro, e nunca o que exige decisao do dono.
+ */
+async function comandoAtualizar(argv) {
+    const raiz = await achaRaiz();
+    const itens = await diagnosticaAtualizacao(raiz, await versaoInstalada(import.meta.url), await versaoPublicada(AbortSignal.timeout(6000)));
+    const simbolo = { "em-dia": "ok  ", aplicar: "->  ", perguntar: "??  ", manual: "!   " };
+    for (const i of itens) {
+        console.log(`${simbolo[i.acao]}${i.o_que}: ${i.situacao}${i.detalhe ? ` — ${i.detalhe}` : ""}`);
+    }
+    const aAplicar = itens.filter(i => i.acao === "aplicar");
+    const aPerguntar = itens.filter(i => i.acao === "perguntar");
+    if (!argv.includes("--aplicar")) {
+        console.log(aAplicar.length
+            ? `\n${aAplicar.length} item(ns) podem ser aplicados: dd-harness atualizar --aplicar`
+            : "\nNada a aplicar automaticamente.");
+    }
+    else if (aAplicar.length) {
+        console.log("");
+        for (const linha of await aplicaAtualizacao(raiz, itens))
+            console.log(linha);
+    }
+    // Estes ficam de fora do `--aplicar` de proposito: o arquivo foi editado a mao, e so o
+    // dono sabe se a edicao dele continua valendo depois da mudanca do molde.
+    if (aPerguntar.length) {
+        console.log(`\n${aPerguntar.length} item(ns) NÃO foram tocados por exigirem decisão sua:`);
+        for (const i of aPerguntar)
+            console.log(`  ${i.o_que}: ${i.detalhe ?? i.situacao}`);
+        console.log("  Use a skill atualizar-harness para conduzir esses casos.");
+    }
+}
 async function comandoInit(argv) {
     const tenant = argumento(argv, "tenant");
     const projeto = argumento(argv, "projeto");
@@ -591,7 +631,7 @@ async function comandoApagar(argv) {
     if (!r.apagou) {
         console.log(r.detalhe);
         if (r.confirmacaoEsperada) {
-            console.log(`
+            console.log(`
   dd-harness apagar ${endereco} --confirmar ${r.confirmacaoEsperada}`);
         }
         // Sem exit diferente de zero: recusar por falta de confirmacao nao e falha, e o
@@ -644,7 +684,7 @@ async function comandoBuscar(argv) {
         if (!r.semantica) {
             console.log("  (só busca textual: sem provedor de embedding no serviço)");
         }
-        avisaSobreAFila(r.esperandoIndexacao);
+        await avisaSobreAFila(r.esperandoIndexacao);
         return;
     }
     console.log(r.semantica
@@ -654,19 +694,26 @@ async function comandoBuscar(argv) {
         console.log(`  ${a.endereco} — ${a.titulo}`);
         console.log(`    ${a.resumo}`);
     }
-    avisaSobreAFila(r.esperandoIndexacao);
+    await 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) {
+async function avisaSobreAFila(esperando) {
     if (esperando <= 0)
         return;
+    // Dispara em vez de pedir: indexar e trabalho da maquina. O comando so seria executavel
+    // dentro do monorepo do harness, e quem roda `buscar` esta no projeto dele.
+    const worker = await subiuOWorker(process.cwd(), esperando);
     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`.");
+    console.log(worker.subiu
+        ? "  melhores que não apareceram aqui. Indexação disparada; repita a busca em instantes."
+        : worker.motivo === "sem-worker"
+            ? "  melhores que não apareceram aqui. Configure o worker com `dd-harness worker --configurar`."
+            : "  melhores que não apareceram aqui. Não consegui disparar o worker automaticamente.");
 }
 async function comandoReancorar(argv) {
     const endereco = argv[0];
@@ -1179,6 +1226,8 @@ async function principal() {
         case "diagnostico":
             console.log((await diagnostico(process.cwd(), resto.includes("--mcp"))).join("\n"));
             break;
+        case "atualizar":
+            return comandoAtualizar(resto);
         case "integrar": {
             const hosts = selecionaHosts(argumento(resto, "host") ?? "todos");
             for (const aviso of await instalaHosts(process.cwd(), hosts))

package/dist/moldes-historicos.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Os textos do molde que ja estiveram em projetos reais.
+ *
+ * GERADO por scripts/extrai-moldes-historicos.mjs a partir do historico do git. Serve a uma
+ * coisa so: reconhecer o bloco de um projeto que ficou para tras, para migra-lo sozinho em
+ * vez de perguntar. Sem isto, "projeto desatualizado" e "arquivo editado a mao" ficam
+ * indistinguiveis — e o primeiro, que e o caso comum, receberia o tratamento do segundo.
+ *
+ * Do mais novo para o mais antigo. Nao editar a mao: regenerar.
+ */
+export declare const MOLDES_HISTORICOS: string[];

package/dist/moldes-historicos.js

@@ -0,0 +1,90 @@
+/**
+ * Os textos do molde que ja estiveram em projetos reais.
+ *
+ * GERADO por scripts/extrai-moldes-historicos.mjs a partir do historico do git. Serve a uma
+ * coisa so: reconhecer o bloco de um projeto que ficou para tras, para migra-lo sozinho em
+ * vez de perguntar. Sem isto, "projeto desatualizado" e "arquivo editado a mao" ficam
+ * indistinguiveis — e o primeiro, que e o caso comum, receberia o tratamento do segundo.
+ *
+ * Do mais novo para o mais antigo. Nao editar a mao: regenerar.
+ */
+export const MOLDES_HISTORICOS = [
+    // ca1e529
+    `## Protocolo do dd-harness
+
+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.
+
+Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
+
+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.
+
+E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
+ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
+já saiu errado, e é tarde.
+
+Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
+frase que antecede pular o procedimento. A política diz quais são obrigatórias
+e quando.`,
+    // 875342e
+    `## Protocolo do dd-harness
+
+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.
+
+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.
+
+E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
+ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
+já saiu errado, e é tarde.
+
+Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
+frase que antecede pular o procedimento. A política diz quais são obrigatórias
+e quando.`,
+    // f59da48
+    `## Protocolo do dd-harness
+
+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.
+
+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.`,
+    // 5fb3f02
+    `## Protocolo do dd-harness
+
+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.`,
+];

package/dist/skills-iniciais.d.ts

@@ -11,10 +11,13 @@ import type { NovaSkillInicial } from "./skill.js";
  * recebe nada: se alguem apagou uma delas, foi decisao — e recria-la a cada `start`
  * desfaria a decisao em silencio, toda vez.
  *
- * GERADO a partir dos SKILL.md em .claude/skills deste repositorio. Corrija la e
- * regenere; editar este arquivo a mao faz a correcao se perder na proxima geracao.
+ * GERADO por scripts/gera-skills-iniciais.mjs a partir dos SKILL.md em .claude/skills
+ * deste repositorio. Corrija la e regenere; editar este arquivo a mao faz a correcao se
+ * perder na proxima geracao.
  */
 export type SkillInicial = NovaSkillInicial & {
     ferramentas?: string[];
+    so_por_comando?: boolean;
+    dica_de_argumento?: string;
 };
 export declare const SKILLS_INICIAIS: SkillInicial[];

package/dist/skills-iniciais.js

@@ -458,4 +458,121 @@ Se a decisão vier com uma razão que sobrevive ao dia de hoje — "escolhemos X
 fornecedor limita Y" —, isso pode ser memória. Passe pelos três filtros antes de gravar;
 "experimentamos e gostamos" não passa em nenhum deles.`,
     },
+    {
+        slug: "atualizar-harness",
+        descricao: `Põe um projeto que consome o dd-harness na versão atual — CLI, hooks e o bloco do protocolo no CLAUDE.md/AGENTS.md — sem tocar no que é do projeto. Invoque quando o usuário pedir para atualizar ou alinhar um projeto ao harness atual, passando o caminho da pasta. Só por pedido explícito: escreve em OUTRO repositório.`,
+        ferramentas: ["mcp__dd-harness__ler_changelog", "Read", "Glob", "Grep", "Edit", "Bash"],
+        so_por_comando: true,
+        dica_de_argumento: "<caminho da pasta do projeto>",
+        conteudo: `# Atualizar o harness de um projeto
+
+Põe um projeto que consome o dd-harness na versão atual: CLI, hooks, e o bloco do
+protocolo nos pontos de entrada (\`CLAUDE.md\` e \`AGENTS.md\`).
+
+**Entrada esperada:** o caminho da pasta do projeto. Se o usuário não passou, pergunte —
+não presuma que é o diretório atual, porque esta skill quase sempre roda apontando para
+OUTRO projeto.
+
+---
+
+## 0. Antes de tudo: entenda o \`CLAUDE.md\` do alvo
+
+**Este é o passo mais importante da skill, e o único que não dá para automatizar.** Faça-o
+antes de rodar qualquer comando que escreva.
+
+O \`CLAUDE.md\` **é do projeto, não do dd-harness**. Cada um escreve o seu: regras de
+negócio, combinados da equipe, jeito de trabalhar daquele time. O harness ocupa ali um
+bloco delimitado — e **só esse bloco é nosso**.
+
+Leia o arquivo inteiro e responda, para você mesmo, três perguntas:
+
+1. **O que ali é do harness?** O bloco entre \`<!-- dd-harness:inicio ... -->\` e
+   \`<!-- dd-harness:fim -->\`. Se não houver marcas, o bloco é o trecho que fala de
+   \`ler_artefato\`/\`ler_roadmap\`/\`listar_skills\` — o protocolo que o molde escreve.
+
+2. **O que ali é do projeto?** Todo o resto. Regras próprias, seções inventadas pelo time,
+   uma linha que alguém acrescentou numa sexta-feira e não explicou. **Nada disso se toca.**
+
+3. **Alguém escreveu dentro do bloco?** É o caso que exige você. Uma regra do projeto pode
+   ter sido acrescentada lá dentro por conveniência — e ela tem que sobreviver à
+   atualização. Perceber isso é a diferença entre atualizar e destruir.
+
+> Já aconteceu: uma linha escrita à mão pelo dono do projeto foi tratada como texto do
+> molde e sobrescrita. Ele teve que dizer "é pq eu botei la". O arquivo é dele; a régua é
+> essa.
+
+**Regra que resume tudo:** na dúvida sobre se um trecho é nosso ou do projeto, **é do
+projeto**. Pergunte em vez de decidir.
+
+---
+
+## 1. Diagnostique
+
+\`\`\`
+cd <caminho-do-projeto>
+dd-harness atualizar
+\`\`\`
+
+Ele relata, sem escrever nada, quatro coisas: a versão do CLI, o estado do bloco em
+\`CLAUDE.md\` e \`AGENTS.md\`, e os hooks. Cada item vem com uma ação:
+
+| Marca | Significa |
+|---|---|
+| \`ok\` | em dia, nada a fazer |
+| \`->\` | pode ser aplicado com segurança |
+| \`??\` | **exige decisão sua** — arquivo editado a mão |
+| \`!\` | manual (o CLI global é por máquina, não por projeto) |
+
+## 2. Descubra o que mudou
+
+O bloco carimba a versão do molde (ex: \`v1.2.0\`). Compare com a atual e leia, no
+\`CHANGELOG.md\` do dd-harness, o que mudou entre as duas. É isso que diz **o que** está
+chegando ao projeto — e permite explicar ao usuário, em vez de só dizer "atualizei".
+
+Se a diferença não mexe com o projeto, diga isso: atualização que não muda nada é
+informação útil, não fracasso.
+
+## 3. Aplique o seguro
+
+\`\`\`
+dd-harness atualizar --aplicar
+\`\`\`
+
+Isto escreve **só** os itens \`->\`: troca o miolo do bloco, acrescenta hooks que faltam,
+cria o arquivo que não existe. O que está fora do bloco não é lido nem reescrito.
+
+Os itens \`??\` ficam intactos de propósito — o comando não os toca.
+
+## 4. Conduza os casos que exigem decisão
+
+Para cada item \`??\`, faça o trabalho que o comando não pode fazer:
+
+1. **Mostre ao usuário o que está lá** e o que o molde novo traz.
+2. **Diga o que você acha que aconteceu** — "parece que você acrescentou esta linha
+   sobre o Slack dentro do nosso bloco".
+3. **Proponha o encaixe**, que quase sempre é: manter a linha dele, atualizar o resto, e
+   sugerir mover a linha dele para FORA do bloco, para não conflitar de novo na próxima
+   versão. Essa sugestão é o que impede o problema de se repetir.
+4. **Aguarde o OK.** Nunca edite um bloco \`??\` sem resposta explícita.
+
+## 5. O CLI global
+
+Se o diagnóstico marcou o CLI com \`!\`, o comando é:
+
+\`\`\`
+npm i -g dd-harness@latest
+\`\`\`
+
+Diga ao usuário que isso vale para **a máquina**, não para o projeto — rodar em cada pasta
+não muda nada, e ele só precisa fazer isso uma vez.
+
+## 6. Feche
+
+Relate, em poucas linhas: o que foi atualizado, de que versão para qual, o que ficou
+pendente de decisão e por quê. Se você tocou em \`CLAUDE.md\`, **diga explicitamente que o
+que estava fora do bloco continua intacto** — é a garantia que o usuário quer ouvir.
+
+Se o projeto tem git, sugira conferir o diff antes de commitar. Não commite: o projeto é
+do usuário e as regras de commit dele são dele.`,
+    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-harness",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "type": "module",
   "description": "Política, memória e integrações de Claude Code, Codex e Antigravity. CLI sem dependências de runtime.",
   "license": "UNLICENSED",