dd-harness 0.26.0 → 0.27.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, 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";
@@ -439,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());

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,15 @@
+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 `como-desenvolver`, foi decisao — e recria-la a cada
+ * `start` desfaria a decisao em silencio, toda vez.
+ */
+export type SkillInicial = NovaSkillInicial;
+export declare const SKILLS_INICIAIS: SkillInicial[];

package/dist/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/package.json

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