dd-harness 0.26.0 → 0.28.0

package/dist/curar.js

@@ -127,6 +127,7 @@ export async function apaga(raiz, endereco, confirmacao) {
         headers: cabecalhos(token, true),
         body: JSON.stringify({
             tenant: config.tenant,
+            projeto: config.projeto,
             ...(confirmacao ? { confirmacao } : {}),
         }),
     });

package/dist/index.js

@@ -21,6 +21,8 @@ import { pergunta, escolha, fechaPerguntas } from "./pergunta.js";
 import { buscaPolitica } from "./politica.js";
 import { avisoDeOrdem, blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
 import { decideDoHook, guardaCache } from "./cinto.js";
+import { escrevePonteirosDeSkills, leSkill, leSkills, semeiaSkills } from "./skill.js";
+import { SKILLS_INICIAIS } from "./skills-iniciais.js";
 import { busca } from "./buscar.js";
 import { apaga, arquiva, edita, le, promove } from "./curar.js";
 import { criaPasta } from "./pasta.js";
@@ -75,6 +77,9 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
   dd-harness cinto                  o interceptador pré-voo: lê a edição no stdin
                                      e devolve a memória que fala daquele trecho.
                                      Quem chama é o hook PreToolUse, não você
+  dd-harness skills                 as skills deste projeto e quando cada uma serve
+  dd-harness skill <nome>           o procedimento de uma delas (o mesmo que o
+                                     agente recebe ao invocá-la)
   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>]
@@ -113,6 +118,39 @@ function argumento(argv, nome) {
 }
 const API_PADRAO = "https://dd-harness.vercel.app";
 // --- roadmap e changelog ---
+/**
+ * `skills` e `skill <slug>` — so LEITURA.
+ *
+ * Criar e editar ficam na interface de proposito: escrever procedimento e trabalho de
+ * texto longo, e um editor de verdade e melhor que um flag de linha de comando. O que o
+ * terminal precisa e ver o que existe e conferir um procedimento sem trocar de janela.
+ */
+async function comandoSkills() {
+    const skills = await leSkills(process.cwd());
+    if (skills.length === 0) {
+        console.log("Nenhuma skill neste projeto.\n" +
+            "Rode `dd-harness start` para semear as iniciais, ou crie uma pela interface.");
+        return;
+    }
+    for (const s of skills) {
+        console.log(`/${s.slug}${s.so_por_comando ? "  (só por comando)" : ""}`);
+        console.log(`  ${s.descricao}`);
+        console.log("");
+    }
+    console.log(`${skills.length} skill(s). \`dd-harness skill <nome>\` mostra o procedimento.`);
+}
+async function comandoSkill(argv) {
+    const slug = argv[0];
+    if (!slug || slug.startsWith("-")) {
+        throw new Error("uso: dd-harness skill <nome>");
+    }
+    const s = await leSkill(process.cwd(), slug);
+    console.log(`# ${s.slug}
+`);
+    console.log(s.descricao);
+    console.log("");
+    console.log(s.conteudo.trim() || "_(sem procedimento escrito — a skill existe e não faz nada.)_");
+}
 async function comandoRoadmap() {
     console.log(formataRoadmap(await leFases(process.cwd())));
 }
@@ -439,6 +477,33 @@ async function comandoStart() {
             acrescentado: `atualizado ${arquivo} (apontamento acrescentado ao que já existia)`,
         }[r.estado]);
     }
+    // 6.5. Os ponteiros das skills do projeto.
+    //
+    // O Claude Code descobre skill lendo `.claude/skills/*/SKILL.md` na ABERTURA da sessao,
+    // e servidor MCP nao fornece skill — entao o arquivo em disco e obrigatorio. O que ele
+    // carrega e so o frontmatter mais a chamada a `ler_skill`: o procedimento fica no
+    // servico, e corrigi-lo corrige em todos os repositorios de uma vez.
+    //
+    // Nunca falha o `start`: projeto sem skill e o caso comum, e nao ter skill nao impede
+    // nada do resto.
+    try {
+        // Projeto novo nasce com as skills iniciais, como nasce com politica e briefing. Num
+        // projeto que ja tem as suas, isto nao faz nada.
+        const { criadas } = await semeiaSkills(process.cwd(), SKILLS_INICIAIS);
+        if (criadas.length > 0) {
+            console.log(`criada(s) ${criadas.length} skill(s) inicial(is): ${criadas.join(", ")}`);
+        }
+        const skills = await leSkills(process.cwd());
+        if (skills.length > 0) {
+            const { escritos } = await escrevePonteirosDeSkills(process.cwd(), skills);
+            console.log(escritos > 0
+                ? `escritos ${escritos} ponteiro(s) de skill em .claude/skills/`
+                : `${skills.length} skill(s) — ponteiros já estavam em dia`);
+        }
+    }
+    catch {
+        // Serviço fora do ar ou projeto recém-criado: o `start` segue.
+    }
     // 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.
     const semWorkerConfigurado = !(await temWorkerConfigurado());
