dd-harness-mcp 0.9.0 → 0.10.0

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

@@ -63,13 +63,20 @@ export async function escreveMcp(raiz) {
     return { ok: true, estado: eraVazio ? "criado" : "acrescentado" };
 }
 /**
- * `AGENTS.md` e markdown livre, nao JSON — nao ha "mesclar" de verdade. Se o arquivo ja
- * existe (com qualquer conteudo), so acrescenta a instrucao no fim; nunca sobrescreve
- * o que a pessoa escreveu, porque markdown de outra ferramenta e mais dificil de separar
- * do nosso do que uma chave de objeto.
+ * Os dois pontos de entrada do repositorio — `CLAUDE.md` (Claude Code) e `AGENTS.md`
+ * (Codex, Cursor, Gemini CLI, Windsurf) — sao ESPELHOS: o mesmo apontamento para o
+ * dd-harness, sem regra propria. Nenhum dos dois e opcional, e nao ha pergunta sobre
+ * "qual ferramenta voce usa": quem abre o repositorio encontra o protocolo pela porta
+ * que a SUA ferramenta le, e as duas dizem a mesma coisa. Regra fica no servico; aqui
+ * fica so o ponteiro — por isso espelhar nao duplica nada que possa divergir.
+ *
+ * Markdown e livre, nao JSON: nao ha "mesclar" de verdade. Se o arquivo ja existe (com
+ * qualquer conteudo), so acrescenta a instrucao no fim; nunca sobrescreve o que a pessoa
+ * escreveu, porque markdown alheio e mais dificil de separar do nosso do que uma chave
+ * de objeto.
  */
