dd-harness 0.28.0 → 0.30.0

package/dist/escreve-config.js

@@ -126,4 +126,8 @@ de ler código, responder ou planejar.
 
 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.`;
+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. A política diz quais são obrigatórias e quando.`;

package/dist/git.d.ts

@@ -0,0 +1,37 @@
+/**
+ * O repositorio git do projeto — criado pelo `start` quando ainda nao existe.
+ *
+ * Sem git, metade do dd-harness fica muda e ninguem avisa: `check --commit` nao tem
+ * commit para cruzar, `sugerir_ancoras` devolve lista vazia (a rodada 006 bateu nisso), e
+ * o gancho `post-commit` nao tem onde morar. Nada disso falha com erro — tudo degrada em
+ * silencio, que e a classe de defeito que este projeto existe para combater.
+ *
+ * Criar e barato e reversivel (`rm -rf .git`); nao criar custa features que a pessoa nem
+ * descobre que tem.
+ */
+export type EstadoDoGit = "ja-era" | "criado" | "git-indisponivel" | "falhou";
+/** Ja e um repositorio? Responde pelo proprio git, nao pela existencia de `.git` — submodulo e worktree tem `.git` como ARQUIVO, e checar a pasta erraria nos dois. */
+export declare function ehRepositorio(raiz: string): Promise<boolean>;
+/**
+ * Cria o repositorio, se ainda nao houver.
+ *
+ * Nao faz commit inicial: o que commitar e decisao de quem esta comecando o projeto, e um
+ * commit automatico com os arquivos que o `start` acabou de escrever criaria uma historia
+ * que ninguem pediu — inclusive num repositorio que a pessoa talvez queira que comece
+ * vazio.
+ *
+ * Nunca lanca. `start` nao pode falhar porque o git nao esta instalado.
+ */
+export declare function iniciaRepositorio(raiz: string): Promise<EstadoDoGit>;
+/**
+ * Escreve o gancho `post-commit`, que devolve a memoria ao code review.
+ *
+ * Ate aqui ele era IMPRESSO para a pessoa colar, pela regra de que `.git/hooks` nao e
+ * nosso. A regra continua valendo para repositorio que ja existia — mas num que o
+ * proprio `start` acabou de criar nao ha nada de ninguem para preservar, e imprimir
+ * instrucao que so vale se alguem copiar e colar e o mesmo "rode X depois" que a rodada
+ * 006 mostrou que ninguem segue.
+ *
+ * Nunca sobrescreve um gancho existente: ali ha trabalho de outra pessoa.
+ */
+export declare function escreveGanchoDeCommit(raiz: string): Promise<"criado" | "ja-tinha" | "falhou">;

package/dist/git.js