@@ -791,6 +856,25 @@ async function comandoPolitica(argv) {
         if (r.memorias) {
             await guardaCache(process.cwd(), { memorias: r.memorias });
         }
+        // Os ponteiros das skills, pelo mesmo motivo — e por um a mais: skill criada na
+        // interface so virava arquivo no proximo `dd-harness start`, e "rode X depois" e
+        // instrucao que ninguem segue (medido na rodada 006, com o cache do cinto).
+        //
+        // Escrever AQUI acerta o tempo exato: o Claude Code descobre skill na ABERTURA da
+        // sessao, entao o ponteiro criado agora vale a partir da proxima — que e o mais cedo
+        // que a skill poderia existir para o host, faca-se o que se fizer.
+        //
+        // Custa uma requisicao a mais na abertura. Nao vai de carona no payload da politica
+        // porque skill nao entra no contexto da sessao: o que o host le e o arquivo, e o
+        // servidor so precisa ser consultado para escreve-lo.
+        try {
+            const skills = await leSkills(process.cwd());
+            if (skills.length > 0)
+                await escrevePonteirosDeSkills(process.cwd(), skills);
+        }
+        catch {
+            // Sem skills, sem rede, ou projeto novo: o hook nao pode falhar por causa disto.
+        }
         console.log(JSON.stringify({ hookSpecificOutput: contextoDaSessao(r, worker) }));
         return;
     }
@@ -863,11 +947,19 @@ 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. Por fim, pergunte se o trabalho deste projeto tem **fases** — algo que " +
+                "6. 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." +
+                "roadmap é opcional e siga sem ele — não insista.\n" +
+                // 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 " +
+                "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 " +
+                "válida. Se a skill não existir nesta sessão, siga sem ela." +
                 fila,
         };
     }
