dd-harness 0.37.0 → 0.38.0

package/README.md

@@ -1,103 +1,103 @@
-# dd-harness
-
-Política e briefing carregados do serviço; memória consultada por MCP ou CLI.
-A fonte dos artefatos continua no serviço. O cliente mantém configuração, ponteiros
-para skills e estado descartável fora do repositório.
-
-Requer Node >=20.3.0. CLI sem dependências de runtime.
-
-## Instalação e configuração
-
-```sh
-npm install -g dd-harness@latest
-npx -y dd-harness-mcp@latest --help
-dd-harness start --host todos
-```
-
-Para um projeto já criado no serviço:
-
-```sh
-dd-harness init --tenant meu-espaco --projeto meu-projeto
-dd-harness login --token <token>
-dd-harness integrar --host claude,codex,antigravity
-dd-harness diagnostico --mcp
-```
-
-`start` usa Claude por padrão. `--host` aceita `claude`, `codex`,
-`antigravity`, uma lista separada por vírgulas ou `todos`.
-`integrar` instala nos três por padrão e preserva configurações alheias.
-O token nasce em /tokens e fica em ~/.dd-harness/credentials.json, por origem de API.
-Para serviço local, use `init --api http://localhost:3000` antes do login.
-
-## Hosts
-
-| Host | MCP | Boot e guarda | Skills |
-|---|---|---|---|
-| Claude Code | .mcp.json | .claude/settings.json | .claude/skills |
-| Codex | .codex/config.toml | .codex/hooks.json | .agents/skills |
-| Antigravity | .agents/mcp_config.json | .agents/hooks.json | .agents/skills |
-
-Codex exige revisão/confiança dos hooks em /hooks. Instalação não comprova ativação.
-Antigravity usa PreInvocation e mensagem efêmera: política e briefing são consultados
-antes de cada inferência. Sua guarda usa `ask` para respeitar concessões já existentes;
-ela pode acrescentar confirmações. Não amplia permissões automaticamente.
-
-Sem boot válido, a guarda recusa ferramentas cobertas, inclusive shell. Leitura conhecida
-e onboarding controlado continuam possíveis. Os hooks precisam estar ativos: não são
-sandbox nem controlam ferramentas que o aplicativo não encaminha a eles.
-Após boot válido, shell não tem análise de diff antecipada; avisos por âncora cobrem
-edições estruturadas, patches, remoções e renomeações.
-
-Configurações MCP novas levam DD_HARNESS_ROOT explícito. Ao copiar/mover um checkout,
-confira essa raiz com diagnostico. O MCP recusa divergência entre a raiz explícita e
-o projeto identificado no diretório de execução. Corrija a configuração e reinicie o host.
-
-## Uso diário
-
-```sh
-dd-harness politica
-dd-harness buscar "contrato de integração"
-dd-harness ler regras/contrato
-dd-harness gravar memoria.md
-dd-harness editar memoria.md
-dd-harness arquivar regras/contrato --motivo obsoleta
-dd-harness status
-dd-harness skills
-dd-harness roadmap
-dd-harness changelog
-dd-harness --help
-```
-
-`check` mede e grava observações de deriva; `status` só consulta.
-O antigo comando `sync` não faz parte do CLI atual.
-`politica --hook` e `cinto` permanecem como compatibilidade legada;
-use `integrar` para instalar `sessao` e `guarda`.
-
-## Estado e conflitos
-
-- Política/briefing não são materializados. Âncoras/resumos, sessão e manifestos ficam
-  em ~/.dd-harness/repos, isolados por caminho/projeto/credencial quando aplicável.
-- DD_HARNESS_HOME permite isolamento explícito em testes. Nunca aponte testes ao estado pessoal.
-- Uma sessão validada expira em quatro horas. Boot, retomada e compactação revalidam.
-  Alterações locais de política/briefing via MCP invalidam a sessão; reabra depois de editar.
-  Alterações remotas feitas por outro cliente são percebidas no próximo boot/revalidação.
-- Curadoria invalida as âncoras do checkout atual. A próxima edição as consulta novamente.
-- Só ponteiros registrados e intactos são atualizados/removidos. Skills manuais, editadas
-  ou redirecionadas por links são preservadas e aparecem como conflitos.
-- Skills marcadas só por comando não são instaladas para descoberta automática em
-  .agents; use listar_skills/ler_skill após pedido explícito. Metadados próprios do
-  Claude não são prometidos como portáveis.
-- Se há fila e worker local configurado, o boot solicita um lote. O log fica em
-  ~/.dd-harness/worker.log; solicitar não significa que a indexação concluiu.
-
-## Escritas e commits
-
-Só GET/HEAD têm retry automático (até três tentativas, timeout por tentativa).
-POST/PATCH/PUT/DELETE não são repetidos. Falha de conexão, 5xx ou resposta incompleta
-em escrita exige consultar o estado antes de tentar novamente.
-
-A política entregue exige `[IDENTIFICAÇÃO] - tipo: descrição` nos commits de agentes:
-`[CODEX] - feat: ...`, `[CLAUDE] - fix: ...`, `[GEMINI] - docs: ...`.
-Identifique quem realmente commitou, inclusive ao usar outro editor. A regra não altera
-Git author nem concede autorização de commit/push. É regra de trabalho do agente,
-não inferência automática de identidade nem hook que renomeia commits humanos.
+# dd-harness
+
+Política e briefing carregados do serviço; memória consultada por MCP ou CLI.
+A fonte dos artefatos continua no serviço. O cliente mantém configuração, ponteiros
+para skills e estado descartável fora do repositório.
+
+Requer Node >=20.3.0. CLI sem dependências de runtime.
+
+## Instalação e configuração
+
+```sh
+npm install -g dd-harness@latest
+npx -y dd-harness-mcp@latest --help
+dd-harness start --host todos
+```
+
+Para um projeto já criado no serviço:
+
+```sh
+dd-harness init --tenant meu-espaco --projeto meu-projeto
+dd-harness login --token <token>
+dd-harness integrar --host claude,codex,antigravity
+dd-harness diagnostico --mcp
+```
+
+`start` usa Claude por padrão. `--host` aceita `claude`, `codex`,
+`antigravity`, uma lista separada por vírgulas ou `todos`.
+`integrar` instala nos três por padrão e preserva configurações alheias.
+O token nasce em /tokens e fica em ~/.dd-harness/credentials.json, por origem de API.
+Para serviço local, use `init --api http://localhost:3000` antes do login.
+
+## Hosts
+
+| Host | MCP | Boot e guarda | Skills |
+|---|---|---|---|
+| Claude Code | .mcp.json | .claude/settings.json | .claude/skills |
+| Codex | .codex/config.toml | .codex/hooks.json | .agents/skills |
+| Antigravity | .agents/mcp_config.json | .agents/hooks.json | .agents/skills |
+
+Codex exige revisão/confiança dos hooks em /hooks. Instalação não comprova ativação.
+Antigravity usa PreInvocation e mensagem efêmera: política e briefing são consultados
+antes de cada inferência. Sua guarda usa `ask` para respeitar concessões já existentes;
+ela pode acrescentar confirmações. Não amplia permissões automaticamente.
+
+Sem boot válido, a guarda recusa ferramentas cobertas, inclusive shell. Leitura conhecida
+e onboarding controlado continuam possíveis. Os hooks precisam estar ativos: não são
+sandbox nem controlam ferramentas que o aplicativo não encaminha a eles.
+Após boot válido, shell não tem análise de diff antecipada; avisos por âncora cobrem
+edições estruturadas, patches, remoções e renomeações.
+
+Configurações MCP novas levam DD_HARNESS_ROOT explícito. Ao copiar/mover um checkout,
+confira essa raiz com diagnostico. O MCP recusa divergência entre a raiz explícita e
+o projeto identificado no diretório de execução. Corrija a configuração e reinicie o host.
+
+## Uso diário
+
+```sh
+dd-harness politica
+dd-harness buscar "contrato de integração"
+dd-harness ler regras/contrato
+dd-harness gravar memoria.md
+dd-harness editar memoria.md
+dd-harness arquivar regras/contrato --motivo obsoleta
+dd-harness status
+dd-harness skills
+dd-harness roadmap
+dd-harness changelog
+dd-harness --help
+```
+
+`check` mede e grava observações de deriva; `status` só consulta.
+O antigo comando `sync` não faz parte do CLI atual.
+`politica --hook` e `cinto` permanecem como compatibilidade legada;
+use `integrar` para instalar `sessao` e `guarda`.
+
+## Estado e conflitos
+
+- Política/briefing não são materializados. Âncoras/resumos, sessão e manifestos ficam
+  em ~/.dd-harness/repos, isolados por caminho/projeto/credencial quando aplicável.
+- DD_HARNESS_HOME permite isolamento explícito em testes. Nunca aponte testes ao estado pessoal.
+- Uma sessão validada expira em quatro horas. Boot, retomada e compactação revalidam.
+  Alterações locais de política/briefing via MCP invalidam a sessão; reabra depois de editar.
+  Alterações remotas feitas por outro cliente são percebidas no próximo boot/revalidação.
+- Curadoria invalida as âncoras do checkout atual. A próxima edição as consulta novamente.
+- Só ponteiros registrados e intactos são atualizados/removidos. Skills manuais, editadas
+  ou redirecionadas por links são preservadas e aparecem como conflitos.
+- Skills marcadas só por comando não são instaladas para descoberta automática em
+  .agents; use listar_skills/ler_skill após pedido explícito. Metadados próprios do
+  Claude não são prometidos como portáveis.
+- Se há fila e worker local configurado, o boot solicita um lote. O log fica em
+  ~/.dd-harness/worker.log; solicitar não significa que a indexação concluiu.
+
+## Escritas e commits
+
+Só GET/HEAD têm retry automático (até três tentativas, timeout por tentativa).
+POST/PATCH/PUT/DELETE não são repetidos. Falha de conexão, 5xx ou resposta incompleta
+em escrita exige consultar o estado antes de tentar novamente.
+
+A política entregue exige `[IDENTIFICAÇÃO] - tipo: descrição` nos commits de agentes:
+`[CODEX] - feat: ...`, `[CLAUDE] - fix: ...`, `[GEMINI] - docs: ...`.
+Identifique quem realmente commitou, inclusive ao usar outro editor. A regra não altera
+Git author nem concede autorização de commit/push. É regra de trabalho do agente,
+não inferência automática de identidade nem hook que renomeia commits humanos.

