dd-harness 0.1.0 → 0.1.3

package/LICENSE

@@ -1,11 +1,11 @@
-Copyright (c) 2026 Diego Dias
-
-Todos os direitos reservados.
-
-Este software é publicado no registro npm apenas para distribuição ao seu autor e a
-quem ele autorizar expressamente. Nenhuma permissão de uso, cópia, modificação,
-distribuição ou criação de obras derivadas é concedida por esta publicação.
-
-All rights reserved. This software is published to the npm registry for distribution
-to its author and to those he expressly authorizes. No permission to use, copy,
-modify, distribute, or create derivative works is granted by this publication.
+Copyright (c) 2026 Diego Dias
+
+Todos os direitos reservados.
+
+Este software é publicado no registro npm apenas para distribuição ao seu autor e a
+quem ele autorizar expressamente. Nenhuma permissão de uso, cópia, modificação,
+distribuição ou criação de obras derivadas é concedida por esta publicação.
+
+All rights reserved. This software is published to the npm registry for distribution
+to its author and to those he expressly authorizes. No permission to use, copy,
+modify, distribute, or create derivative works is granted by this publication.

package/README.md

@@ -1,64 +1,64 @@
-# dd-harness
-
-Materializa a **política**, o **briefing** e o **Brain** do
-[dd-harness](https://dd-harness.vercel.app) dentro do seu repositório, para que a sessão
-do agente de código abra já sabendo as regras e as decisões do projeto.
-
-Sem dependência: `fetch`, `crypto` e `fs` são do Node. Um CLI que vive pinado em
-repositório alheio precisa envelhecer bem, e cada dependência é uma chance de não
-envelhecer.
-
-## Instalação
-
-```sh
-npm install -g dd-harness
-```
-
-Ou sem instalar nada:
-
-```sh
-npx dd-harness sync
-```
-
-Requer Node 20 ou mais novo.
-
-## Uso
-
-```sh
-dd-harness init --tenant <espaço> --projeto <projeto>   # prepara o repositório
-dd-harness login --token <token>                        # credencial desta máquina
-dd-harness sync                                         # escreve os artefatos
-dd-harness check [--commit <sha>]                       # mede âncoras e reporta deriva
-dd-harness status                                       # só lê: o que espera julgamento
-```
-
-O token pessoal nasce na tela `/tokens` do serviço. Ele é guardado em
-`~/.dd-harness/credentials.json` (modo `0600`, por origem de API) — **fora** do
-repositório, para não viajar num commit.
-
-## O que aparece no seu repositório
-
-```
-.dd-harness.json      configuração (tenant, projeto, api) — escrita à mão
-CLAUDE.md             SEU arquivo; o sync nunca o reescreve
-dd-harness/           tudo o que é gerado
-  politica.md
-  BRIEFING.md
-  brain/
-  manifest.json
-```
-
-Na raiz fica apenas o **seu** `CLAUDE.md`, que importa a política com a linha
-`@dd-harness/politica.md`. Isso deixa conviverem a parte gerenciada e o que o
-repositório tem de próprio — adotar um projeto existente é acrescentar uma linha, não
-sobrescrever nada.
-
-O `sync` confere esse ponteiro a cada execução, inclusive quando o serviço não mudou:
-import quebrado ou linha ausente faz a sessão abrir **sem política e sem avisar**. Isso
-foi medido, não suposto.
-
-## Deriva
-
-`dd-harness check` mede as âncoras das memórias contra o estado real do repositório e
-reporta o que saiu do lugar. Com `--commit <sha>` ele também cruza as âncoras com o diff
-daquele commit — a memória volta ao code review. Nada bloqueia: avisa.
+# dd-harness
+
+Materializa a **política**, o **briefing** e o **Brain** do
+[dd-harness](https://dd-harness.vercel.app) dentro do seu repositório, para que a sessão
+do agente de código abra já sabendo as regras e as decisões do projeto.
+
+Sem dependência: `fetch`, `crypto` e `fs` são do Node. Um CLI que vive pinado em
+repositório alheio precisa envelhecer bem, e cada dependência é uma chance de não
+envelhecer.
+
+## Instalação
+
+```sh
+npm install -g dd-harness
+```
+
+Ou sem instalar nada:
+
+```sh
+npx dd-harness sync
+```
+
+Requer Node 20 ou mais novo.
+
+## Uso
+
+```sh
+dd-harness init --tenant <espaço> --projeto <projeto>   # prepara o repositório
+dd-harness login --token <token>                        # credencial desta máquina
+dd-harness sync                                         # escreve os artefatos
+dd-harness check [--commit <sha>]                       # mede âncoras e reporta deriva
+dd-harness status                                       # só lê: o que espera julgamento
+```
+
+O token pessoal nasce na tela `/tokens` do serviço. Ele é guardado em
+`~/.dd-harness/credentials.json` (modo `0600`, por origem de API) — **fora** do
+repositório, para não viajar num commit.
+
+## O que aparece no seu repositório
+
+```
+.dd-harness.json      configuração (tenant, projeto, api) — escrita à mão
+CLAUDE.md             SEU arquivo; o sync nunca o reescreve
+dd-harness/           tudo o que é gerado
+  politica.md
+  BRIEFING.md
+  brain/
+  manifest.json
+```
+
+Na raiz fica apenas o **seu** `CLAUDE.md`, que importa a política com a linha
+`@dd-harness/politica.md`. Isso deixa conviverem a parte gerenciada e o que o
+repositório tem de próprio — adotar um projeto existente é acrescentar uma linha, não
+sobrescrever nada.
+
+O `sync` confere esse ponteiro a cada execução, inclusive quando o serviço não mudou:
+import quebrado ou linha ausente faz a sessão abrir **sem política e sem avisar**. Isso
+foi medido, não suposto.
+
+## Deriva
+
+`dd-harness check` mede as âncoras das memórias contra o estado real do repositório e
+reporta o que saiu do lugar. Com `--commit <sha>` ele também cruza as âncoras com o diff
+daquele commit — a memória volta ao code review. Nada bloqueia: avisa.

package/dist/buscar.js

@@ -0,0 +1,21 @@
+import { leConfigDoRepo, leToken } from "./config.js";
+export async function busca(raiz, consulta, limite) {
+    const config = await leConfigDoRepo(raiz);
+    const token = await leToken(config.api);
+    if (!token) {
+        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
+    }
+    const url = new URL(`${config.api}/api/v1/busca`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    url.searchParams.set("q", consulta);
+    if (limite)
+        url.searchParams.set("limite", String(limite));
+    const resposta = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+    if (!resposta.ok) {
+        const { erro } = (await resposta.json().catch(() => ({})));
+        throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
+    }
+    const lido = (await resposta.json());
+    return { semantica: lido.semantica, provedor: lido.provedor, achados: lido.resultados };
+}

package/dist/check.js

@@ -72,7 +72,7 @@ export async function check(raiz, commit) {
         ? memoriasTocadas(brain, await caminhosDoCommit(raiz, commit))
         : [];
     if (medicoes.length === 0) {
-        return { medidas: 0, ausentes: [], novas: 0, base: 0, jaAbertas: 0, tocadas };
+        return { medidas: 0, ausentes: [], novas: 0, base: 0, jaAbertas: 0, fechadas: 0, tocadas };
     }
     const envio = await fetch(`${config.api}/api/v1/deriva`, {
         method: "POST",
@@ -97,6 +97,7 @@ export async function check(raiz, commit) {
         novas: julgamento.novas,
         base: julgamento.base,
         jaAbertas: julgamento.ja_abertas,
+        fechadas: julgamento.fechadas ?? 0,
         tocadas,
     };
 }

package/dist/curar.js

@@ -0,0 +1,66 @@
+import { readFile } from "node:fs/promises";
+import { leConfigDoRepo, leToken } from "./config.js";
+import { interpreta } from "./gravar.js";
+/**
+ * Curadoria pelo agente: editar e arquivar.
+ *
+ * `gravar` sabia criar e mais nada. Uma memoria errada ficava errada, porque corrigir
+ * exigia abrir a interface — e o `CLAUDE.md` trata curadoria como obrigacao ("se
+ * encontrar uma memoria obsoleta ou errada, corrija").
+ *
+ * Editar reaproveita o mesmo markdown de `gravar`, de proposito: o agente edita o arquivo
+ * que o `sync` materializou e manda de volta. Um formato so para as duas operacoes, e o
+ * que ele ja sabe ler.
+ */
+async function credencial(raiz) {
+    const config = await leConfigDoRepo(raiz);
+    const token = await leToken(config.api);
+    if (!token) {
+        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
+    }
+    return { config, token };
+}
+async function recusa(resposta) {
+    const { erro } = (await resposta.json().catch(() => ({})));
+    throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
+}
+export async function edita(raiz, caminho) {
+    const { config, token } = await credencial(raiz);
+    const memoria = interpreta(await readFile(caminho, "utf8"));
+    const endereco = `${memoria.pasta}/${memoria.slug}`;
+    const resposta = await fetch(`${config.api}/api/v1/memorias/${endereco}`, {
+        method: "PATCH",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            titulo: memoria.titulo,
+            resumo: memoria.resumo,
+            corpo: memoria.corpo,
+            dano: memoria.dano,
+            invisibilidade: memoria.invisibilidade,
+            externalidade: memoria.externalidade,
+            ancoras: memoria.ancoras,
+        }),
+    });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return { endereco, ancoras: memoria.ancoras.length };
+}
+export async function arquiva(raiz, endereco, opcoes) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await fetch(`${config.api}/api/v1/memorias/${endereco}`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            motivo: opcoes.motivo,
+            ...(opcoes.substituidaPor ? { substituida_por: opcoes.substituidaPor } : {}),
+        }),
+    });
+    if (!resposta.ok)
+        await recusa(resposta);
+    const lido = (await resposta.json());
+    return lido;
+}