-export async function escreveAgents(raiz) {
-    const caminho = join(raiz, "AGENTS.md");
+export async function escrevePonteiro(raiz, arquivo) {
+    const caminho = join(raiz, arquivo);
     const instrucao = SUGESTAO_AGENTS;
     let atual = null;
     try {
@@ -88,14 +95,16 @@ export async function escreveAgents(raiz) {
     await writeFile(caminho, `${atual}${separador}${instrucao}\n`, "utf8");
     return { estado: "acrescentado" };
 }
-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.
+/** Compatibilidade: `init` ainda chama pelo nome antigo. */
+export const escreveAgents = (raiz) => escrevePonteiro(raiz, "AGENTS.md");
+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.`;

package/dist/cli/src/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { access } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
 // DEP0190: Node imprime esse warning direto no stderr no instante em que
 // `spawn(..., { shell: true })` recebe um array de args — de forma sincrona, ANTES de
@@ -14,11 +14,12 @@ process.removeAllListeners("warning");
 import { termosDaConsulta } from "./argv.js";
 import { check, status } from "./check.js";
 import { CAMINHO_CONFIG, guardaConfigDaMaquina, guardaToken, leConfigDaMaquina, leConfigDoRepo, leToken, } from "./config.js";
-import { escreveAgents, escreveHook, escreveMcp } from "./escreve-config.js";
+import { escreveHook, escreveMcp, escrevePonteiro } from "./escreve-config.js";
 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 { busca } from "./buscar.js";
 import { arquiva, edita, le } from "./curar.js";
 import { criaPasta } from "./pasta.js";
@@ -61,6 +62,16 @@ 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 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
 
@@ -88,6 +99,77 @@ function argumento(argv, nome) {
     return i >= 0 ? argv[i + 1] : undefined;
 }
 const API_PADRAO = "https://dd-harness.vercel.app";
+// --- roadmap e changelog ---
+async function comandoRoadmap() {
+    console.log(formataRoadmap(await leFases(process.cwd())));
+}
+async function comandoChangelog(argv) {
+    const versao = argumento(argv, "versao");
+    const fases = await leFases(process.cwd(), { status: "concluida", ...(versao ? { versao } : {}) });
+    console.log(formataChangelog(fases));
+}
+const STATUS_DE_FASE = ["ideia", "aberta", "concluida", "descartada"];
+function statusDoArgv(argv) {
+    const s = argumento(argv, "status");
+    if (s === undefined)
+        return undefined;
+    if (!STATUS_DE_FASE.includes(s)) {
+        throw new Error(`--status: use ${STATUS_DE_FASE.join(", ")}.`);
+    }
+    return s;
+}
+/** `--conteudo` aponta para um .md, como `gravar` e `editar` — markdown de verdade nao cabe em flag. */
+async function conteudoDoArgv(argv) {
+    const caminho = argumento(argv, "conteudo");
+    return caminho === undefined ? undefined : readFile(caminho, "utf8");
+}
+/**
+ * `fase criar` e `fase editar`. Concluir uma fase e `fase editar <slug> --status concluida`
+ * — nao ha verbo proprio de proposito: e uma edicao de status como qualquer outra, e e o
+ * banco que a transforma em changelog.
+ */
+async function comandoFase(argv) {
+    const [acao, ...resto] = argv;
+    if (acao === "criar") {
+        const titulo = argumento(resto, "titulo");
+        if (!titulo)
+            throw new Error('fase criar exige --titulo "<título>".');
+        const status = statusDoArgv(resto);
+        if (status === "descartada")
+            throw new Error("não se cria uma fase já descartada.");
+        const { fase } = await criaFase(process.cwd(), {
+            titulo,
+            conteudo: await conteudoDoArgv(resto),
+            versao: argumento(resto, "versao"),
+            status,
+            slug: argumento(resto, "slug"),
+        });
+        console.log(`Fase ${fase.slug} criada — ordem ${fase.ordem}, ${fase.status}` +
+            (fase.versao ? `, versão ${fase.versao}` : "") +
+            ".");
+        return;
+    }
+    if (acao === "editar") {
+        const [slug, ...opcoes] = resto;
+        if (!slug || slug.startsWith("--"))
+            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, {
+            titulo: argumento(opcoes, "titulo"),
+            conteudo: await conteudoDoArgv(opcoes),
+            versao: opcoes.includes("--sem-versao") ? null : argumento(opcoes, "versao"),
+            status,
+            ordem: ordemBruta === undefined ? undefined : Number(ordemBruta),
+        });
+        console.log(`Fase ${fase.slug} atualizada — ${fase.status}` +
+            (fase.versao ? `, versão ${fase.versao}` : "") +
+            (status === "concluida" ? " (saiu do roadmap, entrou no changelog)" : "") +
+            ".");
+        return;
+    }
+    throw new Error('uso: dd-harness fase criar --titulo "<t>" [...]  |  dd-harness fase editar <slug> [...]');
+}
 /**
  * Forca o `npx` a baixar e cachear `dd-harness-mcp` AGORA, dentro do wizard — nunca na
  * primeira conexao do Claude Code. Sem isto, a primeira instalacao acontecia so quando
@@ -287,15 +369,18 @@ async function comandoStart() {
                 "conexão do Claude Code pode demorar ou falhar; se falhar, abra uma nova sessão " +
                 "e tente de novo.");
     }
-    // 6. AGENTS.md — so quem usa outra ferramenta alem do Claude Code precisa.
-    const outraFerramenta = await pergunta("\nVai abrir este projeto em Codex, Cursor ou outra ferramenta além do Claude " +
-        "Code? [s/N]: ");
-    if (/^s/i.test(outraFerramenta)) {
-        const agents = await escreveAgents(process.cwd());
-        console.log({ criado: "criado  AGENTS.md",
-            "ja-tinha": "mantido AGENTS.md — já apontava para a política",
-            acrescentado: "atualizado AGENTS.md (instrução acrescentada ao que já existia)",
-        }[agents.estado]);
+    // 6. CLAUDE.md e AGENTS.md — os dois SEMPRE, sem perguntar. Sao espelhos: o mesmo
+    // apontamento para o servico, cada um na porta que uma familia de ferramenta le. A
+    // pergunta "usa outra ferramenta?" saiu porque a resposta nao muda nada que valha a
+    // pena — quem responde "nao" hoje abre o repositorio no Cursor semana que vem e nao
+    // encontra protocolo nenhum, e o custo de ja ter o arquivo e um ponteiro de 8 linhas.
+    console.log("");
+    for (const arquivo of ["CLAUDE.md", "AGENTS.md"]) {
+        const r = await escrevePonteiro(process.cwd(), arquivo);
+        console.log({ criado: `criado  ${arquivo}`,
+            "ja-tinha": `mantido ${arquivo} — já apontava para a política`,
+            acrescentado: `atualizado ${arquivo} (apontamento acrescentado ao que já existia)`,
+        }[r.estado]);
     }
     // 7. Onde esta o monorepo do worker nesta maquina? So pergunta uma vez, e so importa
     // se houver memoria na fila agora — pular aqui nao trava nada, so avisa mais vezes.
@@ -585,6 +670,9 @@ function contextoDaSessao(r, worker) {
             additionalContext: "# Política deste projeto (carregada do dd-harness)\n\n" +
                 "As regras abaixo valem para esta sessão inteira.\n\n" +
                 r.conteudo +
+                // Depois da politica, antes dos avisos operacionais: o roadmap e contexto de
+                // trabalho, a fila e ruido de infraestrutura. Vazio quando nao ha fase aberta.
+                blocoDeSessao(r.roadmap) +
                 fila,
         };
     }
@@ -799,6 +887,12 @@ async function principal() {
             return comandoStatus();
         case "politica":
             return comandoPolitica(resto);
+        case "roadmap":
+            return comandoRoadmap();
+        case "changelog":
+            return comandoChangelog(resto);
+        case "fase":
+            return comandoFase(resto);
         case "--version":
         case "-V":
         case "version":

package/dist/cli/src/politica.js

@@ -24,6 +24,7 @@ export async function buscaPolitica(raiz) {
         const payload = (await resposta.json());
         const conteudo = payload.politica?.trim();
         const esperandoIndexacao = payload.esperando_indexacao ?? 0;
+        const roadmap = payload.roadmap;
         // `briefado` e do SERVICO, nao inferido aqui: exige politica E briefing, os dois
         // obrigatorios. So checar `politica` vazia deixava passar o caso de politica
         // existir sem briefing — a sessao seguia como "ok" com metade do briefing faltando,
@@ -31,7 +32,7 @@ export async function buscaPolitica(raiz) {
         if (!conteudo || payload.briefado === false) {
             return { estado: "sem-politica", esperandoIndexacao };
         }
-        return { estado: "ok", conteudo, esperandoIndexacao };
+        return { estado: "ok", conteudo, esperandoIndexacao, roadmap };
     }
     catch (erro) {
         return { estado: "inalcancavel", motivo: mensagem(erro) };

package/dist/cli/src/roadmap.js

@@ -0,0 +1,153 @@
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
+// --- rede ---
+export async function leFases(raiz, filtro = {}) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/roadmap`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    if (filtro.status)
+        url.searchParams.set("status", filtro.status);
+    if (filtro.versao)
+        url.searchParams.set("versao", filtro.versao);
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json()).fases;
+}
+export async function leFase(raiz, slug) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/roadmap/${encodeURIComponent(slug)}`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json()).fase;
+}
+export async function criaFase(raiz, dados) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/roadmap`, {
+        method: "POST",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({ tenant: config.tenant, projeto: config.projeto, ...dados }),
+    });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json());
+}
+export async function editaFase(raiz, slug, dados) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/roadmap/${encodeURIComponent(slug)}`, {
+        method: "PATCH",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({ tenant: config.tenant, projeto: config.projeto, ...dados }),
+    });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json());
+}
+// --- formatacao (pura) ---
+/** Rotulo do grupo de fases concluidas sem versao: o "Unreleased" do Keep a Changelog. */
+export const SEM_VERSAO = "Sem versão (ainda não lançado)";
+const rotuloDeVersao = (versao) => (versao ? ` (${versao})` : "");
+/**
+ * O bloco que entra no contexto da sessao, colado depois da politica. Vazio quando o
+ * projeto nao tem fase aberta: aviso sem motivo em toda sessao e o que ensina a ignorar
+ * aviso — e roadmap e opcional.
+ *
+ * So a fase atual vai em texto integral. As proximas vao por titulo, e as concluidas nem
+ * isso — so a contagem. E a reducao de tokens que o modelo file-based nao tinha como
+ * fazer: la o arquivo entrava inteiro, feito e por fazer.
+ */
+export function blocoDeSessao(r) {
+    if (!r?.agora)
+        return "";
+    const linhas = [
+        "",
+        "",
+        "---",
+        "",
+        "# Roadmap deste projeto (dd-harness)",
+        "",
+        `## Agora — ${r.agora.titulo}${rotuloDeVersao(r.agora.versao)}`,
+        "",
+        r.agora.conteudo.trim() || "_(fase sem descrição — pergunte ao usuário o que ela cobre.)_",
+    ];
+    if (r.a_seguir.length > 0) {
+        linhas.push("", "## A seguir");
+        for (const f of r.a_seguir)
+            linhas.push(`- ${f.titulo}${rotuloDeVersao(f.versao)}`);
+    }
+    linhas.push("", r.concluidas > 0
+        ? `${r.concluidas} fase(s) já concluída(s) — \`ler_changelog\` mostra o que foi entregue.`
+        : "Nenhuma fase concluída ainda.", "", "É da fase **Agora** que saem os passos desta sessão. Quando ela terminar, proponha ao " +
+        "usuário marcá-la concluída (`editar_fase` com `status: \"concluida\"`) — ela sai do " +
+        "roadmap e entra no changelog sozinha. O roadmap guarda o quê e quando; o porquê das " +
+        "decisões vai ao Brain, pelos três filtros, e fase concluída não gera memória por padrão.");
+    return linhas.join("\n");
+}
+/**
+ * O roadmap para o terminal e para `ler_roadmap`: recebe TODAS as fases do projeto e
+ * separa por status. Concluidas nao aparecem aqui — sao changelog.
+ */
+export function formataRoadmap(fases) {
+    const porOrdem = (a, b) => a.ordem - b.ordem;
+    const abertas = fases.filter((f) => f.status === "aberta").sort(porOrdem);
+    const ideias = fases.filter((f) => f.status === "ideia").sort(porOrdem);
+    const concluidas = fases.filter((f) => f.status === "concluida").length;
+    if (abertas.length === 0 && ideias.length === 0) {
+        return ("Este projeto não tem roadmap." +
+            (concluidas > 0 ? ` (${concluidas} fase(s) concluída(s) no changelog.)` : "") +
+            "\nCrie a primeira fase: `dd-harness fase criar --titulo \"...\"`.");
+    }
+    const linhas = [];
+    const [agora, ...aSeguir] = abertas;
+    if (agora) {
+        linhas.push(`## Agora — ${agora.titulo}${rotuloDeVersao(agora.versao)}  [${agora.slug}]`, "");
+        linhas.push(agora.conteudo.trim() || "_(sem descrição)_");
+    }
+    if (aSeguir.length > 0) {
+        linhas.push("", "## A seguir");
+        for (const f of aSeguir)
+            linhas.push(`- ${f.titulo}${rotuloDeVersao(f.versao)}  [${f.slug}]`);
+    }
+    if (ideias.length > 0) {
+        linhas.push("", "## Ideias (não comprometidas)");
+        for (const f of ideias)
+            linhas.push(`- ${f.titulo}${rotuloDeVersao(f.versao)}  [${f.slug}]`);
+    }
+    // Neutro de proposito: este texto sai igual no terminal e na ferramenta MCP, e cada
+    // porta tem o seu jeito de abrir o changelog.
+    linhas.push("", concluidas > 0
+        ? `${concluidas} fase(s) concluída(s) — estão no changelog.`
+        : "Nenhuma fase concluída ainda.");
+    return linhas.join("\n");
+}
+/**
+ * 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
+ * primeira aparicao — versao e rotulo livre, entao nao ha como ordena-la melhor que pelo
+ * tempo em que suas fases foram concluidas.
+ */
+export function formataChangelog(concluidas) {
+    if (concluidas.length === 0)
+        return "Nenhuma fase concluída ainda.";
+    const grupos = new Map();
+    for (const f of concluidas) {
+        const chave = f.versao ?? SEM_VERSAO;
+        const grupo = grupos.get(chave) ?? [];
+        grupo.push(f);
+        grupos.set(chave, grupo);
+    }
+    const linhas = [];
+    for (const [versao, fases] of grupos) {
+        if (linhas.length > 0)
+            linhas.push("");
+        linhas.push(`## ${versao}`);
+        for (const f of fases) {
+            const data = f.concluida_em ? f.concluida_em.slice(0, 10) : "";
+            linhas.push(`- ${f.titulo}${data ? ` — ${data}` : ""}  [${f.slug}]`);
+        }
+    }
+    return linhas.join("\n");
+}

