dd-harness-mcp 0.8.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";
@@ -33,61 +34,142 @@ import { subiuOWorker } from "./worker.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
-
-  dd-harness start                  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>]
-                                     prepara o repositório (config + CLAUDE.md)
-  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 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 --help
-  dd-harness --version              qual binário está instalado nesta máquina
-
-Nada do dd-harness fica em disco: a política chega pelo hook de sessão, e a
-memória pela busca, na hora.
+const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
+
+  dd-harness start                  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>]
+                                     prepara o repositório (config + CLAUDE.md)
+  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 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 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
+
+Nada do dd-harness fica em disco: a política chega pelo hook de sessão, e a
+memória pela busca, na hora.
 `;
 /**
  * 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.
-
-O hook da política (\`dd-harness politica --hook\`) é outra coisa, e não é
+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.
+
+O hook da política (\`dd-harness politica --hook\`) é outra coisa, e não é
 opcional — \`dd-harness init\` imprime a linha para o \`.claude/settings.json\`.`;
 function argumento(argv, nome) {
     const i = argv.indexOf(`--${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
@@ -151,6 +233,10 @@ function tentaAbrirNavegador(url) {
         // Segue sem navegador — a URL impressa antes desta chamada ja resolve.
     }
 }
+/** Token no terminal aparece mascarado: o prefixo basta para reconhecer, o segredo nao precisa ser lido em voz alta. */
+function mascara(token) {
+    return token.length <= 16 ? "***" : `${token.slice(0, 12)}...${token.slice(-4)}`;
+}
 /**
  * `dd-harness start` — o wizard para pasta vazia.
  *
@@ -185,13 +271,27 @@ async function comandoStart() {
             "novo — start segue mesmo assim, mas pode faltar correção.\n");
     }
     // 1. Credencial. Sem ela nada do resto e possivel — nem listar tenant.
+    // O estado aparece SEMPRE, mesmo quando ja existe credencial: antes o passo era
+    // pulado em silencio, e quem rodava `start` com um token velho (ou de outra conta)
+    // nao tinha como perceber — o wizard so falhava depois, ao listar espacos.
     let token = await leToken(API_PADRAO);
+    if (token) {
+        console.log(`Credencial: ${mascara(token)} (${API_PADRAO})`);
+        const troca = await pergunta("Usar esta credencial? [S/n]: ");
+        if (/^n/i.test(troca))
+            token = null;
+    }
     if (!token) {
-        console.log(`Sem credencial salva para ${API_PADRAO}.`);
-        token = await pergunta("Cole o token pessoal (crie um em /tokens na interface): ");
+        const url = `${API_PADRAO}/tokens`;
+        console.log(`\nCrie um token pessoal em ${url} — abrindo no navegador...`);
+        tentaAbrirNavegador(url);
+        token = await pergunta("Cole o token aqui: ");
+        if (!token)
+            throw new Error("sem token não dá para seguir: `start` fala com o serviço em todos os passos.");
         await guardaToken(API_PADRAO, token);
-        console.log("Credencial guardada.\n");
+        console.log("Credencial guardada.");
     }
+    console.log("");
     // 2. Espaco (tenant). Criar um e ato de dono — nunca por aqui — mas ESCOLHER entre
     // os que ja existem e so leitura, e e o que faltava para nao exigir o slug de memoria.
     let tenants = await listaTenants(API_PADRAO, token);
@@ -203,18 +303,28 @@ async function comandoStart() {
         tenants = await listaTenants(API_PADRAO, token);
     }
     const tenant = await escolha("\nEscolha um espaço:", tenants.map((t) => ({ rotulo: `${t.nome} (${t.slug})`, valor: t.slug })));
-    // 3. Projeto. Criar e subordinado a estar num espaco — isso o CLI ja faz sozinho.
-    const nomeSugerido = process.cwd().split(/[\\/]/).pop() ?? "meu-projeto";
+    // 3. Projeto. Criar e subordinado a estar num espaco - isso o CLI ja faz sozinho.
+    // A pasta se chama `tiktok-drawer`; o projeto se chama `TikTok Drawer`. Sugerir o
+    // nome da pasta cru fazia o wizard propor um identificador onde se pede um titulo —
+    // e o slug, que e quem precisa daquele formato, ja sai daqui de baixo sozinho.
+    const pasta = process.cwd().split(/[\\/]/).pop() ?? "meu-projeto";
+    const nomeSugerido = pasta
+        .replace(/[-_]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (c) => c.toUpperCase()) || "Meu Projeto";
     const nome = (await pergunta(`\nNome do projeto [${nomeSugerido}]: `)) || nomeSugerido;
-    // Nome so com caracteres especiais (ex: "!!!") normaliza para string vazia — o
-    // fallback evita sugerir slug vazio, que o servidor recusaria com erro confuso.
-    const slugSugerido = nome
+    // O slug sai do nome, sem perguntar: e identificador, nao escolha editorial, e quem
+    // esta comecando nao tem como saber que ele vira a chave do `.dd-harness.json`.
+    // Nome so com caracteres especiais (ex: "!!!") normaliza para string vazia - o
+    // fallback evita slug vazio, que o servidor recusaria com erro confuso.
+    const slugDoProjeto = nome
         .toLowerCase()
         .normalize("NFD")
         .replace(/[̀-ͯ]/g, "")
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "") || "meu-projeto";
-    const slugDoProjeto = (await pergunta(`Identificador curto (slug) [${slugSugerido}]: `)) || slugSugerido;
+    console.log(`Identificador: ${slugDoProjeto}`);
     const resultadoProjeto = await criaProjeto(process.cwd(), slugDoProjeto, nome, {
         tenant,
         api: API_PADRAO,
@@ -259,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.
@@ -557,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,
         };
     }
@@ -771,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,146 @@ 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;
 }
-serveStdio(criaServidor);
+/**
+ * `--help` / `--version` respondem e SAEM. Sem isto, qualquer invocacao com argumento
+ * caia no `serveStdio` e ficava esperando stdin para sempre — e foi assim que o
+ * aquecedor de cache do `dd-harness start` (que chamava `npx -y dd-harness-mcp --help`
+ * so para forcar o download) travou o wizard inteiro depois que o shebang passou a
+ * deixar o servidor subir de verdade.
+ */
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+    console.log(`dd-harness-mcp — servidor MCP do dd-harness (fala por stdio, nao por terminal)
+
+Nao se roda a mao: quem o inicia e o host MCP (Claude Code, Codex, Cursor), pela
+declaracao em \`.mcp.json\`. Sem um host do outro lado ele fica esperando mensagem
+no stdin, que e o comportamento correto de um servidor stdio.
+
+  --help      esta mensagem
+  --version   a versao instalada
+
+Para declarar no seu repositorio, rode \`dd-harness start\`.`);
+}
+else if (args.includes("--version") || args.includes("-V")) {
+    const { readFile } = await import("node:fs/promises");
+    const { fileURLToPath } = await import("node:url");
+    const { dirname, join } = await import("node:path");
+    // `dist/mcp/src/index.js` -> tres niveis ate a raiz do pacote.
+    const aqui = dirname(fileURLToPath(import.meta.url));
+    const lido = await readFile(join(aqui, "..", "..", "..", "package.json"), "utf8");
+    console.log(JSON.parse(lido).version ?? "desconhecida");
+}
+else {
+    serveStdio(criaServidor);
+}