package/dist/gravar.js

@@ -0,0 +1,111 @@
+import { readFile } from "node:fs/promises";
+import { leConfigDoRepo, leToken } from "./config.js";
+const OBRIGATORIOS = ["name", "titulo", "description", "pasta"];
+/** Frontmatter simples: `chave: valor` por linha. Sem lib de YAML — nao ha aninhamento. */
+function leFrontmatter(texto) {
+    const linhas = texto.replace(/\r\n/g, "\n").split("\n");
+    if (linhas[0]?.trim() !== "---") {
+        throw new Error("o arquivo precisa começar com `---` e um frontmatter.");
+    }
+    const fim = linhas.indexOf("---", 1);
+    if (fim === -1)
+        throw new Error("frontmatter sem `---` de fechamento.");
+    const campos = new Map();
+    for (const linha of linhas.slice(1, fim)) {
+        const corte = linha.indexOf(":");
+        if (corte === -1)
+            continue;
+        campos.set(linha.slice(0, corte).trim(), linha.slice(corte + 1).trim());
+    }
+    return { campos, resto: linhas.slice(fim + 1).join("\n") };
+}
+/** `**Dano:** texto` — devolve o texto, sem o rotulo. */
+function filtro(corpo, rotulo) {
+    const achado = corpo.match(new RegExp(`\\*\\*${rotulo}:\\*\\*\\s*([\\s\\S]*?)(?=\\n\\s*\\n\\*\\*|\\n## |$)`, "i"));
+    const valor = achado?.[1]?.trim() ?? "";
+    if (!valor)
+        throw new Error(`falta o filtro **${rotulo}:** no arquivo.`);
+    return valor;
+}
+/** Itens de lista da secao de ancoras, com ou sem crase em volta. */
+function ancorasDe(texto) {
+    const secao = texto.split(/\n##\s+[ÂA]ncoras\s*\n/i)[1];
+    if (!secao)
+        return [];
+    return secao
+        .split("\n")
+        .map((l) => l.match(/^\s*[-*]\s+(.+?)\s*$/)?.[1])
+        .filter((v) => Boolean(v))
+        .map((v) => v.replace(/^`|`$/g, "").trim())
+        .filter(Boolean);
+}
+export function interpreta(texto) {
+    const { campos, resto } = leFrontmatter(texto);
+    for (const chave of OBRIGATORIOS) {
+        if (!campos.get(chave))
+            throw new Error(`frontmatter sem \`${chave}\`.`);
+    }
+    // O corpo vai ate a secao dos filtros; dali para baixo e metadado, nao conteudo.
+    const corte = resto.search(/\n##\s+Os tr[êe]s filtros\s*\n/i);
+    if (corte === -1)
+        throw new Error("falta a seção `## Os três filtros`.");
+    const corpo = resto
+        .slice(0, corte)
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .trim();
+    if (!corpo)
+        throw new Error("o corpo da memória está vazio.");
+    const cauda = resto.slice(corte);
+    const tambem = campos.get("projetos") ?? "";
+    return {
+        slug: campos.get("name"),
+        titulo: campos.get("titulo"),
+        resumo: campos.get("description"),
+        pasta: campos.get("pasta"),
+        corpo,
+        dano: filtro(cauda, "Dano"),
+        invisibilidade: filtro(cauda, "Invisibilidade"),
+        externalidade: filtro(cauda, "Externalidade"),
+        ancoras: ancorasDe(cauda),
+        tambemEm: tambem
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+    };
+}
+export async function grava(raiz, caminho) {
+    const config = await leConfigDoRepo(raiz);
+    const token = await leToken(config.api);
+    if (!token) {
+        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
+    }
+    const memoria = interpreta(await readFile(caminho, "utf8"));
+    const resposta = await fetch(`${config.api}/api/v1/memorias`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            pasta: memoria.pasta,
+            slug: memoria.slug,
+            titulo: memoria.titulo,
+            resumo: memoria.resumo,
+            corpo: memoria.corpo,
+            dano: memoria.dano,
+            invisibilidade: memoria.invisibilidade,
+            externalidade: memoria.externalidade,
+            ancoras: memoria.ancoras,
+            tambem_em: memoria.tambemEm,
+        }),
+    });
+    if (!resposta.ok) {
+        const { erro } = (await resposta.json().catch(() => ({})));
+        throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
+    }
+    const { endereco } = (await resposta.json());
+    return {
+        endereco,
+        ancoras: memoria.ancoras.length,
+        projetos: 1 + memoria.tambemEm.length,
+    };
+}