package/dist/mcp/src/index.js

@@ -12,6 +12,7 @@ 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";
 /**
  * O mesmo servico, outra porta.
  *
@@ -292,6 +293,115 @@ Conteúdo vazio é válido e significa apagar o artefato.`,
             return falha(erro);
         }
     });
+    // --- roadmap e changelog: o mesmo dado, duas leituras ---
+    server.registerTool("ler_roadmap", {
+        description: `As fases ABERTAS do projeto: a atual em texto integral (o "Agora" — um foco por vez) e as próximas por título (o "A seguir"). Opcionalmente as ideias não comprometidas.
+
+A fase atual já chega no início da sessão, junto da política. Use isto quando precisar ver as próximas com mais detalhe, ou quando o roadmap tiver mudado durante a sessão.
+
+Fase concluída NÃO aparece aqui — é changelog (\`ler_changelog\`). Roadmap é opcional: projeto sem fase devolve isso, e não é erro. Se o trabalho tiver fases de verdade e não houver roadmap, proponha criar a primeira com \`criar_fase\`.`,
+        inputSchema: z.object({
+            incluir_ideias: z
+                .boolean()
+                .optional()
+                .describe("Mostrar também as fases com status `ideia` (não comprometidas). Padrão: não."),
+        }),
+    }, async ({ incluir_ideias }) => {
+        try {
+            const fases = await leFases(raiz);
+            const visiveis = incluir_ideias ? fases : fases.filter((f) => f.status !== "ideia");
+            return texto(formataRoadmap(visiveis));
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
+    server.registerTool("ler_changelog", {
+        description: `O que já foi ENTREGUE: as fases concluídas, agrupadas por versão, da mais recente para a mais antiga. Fase concluída sem versão aparece em "${"Sem versão (ainda não lançado)"}" — feita, mas ainda fora de uma versão fechada.
+
+Não existe changelog separado do roadmap: isto é a leitura das mesmas fases com \`status: "concluida"\`. Por isso nunca diverge do que foi planejado.
+
+Use para responder "o que entregamos na 1.0?" ou "o que já está pronto?". Para o corpo de uma fase específica, o endereço entre colchetes é o \`slug\`.`,
+        inputSchema: z.object({
+            versao: z
+                .string()
+                .optional()
+                .describe("Filtra por uma versão exata (rótulo livre, como \"1.0.0\" ou \"onda 2\")."),
+        }),
+    }, async ({ versao }) => {
+        try {
+            const fases = await leFases(raiz, { status: "concluida", ...(versao ? { versao } : {}) });
+            return texto(formataChangelog(fases));
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
+    server.registerTool("criar_fase", {
+        description: `Cria uma fase no roadmap. Proponha ao humano antes: o roadmap é a direção do projeto, e uma fase nova é um compromisso.
+
+Uma fase é uma etapa com checklist — o checklist vai DENTRO do conteúdo, em markdown (\`- [ ] item\`). A unidade de estado é a fase: marcar um item é editar o texto; concluir a fase é mudar o status.
+
+\`status: "concluida"\` na criação é o caminho do trabalho NÃO planejado (um hotfix, um ajuste feito na hora) entrar no changelog: cria a fase já feita. Não invente uma fase "aberta" para algo que já aconteceu.
+
+\`versao\` é rótulo livre (\`1.0.0\`, \`onda 2\`, \`lançamento\`) e opcional — pode ser atribuída depois, ao fechar uma versão. O slug (endereço) é derivado do título e fixo: escolha o título pensando nisso.`,
+        inputSchema: z.object({
+            titulo: z.string().min(2).max(120).describe("Curto e específico: `Autenticação por e-mail`, não `Fase 2`."),
+            conteudo: z
+                .string()
+                .max(50000)
+                .optional()
+                .describe("Markdown: o que a fase cobre e o checklist (`- [ ] item`). Pode ficar vazio e ser preenchido depois."),
+            versao: z
+                .string()
+                .max(40)
+                .optional()
+                .describe("Versão prevista ou, se já concluída, a versão em que saiu. Rótulo livre."),
+            status: z
+                .enum(["ideia", "aberta", "concluida"])
+                .optional()
+                .describe("Padrão `aberta`. `ideia` = não comprometida, fora do roadmap ativo. `concluida` = já feita (hotfix)."),
+        }),
+    }, async ({ titulo, conteudo, versao, status }) => {
+        try {
+            const { fase } = await criaFase(raiz, { titulo, conteudo, versao, status });
+            return texto(`Fase \`${fase.slug}\` criada — ordem ${fase.ordem}, ${fase.status}` +
+                (fase.versao ? `, versão ${fase.versao}` : "") +
+                (fase.status === "concluida" ? ". Já está no changelog." : "."));
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
+    server.registerTool("editar_fase", {
+        description: `Edita uma fase pelo \`slug\`: título, conteúdo (o checklist), versão, status ou ordem. Mande só o que muda.
+
+CONCLUIR uma fase é isto com \`status: "concluida"\`. Proponha ao humano antes — é ele quem decide que a fase acabou. Ao concluir, a fase sai do roadmap e entra no changelog sozinha; nada precisa ser movido ou reescrito. Reabrir é \`status: "aberta"\`. \`descartada\` tira do roadmap sem entrar no changelog e sem apagar o rastro.
+
+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".`,
+        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(),
+            conteudo: z.string().max(50000).optional().describe("Substitui o conteúdo inteiro — para marcar um item, mande o checklist completo com o item marcado."),
+            versao: z.string().max(40).nullable().optional().describe("Rótulo livre; `null` remove."),
+            status: z.enum(["ideia", "aberta", "concluida", "descartada"]).optional(),
+            ordem: z.number().int().positive().optional(),
+        }),
+    }, async ({ slug, ...mudancas }) => {
+        try {
+            const { fase } = 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." : "."));
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
     return server;
 }
 /**

package/package.json

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