@@ -0,0 +1,67 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const roda = promisify(execFile);
+/** Ja e um repositorio? Responde pelo proprio git, nao pela existencia de `.git` — submodulo e worktree tem `.git` como ARQUIVO, e checar a pasta erraria nos dois. */
+export async function ehRepositorio(raiz) {
+    try {
+        const { stdout } = await roda("git", ["rev-parse", "--is-inside-work-tree"], { cwd: raiz });
+        return stdout.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Cria o repositorio, se ainda nao houver.
+ *
+ * Nao faz commit inicial: o que commitar e decisao de quem esta comecando o projeto, e um
+ * commit automatico com os arquivos que o `start` acabou de escrever criaria uma historia
+ * que ninguem pediu — inclusive num repositorio que a pessoa talvez queira que comece
+ * vazio.
+ *
+ * Nunca lanca. `start` nao pode falhar porque o git nao esta instalado.
+ */
+export async function iniciaRepositorio(raiz) {
+    if (await ehRepositorio(raiz))
+        return "ja-era";
+    try {
+        await roda("git", ["init"], { cwd: raiz });
+        return "criado";
+    }
+    catch (erro) {
+        return erro.code === "ENOENT" ? "git-indisponivel" : "falhou";
+    }
+}
+/**
+ * Escreve o gancho `post-commit`, que devolve a memoria ao code review.
+ *
+ * Ate aqui ele era IMPRESSO para a pessoa colar, pela regra de que `.git/hooks` nao e
+ * nosso. A regra continua valendo para repositorio que ja existia — mas num que o
+ * proprio `start` acabou de criar nao ha nada de ninguem para preservar, e imprimir
+ * instrucao que so vale se alguem copiar e colar e o mesmo "rode X depois" que a rodada
+ * 006 mostrou que ninguem segue.
+ *
+ * Nunca sobrescreve um gancho existente: ali ha trabalho de outra pessoa.
+ */
+export async function escreveGanchoDeCommit(raiz) {
+    const { join } = await import("node:path");
+    const { readFile, writeFile, chmod } = await import("node:fs/promises");
+    const caminho = join(raiz, ".git", "hooks", "post-commit");
+    try {
+        await readFile(caminho, "utf8");
+        return "ja-tinha";
+    }
+    catch {
+        // Sem gancho: escreve.
+    }
+    try {
+        // `|| true` porque aviso nao pode falhar um commit que ja aconteceu — o gancho roda
+        // DEPOIS, e sair diferente de zero aqui so polui a saida de quem commitou.
+        await writeFile(caminho, '#!/bin/sh\n# dd-harness: avisa quais memórias falam do que este commit mudou.\ndd-harness check --commit "$(git rev-parse HEAD)" || true\n', "utf8");
+        await chmod(caminho, 0o755);
+        return "criado";
+    }
+    catch {
+        return "falhou";
+    }
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { termosDaConsulta } from "./argv.js";
 import { check, status } from "./check.js";
 import { CAMINHO_CONFIG, guardaConfigDaMaquina, guardaToken, leConfigDaMaquina, leConfigDoRepo, leToken, } from "./config.js";
 import { escreveHook, escreveMcp, escrevePonteiro } from "./escreve-config.js";
+import { escreveGanchoDeCommit, iniciaRepositorio } from "./git.js";
 import { grava } from "./gravar.js";
 import { init, SUGESTAO_AGENTS, SUGESTAO_HOOK, SUGESTAO_MCP } from "./init.js";
 import { pergunta, escolha, fechaPerguntas } from "./pergunta.js";
@@ -426,6 +427,28 @@ async function comandoStart() {
     console.log(resultadoProjeto.jaExistia
         ? `\nProjeto ${resultadoProjeto.projeto} já existia — usando ele.`
         : `\nProjeto ${resultadoProjeto.projeto} criado.`);
+    // 3.5. O repositorio git.
+    //
+    // Sem ele, metade do dd-harness fica muda SEM AVISAR: `check --commit` nao tem o que
+    // cruzar, `sugerir_ancoras` devolve vazio (a rodada 006 bateu nisso), e o gancho de
+    // commit nao tem onde morar. Criar aqui e barato e reversivel; nao criar custa features
+    // que a pessoa nem descobre que tem.
+    const git = await iniciaRepositorio(process.cwd());
+    console.log({
+        criado: "criado  repositório git (`git init`)",
+        "ja-era": "mantido repositório git — já existia",
+        "git-indisponivel": "AVISO: git não encontrado nesta máquina. `check --commit` e a sugestão de " +
+            "âncoras não vão funcionar até você instalá-lo.",
+        falhou: "AVISO: não consegui rodar `git init` aqui — siga e crie à mão se quiser.",
+    }[git]);
+    // O gancho so quando FOMOS nos que criamos o repositorio: num que ja existia,
+    // `.git/hooks` e de outra pessoa, e a regra de sempre vale — sugerir, nunca escrever.
+    if (git === "criado") {
+        const gancho = await escreveGanchoDeCommit(process.cwd());
+        if (gancho === "criado") {
+            console.log("criado  .git/hooks/post-commit (devolve a memória ao code review)");
+        }
+    }
     // 4. Config do repositorio — o unico arquivo que `init` tambem escreveria.
     const r = await init(process.cwd(), { tenant, projeto: resultadoProjeto.projeto, api: API_PADRAO });
     console.log(r.config === "criada" ? `criado  ${CAMINHO_CONFIG}` : `mantido ${CAMINHO_CONFIG}`);
@@ -899,6 +922,31 @@ async function comandoPolitica(argv) {
  * so faria o Claude Code registrar falha no transcript — que ninguem le — enquanto a
  * sessao seguiria sem saber que esta sem protocolo.
  */
+/**
+ * Lembra que ha skills — so quando a POLITICA nao lembra.
+ *
+ * Medido em uso real: a skill aparecia na listagem do host, a descricao estava no
+ * contexto, e mesmo assim nao era invocada. Estar disponivel nao e ser usada.
+ *
+ * O conserto de verdade e a politica dizer quando cada skill e obrigatoria — e o passo 5
+ * do briefing agora manda escrever isso. Mas projeto ja briefado nao passa mais por la, e
+ * a politica dele continua sem a regra. Esta linha cobre esse intervalo.
+ *
+ * CALA quando a politica ja fala de skill: repetir o que ela diz treina a ler a politica
+ * como se fosse opcional, e a politica e a unica coisa aqui que o agente trata como
+ * regra. A deteccao e grosseira de proposito — qualquer mencao basta, porque o custo de
+ * calar a mais e zero e o de repetir e corroer a autoridade do texto principal.
+ */
+function lembreteDeSkills(politica) {
+    if (/skill/i.test(politica))
+        return "";
+    return ("\n\n---\n\n" +
+        "Este projeto pode ter **skills** — procedimentos escritos para o trabalho que se " +
+        "repete. `listar_skills` mostra quais, e `ler_skill` traz o passo a passo.\n\n" +
+        "Invoque a que couber **antes** de fazer o trabalho, não depois: skill lida no fim " +
+        "vira revisão do que já saiu errado. Se a política não disser quais são " +
+        "obrigatórias, vale propor ao usuário que ela passe a dizer.");
+}
 function contextoDaSessao(r, worker) {
     const base = { hookEventName: "SessionStart" };
     const fila = avisoDaFila(r.esperandoIndexacao ?? 0, worker);
@@ -911,6 +959,7 @@ function contextoDaSessao(r, worker) {
                 // 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) +
+                lembreteDeSkills(r.conteudo) +
                 fila,
         };
     }
@@ -925,9 +974,28 @@ function contextoDaSessao(r, worker) {
                 "que ele já diz é ponto de partida, não é para ser ignorado.\n" +
                 "2. Pergunte ao usuário o que o código e o `CLAUDE.md` não revelarem: " +
                 "objetivo do projeto, stack principal, restrições e convenções.\n" +
-                "3. Mostre o rascunho da política e do briefing e espere a confirmação " +
+                // O git decide o quanto o agente age sozinho, e e a UNICA decisao subtrativa do
+                // protocolo: nasce fechada e so abre por escolha explicita. Perguntar AQUI, junto
+                // da stack, e o unico momento em que alguem esta pensando no fluxo do projeto —
+                // depois vira negociacao no meio da tarefa, que e onde a permissao acaba sendo
+                // dada por conveniencia.
+                "3. Pergunte SOBRE GIT — é isso que define o quanto o agente age sozinho, e a " +
+                "resposta vira regra escrita na política, nunca acordo tácito:\n" +
+                "   - **O agente pode commitar?** O padrão é NÃO. Só abra se o usuário disser " +
+                "que sim, e escreva na política exatamente o que ele autorizou.\n" +
+                "   - **E `push`?** Trate separado de commit: commit local é reversível, `push` " +
+                "publica. Quem autoriza um não autoriza o outro por tabela.\n" +
+                "   - **Com que frequência?** A cada mudança que funciona, ao fim da tarefa, ou " +
+                "só quando pedirem? Isso muda quanto ruído o histórico carrega.\n" +
+                "   - **Branch ou direto na principal?** Se houver fluxo de branch, escreva " +
+                "qual — o agente não adivinha convenção de nome.\n" +
+                "   - **O que NUNCA fazer**, mesmo com autorização: `push --force`, " +
+                "`reset --hard`, reescrever história publicada. Ficam fora por padrão.\n" +
+                "   Escreva cada resposta como regra. \"Ele sabe o que pode\" não sobrevive à " +
+                "próxima sessão, que começa sem memória disto.\n" +
+                "4. Mostre o rascunho da política e do briefing e espere a confirmação " +
                 "explícita do usuário antes de escrever.\n" +
-                "4. Escreva os dois com a ferramenta MCP `escrever_artefato` " +
+                "5. Escreva os dois com a ferramenta MCP `escrever_artefato` " +
                 "(`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" +
@@ -938,7 +1006,16 @@ function contextoDaSessao(r, worker) {
                 "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 " +
+                // Medido em uso real: a skill aparecia na listagem, a descricao estava no
+                // contexto, e mesmo assim nao era invocada. Estar disponivel nao e ser usada — o
+                // que faz o agente parar e invocar e a POLITICA dizer que e obrigatorio, porque
+                // ela e o unico texto que ele trata como regra em vez de catalogo.
+                "   Inclua também QUANDO cada skill é obrigatória — o gatilho, não a lista. " +
+                "Chame `listar_skills` para ver o que o projeto tem e escreva uma linha por " +
+                "skill que não pode ser pulada. Exemplo: \"ao escrever ou editar código, " +
+                "invoque `como-desenvolver` ANTES de começar\". Sem isso a skill existe, " +
+                "aparece na listagem e mesmo assim não é usada — foi medido.\n" +
+                "6. 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. O ponteiro " +
                 "precisa citar `ler_artefato` **e** `ler_roadmap`: quem chega por ele (Codex, " +
@@ -947,7 +1024,7 @@ function contextoDaSessao(r, worker) {
                 // 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. Pergunte se o trabalho deste projeto tem **fases** — algo que " +
+                "7. 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 " +
@@ -955,7 +1032,7 @@ function contextoDaSessao(r, worker) {
                 // O unico momento em que a stack acabou de ser descrita. Depois disto ninguem
                 // pergunta de novo, e uma skill que so se descobre lendo a lista nao se descobre —
                 // foi o mesmo gap que o roadmap teve, e que o passo 6 fechou.
-                "7. Por fim, invoque a skill `propor-ferramentas`. A stack acabou de ser " +
+                "8. Por fim, invoque a skill `propor-ferramentas`. A stack acabou de ser " +
                 "descrita e as restrições estão frescas — é o único momento em que a pesquisa " +
                 "tem o filtro certo. Ela **propõe**: MCP, skill ou lib que combine com este " +
                 "projeto, nada é instalado sem o OK do usuário, e recusar tudo é resposta " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-harness",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "type": "module",
   "description": "Cliente do dd-harness: politica no inicio da sessao, e memoria por busca — nada em disco. Sem dependencia: fetch, crypto e fs sao do Node.",
   "license": "UNLICENSED",