package/dist/index.js

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 import { check, status } from "./check.js";
 import { leConfigDoRepo, guardaToken } from "./config.js";
+import { grava } from "./gravar.js";
 import { init } from "./init.js";
 import { LINHA_DE_IMPORT } from "./materializa.js";
+import { busca } from "./buscar.js";
+import { arquiva, edita } from "./curar.js";
+import { criaPasta } from "./pasta.js";
 import { sync } from "./sync.js";
 /**
  * `dd-harness` — o cliente que materializa os artefatos no repositorio.
@@ -12,23 +16,44 @@ import { sync } from "./sync.js";
  * em repositorio alheio tem que envelhecer bem, e cada dependencia e uma chance de nao
  * envelhecer.
  */
-const AJUDA = `dd-harness — materializa política, briefing e Brain no repositório
-
-  dd-harness init --tenant <t> --projeto <p> [--api <url>]
-                                     prepara o repositório (config + CLAUDE.md)
-  dd-harness login --token <token>   guarda a credencial desta máquina
-  dd-harness sync                    escreve os artefatos em disco
-  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
-  dd-harness status                  só lê: o que espera julgamento
-  dd-harness --help
-
-O gerado vive em dd-harness/. Na raiz fica só o seu CLAUDE.md, que importa a
-política com a linha ${LINHA_DE_IMPORT}
+const AJUDA = `dd-harness — materializa política, briefing e Brain no repositório
+
+  dd-harness init --tenant <t> --projeto <p> [--api <url>]
+                                     prepara o repositório (config + CLAUDE.md)
+  dd-harness login --token <token>   guarda a credencial desta máquina
+  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
+                                     cria a pasta que o gravar exige
+  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
+  dd-harness editar <arquivo.md>     corrige o que já está gravado
+  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
+                     [--substituida-por <pasta>/<slug>]
+                                     tira de circulação sem apagar
+  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
+  dd-harness sync                    escreve os artefatos em disco
+  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
+  dd-harness status                  só lê: o que espera julgamento
+  dd-harness --help
+
+O gerado vive em dd-harness/. Na raiz fica só o seu CLAUDE.md, que importa a
+política com a linha ${LINHA_DE_IMPORT}
 `;
 /** O aviso existe porque o import falha em silêncio — foi medido, não suposto. */
 function avisaSobreOPonteiro(ponteiro) {
     if (ponteiro === "ok" || ponteiro === "sem-politica")
         return;
+    // O import pendurado e o inverso dos outros dois: a linha esta la, o alvo e que nao
+    // existe. Dizer "acrescente a linha" aqui mandaria a pessoa para o lugar errado.
+    if (ponteiro === "aponta-para-o-vazio") {
+        console.error([
+            "",
+            `AVISO: o CLAUDE.md importa ${LINHA_DE_IMPORT}, mas não há política no serviço.`,
+            "O arquivo apontado não existe, e import quebrado falha em silêncio: a sessão abre",
+            "sem protocolo e nada avisa.",
+            "",
+            "Escreva a política do projeto no serviço, ou tire a linha do CLAUDE.md.",
+        ].join("\n"));
+        return;
+    }
     const motivo = ponteiro === "sem-claude-md"
         ? "não há CLAUDE.md na raiz"
         : "o CLAUDE.md da raiz não importa a política";
@@ -47,17 +72,17 @@ function avisaSobreOPonteiro(ponteiro) {
  * nosso: escrever la dentro sem a pessoa pedir e o mesmo tipo de invasao que
  * sobrescrever o CLAUDE.md dela. Quem cola, decide.
  */
-const GANCHOS = `
-Opcional — dois ganchos que valem a pena:
-
-  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
-    #!/bin/sh
-    dd-harness check --commit "$(git rev-parse HEAD)" || true
-
-  .claude/settings.json    (na abertura da sessão, o que espera julgamento)
-    "hooks": { "SessionStart": [{ "hooks": [{ "type": "command",
-      "command": "dd-harness status" }] }] }
-
+const GANCHOS = `
+Opcional — dois ganchos que valem a pena:
+
+  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
+    #!/bin/sh
+    dd-harness check --commit "$(git rev-parse HEAD)" || true
+
+  .claude/settings.json    (na abertura da sessão, o que espera julgamento)
+    "hooks": { "SessionStart": [{ "hooks": [{ "type": "command",
+      "command": "dd-harness status" }] }] }
+
 Os dois terminam em sucesso mesmo com deriva: avisam, não bloqueiam.`;
 function argumento(argv, nome) {
     const i = argv.indexOf(`--${nome}`);
@@ -90,6 +115,57 @@ async function comandoLogin(argv) {
     const caminho = await guardaToken(config.api, token);
     console.log(`credencial de ${config.api} guardada em ${caminho}`);
 }
+async function comandoEditar(argv) {
+    const caminho = argv[0];
+    if (!caminho || caminho.startsWith("-")) {
+        throw new Error("uso: dd-harness editar <arquivo.md>");
+    }
+    const r = await edita(process.cwd(), caminho);
+    console.log(`editado  ${r.endereco}`);
+    console.log(`  ${r.ancoras} âncora(s). Rode \`dd-harness sync\` para materializar.`);
+}
+const MOTIVOS = ["obsoleta", "incorreta", "fora_dos_filtros"];
+async function comandoArquivar(argv) {
+    const endereco = argv[0];
+    const motivo = argumento(argv, "motivo");
+    if (!endereco || endereco.startsWith("-") || !endereco.includes("/")) {
+        throw new Error("uso: dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>");
+    }
+    // Lista fechada tambem no cliente: errar o motivo aqui devolve a lista, em vez de um
+    // 400 do servidor com a mesma informacao mais longe de quem digitou.
+    if (!motivo || !MOTIVOS.includes(motivo)) {
+        throw new Error(`--motivo precisa ser um de: ${MOTIVOS.join(", ")}`);
+    }
+    const r = await arquiva(process.cwd(), endereco, {
+        motivo: motivo,
+        substituidaPor: argumento(argv, "substituida-por"),
+    });
+    console.log(`arquivado  ${r.endereco} (${r.motivo})`);
+    console.log("  foi para o histórico, não foi apagada. Rode `dd-harness sync`.");
+}
+async function comandoBuscar(argv) {
+    const consulta = argv.filter((a) => !a.startsWith("--")).join(" ").trim();
+    if (!consulta)
+        throw new Error('uso: dd-harness buscar "<pergunta>"');
+    const limite = Number(argumento(argv, "limite")) || undefined;
+    const r = await busca(process.cwd(), consulta, limite);
+    if (!r.achados.length) {
+        console.log("nada encontrado.");
+        // Sem esta linha, "nada encontrado" vira "nao existe" — quando pode ser so a
+        // semantica desligada, e a memoria estar la com outras palavras.
+        if (!r.semantica) {
+            console.log("  (só busca textual: sem provedor de embedding no serviço)");
+        }
+        return;
+    }
+    console.log(r.semantica
+        ? `${r.achados.length} resultado(s) — busca híbrida (${r.provedor}):`
+        : `${r.achados.length} resultado(s) — só textual, sem semântica:`);
+    for (const a of r.achados) {
+        console.log(`  ${a.endereco} — ${a.titulo}`);
+        console.log(`    ${a.resumo}`);
+    }
+}
 async function comandoSync() {
     const resultado = await sync(process.cwd());
     if (resultado.tipo === "editado-a-mao") {
@@ -142,7 +218,12 @@ async function comandoCheck(argv) {
     if (r.jaAbertas > 0) {
         console.log(`${r.jaAbertas} já estava(m) aberta(s) — nada novo, só o carimbo.`);
     }
-    if (!r.ausentes.length && r.novas === 0 && r.jaAbertas === 0) {
+    // Reverter uma mudanca fecha a observacao que ela abriu. Anunciar isso importa: sem a
+    // linha, a fila encolhe sem explicacao e quem olha o `status` acha que perdeu algo.
+    if (r.fechadas > 0) {
+        console.log(`${r.fechadas} deriva(s) fechada(s): o alvo voltou a bater com a linha de base.`);
+    }
+    if (!r.ausentes.length && r.novas === 0 && r.jaAbertas === 0 && r.fechadas === 0) {
         console.log("nenhuma deriva: o mundo ainda bate com o que as memórias dizem.");
     }
     // O cruzamento com o diff e outra coisa que deriva: e "voce acabou de mexer no que
@@ -177,6 +258,33 @@ async function comandoStatus() {
             console.log(`  ${m.pasta}/${m.memoria} — ${m.titulo}`);
     }
 }
+async function comandoPasta(argv) {
+    const slug = argv[0];
+    const definicao = argumento(argv, "definicao");
+    if (!slug || slug.startsWith("-") || !definicao) {
+        throw new Error('uso: dd-harness pasta <slug> --definicao "o que entra e o que não entra"');
+    }
+    const r = await criaPasta(process.cwd(), slug, definicao);
+    console.log(r.jaExistia
+        ? `pasta ${r.pasta} já existia — nada criado.`
+        : `criada  pasta ${r.pasta}. Agora \`dd-harness gravar <arquivo.md>\` aceita \`pasta: ${r.pasta}\`.`);
+}
+/**
+ * O agente escreve o arquivo — que e o que ele ja fazia no modelo file-based — e este
+ * comando o transforma em requisicao. O arquivo nao fica no repositorio: quem
+ * materializa e o `sync`, a partir do servico, para nao existir copia escrita a mao ao
+ * lado da copia gerada.
+ */
+async function comandoGravar(argv) {
+    const caminho = argv[0];
+    if (!caminho || caminho.startsWith("-")) {
+        throw new Error("uso: dd-harness gravar <arquivo.md>");
+    }
+    const r = await grava(process.cwd(), caminho);
+    console.log(`gravado  ${r.endereco}`);
+    console.log(`  ${r.ancoras} âncora(s), valendo para ${r.projetos} projeto(s).` +
+        " Rode `dd-harness sync` para materializar.");
+}
 async function principal() {
     const [comando, ...resto] = process.argv.slice(2);
     switch (comando) {
@@ -184,6 +292,16 @@ async function principal() {
             return comandoInit(resto);
         case "login":
             return comandoLogin(resto);
+        case "pasta":
+            return comandoPasta(resto);
+        case "gravar":
+            return comandoGravar(resto);
+        case "editar":
+            return comandoEditar(resto);
+        case "arquivar":
+            return comandoArquivar(resto);
+        case "buscar":
+            return comandoBuscar(resto);
         case "sync":
             return comandoSync();
         case "check":

package/dist/init.js

@@ -10,12 +10,12 @@ import { LINHA_DE_IMPORT } from "./materializa.js";
  * acrescenta a linha ao que voce escreveu, sem tocar no resto. Adotar um projeto vira
  * uma linha, e nao um ritual de mover arquivo.
  */
-const CABECALHO = `# CLAUDE.md
-
-Este arquivo é seu: escreva aqui o que for específico deste repositório.
-
-A linha abaixo importa a política gerenciada pelo dd-harness. **Não a remova** — sem
-ela a sessão abre sem protocolo, e nada avisa.
+const CABECALHO = `# CLAUDE.md
+
+Este arquivo é seu: escreva aqui o que for específico deste repositório.
+
+A linha abaixo importa a política gerenciada pelo dd-harness. **Não a remova** — sem
+ela a sessão abre sem protocolo, e nada avisa.
 `;
 export async function init(raiz, dados) {
     const caminhoConfig = join(raiz, CAMINHO_CONFIG);

package/dist/materializa.js

@@ -54,12 +54,19 @@ export function arquivoDoIndice(brain) {
     const ativas = brain.memorias.filter((m) => m.status === "ativa");
     const historico = brain.memorias.filter((m) => m.status === "historico");
     const linha = (m) => `- [${m.titulo}](${m.pasta}/${m.slug}.md) — ${m.resumo.replace(/\n/g, " ")}`;
-    const secoes = brain.pastas
-        .map((pasta) => {
-        const memorias = ativas.filter((m) => m.pasta === pasta.slug);
+    // O indice e montado pelas pastas, mas quem manda e a memoria: pasta que so aparece no
+    // `pasta:` de uma memoria tambem vira secao. Sem isso a memoria fica em disco e fora do
+    // indice — arquivo presente que nenhum agente encontra, que e a mesma falha silenciosa
+    // do import quebrado.
+    const definicoes = new Map(brain.pastas.map((p) => [p.slug, p.definicao]));
+    const slugs = [...new Set([...definicoes.keys(), ...ativas.map((m) => m.pasta)])].sort();
+    const secoes = slugs
+        .map((slug) => {
+        const memorias = ativas.filter((m) => m.pasta === slug);
+        const definicao = definicoes.get(slug);
         return [
-            `## ${pasta.slug}`,
-            `<!-- ${pasta.definicao} -->`,
+            `## ${slug}`,
+            `<!-- ${definicao ?? "(definição não veio do serviço)"} -->`,
             ...(memorias.length ? memorias.map(linha) : ["<!-- (vazia) -->"]),
         ].join("\n");
     })

package/dist/pasta.js

@@ -0,0 +1,36 @@
+import { leConfigDoRepo, leToken } from "./config.js";
+/**
+ * `dd-harness pasta <slug> --definicao "..."` — cria a pasta sem sair da sessao.
+ *
+ * `gravar` recusa quando a pasta nao existe, e essa recusa e boa: e ela que impede um
+ * typo no `pasta:` de virar pasta nova em silencio. O que faltava era a saida — ate aqui
+ * o agente parava e pedia que alguem abrisse o navegador.
+ */
+export async function criaPasta(raiz, slug, definicao) {
+    const config = await leConfigDoRepo(raiz);
+    const token = await leToken(config.api);
+    if (!token) {
+        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
+    }
+    const resposta = await fetch(`${config.api}/api/v1/pastas`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            slug,
+            definicao,
+        }),
+    });
+    // Pasta que ja existe nao e falha para quem chamou: o estado desejado ja vale. Vale
+    // dizer que ja existia — quem pediu pode estar corrigindo um typo e precisa saber que
+    // nao criou nada.
+    if (resposta.status === 409)
+        return { pasta: slug, jaExistia: true };
+    if (!resposta.ok) {
+        const { erro } = (await resposta.json().catch(() => ({})));
+        throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
+    }
+    const { pasta } = (await resposta.json());
+    return { pasta, jaExistia: false };
+}

package/dist/sync.js

@@ -57,16 +57,19 @@ async function buscaBrain(config, token, etag) {
 /**
  * O `CLAUDE.md` da raiz existe e importa a politica?
  *
- * Nao ha politica no servico? Entao nao ha o que apontar, e a ausencia do ponteiro nao e
- * problema — avisar aqui seria ruido que ensina a ignorar aviso.
+ * Sem politica no servico E sem a linha, nao ha o que apontar nem o que avisar — avisar
+ * ai seria ruido que ensina a ignorar aviso. Mas com a linha escrita e a politica vazia o
+ * import esta pendurado de verdade, e esse e o silencio que a memoria
+ * `import-do-claude-md-falha-calado` manda quebrar.
  */
 export async function confereOPonteiro(raiz, temPolitica) {
-    if (!temPolitica)
-        return "sem-politica";
     const claudeMd = await leSeExistir(join(raiz, "CLAUDE.md"));
+    const temALinha = claudeMd?.includes(LINHA_DE_IMPORT) ?? false;
+    if (!temPolitica)
+        return temALinha ? "aponta-para-o-vazio" : "sem-politica";
     if (claudeMd === null)
         return "sem-claude-md";
-    return claudeMd.includes(LINHA_DE_IMPORT) ? "ok" : "sem-a-linha";
+    return temALinha ? "ok" : "sem-a-linha";
 }
 export async function sync(raiz) {
     const config = await leConfigDoRepo(raiz);

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "dd-harness",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "type": "module",
   "description": "Materializa politica, briefing e Brain do dd-harness no repositorio. Sem dependencia: fetch, crypto e fs sao do Node.",
   "license": "UNLICENSED",
   "author": "Diego Dias",
-  "keywords": ["claude-code", "ai-agents", "memory", "brain", "cli"],
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "memory",
+    "brain",
+    "cli"
+  ],
   "homepage": "https://dd-harness.vercel.app",
   "repository": {
     "type": "git",
@@ -15,7 +21,9 @@
   "bin": {
     "dd-harness": "dist/index.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "engines": {
     "node": ">=20"
   },