@@ -1067,6 +1159,10 @@ async function principal() {
             return comandoPolitica(resto);
         case "cinto":
             return comandoCinto();
+        case "skills":
+            return comandoSkills();
+        case "skill":
+            return comandoSkill(resto);
         case "roadmap":
             return comandoRoadmap();
         case "changelog":

package/dist/skill.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Skills: o procedimento mora no servico, o disco guarda so o ponteiro.
+ *
+ * O Claude Code descobre skill lendo `.claude/skills/<nome>/SKILL.md` na ABERTURA da
+ * sessao, e nenhum servidor MCP pode fornecer skill — o protocolo serve ferramentas e
+ * prompts, nao skills. Entao o arquivo em disco e inevitavel.
+ *
+ * O que e evitavel e o CONTEUDO em disco. O ponteiro carrega o frontmatter real (que e o
+ * que o host le para listar e decidir invocar) e um corpo de poucas linhas mandando
+ * chamar `ler_skill`. O procedimento fica num lugar so, e corrigi-lo corrige em todos os
+ * repositorios — que e o motivo de skills terem saido do disco.
+ *
+ * Repare que o custo de contexto NAO e o motivo: o Claude Code ja carrega so a descricao
+ * de cada skill e busca o corpo quando invocada. O ponteiro nao economiza nada ali — ele
+ * resolve divergencia, nao peso.
+ */
+export type Skill = {
+    slug: string;
+    descricao: string;
+    so_por_comando: boolean;
+    ferramentas: string[];
+    dica_de_argumento: string | null;
+    caminhos: string[];
+    atualizada_em: string;
+};
+export type SkillCompleta = Skill & {
+    conteudo: string;
+};
+export declare function leSkills(raiz: string): Promise<Skill[]>;
+export declare function leSkill(raiz: string, slug: string): Promise<SkillCompleta>;
+export declare function criaSkill(raiz: string, dados: NovaSkillInicial & Partial<Pick<Skill, "so_por_comando" | "ferramentas" | "caminhos" | "dica_de_argumento">>): Promise<{
+    skill: Skill;
+}>;
+/**
+ * O SKILL.md que vai para o disco: frontmatter de verdade, corpo que aponta para o MCP.
+ *
+ * `allowed-tools` sempre inclui a ferramenta que busca o procedimento — sem ela o ponteiro
+ * pediria permissao para ler a propria skill, e um "permitir?" antes de cada invocacao
+ * ensina a desligar o mecanismo.
+ */
+export declare function ponteiroDaSkill(skill: Skill): string;
+/**
+ * Escreve os ponteiros de todas as skills do projeto.
+ *
+ * NAO apaga diretorio que sobrou: uma skill apagada no servico deixa o ponteiro orfao, e
+ * varrer `.claude/skills/` inteiro levaria junto as skills que a pessoa escreveu a mao —
+ * que sao legitimas e nao passam por aqui. O DELETE da API avisa o que apagar; a decisao
+ * de apagar arquivo alheio nao e nossa.
+ */
+export declare function escrevePonteirosDeSkills(raiz: string, skills: Skill[]): Promise<{
+    escritos: number;
+}>;
+/** O minimo para criar uma skill: o resto tem default no banco. */
+export type NovaSkillInicial = {
+    slug: string;
+    descricao: string;
+    conteudo: string;
+};
+/**
+ * Semeia as skills iniciais — so num projeto que ainda nao tem nenhuma.
+ *
+ * A checagem e "nenhuma skill", e nao "esta skill especifica": quem apagou
+ * `como-desenvolver` tomou uma decisao, e recria-la a cada `start` a desfaria em silencio.
+ * Projeto com qualquer skill propria ja passou do ponto de ser semeado.
+ *
+ * Devolve o que criou. Nunca lanca por falha de rede: semear e conveniencia de projeto
+ * novo, e um `start` nao pode falhar porque o mimo nao pode ser entregue.
+ */
+export declare function semeiaSkills(raiz: string, iniciais: NovaSkillInicial[]): Promise<{
+    criadas: string[];
+}>;

package/dist/skill.js

@@ -0,0 +1,143 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
+// --- rede ---
+export async function leSkills(raiz) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/skills`);
+    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()).skills;
+}
+export async function leSkill(raiz, slug) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/skills/${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()).skill;
+}
+export async function criaSkill(raiz, 
+// Só o que a API aceita na criação: `atualizada_em` é do servidor, e aceitá-la no tipo
+// prometeria um campo que o Zod descarta em silêncio.
+dados) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/skills`, {
+        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());
+}
+// --- o ponteiro em disco (puro, para ser testado sem rede) ---
+/**
+ * Escapa o que quebraria o YAML do frontmatter.
+ *
+ * A descricao vem de texto livre editado na interface: `: ` no meio dela faz o parser ler
+ * uma chave nova, e uma quebra de linha encerra o valor. Aspas duplas com escape resolvem
+ * os dois — e um frontmatter quebrado nao da erro visivel, a skill simplesmente some da
+ * lista.
+ */
+function comoEscalarYaml(texto) {
+    return `"${texto.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, " ")}"`;
+}
+/**
+ * O SKILL.md que vai para o disco: frontmatter de verdade, corpo que aponta para o MCP.
+ *
+ * `allowed-tools` sempre inclui a ferramenta que busca o procedimento — sem ela o ponteiro
+ * pediria permissao para ler a propria skill, e um "permitir?" antes de cada invocacao
+ * ensina a desligar o mecanismo.
+ */
+export function ponteiroDaSkill(skill) {
+    const frontmatter = [
+        "---",
+        `name: ${skill.slug}`,
+        `description: ${comoEscalarYaml(skill.descricao)}`,
+    ];
+    if (skill.so_por_comando)
+        frontmatter.push("disable-model-invocation: true");
+    if (skill.dica_de_argumento) {
+        frontmatter.push(`argument-hint: ${comoEscalarYaml(skill.dica_de_argumento)}`);
+    }
+    const ferramentas = ["mcp__dd-harness__ler_skill", ...skill.ferramentas];
+    frontmatter.push(`allowed-tools: ${ferramentas.join(", ")}`);
+    if (skill.caminhos.length > 0) {
+        frontmatter.push(`paths: ${skill.caminhos.join(", ")}`);
+    }
+    frontmatter.push("---");
+    return `${frontmatter.join("\n")}
+
+# ${skill.slug}
+
+O procedimento desta skill vive no dd-harness, não neste arquivo.
+
+**Chame a ferramenta MCP \`ler_skill\` com \`slug: "${skill.slug}"\` e siga o que ela
+devolver.** É a primeira ação — não tente executar a skill a partir deste arquivo, que é
+só o ponteiro.
+
+Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado: avise o
+usuário em vez de improvisar um procedimento.
+`;
+}
+/**
+ * Escreve os ponteiros de todas as skills do projeto.
+ *
+ * NAO apaga diretorio que sobrou: uma skill apagada no servico deixa o ponteiro orfao, e
+ * varrer `.claude/skills/` inteiro levaria junto as skills que a pessoa escreveu a mao —
+ * que sao legitimas e nao passam por aqui. O DELETE da API avisa o que apagar; a decisao
+ * de apagar arquivo alheio nao e nossa.
+ */
+export async function escrevePonteirosDeSkills(raiz, skills) {
+    let escritos = 0;
+    for (const skill of skills) {
+        const dir = join(raiz, ".claude", "skills", skill.slug);
+        const caminho = join(dir, "SKILL.md");
+        const novo = ponteiroDaSkill(skill);
+        // Só escreve quando muda: reescrever igual sujaria o `git status` a cada `start`.
+        const atual = await readFile(caminho, "utf8").catch(() => null);
+        if (atual === novo)
+            continue;
+        await mkdir(dir, { recursive: true });
+        await writeFile(caminho, novo, "utf8");
+        escritos++;
+    }
+    return { escritos };
+}
+/**
+ * Semeia as skills iniciais — so num projeto que ainda nao tem nenhuma.
+ *
+ * A checagem e "nenhuma skill", e nao "esta skill especifica": quem apagou
+ * `como-desenvolver` tomou uma decisao, e recria-la a cada `start` a desfaria em silencio.
+ * Projeto com qualquer skill propria ja passou do ponto de ser semeado.
+ *
+ * Devolve o que criou. Nunca lanca por falha de rede: semear e conveniencia de projeto
+ * novo, e um `start` nao pode falhar porque o mimo nao pode ser entregue.
+ */
+export async function semeiaSkills(raiz, iniciais) {
+    try {
+        const existentes = await leSkills(raiz);
+        if (existentes.length > 0)
+            return { criadas: [] };
+        const criadas = [];
+        for (const nova of iniciais) {
+            try {
+                await criaSkill(raiz, nova);
+                criadas.push(nova.slug);
+            }
+            catch {
+                // Uma skill que nao entrou nao impede as outras — nem o `start`.
+            }
+        }
+        return { criadas };
+    }
+    catch {
+        return { criadas: [] };
+    }
+}

package/dist/skills-iniciais.d.ts

@@ -0,0 +1,20 @@
+import type { NovaSkillInicial } from "./skill.js";
+/**
+ * As skills que todo projeto novo nasce tendo.
+ *
+ * Mesma ideia da politica e do briefing: projeto recem-criado ja vem com o minimo para
+ * trabalhar, em vez de comecar vazio esperando que alguem lembre de escrever. A diferenca
+ * e que skill e EDITAVEL na interface — o que entra aqui e ponto de partida do projeto,
+ * nao regra do produto, e ajusta-la e o uso esperado.
+ *
+ * Semeadas so quando o projeto NAO TEM skill alguma. Um projeto que ja tem as suas nao
+ * recebe nada: se alguem apagou uma delas, foi decisao — e recria-la a cada `start`
+ * desfaria a decisao em silencio, toda vez.
+ *
+ * GERADO a partir dos SKILL.md em .claude/skills deste repositorio. Corrija la e
+ * regenere; editar este arquivo a mao faz a correcao se perder na proxima geracao.
+ */
+export type SkillInicial = NovaSkillInicial & {
+    ferramentas?: string[];
+};
+export declare const SKILLS_INICIAIS: SkillInicial[];