package/package.json

@@ -1,40 +1,40 @@
-{
-  "name": "dd-harness-mcp",
-  "version": "0.8.0",
-  "type": "module",
-  "description": "Servidor MCP do dd-harness: o agente consulta e grava memoria como ferramenta, sem passar por arquivo.",
-  "license": "UNLICENSED",
-  "author": "Diego Dias",
-  "keywords": [
-    "claude-code",
-    "mcp",
-    "model-context-protocol",
-    "ai-agents",
-    "memory"
-  ],
-  "homepage": "https://dd-harness.vercel.app",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/diegodias93/dd-harness-online.git",
-    "directory": "packages/mcp"
-  },
-  "//bin": "`dist/mcp/src/` e nao `dist/` porque o build abrange dois diretorios (este pacote e o fonte do CLI), e o `rootDir` comum e `packages/`. Conferir com `npx -y dd-harness-mcp` numa cache limpa antes de publicar — NAO com `node dist/mcp/src/index.js`: rodar pelo caminho direto passa mesmo quando o pacote instalado esta quebrado, porque o defeito mora no shim que o npm gera. Sem o shebang em `src/index.ts` o shim `.cmd` do Windows chama o `.js` sem `node` na frente, e o servidor morre limpo (exit 0, em silencio) antes do handshake — o cliente so ve CONNECTION_CLOSED.",
-  "bin": {
-    "dd-harness-mcp": "dist/mcp/src/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/server": "^2.0.0",
-    "zod": "^4.5.4"
-  },
-  "scripts": {
-    "typecheck": "tsc -p . --noEmit",
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build"
-  }
-}
+{
+  "name": "dd-harness-mcp",
+  "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",
+  "author": "Diego Dias",
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "memory"
+  ],
+  "homepage": "https://dd-harness.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegodias93/dd-harness-online.git",
+    "directory": "packages/mcp"
+  },
+  "//bin": "`dist/mcp/src/` e nao `dist/` porque o build abrange dois diretorios (este pacote e o fonte do CLI), e o `rootDir` comum e `packages/`. Conferir com `npx -y dd-harness-mcp` numa cache limpa antes de publicar — NAO com `node dist/mcp/src/index.js`: rodar pelo caminho direto passa mesmo quando o pacote instalado esta quebrado, porque o defeito mora no shim que o npm gera. Sem o shebang em `src/index.ts` o shim `.cmd` do Windows chama o `.js` sem `node` na frente, e o servidor morre limpo (exit 0, em silencio) antes do handshake — o cliente so ve CONNECTION_CLOSED.",
+  "bin": {
+    "dd-harness-mcp": "dist/mcp/src/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.5.4"
+  },
+  "scripts": {
+    "typecheck": "tsc -p . --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}