dd-harness-mcp 0.10.0 → 0.12.0

package/dist/cli/src/check.js

@@ -99,6 +99,7 @@ export async function check(raiz, commit) {
             fechadas: 0,
             tocadas,
             reancoragens,
+            semGit: mudancas.semGit,
         };
     }
     const envio = await pede(`${config.api}/api/v1/deriva`, {
@@ -127,5 +128,6 @@ export async function check(raiz, commit) {
         fechadas: julgamento.fechadas ?? 0,
         tocadas,
         reancoragens,
+        semGit: mudancas.semGit,
     };
 }

package/dist/cli/src/diff.js

@@ -17,10 +17,34 @@ export async function caminhosDoCommit(raiz, commit) {
         const { stdout } = await roda("git", ["diff-tree", "--no-commit-id", "-r", "-M", "--name-status", commit], { cwd: raiz });
         return interpretaNameStatus(stdout);
     }
-    catch {
-        return { caminhos: [], renames: [] };
+    catch (erro) {
+        // Continua sem lancar — o gancho `post-commit` nao pode falhar por causa de um aviso.
+        // O que muda e que a razao volta junto, para quem chamou poder dize-la em vez de
+        // mostrar "nenhuma mudanca" quando na verdade nada foi consultado.
+        return { caminhos: [], renames: [], semGit: classificaFalhaDoGit(erro) };
     }
 }
+/**
+ * Traduz a falha do `git diff-tree` nos tres casos que pedem respostas diferentes de quem
+ * chamou: consertar o repositorio, conferir o SHA, ou instalar o git.
+ *
+ * A leitura e do stderr porque o `git` usa o mesmo codigo de saida (128) para "not a git
+ * repository" e para "bad object" — o texto e o unico jeito de separar os dois.
+ */
+function classificaFalhaDoGit(erro) {
+    const e = erro;
+    if (e.code === "ENOENT")
+        return "git-indisponivel";
+    const stderr = e.stderr ?? "";
+    if (/not a git repository/i.test(stderr))
+        return "sem-repositorio";
+    if (/bad object|unknown revision|ambiguous argument/i.test(stderr)) {
+        return "commit-desconhecido";
+    }
+    // Falha que nao sabemos nomear: ainda e melhor avisar que o cruzamento nao aconteceu do
+    // que deixar passar como silencio.
+    return "git-indisponivel";
+}
 /**
  * Le a saida de `--name-status`: uma letra de status, TAB, e um ou dois caminhos.
  *

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

@@ -107,4 +107,8 @@ de ler código, responder ou planejar.
 
 - Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
   avise o usuário e **não modifique nada** até ele resolver.
-- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.`;
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
+desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
+válido — não crie fase sem o usuário pedir.`;

package/dist/cli/src/index.js

@@ -19,7 +19,7 @@ import { grava } from "./gravar.js";
 import { init, SUGESTAO_AGENTS, SUGESTAO_HOOK, SUGESTAO_MCP } from "./init.js";
 import { pergunta, escolha, fechaPerguntas } from "./pergunta.js";
 import { buscaPolitica } from "./politica.js";
-import { blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
+import { avisoDeOrdem, blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
 import { busca } from "./buscar.js";
 import { arquiva, edita, le } from "./curar.js";
 import { criaPasta } from "./pasta.js";
@@ -155,7 +155,7 @@ async function comandoFase(argv) {
             throw new Error("fase editar exige o slug da fase.");
         const ordemBruta = argumento(opcoes, "ordem");
         const status = statusDoArgv(opcoes);
-        const { fase } = await editaFase(process.cwd(), slug, {
+        const { fase, atras_de } = await editaFase(process.cwd(), slug, {
             titulo: argumento(opcoes, "titulo"),
             conteudo: await conteudoDoArgv(opcoes),
             versao: opcoes.includes("--sem-versao") ? null : argumento(opcoes, "versao"),
@@ -165,7 +165,8 @@ async function comandoFase(argv) {
         console.log(`Fase ${fase.slug} atualizada — ${fase.status}` +
             (fase.versao ? `, versão ${fase.versao}` : "") +
             (status === "concluida" ? " (saiu do roadmap, entrou no changelog)" : "") +
-            ".");
+            "." +
+            avisoDeOrdem(fase, atras_de, ordemBruta !== undefined));
         return;
     }
     throw new Error('uso: dd-harness fase criar --titulo "<t>" [...]  |  dd-harness fase editar <slug> [...]');
@@ -553,8 +554,29 @@ async function comandoReancorar(argv) {
     console.log(`  para ${r.para}`);
     console.log("  Rode `dd-harness check --commit <sha>` para medir a base nova.");
 }
+/**
+ * Pediram `--commit` e o cruzamento com o diff nao aconteceu. Avisa ANTES do resto: sem
+ * isto a saida e identica a de um commit que nao tocou em nada indexado, e quem pediu o
+ * cruzamento nao tem como saber que ele nao existiu.
+ *
+ * Aviso, nao erro: o gancho `post-commit` termina em sucesso mesmo assim, e a medicao das
+ * ancoras (que nao depende de git) continua valendo.
+ */
+function avisaSemGit(motivo) {
+    const texto = {
+        "sem-repositorio": "esta pasta não é um repositório git — não há diff para cruzar com as âncoras.",
+        "commit-desconhecido": "o git não reconhece este commit — confira o SHA.",
+        "git-indisponivel": "não consegui rodar o git aqui.",
+    }[motivo];
+    console.log(`AVISO: ${texto}`);
+    console.log("       As âncoras foram medidas assim mesmo; só o cruzamento com o");
+    console.log("       commit ficou de fora.");
+    console.log("");
+}
 async function comandoCheck(argv) {
     const r = await check(process.cwd(), argumento(argv, "commit"));
+    if (r.semGit)
+        avisaSemGit(r.semGit);
     if (r.medidas === 0) {
         console.log("nenhuma âncora para medir.");
         return;
@@ -693,9 +715,27 @@ function contextoDaSessao(r, worker) {
                 "(`tipo: \"politica\"` e `tipo: \"briefing\"`, uma chamada cada). Se essa " +
                 "ferramenta não estiver disponível nesta sessão, pare e diga ao usuário que " +
                 "o servidor MCP do dd-harness precisa estar conectado para isto.\n" +
+                // A politica e escrita do zero pelo agente, e este texto e o unico lugar que diz o
+                // que ela precisa conter. Sem esta linha, o roadmap chega ao contexto e nao obriga
+                // a nada: informacao passiva, que e como uma feature existe sem ser usada.
+                "   Na política, inclua uma linha sobre o roadmap: a fase **Agora** é o foco da " +
+                "sessão, e ao terminá-la o agente **propõe** concluí-la (`editar_fase` com " +
+                "`status: \"concluida\"`) — nunca conclui por conta própria, porque quem decide " +
+                "que uma fase acabou é o usuário.\n" +
                 "5. Depois de escrever os dois, sobrescreva o `CLAUDE.md` da raiz com um " +
                 "ponteiro curto para a política deste serviço — a verdade passa a morar " +
-                "aqui, e o `CLAUDE.md` local nunca mais precisa ser editado à mão." +
+                "aqui, e o `CLAUDE.md` local nunca mais precisa ser editado à mão. O ponteiro " +
+                "precisa citar `ler_artefato` **e** `ler_roadmap`: quem chega por ele (Codex, " +
+                "Cursor, ou o Claude Code quando o hook não roda) não tem outro jeito de " +
+                "descobrir que há roadmap.\n" +
+                // O momento certo de perguntar: quem acabou de descrever o projeto tem o contexto
+                // fresco para dizer por onde ele vai. Depois disso, ninguem mais pergunta — e uma
+                // feature que so se descobre lendo a lista de ferramentas nao se descobre.
+                "6. Por fim, pergunte se o trabalho deste projeto tem **fases** — algo que " +
+                "atravessa sessões, com ordem entre as partes. Se tiver, proponha as primeiras e " +
+                "crie-as com `criar_fase`; a de menor ordem vira o foco de cada sessão, e " +
+                "concluí-la a move para o changelog sozinha. Se for um projeto pequeno, diga que " +
+                "roadmap é opcional e siga sem ele — não insista." +
                 fila,
         };
     }

package/dist/cli/src/roadmap.js

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

package/dist/mcp/src/index.js

@@ -12,7 +12,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";
+import { avisoDeOrdem, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "../../cli/src/roadmap.js";
 /**
  * O mesmo servico, outra porta.
  *
@@ -284,9 +284,13 @@ Conteúdo vazio é válido e significa apagar o artefato.`,
     }, async ({ tipo, conteudo }) => {
         try {
             const r = await escreveArtefato(raiz, tipo, conteudo);
+            // Sem promessa de atraso: a politica nova ja vale para quem LER daqui em diante,
+            // inclusive nesta sessao (`ler_artefato` logo em seguida devolve o conteudo novo).
+            // O que nao muda sozinho e o que ja foi injetado no contexto pelo hook, no inicio
+            // da sessao — e essa e a distincao que a mensagem precisa fazer.
             return texto(`${r.criou ? "Criado" : "Atualizado"} o ${r.artefato} — ${r.tamanho} caractere(s).` +
                 (tipo === "politica"
-                    ? " A política nova vale a partir da próxima sessão."
+                    ? " Já vale para quem ler a partir de agora; o que foi carregado no início desta sessão não muda sozinho."
                     : ""));
         }
         catch (erro) {
@@ -380,7 +384,7 @@ CONCLUIR uma fase é isto com \`status: "concluida"\`. Proponha ao humano antes
 
 Fase concluída NÃO gera memória no Brain por padrão. O roadmap guarda o quê e quando; o porquê de uma decisão só vira memória se passar nos três filtros — e aí o caminho é \`gravar_memoria\`, não o conteúdo da fase.
 
-\`versao: null\` tira a versão. \`ordem\` reposiciona: a aberta de menor ordem é o "Agora".`,
+\`versao: null\` tira a versão. \`ordem\` reposiciona: a aberta de menor ordem é o "Agora". Duas fases podem ter a mesma ordem — aí a mais antiga vem primeiro, então repetir a ordem da fase atual NÃO promove a sua. A resposta diz em que posição a fase ficou e, se ela seguiu atrás de outra, qual.`,
         inputSchema: z.object({
             slug: z.string().min(1).describe("O endereço da fase, como aparece entre colchetes em `ler_roadmap` e `ler_changelog`."),
             titulo: z.string().min(2).max(120).optional(),
@@ -391,12 +395,13 @@ Fase concluída NÃO gera memória no Brain por padrão. O roadmap guarda o quê
         }),
     }, async ({ slug, ...mudancas }) => {
         try {
-            const { fase } = await editaFase(raiz, slug, mudancas);
+            const { fase, atras_de } = await editaFase(raiz, slug, mudancas);
             // A frase de transicao so quando a conclusao foi o PEDIDO — editar o texto de uma
             // fase ja concluida nao a faz "sair do roadmap" de novo.
             return texto(`Fase \`${fase.slug}\` atualizada — ${fase.status}` +
                 (fase.versao ? `, versão ${fase.versao}` : "") +
-                (mudancas.status === "concluida" ? ". Saiu do roadmap e entrou no changelog." : "."));
+                (mudancas.status === "concluida" ? ". Saiu do roadmap e entrou no changelog." : ".") +
+                avisoDeOrdem(fase, atras_de, mudancas.ordem !== undefined));
         }
         catch (erro) {
             return falha(erro);

package/package.json

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