package/dist/skills-iniciais.js

@@ -0,0 +1,461 @@
+export const SKILLS_INICIAIS = [
+    {
+        slug: "como-desenvolver",
+        descricao: `Como desenvolver neste projeto — simplicidade, modularização, mudanças cirúrgicas e execução orientada a objetivos verificados de fato. Invoque ao escrever ou editar código para garantir qualidade. Não cobre segurança nem o protocolo de briefing (isso é sempre obrigatório, vive no CLAUDE.md).`,
+        ferramentas: [],
+        conteudo: `# Como Desenvolver
+
+Aplique ao escrever ou editar código. Quando duas seções parecerem puxar em direções opostas numa mesma tarefa, a nota de precedência na Seção 4 resolve o conflito mais comum — não decida em silêncio.
+
+## 1. Simplicidade Primeiro
+
+**Mínimo de código que resolve o problema pedido. Nada especulativo.**
+
+- Sem funcionalidades além do que foi pedido.
+- Sem abstrações para código de uso único.
+- Sem "flexibilidade" ou "configurabilidade" que ninguém pediu.
+- Sem tratamento de erro para cenários impossíveis.
+- Se escreveu 200 linhas e dava em 50, reescreva.
+
+**Anti-padrão: gold-plating** — entregar mais do que foi pedido porque "já que estava ali" (um parâmetro extra sem uso, um \`try/catch\` para erro impossível, uma opção com um único valor possível). Perceber isso no que acabou de escrever é sinal de cortar antes de seguir.
+
+O teste: para cada função, parâmetro ou arquivo novo, aponte a frase do pedido que o justifica. Se não conseguir apontar, corte.
+
+## 2. Modularização e Componentização
+
+**Prefira peças pequenas e com responsabilidade única a um monólito grande.** Vale para qualquer código — front-end, back-end, scripts.
+
+- **Uma responsabilidade por unidade.** Se você descreve o que ela faz usando "e" várias vezes, ela faz coisa demais.
+- **Separe as camadas.** Não misture lógica de negócio, acesso a dados e apresentação no mesmo lugar.
+- **Extraia o que repete ou o que cresce dentro do código que a tarefa já toca** — só depois que existe de fato. Regra prática: na segunda vez que o mesmo trecho aparece nesse território, considere extrair; na terceira, extraia. Repetição pré-existente que a tarefa não tocaria por si só não conta — mexer nela é a Seção 3 quem decide, não esta.
+- **No front-end:** componente que rola por centenas de linhas quase sempre é vários componentes disfarçados.
+
+O teste: *"Eu preciso rolar muito para entender esta unidade, ou guardar várias coisas na cabeça ao mesmo tempo?"* Se sim, divida.
+
+**Mas não fragmente à toa.** Dividir peças minúsculas demais cria o problema oposto — saltar entre dez arquivos para seguir uma linha de raciocínio. Divida por responsabilidade, não por contagem de linhas.
+
+## 3. Mudanças Cirúrgicas
+
+**Toque apenas no necessário. Limpe apenas sua própria bagunça.**
+
+Ao editar código existente:
+- Não "melhore" código adjacente, comentários ou formatação fora da tarefa.
+- Não refatore o que não está quebrado.
+- Mantenha o estilo existente, mesmo que você faria diferente.
+- Viu código morto não relacionado? Cite no seu relatório final ao usuário — não apague, e não anote isso dentro do arquivo (a anotação em si já seria uma edição fora do pedido).
+
+Quando suas mudanças criam órfãos:
+- Remova imports/variáveis/funções que **suas** mudanças tornaram inúteis.
+- Não remova código morto pré-existente sem ser solicitado.
+
+**Quando a mudança toca um contrato usado em mais de um lugar** (assinatura, formato de dado, schema, campo de API, nome exportado): antes de considerar pronto, busque quem mais depende daquilo — não só o ponto que motivou a tarefa. Um chamador desatualizado é a mesma tarefa, incompleta.
+
+O teste: releia o diff final. Cada linha alterada deve rastrear diretamente à solicitação do usuário — a que não rastreia, reverta.
+
+## 4. Execução Orientada a Objetivos
+
+**Defina critérios de sucesso verificáveis. Itere até verificar de fato — não até parecer pronto.**
+
+Transforme tarefas vagas em objetivos verificáveis:
+- "Adicionar validação" → "Escreva testes para entradas inválidas, depois faça-os passar."
+- "Corrigir o bug" → "Escreva um teste que o reproduza, depois faça-o passar."
+
+Para tarefas com múltiplos passos, declare um plano breve:
+\`\`\`
+1. [Passo] → verificar: [checagem]
+2. [Passo] → verificar: [checagem]
+\`\`\`
+
+**Verificar é executar, não ler.** Compilar ou "parecer certo" na leitura não é verificação. Antes de declarar algo pronto, rode o código (teste, script, rota, comando) e observe o resultado real. Sem como executar no ambiente disponível, diga isso explicitamente em vez de presumir que passaria.
+
+**Nem tudo precisa de teste escrito — tudo precisa de execução verificada.** Escreva teste para lógica com ramificação, cálculo, estado, ou um bug que já aconteceu (para não voltar). Para o que só delega ou é trivialmente correto pela leitura, não escreva teste — mas rode uma vez para confirmar.
+
+**Se o critério declarado falhar, é sinal para diagnosticar — não obstáculo para contornar.** Nunca afrouxe a asserção, pule o teste incômodo, ou tente de novo sem entender a causa. Se a conclusão for que o critério original estava errado (não o código), diga isso antes de trocá-lo.
+
+**Precedência com a Seção 1:** o critério de verificação em si (o teste, a checagem) não é "funcionalidade especulativa" mesmo sem pedido explícito de testes — verificar o próprio trabalho é parte de executar a tarefa. Mas o critério cobre exatamente o que foi pedido, nem mais: um teste que cobre casos fora do escopo volta a violar a Seção 1.
+
+Critérios fortes deixam você iterar sozinho. Critérios fracos ("faça funcionar") forçam esclarecimentos constantes.`,
+    },
+    {
+        slug: "gravar-com-ancora",
+        descricao: `Grava uma memória no Brain amarrada ao ponto do código de que ela fala. Invoque quando for gravar memória que descreve um arquivo, função, chave de config ou trecho específico — a âncora é o que faz a memória ser entregue a quem mexer ali depois. Não use para memória que fala do projeto como um todo.`,
+        ferramentas: ["mcp__dd-harness__sugerir_ancoras", "mcp__dd-harness__gravar_memoria", "mcp__dd-harness__buscar_memoria", "Read", "Grep"],
+        conteudo: `# Gravar memória com âncora
+
+Memória sem âncora só aparece se alguém lembrar de buscar — e é justamente quando o
+agente *acha que sabe* que ele não busca. A âncora inverte isso: ela faz a memória chegar
+antes da edição, sem ninguém pedir.
+
+Este procedimento é sobre **escolher o alvo certo**. Gravar é uma chamada; escolher a
+âncora é a decisão que faz a memória proteger algo ou nascer inerte.
+
+## 1. Confira que ela não existe
+
+Chame \`buscar_memoria\` com a pergunta que a memória responderia. Se já houver uma que diz
+a mesma coisa, **edite aquela** em vez de criar uma segunda — duas memórias dizendo o
+mesmo se contradizem no dia em que uma for corrigida.
+
+## 2. Descubra o que a sessão tocou
+
+\`sugerir_ancoras\` devolve os arquivos modificados. Isso é **matéria-prima, não escolha**:
+a lista mostra onde o trabalho aconteceu, e a âncora certa é o ponto de que a *memória*
+fala — que pode ser um arquivo que você só leu.
+
+Lista vazia (projeto sem git) não é impedimento: pergunte ao usuário qual ponto a memória
+guarda.
+
+## 3. Escolha o alvo — a decisão que importa
+
+**Prefira sempre \`arquivo#trecho\` a \`arquivo\` inteiro.**
+
+Medido neste projeto: duas memórias ancoradas no mesmo \`config/limites.json\` eram **as
+duas** sinalizadas quando só uma das chaves mudava. Alerta que dispara no lugar errado
+ensina a ignorar o mecanismo — e aí ele deixa de proteger.
+
+O trecho precisa ser **estável e específico**:
+
+| Bom alvo | Por quê |
+|---|---|
+| \`SECURITY DEFINER\` | é a decisão em si; some só se a decisão mudar |
+| \`poolConexoesPostgres\` | nome de chave, sobrevive a reformatação |
+| \`processarPagamento\` | nome de função, muda só em rename deliberado |
+
+| Alvo ruim | Por quê |
+|---|---|
+| \`const x = 3\` | a próxima refatoração reescreve |
+| \`// TODO\` | aparece em toda parte do arquivo |
+| uma linha inteira de código | qualquer espaço a mais quebra o casamento |
+
+**Confirme antes de gravar:** abra o arquivo e veja quantas linhas contêm o texto do alvo.
+Se aparecer em dez lugares, o alvo é largo demais. Se não aparecer em nenhum, a âncora
+nasce quebrada — e ninguém descobre, porque alvo ausente parece deriva legítima.
+
+## 4. Âncora de diretório: quando cabe
+
+\`supabase/migrations\` faz sentido para memória que fala da pasta inteira ("toda migration
+precisa de X"). Não use diretório quando a memória fala de um arquivo dentro dele.
+
+## 5. Proponha ao humano, com o alvo explícito
+
+Diga qual âncora você escolheu **e por quê aquele trecho**. Se você não consegue explicar
+por que o alvo é estável, provavelmente ele não é.
+
+Só então chame \`gravar_memoria\`.
+
+## Se a memória não tem ponto no código
+
+Grave sem âncora, e **diga isso ao usuário**: ela só será encontrada por busca, e ninguém
+será avisado ao mexer em nada. Para memória sobre um acordo com cliente ou uma regra da
+organização, isso é o correto — não force uma âncora que não existe só para ter uma.`,
+    },
+    {
+        slug: "resolver-deriva",
+        descricao: `Decide o que fazer quando o check acusa deriva numa memória — se ela ainda vale, se a âncora mudou de lugar, ou se o mundo mudou e ela morreu. Invoque ao ver ALVO AUSENTE ou alvo alterado no resultado de dd-harness check, ou quando o status mostrar observações esperando julgamento.`,
+        ferramentas: ["mcp__dd-harness__ler_memoria", "mcp__dd-harness__editar_memoria", "mcp__dd-harness__arquivar_memoria", "Read", "Grep", "Bash(dd-harness check:*)", "Bash(dd-harness status:*)", "Bash(dd-harness reancorar:*)", "Bash(git log:*)", "Bash(git diff:*)"],
+        conteudo: `# Resolver deriva
+
+Deriva é a memória avisando que o mundo que ela descreve mudou. Há **três** respostas
+possíveis, e o atalho tentador é sempre o mesmo — marcar "ainda vale" e fechar o alarme.
+
+É assim que um Brain apodrece parecendo saudável: nenhuma observação aberta, e metade das
+memórias descrevendo um código que não existe mais.
+
+## Primeiro: qual é o tipo?
+
+\`dd-harness check\` distingue dois, e eles pedem coisas diferentes.
+
+**ALVO AUSENTE** — o arquivo ou trecho não existe mais no caminho ancorado.
+**Alterado** — o alvo existe e o conteúdo mudou desde a linha de base.
+
+## ALVO AUSENTE: quase sempre é reancorar
+
+O arquivo mudou de lugar. Se houve rename no commit, o \`check --commit\` já imprime o
+comando \`dd-harness reancorar\` pronto — **confira o destino antes de rodar**: rename por
+similaridade é heurística do git, e reancorar para o lugar errado move a memória em
+silêncio, o que é pior que o alvo ausente.
+
+Se não houve rename, procure o conteúdo (\`Grep\` pelo trecho ancorado). Três desfechos:
+
+- **achou noutro lugar** → reancore para lá
+- **o trecho foi renomeado** (a função virou outra coisa) → reancore para o nome novo, e
+  confira se a memória ainda descreve o que aquele código faz
+- **sumiu de vez** → o mundo mudou; siga para "a memória morreu"
+
+## Alterado: leia a memória ANTES de decidir
+
+Isto é o passo que o atalho pula. Abra a memória com \`ler_memoria\` e leia o **porquê** —
+não o título. A pergunta é:
+
+> A razão que fez esta memória existir continua verdadeira?
+
+Compare com o que mudou (\`git diff\` no alvo). Três desfechos, e cada um tem uma ação
+diferente:
+
+**1. A memória ainda vale** — o código mudou por perto, mas a razão externa continua de
+pé (o fornecedor continua limitando, o compliance continua exigindo). Resolva como "ainda
+vale": a linha de base passa a ser o estado atual.
+
+**2. A memória vale, mas o texto envelheceu** — a razão é a mesma, a descrição não bate
+mais com o código. **Edite a memória** e depois resolva. Resolver sem editar guarda uma
+memória que vai confundir quem a ler.
+
+**3. A razão deixou de existir** — o fornecedor mudou o limite, a lib foi trocada, a
+decisão foi revertida. Aí não é "ainda vale": é \`arquivar_memoria\` com motivo
+\`obsoleta\`. Se outra memória tomou o lugar, use \`--substituida-por\`.
+
+## Nunca faça
+
+**Não resolva em lote.** Cinco observações abertas são cinco perguntas diferentes; marcar
+todas como "ainda vale" é o mesmo que não ter medido nada.
+
+**Não decida sozinho pelo arquivamento.** Resolver "ainda vale" é reversível — a próxima
+deriva reabre. Arquivar tira a memória de circulação, e quem vier depois não saberá que
+ela existiu se você errar. Proponha ao humano.
+
+**Não edite o código para fechar a deriva.** Se o alvo mudou porque alguém corrigiu um
+bug, o código está certo e a memória é que precisa acompanhar.
+
+## O caso que parece deriva e não é
+
+Se o primeiro \`check\` de um projeto acusa tudo, isso não é deriva: é a **linha de base
+sendo adotada**. Medido numa rodada de teste — rodar o primeiro \`check\` com o código já
+alterado fixa o estado errado como base, e reverter para o valor correto passa a ser "a
+mudança". Rode \`check\` antes de editar, não depois.`,
+    },
+    {
+        slug: "promover-ou-nao",
+        descricao: `Decide se uma memória deve valer para todo projeto do espaço, ou continuar só neste. Invoque ao gravar ou revisar uma memória que parece falar de algo maior que o projeto — um limite de fornecedor, uma regra da organização, uma armadilha da linguagem. Também ao revisar as globais existentes.`,
+        ferramentas: ["mcp__dd-harness__ler_memoria", "mcp__dd-harness__buscar_memoria", "mcp__dd-harness__promover_memoria"],
+        conteudo: `# Promover, ou não
+
+Memória global vale para **todo projeto do espaço, inclusive os que ainda não existem**.
+Ela chega ao contexto de qualquer sessão e dispara o alerta antes da edição, como as do
+próprio projeto.
+
+Isso é força e é risco: memória global errada **erra em escala**.
+
+## O teste, em uma pergunta
+
+> Se o próximo projeto repetir este erro, esta memória o teria evitado?
+
+Se a resposta for sim, é global. Se você precisa construir um cenário para chegar ao sim,
+não é.
+
+## O que passa
+
+A razão vem de **fora deste projeto** e continuaria valendo se o projeto não existisse:
+
+- **limite de fornecedor** — "o gateway recusa mais de N tentativas por contrato"
+- **regra da organização** — "todo repositório aqui exige revisão de dois"
+- **armadilha da linguagem ou da ferramenta** — "\`REVOKE\` por coluna não tem efeito
+  quando existe \`GRANT\` na tabela inteira"
+- **bug de terceiro com workaround** — "a versão X da lib quebra em Y; não subir"
+
+Repare no padrão: nenhuma delas menciona um arquivo deste repositório.
+
+## O que NÃO passa
+
+- **decisão deste projeto** — "aqui usamos Drizzle em vez de Prisma". Vale para um
+  projeto; noutro a escolha pode ser outra, e a memória global mentiria.
+- **acordo com um cliente específico** — é do projeto daquele cliente.
+- **algo ancorado num arquivo deste repositório** — se a âncora aponta para
+  \`src/pagamento.js\`, a memória fala deste código. Para alcançar alguns projetos
+  nomeados, existe \`projetos:\` no frontmatter, que é uma **lista** — diferente de global,
+  que é uma propriedade.
+- **"é interessante para todos saberem"** — interessante não é o critério. O critério é
+  o erro que ela evita.
+
+## A ordem importa
+
+**Grave no projeto primeiro. Promova depois.**
+
+A memória nasce onde a lição apareceu, e continua morando lá mesmo depois de promovida —
+a origem é metade do porquê. *"Descobrimos isto no projeto de pagamentos"* explica a
+lição de um jeito que uma origem apagada não explicaria.
+
+## Proponha, não promova
+
+Promover multiplica o alcance. Leve ao humano com:
+
+1. **o teste respondido** — qual erro futuro ela evita, em que projeto plausível
+2. **por que não é deste projeto** — a razão externa, nomeada
+3. **o que acontece se estiver errada** — ela vai chegar a todo projeto do espaço
+
+Só então \`promover_memoria\`.
+
+## Revisar as globais
+
+É reversível: \`promover_memoria\` com \`global: false\` traz de volta. Ao revisar o acervo
+global, reaplique o teste em cada uma — uma memória que era global e virou específica
+(porque o fornecedor mudou, porque a regra caiu) deve voltar ao projeto, não ficar.
+
+**Uma trava a conhecer:** uma global sem vínculo com projeto algum **não pode ser
+despromovida** — isso a deixaria invisível. Vincule-a a um projeto antes, ou apague.`,
+    },
+    {
+        slug: "escrever-skill",
+        descricao: `Escreve uma skill que o modelo de fato invoca e segue, em vez de uma que existe e nunca dispara. Invoque ao criar ou revisar uma skill deste projeto — ou quando notar que um procedimento já foi explicado três vezes e devia estar escrito.`,
+        ferramentas: ["mcp__dd-harness__listar_skills", "Read"],
+        conteudo: `# Escrever uma skill que funciona
+
+A falha mais comum de skill não é estar errada — é **nunca disparar**. Ela existe, o
+procedimento está certo, e o modelo nunca a invoca. Não há erro, ninguém descobre, e o
+esforço de escrevê-la some.
+
+O segundo modo de falha é ser prosa: um texto que descreve o assunto em vez de dar os
+passos, e que o modelo lê sem mudar nada do que ia fazer.
+
+## Antes: isto é mesmo uma skill?
+
+Três filtros, **conjuntivos**. Falhou um, não escreva.
+
+| # | Filtro | A pergunta | É skill se |
+|---|---|---|---|
+| 1 | **Repetição consumada** | Isto já foi executado três vezes, em sessões diferentes? | sim — a terceira, não a segunda |
+| 2 | **Passos, não conhecimento** | É uma sequência que se executa, ou um fato que se sabe? | passos — fato é memória |
+| 3 | **Estável** | Os passos seriam os mesmos daqui a três meses? | sim — o que muda a cada uso é prosa |
+
+"Seria conveniente ter" não é repetição. "Fiz duas vezes" não é três.
+
+Chame \`listar_skills\` antes: se já existe uma que cobre o assunto, **edite aquela**. Duas
+skills parecidas competem pela invocação, e o modelo escolhe mal entre elas.
+
+## A descrição é metade do trabalho
+
+É o **único campo que o modelo lê antes de decidir** invocar, e ele fica no contexto de
+toda sessão — inclusive nas que não usam a skill.
+
+**Escreva o gatilho, não o resumo.** A pergunta que a descrição responde é *"quando eu
+deveria parar e usar isto?"*, não *"o que isto é?"*.
+
+| Descrição ruim | Por quê |
+|---|---|
+| "Ajuda com memórias" | não diz quando; nunca dispara |
+| "Procedimento de gravação" | descreve a skill, não a situação |
+| "Use esta skill para gravar" | circular |
+
+| Descrição boa | Por quê |
+|---|---|
+| "Invoque ao gravar memória que descreve um arquivo, função ou chave de config" | nomeia a situação |
+| "Invoque ao ver ALVO AUSENTE no resultado de \`dd-harness check\`" | nomeia o gatilho literal |
+
+**Diga também quando NÃO usar**, se houver confusão provável com outra skill. Uma linha de
+exclusão evita a skill errada disparar.
+
+## O corpo: passos e decisões, não explicação
+
+O corpo só entra no contexto quando a skill é invocada — aqui cabe detalhe. Mas detalhe
+não é prosa.
+
+- **Numere o que tem ordem.** Se a ordem não importa, não numere.
+- **Escreva a decisão, não só a ação.** "Escolha o alvo" não ajuda; "prefira
+  \`arquivo#trecho\` porque âncora de arquivo dispara para a memória errada" ajuda.
+- **Nomeie o caminho errado atraente.** Toda skill que vale existe porque há um atalho
+  tentador — diga qual é e por que ele custa caro. Sem isso o modelo pega o atalho.
+- **Traga a medição, quando houver.** "Medido: duas memórias no mesmo arquivo eram as
+  duas sinalizadas" vale mais que "pode gerar ruído".
+- **Tabelas para distinguir casos.** Bom/ruim lado a lado decide mais rápido que dois
+  parágrafos.
+
+Se o corpo só repete o que a descrição de uma ferramenta MCP já diz, **não escreva a
+skill** — a ferramenta já ensina isso, e melhor.
+
+## O frontmatter faz diferença
+
+- **\`allowed-tools\`** — as ferramentas que a skill usa. Sem isso ela para a cada passo
+  pedindo permissão, e a pessoa aprende a desligar o mecanismo.
+- **\`paths\`** — globs que carregam a skill só quando o trabalho toca aqueles arquivos. É
+  a mesma ideia da âncora, aplicada ao procedimento. Glob largo demais é uma skill sempre
+  presente, que era o que o campo existia para evitar.
+- **\`disable-model-invocation: true\`** (na interface, "só por comando") — para skill com
+  efeito colateral, onde o momento é de quem digita.
+- **\`argument-hint\`** — só quando a skill recebe argumento.
+
+## Depois de escrever
+
+**Releia a descrição sozinha**, sem o corpo. Se você não souber dizer em que momento
+invocá-la, o modelo também não saberá.
+
+Skill deste projeto vive no serviço: o repositório guarda só o ponteiro, e o
+\`dd-harness start\` o reescreve. Se você mudou a descrição, rode-o — o frontmatter em
+disco não muda sozinho.`,
+    },
+    {
+        slug: "propor-ferramentas",
+        descricao: `Pesquisa e propõe MCP servers, skills e bibliotecas que combinem com a stack deste projeto, validando cada candidato contra fonte antes de sugerir. Invoque logo após concluir o briefing — é quando a stack acabou de ser descrita — ou quando a stack mudar. Só propõe: nada é instalado sem OK, e recusar tudo é resposta válida.`,
+        ferramentas: ["mcp__dd-harness__ler_artefato", "mcp__dd-harness__listar_skills", "mcp__dd-harness__buscar_memoria", "Read", "Glob", "Grep", "WebSearch", "WebFetch"],
+        conteudo: `# Propor ferramentas para este projeto
+
+O briefing acabou de descrever a stack e as restrições. Este é o único momento em que
+esse contexto está fresco — depois dele, ninguém pergunta de novo, e uma ferramenta que
+faria diferença aqui nunca é considerada.
+
+Roda em subagente (\`context: fork\`): o conteúdo bruto das buscas fica lá, e só a proposta
+volta. Por isso leia tudo do serviço no passo 1 — não conte com o histórico da conversa.
+
+> **Só PROPÕE.** Não instala MCP, não cria skill, não adiciona dependência. Cada adoção é
+> uma tarefa nova, com plano e OK. **Recusar tudo é resposta válida e esperada** — se o
+> usuário não quiser nada, não insista.
+
+## 1. O que já existe (antes de buscar qualquer coisa)
+
+Propor o que o projeto já tem gasta a confiança na proposta inteira.
+
+- **Stack, objetivo e restrições:** \`ler_artefato\` com \`tipo: "briefing"\`. As restrições
+  são **filtro duro** — sugestão que as viola precisa ser marcada como tal, ou descartada.
+- **Skills já existentes:** \`listar_skills\`. Duas skills parecidas competem pela
+  invocação, e o modelo escolhe mal entre elas.
+- **MCP e hooks já ligados:** leia \`.mcp.json\` e \`.claude/settings.json\` do repositório —
+  esses continuam em disco, porque é deles que o host lê.
+- **O que já foi rejeitado:** \`buscar_memoria\` pelo nome de cada candidato antes de
+  propô-lo. Pode haver memória dizendo "não usar X porque Y" — repropor o que foi
+  descartado é o erro que mais rápido faz a proposta ser ignorada.
+
+Briefing vazio: **pare e avise**. Sem a stack, a busca não tem filtro e a proposta vira
+lista genérica — que é pior que nenhuma.
+
+## 2. Pesquise com a stack no filtro
+
+Busque informação **atual** (\`WebSearch\`, \`WebFetch\`), não memória. Três categorias:
+
+- **MCP servers** — o que daria ao agente acesso a algo que hoje ele não alcança neste
+  projeto (o banco, o deploy, o rastreador de issues).
+- **Skills** — procedimento repetido que já exista escrito e testado por outros.
+- **Libs e ferramentas** — do ecossistema da stack, para o problema que o projeto tem.
+
+Ancore cada busca na stack real. "Melhores ferramentas de 2026" devolve lista de blog;
+"MCP server para Postgres com RLS" devolve o que serve aqui.
+
+## 3. Valide contra fonte — não contra memória
+
+Para todo candidato, responda com link:
+
+- **Existe de fato?** Repositório, doc ou pacote oficial.
+- **É mantido?** Último release ou commit. Abandonado → descarte ou marque o risco.
+- **Casa com a stack?** Versão da linguagem, do framework, do runtime.
+- **Respeita as restrições?** Confronte com o briefing. Conflito → **diga**, não esconda.
+- **Já não temos equivalente?** Confronte com o passo 1.
+
+Candidato que não passa: **descarte e diga por quê, em uma linha.** Não infle a lista —
+três propostas boas valem mais que dez, e uma lista longa faz o usuário recusar tudo sem
+ler.
+
+## 4. Apresente
+
+Para cada proposta: **o que é**, **o problema deste projeto que ela resolve**, **o custo**
+(dependência nova, chave de API, processo a manter) e o **link**. Nessa ordem — o
+problema antes da solução, senão parece catálogo.
+
+Separe o que é **recomendação** do que é **possibilidade**. Se nada passou na validação,
+diga isso: "não achei nada que valha para esta stack agora" é uma resposta honesta e
+útil.
+
+## 5. Se algo for adotado
+
+Adotar é tarefa nova: plano curto, OK do usuário, e o protocolo normal do projeto.
+
+Se a decisão vier com uma razão que sobrevive ao dia de hoje — "escolhemos X porque o
+fornecedor limita Y" —, isso pode ser memória. Passe pelos três filtros antes de gravar;
+"experimentamos e gostamos" não passa em nenhum deles.`,
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-harness",
-  "version": "0.26.0",
+  "version": "0.28.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",