dd-harness-mcp 0.14.0 → 0.16.0

package/dist/cli/src/cinto.js

@@ -66,13 +66,14 @@ export async function guardaCache(raiz, brain) {
         gravado_em: new Date().toISOString(),
         memorias: brain.memorias
             .filter((m) => m.status === "ativa" && m.ancoras.length > 0)
-            .map(({ pasta, slug, titulo, resumo, status, ancoras }) => ({
+            .map(({ pasta, slug, titulo, resumo, status, ancoras, escopo }) => ({
             pasta,
             slug,
             titulo,
             resumo,
             status,
             ancoras,
+            escopo,
         })),
     };
     try {
@@ -143,7 +144,7 @@ export function caminhoRelativo(raiz, arquivo) {
  * Vazio e o caso comum e tem que sair barato: a maioria das edicoes nao toca ancora
  * alguma, e o silencio ai nao e falta de aviso, e a ausencia de motivo para avisar.
  */
-export function alerta(tocadas, resumos) {
+export function alerta(tocadas, resumos, globais = new Set()) {
     if (tocadas.length === 0)
         return "";
     const linhas = [
@@ -152,7 +153,11 @@ export function alerta(tocadas, resumos) {
     ];
     for (const t of tocadas) {
         const endereco = `${t.pasta}/${t.memoria}`;
-        linhas.push(`## ${t.titulo}`, `\`${endereco}\` — âncora: \`${t.ancora}\``, "");
+        // Marcar a global muda o peso do que se le: a licao nao fala DESTE projeto, fala de
+        // todos. Sem a marca, o agente a avalia como decisao local e pode concluir que "aqui
+        // e diferente" — que e exatamente o raciocinio que a promocao existiu para vencer.
+        const marca = globais.has(endereco) ? " · MEMÓRIA GLOBAL" : "";
+        linhas.push(`## ${t.titulo}${marca}`, `\`${endereco}\` — âncora: \`${t.ancora}\``, "");
         const resumo = resumos.get(endereco);
         if (resumo)
             linhas.push(resumo, "");
@@ -203,11 +208,12 @@ export async function decideDoHook(entrada) {
     if (novas.length === 0)
         return permitir;
     const resumos = new Map(cache.memorias.map((m) => [`${m.pasta}/${m.slug}`, m.resumo]));
+    const globais = new Set(cache.memorias.filter((m) => m.escopo === "global").map((m) => `${m.pasta}/${m.slug}`));
     return JSON.stringify({
         hookSpecificOutput: {
             hookEventName: "PreToolUse",
             permissionDecision: "allow",
-            additionalContext: alerta(novas, resumos),
+            additionalContext: alerta(novas, resumos, globais),
         },
     });
 }

package/dist/cli/src/curar.js

@@ -92,3 +92,53 @@ export async function arquiva(raiz, endereco, opcoes) {
     const lido = (await resposta.json());
     return lido;
 }
+/**
+ * Promove a memoria a global — ou a traz de volta ao projeto de origem.
+ *
+ * Global vale para TODO projeto do espaco, inclusive os que ainda nao existem. E o degrau
+ * acima de `memory_projects`, que lista projetos nomeados: aqui o alcance deixa de ser
+ * uma lista e vira uma propriedade.
+ */
+export async function promove(raiz, endereco, global) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/memorias/${endereco}/escopo`, {
+        method: "PUT",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({ tenant: config.tenant, projeto: config.projeto, global }),
+    });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json());
+}
+/**
+ * Apaga de verdade, em cascata — ancoras, deriva medida, vinculos, tudo.
+ *
+ * Diferente de `arquiva`, que e o caminho normal: arquivar guarda o conteudo porque o que
+ * a memoria dizia pode voltar a importar. Isto e para o que nunca deveria ter existido.
+ *
+ * Sem `confirmacao`, o servidor RECUSA e devolve o que a cascata levaria junto — e so
+ * entao se repete a chamada com o nome do espaco. Duas etapas de proposito: DELETE nao
+ * tem desfazer, e a cascata e invisivel de fora.
+ */
+export async function apaga(raiz, endereco, confirmacao) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/memorias/${endereco}/apagar`, {
+        method: "POST",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            ...(confirmacao ? { confirmacao } : {}),
+        }),
+    });
+    // 409 aqui nao e falha: e "ainda nao" — falta confirmar, ou ha uma arquivada apontando
+    // para esta. O texto do servidor e a resposta, entao ele passa adiante em vez de virar
+    // excecao com mensagem generica.
+    if (resposta.status === 409) {
+        const lido = (await resposta.json());
+        return { apagou: false, detalhe: lido.erro, confirmacaoEsperada: lido.confirmacao_esperada };
+    }
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json());
+}

package/dist/cli/src/index.js

@@ -21,8 +21,10 @@ 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, leSkills, semeiaSkills } from "./skill.js";
+import { SKILLS_INICIAIS } from "./skills-iniciais.js";
 import { busca } from "./buscar.js";
-import { arquiva, edita, le } from "./curar.js";
+import { apaga, arquiva, edita, le, promove } from "./curar.js";
 import { criaPasta } from "./pasta.js";
 import { criaProjeto, listaTenants } from "./projeto.js";
 import { reancora } from "./reancorar.js";
@@ -52,6 +54,15 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
   dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
                      [--substituida-por <pasta>/<slug>]
                                      tira de circulação sem apagar
+  dd-harness promover <pasta>/<slug>
+                                     torna a memória global: vale para TODO
+                                     projeto do espaço, inclusive os futuros
+  dd-harness despromover <pasta>/<slug>
+                                     traz de volta ao alcance dos vínculos
+  dd-harness apagar <pasta>/<slug> [--confirmar <espaço>]
+                                     apaga de vez, em cascata — sem desfazer.
+                                     Para tirar de circulação guardando o
+                                     conteúdo, use "arquivar"
   dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
   dd-harness ler <pasta>/<slug>      imprime a memória inteira, no formato de gravar
   dd-harness reancorar <pasta>/<slug> --de "<alvo>" --para "<alvo>"
@@ -180,6 +191,10 @@ async function comandoFase(argv) {
  * primeira conexao do Claude Code. Sem isto, a primeira instalacao acontecia so quando
  * o host tentava conectar ao servidor MCP, e o handshake tem timeout curto demais para
  * esperar o download: a sessao real via `CONNECTION_CLOSED` em vez de "instalando".
+ *
+ * Roda em TODO `start`, nao so no primeiro: e tambem o ponto em que o cache do npx e
+ * renovado para a versao mais recente. Um projeto ja configurado que roda `start` de novo
+ * sai dali com CLI e MCP frescos, sem ninguem precisar lembrar de atualizar nada.
  */
 function instalaMcp() {
     return new Promise((resolve) => {
@@ -187,7 +202,14 @@ function instalaMcp() {
         // segundos) e, se falhar, ve POR QUE — em vez do "nao consegui" mudo que nao dava
         // pista nenhuma para diagnosticar. O DEP0190 que isto dispara e suprimido no topo
         // do arquivo (`process.removeAllListeners("warning")`).
-        const p = spawn("npx", ["-y", "dd-harness-mcp", "--help"], {
+        //
+        // `@latest` EXPLICITO, e nao `dd-harness-mcp` pelado: sem a tag, o npx serve a copia
+        // que ja estiver no cache dele e nem consulta o registro. Medido na rodada 006 — a
+        // cobaia rodou uma sessao inteira contra um MCP defasado sem nada denunciar. O
+        // `.mcp.json` continua declarando o pacote SEM versao, de proposito: o que precisa
+        // estar fresco e o cache, e fixar versao no arquivo obrigaria a reescrever config em
+        // todo repositorio a cada publicacao.
+        const p = spawn("npx", ["-y", "dd-harness-mcp@latest", "--help"], {
             shell: process.platform === "win32",
             stdio: "inherit",
         });
@@ -221,6 +243,32 @@ async function versaoDesatualizada() {
         return null;
     }
 }
+/**
+ * Instala a versao mais nova do CLI globalmente, de dentro do proprio wizard.
+ *
+ * Ate aqui o `start` so AVISAVA e mandava o usuario rodar `npm i -g` e recomecar — e
+ * "comece de novo" no meio de um wizard e o tipo de instrucao que ninguem segue. A
+ * rodada 006 mostrou o custo: a sessao inteira rodou contra um CLI defasado, com o
+ * relatorio registrando "ja instalado, nao atualizado" como se fosse normal.
+ *
+ * O binario EM EXECUCAO continua sendo o antigo ate este processo terminar — nao ha como
+ * trocar codigo de baixo de si mesmo. Isso e seguro aqui porque o que resta do wizard so
+ * escreve configuracao (JSON e markdown), nada que dependa de correcao nova; e do
+ * proximo comando em diante tudo ja e a versao nova.
+ *
+ * Nunca lanca: falhar em atualizar nao pode travar o `start`. Sem permissao para escrever
+ * no diretorio global (o caso mais comum), o wizard segue e o aviso continua valendo.
+ */
+function atualizaCli(ultima) {
+    return new Promise((resolve) => {
+        const p = spawn("npm", ["install", "-g", `dd-harness@${ultima}`], {
+            shell: process.platform === "win32",
+            stdio: "inherit",
+        });
+        p.on("exit", (code) => resolve(code === 0));
+        p.on("error", () => resolve(false));
+    });
+}
 /**
  * Tenta abrir o navegador padrao. Nunca lanca — falhar em abrir nao pode travar o
  * wizard, so degrada para "aqui esta a URL, abra voce mesmo".
@@ -271,9 +319,14 @@ async function comandoStart() {
     // pre-instalacao do MCP, passo 5.5 abaixo, numa versao anterior a ela existir).
     const desatualizado = await versaoDesatualizada();
     if (desatualizado) {
-        console.log(`AVISO: você está na versão ${desatualizado.atual}, e a mais recente é ` +
-            `${desatualizado.ultima}. Rode \`npm install -g dd-harness@latest\` e comece de ` +
-            "novo — start segue mesmo assim, mas pode faltar correção.\n");
+        console.log(`Atualizando o dd-harness: ${desatualizado.atual} → ${desatualizado.ultima}...`);
+        const atualizou = await atualizaCli(desatualizado.ultima);
+        console.log(atualizou
+            ? `Pronto — ${desatualizado.ultima} instalada. O wizard segue na ${desatualizado.atual} ` +
+                "(o binário em execução não troca sozinho); do próximo comando em diante, a nova.\n"
+            : `Não consegui atualizar — o npm explicou o motivo acima. Você segue na ` +
+                `${desatualizado.atual}, e a mais recente é ${desatualizado.ultima}: rode ` +
+                "`npm install -g dd-harness@latest` quando puder. O start continua assim mesmo.\n");
     }
     // 1. Credencial. Sem ela nada do resto e possivel — nem listar tenant.
     // O estado aparece SEMPRE, mesmo quando ja existe credencial: antes o passo era
@@ -366,7 +419,8 @@ async function comandoStart() {
         }[mcp.estado]);
     }
     if (mcp.ok) {
-        console.log("\nInstalando o servidor dd-harness-mcp (primeira vez pode demorar um pouco)...");
+        console.log("\nInstalando a versão mais recente do servidor dd-harness-mcp " +
+            "(a primeira vez pode demorar um pouco)...");
         const { ok: instalou, erro: erroInstalacao } = await instalaMcp();
         console.log(instalou
             ? "dd-harness-mcp instalado — a próxima sessão do Claude Code conecta na hora."
@@ -387,6 +441,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());
@@ -477,6 +558,49 @@ async function comandoEditar(argv) {
     console.log(`  ${r.ancoras} âncora(s).`);
 }
 const MOTIVOS = ["obsoleta", "incorreta", "fora_dos_filtros"];
+/**
+ * `promover` / `despromover` — o alcance da memoria.
+ *
+ * Global vale para TODO projeto do espaco, inclusive os que ainda nao existem. Nao e o
+ * mesmo que `projetos:` no frontmatter, que lista projetos nomeados: la o alcance e uma
+ * lista, aqui e uma propriedade.
+ */
+async function comandoPromover(argv, global) {
+    const endereco = argv[0];
+    const verbo = global ? "promover" : "despromover";
+    if (!endereco || endereco.startsWith("-") || !endereco.includes("/")) {
+        throw new Error(`uso: dd-harness ${verbo} <pasta>/<slug>`);
+    }
+    const r = await promove(process.cwd(), endereco, global);
+    console.log(global
+        ? `${endereco} agora é GLOBAL — vale para todo projeto de ${r.tenant}, inclusive os que ainda não existem.`
+        : `${endereco} voltou a valer só para os projetos a que está vinculada.`);
+}
+/**
+ * `apagar` — o unico caminho que destroi.
+ *
+ * Duas etapas, e a segunda pede o nome do espaco digitado. Nao e cerimonia: a cascata leva
+ * ancoras e toda a deriva medida delas, e nao ha desfazer. Arquivar continua sendo o
+ * caminho normal — isto e para o que nunca deveria ter existido.
+ */
+async function comandoApagar(argv) {
+    const endereco = argv[0];
+    if (!endereco || endereco.startsWith("-") || !endereco.includes("/")) {
+        throw new Error("uso: dd-harness apagar <pasta>/<slug> [--confirmar <espaço>]");
+    }
+    const r = await apaga(process.cwd(), endereco, argumento(argv, "confirmar"));
+    if (!r.apagou) {
+        console.log(r.detalhe);
+        if (r.confirmacaoEsperada) {
+            console.log(`
+  dd-harness apagar ${endereco} --confirmar ${r.confirmacaoEsperada}`);
+        }
+        // Sem exit diferente de zero: recusar por falta de confirmacao nao e falha, e o
+        // caminho normal da primeira chamada.
+        return;
+    }
+    console.log(`${endereco} apagada — ${r.detalhe}`);
+}
 async function comandoArquivar(argv) {
     const endereco = argv[0];
     const motivo = argumento(argv, "motivo");
@@ -952,6 +1076,12 @@ async function principal() {
             return comandoEditar(resto);
         case "arquivar":
             return comandoArquivar(resto);
+        case "promover":
+            return comandoPromover(resto, true);
+        case "despromover":
+            return comandoPromover(resto, false);
+        case "apagar":
+            return comandoApagar(resto);
         case "ler":
             return comandoLer(resto);
         case "buscar":

package/dist/cli/src/init.js

@@ -17,12 +17,19 @@ export const SUGESTAO_MCP = `{
   }
 }`;
 /**
- * O hook que carrega a politica no inicio de cada sessao.
+ * Os dois hooks do dd-harness, pelas duas razoes que nenhuma instrucao em markdown
+ * resolve.
  *
- * E a garantia de que nenhuma sessao abre sem protocolo — o papel que antes era do
- * arquivo materializado mais a linha de import. Vive num hook, e nao numa instrucao no
- * `CLAUDE.md`, porque instrucao o modelo pode pular: o import quebrado falhava em
- * silencio, e isso foi medido.
+ * `SessionStart` carrega a politica no inicio de cada sessao — a garantia de que nenhuma
+ * abre sem protocolo, papel que antes era do arquivo materializado mais a linha de
+ * import. Vive num hook, e nao numa instrucao no `CLAUDE.md`, porque instrucao o modelo
+ * pode pular: o import quebrado falhava em silencio, e isso foi medido.
+ *
+ * `PreToolUse` e o cinto: cruza o arquivo que esta sendo editado contra as ancoras e
+ * entrega a memoria ANTES da edicao. Existe porque o Brain era todo PULL, e PULL falha
+ * onde mais custa — o agente nao busca memoria quando *acha que sabe*. Os dois vao
+ * juntos aqui de proposito: quem monta o `settings.json` a mao pelo `init` sairia sem o
+ * cinto e sem nunca saber que ele existe.
  *
  * Sugerido e nao escrito, pelo mesmo motivo do `.mcp.json`.
  */
@@ -38,6 +45,17 @@ export const SUGESTAO_HOOK = `{
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dd-harness cinto"
+          }
+        ]
+      }
     ]
   }
 }`;

package/dist/cli/src/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/cli/src/skills-iniciais.js

@@ -0,0 +1,72 @@
+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. 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).`,
+        conteudo: `# Como Desenvolver
+
+Aplique ao escrever ou editar código.
+
+## 1. Simplicidade Primeiro
+
+**Mínimo de código que resolve o problema. 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.
+
+O teste: *"Um engenheiro sênior diria que isso está complicado demais?"* Se sim, simplifique.
+
+> Simplicidade e modularização (Seção 2) não brigam. Você **divide o que já existe e cresce** — não cria camadas para um futuro hipotético. Extrair um módulo de algo que repete é simplificar; criar um módulo "por via das dúvidas" é a complexidade especulativa que esta seção proíbe.
+
+## 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.
+
+Um arquivo ou função que faz coisa demais é difícil de ler, testar, reusar e mudar sem quebrar o resto. Quando algo cresce, divida:
+
+- **Uma responsabilidade por unidade.** Um arquivo, uma função, um componente deve ter um motivo só para mudar. Se você descreve o que ele faz usando "e" várias vezes, ele faz coisa demais.
+- **Separe as camadas.** Não misture lógica de negócio, acesso a dados e apresentação no mesmo lugar. Cada uma muda por razões diferentes.
+- **Extraia o que repete ou o que cresce** — só depois que existe de fato (ver Seção 1). A regra prática: na **segunda** vez que o mesmo trecho aparece, considere extrair; na terceira, extraia.
+- **No front-end:** quebre telas/páginas grandes em componentes menores e nomeados. Um 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 em peças minúsculas demais cria o problema oposto — saltar entre dez arquivos para seguir uma linha de raciocínio. Divida quando a unidade carrega mais de uma responsabilidade, não para perseguir uma 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 que não fazem parte 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? **Mencione — não delete.**
+
+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.
+
+O teste: cada linha alterada deve rastrear diretamente à solicitação do usuário.
+
+## 4. Execução Orientada a Objetivos
+
+**Defina critérios de sucesso. Itere até verificar.**
+
+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."
+- "Refatorar X" → "Garanta que os testes passem antes e depois."
+
+Para tarefas com múltiplos passos, declare um plano breve:
+\`\`\`
+1. [Passo] → verificar: [checagem]
+2. [Passo] → verificar: [checagem]
+3. [Passo] → verificar: [checagem]
+\`\`\`
+
+Critérios fortes deixam você iterar sozinho. Critérios fracos ("faça funcionar") forçam esclarecimentos constantes.`,
+    },
+];

package/dist/mcp/src/index.js

@@ -6,13 +6,14 @@ import * as z from "zod/v4";
 // que e gerado por build e nao vai no git — num checkout limpo (a Vercel) a resolucao
 // falharia, e foi assim que o build de producao caiu uma vez. Aqui o compilador segue o
 // fonte, e o `dist` deste pacote sai com o codigo do CLI embutido.
-import { arquiva, edita, le } from "../../cli/src/curar.js";
+import { apaga, arquiva, edita, le, promove } from "../../cli/src/curar.js";
 import { busca } from "../../cli/src/buscar.js";
 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 { caminhosDaArvore } from "../../cli/src/diff.js";
+import { leSkill, leSkills } from "../../cli/src/skill.js";
 import { avisoDeOrdem, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "../../cli/src/roadmap.js";
 /**
  * O mesmo servico, outra porta.
@@ -100,6 +101,53 @@ Os primeiros achados são os que valem: o piso barra tema alheio, mas num Brain
             return falha(erro);
         }
     });
+    server.registerTool("ler_skill", {
+        description: `O procedimento de uma skill deste projeto. É o que o arquivo \`.claude/skills/<slug>/SKILL.md\` manda chamar — ele é só o ponteiro, o conteúdo vive aqui.
+
+Chame com o \`slug\` que o ponteiro informou e SIGA o que vier, como se estivesse escrito no próprio arquivo. Não improvise o procedimento a partir do nome da skill.
+
+Também serve para consultar uma skill sem invocá-la ("como é mesmo o passo a passo de X?"). \`listar_skills\` mostra o que existe.`,
+        inputSchema: z.object({
+            slug: z
+                .string()
+                .min(1)
+                .describe("O nome da skill, como aparece no `name` do ponteiro e no comando `/`."),
+        }),
+    }, async ({ slug }) => {
+        try {
+            const s = await leSkill(raiz, slug);
+            if (!s.conteudo.trim()) {
+                return texto(`A skill \`${slug}\` existe mas está sem procedimento escrito. Avise o usuário ` +
+                    "em vez de improvisar: uma skill vazia é um passo que alguém pretendia definir.");
+            }
+            return texto(`# ${s.slug}
+
+${s.conteudo.trim()}`);
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
+    server.registerTool("listar_skills", {
+        description: `As skills deste projeto: nome, quando cada uma serve, e se é invocável só por comando.
+
+Devolve a descrição de cada uma, não o procedimento — para o procedimento, \`ler_skill\`. Use quando o usuário perguntar o que existe, ou quando precisar saber se já há skill para um trabalho antes de fazê-lo à mão.`,
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            const skills = await leSkills(raiz);
+            if (skills.length === 0) {
+                return texto("Este projeto não tem skill alguma — e isso é válido. Skill é procedimento " +
+                    "repetido; um que aconteceu uma vez é só uma tarefa.");
+            }
+            const linhas = skills.map((s) => `- \`${s.slug}\`${s.so_por_comando ? " (só por comando)" : ""}: ${s.descricao}`);
+            return texto(`${skills.length} skill(s) neste projeto:\n${linhas.join("\n")}\n\n` +
+                "`ler_skill` traz o procedimento de uma delas.");
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
     server.registerTool("sugerir_ancoras", {
         description: `Os arquivos que esta sessão modificou, para escolher a âncora de uma memória que vai ser gravada.
 
@@ -230,6 +278,66 @@ Use \`substituida_por\` quando outra memória toma o lugar desta — a troca aco
             return falha(erro);
         }
     });
+    server.registerTool("promover_memoria", {
+        description: `Torna uma memória GLOBAL: ela passa a valer para todo projeto deste espaço, inclusive os que ainda não existem.
+
+PROPONHA ao humano e espere o OK. Promover não é editar — é decidir que uma lição vale para tudo que se faz aqui, e o alcance passa a incluir projetos que ninguém escreveu ainda.
+
+Quando propor: a memória descreve algo que NÃO é deste projeto — um limite de fornecedor, uma regra da organização, uma armadilha da linguagem ou da ferramenta, uma decisão que vale para tudo que você constrói. O teste: se o próximo projeto repetir este erro, a memória teria evitado?
+
+Quando NÃO propor: a memória fala de uma escolha deste projeto, de um arquivo deste repositório, de um acordo com um cliente específico. Isso é memória de projeto — e para alcançar alguns projetos nomeados existe \`projetos:\` no frontmatter, que é uma lista, não uma propriedade.
+
+\`global: false\` traz de volta. É reversível, e a memória nunca sai da pasta onde nasceu: a origem é metade do porquê.`,
+        inputSchema: z.object({
+            endereco: z.string().min(1).describe("`<pasta>/<slug>` da memória."),
+            global: z
+                .boolean()
+                .default(true)
+                .describe("`true` promove a global; `false` traz de volta ao alcance dos vínculos."),
+        }),
+    }, async ({ endereco, global }) => {
+        try {
+            const r = await promove(raiz, endereco, global);
+            return texto(global
+                ? `\`${endereco}\` agora é GLOBAL — vale para todo projeto de ${r.tenant}, ` +
+                    "inclusive os que ainda não existem. Ela continua morando na pasta onde nasceu."
+                : `\`${endereco}\` voltou a valer só para os projetos a que está vinculada.`);
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
+    server.registerTool("apagar_memoria", {
+        description: `Apaga uma memória DE VEZ, com as âncoras e toda a deriva medida delas. Não há desfazer.
+
+Na maioria dos casos o certo é \`arquivar_memoria\`, não isto: arquivar tira do Brain ativo e guarda o conteúdo, porque o que a memória dizia pode voltar a importar. Apagar é para o que nunca deveria ter existido — a gravada por engano, a duplicata, o teste.
+
+DUAS ETAPAS. Chame primeiro SEM \`confirmacao\`: a resposta diz o que a cascata levaria junto e qual palavra digitar. Leve isso ao humano e só chame de novo com a confirmação se ele disser para apagar. Nunca invente a confirmação para pular a pergunta — a etapa existe para que uma pessoa veja o custo antes.`,
+        inputSchema: z.object({
+            endereco: z.string().min(1).describe("`<pasta>/<slug>` da memória."),
+            confirmacao: z
+                .string()
+                .optional()
+                .describe("O nome do espaço, exatamente como a primeira chamada informou. Só mande depois de o humano confirmar."),
+        }),
+    }, async ({ endereco, confirmacao }) => {
+        try {
+            const r = await apaga(raiz, endereco, confirmacao);
+            if (!r.apagou) {
+                return texto(`${r.detalhe}` +
+                    (r.confirmacaoEsperada
+                        ? `
+
+Pergunte ao humano antes de seguir. Se ele confirmar, repita com ` +
+                            `\`confirmacao: "${r.confirmacaoEsperada}"\`.`
+                        : ""));
+            }
+            return texto(`\`${endereco}\` apagada — ${r.detalhe}`);
+        }
+        catch (erro) {
+            return falha(erro);
+        }
+    });
     server.registerTool("criar_projeto", {
         description: `Cria um projeto no serviço — o espaço onde as pastas e memórias deste repositório vão morar.
 

package/package.json

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