package/dist/diagnostico.js

@@ -5,9 +5,14 @@ import { achaRaiz, leConfigDoRepo, leToken } from "./config.js";
 import { buscaPolitica } from "./politica.js";
 export async function handshakeMcp(raiz, comando = "npx", args = ["-y", "dd-harness-mcp@latest"]) {
     return new Promise((resolve, reject) => {
+        // `DD_HARNESS_ROOT` fica FORA: passa-la aqui testaria um cenario que o host nao
+        // reproduz, e esconderia justamente a falha procurada — com a raiz explicita correta o
+        // servidor sobe ate quando a declaracao versionada esta quebrada para outra maquina.
+        // O cwd e a raiz, que e como o host lanca.
+        const { DD_HARNESS_ROOT: _ignorado, ...ambiente } = process.env;
         const filho = spawn(comando, args, { cwd: raiz, windowsHide: true,
             shell: process.platform === "win32" && comando === "npx", stdio: ["pipe", "pipe", "pipe"],
-            env: { ...process.env, DD_HARNESS_ROOT: raiz } });
+            env: ambiente });
         let buffer = "", terminou = false, versao = "desconhecida";
         const fim = (erro, resultado) => {
             if (terminou)
@@ -79,8 +84,13 @@ export async function diagnostico(inicio, testarMcp = false) {
         const h = await readFile(join(raiz, hook), "utf8").catch(() => "");
         linhas.push(`${host}: MCP ${m.includes("dd-harness") ? "declarado" : "ausente"}; ` +
             `hooks ${h.includes("dd-harness guarda") && h.includes("dd-harness sessao") ? "declarados" : "ausentes/legados"}; ativação no host requer verificação.`);
-        if (m.includes("dd-harness") && !m.includes(JSON.stringify(raiz)))
-            linhas.push(`${host}: confira DD_HARNESS_ROOT; a raiz explícita atual não foi reconhecida.`);
+        // Invertido de proposito: a raiz explicita era exigida, e passou a ser o defeito. O
+        // arquivo vai para o git, entao um caminho absoluto so vale na maquina que gerou —
+        // noutro checkout o servidor lanca antes do handshake e o host so ve conexao fechada.
+        if (m.includes("dd-harness") && m.includes("DD_HARNESS_ROOT")) {
+            linhas.push(`${host}: DD_HARNESS_ROOT declarado em ${config} — remova. ` +
+                `Caminho absoluto em arquivo versionado quebra em outro checkout; sem ele a raiz sai do cwd.`);
+        }
     }
     const politica = await buscaPolitica(raiz);
     linhas.push(`Contexto: ${politica.estado}${politica.estado === "inalcancavel" ? " — " + politica.motivo : ""}`);

package/dist/escreve-config.js

@@ -140,28 +140,28 @@ export const escreveAgents = (raiz) => escrevePonteiro(raiz, "AGENTS.md");
  * 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.
-
-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
+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.
+
+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.`;

package/dist/hosts.js

@@ -1,4 +1,5 @@
-import { readFile, mkdir } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { access, readFile, mkdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { escreveAtomico, estadoDoRepo } from "./estado-local.js";
 import { escrevePonteiro, SUGESTAO_AGENTS } from "./escreve-config.js";
@@ -48,11 +49,84 @@ function grupo(doc, evento, command, antigos = []) {
     preservados.push({ hooks: [{ type: "command", command, timeout: 60 }] });
     doc[evento] = preservados;
 }
+/**
+ * Onde o `dd-harness-mcp` instalado guarda o arquivo de entrada, ou `null` se nao houver.
+ *
+ * O caminho sai do `bin` do proprio pacote, nao de um literal daqui: ele ja mudou uma vez
+ * (`dist/mcp/src/`, porque o build abrange dois diretorios) e um literal duplicado
+ * envelheceria em silencio — apontando para um arquivo que nao existe, o que o host
+ * reporta como CONNECTION_CLOSED sem dizer mais nada.
+ */
+async function entradaDoMcp() {
+    // `devolve` e nao `resolve`: o `resolve` de `node:path` esta no escopo deste modulo, e
+    // o parametro o sombrearia dentro do callback.
+    const raizGlobal = await new Promise(devolve => {
+        execFile("npm", ["root", "-g"], { shell: process.platform === "win32" }, (erro, saida) => devolve(erro ? "" : saida.trim()));
+    });
+    if (!raizGlobal)
+        return null;
+    const pasta = join(raizGlobal, "dd-harness-mcp");
+    try {
+        const { bin } = JSON.parse(await readFile(join(pasta, "package.json"), "utf8"));
+        const relativo = typeof bin === "string" ? bin : bin?.["dd-harness-mcp"];
+        if (!relativo)
+            return null;
+        const entrada = join(pasta, relativo);
+        await access(entrada);
+        return entrada;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Config de MCP e artefato de MAQUINA, nao de projeto: o bloco carrega o caminho do node
+ * e do pacote instalado ali. Versionar isso entrega a um clone o valor de quem gerou, e o
+ * sintoma no outro lado e sempre o mesmo CONNECTION_CLOSED — que nao diz nada sobre a
+ * causa. Quem clona roda `integrar` e recebe o seu.
+ *
+ * Acrescenta ao que ja existir, sem reescrever: `.gitignore` e arquivo do projeto.
+ */
+async function ignoraConfigDeMaquina(raiz, caminhos) {
+    const arquivo = join(raiz, ".gitignore");
+    const atual = await readFile(arquivo, "utf8").catch((e) => {
+        if (e.code === "ENOENT")
+            return "";
+        throw e;
+    });
+    const linhas = new Set(atual.split(/\r?\n/).map(l => l.trim()));
+    const faltam = caminhos.filter(c => !linhas.has(c));
+    if (!faltam.length)
+        return;
+    const bloco = "# dd-harness: config de MCP e por maquina — rode `dd-harness integrar`\n" + faltam.join("\n") + "\n";
+    await escreveAtomico(arquivo, atual && !atual.endsWith("\n") ? `${atual}\n${bloco}` : atual + bloco);
+}
 /** Cada host usa seu formato. Configuração alheia não é inferida como gerenciada. */
 export async function instalaHosts(raiz, hosts) {
     raiz = resolve(raiz);
     const avisos = [];
-    const mcp = { command: "npx", args: ["-y", "dd-harness-mcp@latest"], env: { DD_HARNESS_ROOT: raiz } };
+    // `npx` NAO serve no Windows, e nao ha variante que sirva: o host lanca o servidor com
+    // `spawn` sem shell, e ali `npx` da ENOENT (nao existe executavel com esse nome) e
+    // `npx.cmd` da EINVAL (o Node recusa .bat/.cmd sem shell desde a CVE-2024-27980). Os
+    // dois chegam ao cliente como CONNECTION_CLOSED, que parece servidor morrendo e nao
+    // comando inalcancavel. Apontar o proprio node para o arquivo e o que sobra — e e o que
+    // todo MCP que funciona nesta plataforma ja faz.
+    //
+    // Gravar caminho de maquina aqui so e legitimo porque estes arquivos sao de maquina: o
+    // `integrar` os poe no .gitignore, e quem clona roda `integrar` e recebe o seu. Num
+    // arquivo versionado seria o mesmo erro que DD_HARNESS_ROOT ja foi.
+    //
+    // Sem DD_HARNESS_ROOT: `raizDoMcp` resolve a raiz pelo cwd, que e onde o host lanca o
+    // servidor. Com a variavel, um caminho de outro checkout o faz lancar antes do
+    // handshake — mesmo CONNECTION_CLOSED, outra causa.
+    const entrada = await entradaDoMcp();
+    const mcp = entrada
+        ? { command: process.execPath, args: [entrada] }
+        : { command: "npx", args: ["-y", "dd-harness-mcp@latest"] };
+    if (!entrada && process.platform === "win32") {
+        avisos.push("MCP declarado via npx, que nao sobe no Windows: instale com " +
+            "`npm i -g dd-harness-mcp@latest` e rode `dd-harness integrar` de novo.");
+    }
     for (const host of hosts) {
         if (host === "codex") {
             const caminho = join(raiz, ".codex", "config.toml");
@@ -62,10 +136,11 @@ export async function instalaHosts(raiz, hosts) {
                 throw e;
             });
             if (atual.includes("dd-harness")) {
-                avisos.push("Codex: servidor já configurado; preservado. Confira command e DD_HARNESS_ROOT com diagnostico.");
+                avisos.push("Codex: servidor já configurado; preservado. Confira o command com diagnostico.");
             }
             else {
-                await escreveAtomico(caminho, atual + `\n[mcp_servers.dd-harness]\ncommand = "npx"\nargs = ["-y", "dd-harness-mcp@latest"]\nstartup_timeout_sec = 60\n[mcp_servers.dd-harness.env]\nDD_HARNESS_ROOT = ${JSON.stringify(raiz)}\n`);
+                const args = mcp.args.map(a => JSON.stringify(a)).join(", ");
+                await escreveAtomico(caminho, atual + `\n[mcp_servers.dd-harness]\ncommand = ${JSON.stringify(mcp.command)}\nargs = [${args}]\nstartup_timeout_sec = 60\n`);
             }
             await json(join(raiz, ".codex", "hooks.json"), doc => {
                 const h = objeto(doc.hooks);
@@ -120,6 +195,7 @@ export async function instalaHosts(raiz, hosts) {
             }
         }
     }
+    await ignoraConfigDeMaquina(raiz, hosts.map(h => h === "claude" ? ".mcp.json" : h === "codex" ? ".codex/config.toml" : ".agents/mcp_config.json"));
     await mkdir(dirname(join(raiz, "AGENTS.md")), { recursive: true });
     await escrevePonteiro(raiz, "AGENTS.md");
     if (hosts.includes("claude"))