dd-harness 0.38.2 → 0.39.0

package/README.md

@@ -1,103 +1,103 @@
-# dd-harness
-
-Política e briefing carregados do serviço; memória consultada por MCP ou CLI.
-A fonte dos artefatos continua no serviço. O cliente mantém configuração, ponteiros
-para skills e estado descartável fora do repositório.
-
-Requer Node >=20.3.0. CLI sem dependências de runtime.
-
-## Instalação e configuração
-
-```sh
-npm install -g dd-harness@latest
-npx -y dd-harness-mcp@latest --help
-dd-harness start --host todos
-```
-
-Para um projeto já criado no serviço:
-
-```sh
-dd-harness init --tenant meu-espaco --projeto meu-projeto
-dd-harness login --token <token>
-dd-harness integrar --host claude,codex,antigravity
-dd-harness diagnostico --mcp
-```
-
-`start` usa Claude por padrão. `--host` aceita `claude`, `codex`,
-`antigravity`, uma lista separada por vírgulas ou `todos`.
-`integrar` instala nos três por padrão e preserva configurações alheias.
-O token nasce em /tokens e fica em ~/.dd-harness/credentials.json, por origem de API.
-Para serviço local, use `init --api http://localhost:3000` antes do login.
-
-## Hosts
-
-| Host | MCP | Boot e guarda | Skills |
-|---|---|---|---|
-| Claude Code | .mcp.json | .claude/settings.json | .claude/skills |
-| Codex | .codex/config.toml | .codex/hooks.json | .agents/skills |
-| Antigravity | .agents/mcp_config.json | .agents/hooks.json | .agents/skills |
-
-Codex exige revisão/confiança dos hooks em /hooks. Instalação não comprova ativação.
-Antigravity usa PreInvocation e mensagem efêmera: política e briefing são consultados
-antes de cada inferência. Sua guarda usa `ask` para respeitar concessões já existentes;
-ela pode acrescentar confirmações. Não amplia permissões automaticamente.
-
-Sem boot válido, a guarda recusa ferramentas cobertas, inclusive shell. Leitura conhecida
-e onboarding controlado continuam possíveis. Os hooks precisam estar ativos: não são
-sandbox nem controlam ferramentas que o aplicativo não encaminha a eles.
-Após boot válido, shell não tem análise de diff antecipada; avisos por âncora cobrem
-edições estruturadas, patches, remoções e renomeações.
-
-Configurações MCP novas levam DD_HARNESS_ROOT explícito. Ao copiar/mover um checkout,
-confira essa raiz com diagnostico. O MCP recusa divergência entre a raiz explícita e
-o projeto identificado no diretório de execução. Corrija a configuração e reinicie o host.
-
-## Uso diário
-
-```sh
-dd-harness politica
-dd-harness buscar "contrato de integração"
-dd-harness ler regras/contrato
-dd-harness gravar memoria.md
-dd-harness editar memoria.md
-dd-harness arquivar regras/contrato --motivo obsoleta
-dd-harness status
-dd-harness skills
-dd-harness roadmap
-dd-harness changelog
-dd-harness --help
-```
-
-`check` mede e grava observações de deriva; `status` só consulta.
-O antigo comando `sync` não faz parte do CLI atual.
-`politica --hook` e `cinto` permanecem como compatibilidade legada;
-use `integrar` para instalar `sessao` e `guarda`.
-
-## Estado e conflitos
-
-- Política/briefing não são materializados. Âncoras/resumos, sessão e manifestos ficam
-  em ~/.dd-harness/repos, isolados por caminho/projeto/credencial quando aplicável.
-- DD_HARNESS_HOME permite isolamento explícito em testes. Nunca aponte testes ao estado pessoal.
-- Uma sessão validada expira em quatro horas. Boot, retomada e compactação revalidam.
-  Alterações locais de política/briefing via MCP invalidam a sessão; reabra depois de editar.
-  Alterações remotas feitas por outro cliente são percebidas no próximo boot/revalidação.
-- Curadoria invalida as âncoras do checkout atual. A próxima edição as consulta novamente.
-- Só ponteiros registrados e intactos são atualizados/removidos. Skills manuais, editadas
-  ou redirecionadas por links são preservadas e aparecem como conflitos.
-- Skills marcadas só por comando não são instaladas para descoberta automática em
-  .agents; use listar_skills/ler_skill após pedido explícito. Metadados próprios do
-  Claude não são prometidos como portáveis.
-- Se há fila e worker local configurado, o boot solicita um lote. O log fica em
-  ~/.dd-harness/worker.log; solicitar não significa que a indexação concluiu.
-
-## Escritas e commits
-
-Só GET/HEAD têm retry automático (até três tentativas, timeout por tentativa).
-POST/PATCH/PUT/DELETE não são repetidos. Falha de conexão, 5xx ou resposta incompleta
-em escrita exige consultar o estado antes de tentar novamente.
-
-A política entregue exige `[IDENTIFICAÇÃO] - tipo: descrição` nos commits de agentes:
-`[CODEX] - feat: ...`, `[CLAUDE] - fix: ...`, `[GEMINI] - docs: ...`.
-Identifique quem realmente commitou, inclusive ao usar outro editor. A regra não altera
-Git author nem concede autorização de commit/push. É regra de trabalho do agente,
-não inferência automática de identidade nem hook que renomeia commits humanos.
+# dd-harness
+
+Política e briefing carregados do serviço; memória consultada por MCP ou CLI.
+A fonte dos artefatos continua no serviço. O cliente mantém configuração, ponteiros
+para skills e estado descartável fora do repositório.
+
+Requer Node >=20.3.0. CLI sem dependências de runtime.
+
+## Instalação e configuração
+
+```sh
+npm install -g dd-harness@latest
+npx -y dd-harness-mcp@latest --help
+dd-harness start --host todos
+```
+
+Para um projeto já criado no serviço:
+
+```sh
+dd-harness init --tenant meu-espaco --projeto meu-projeto
+dd-harness login --token <token>
+dd-harness integrar --host claude,codex,antigravity
+dd-harness diagnostico --mcp
+```
+
+`start` usa Claude por padrão. `--host` aceita `claude`, `codex`,
+`antigravity`, uma lista separada por vírgulas ou `todos`.
+`integrar` instala nos três por padrão e preserva configurações alheias.
+O token nasce em /tokens e fica em ~/.dd-harness/credentials.json, por origem de API.
+Para serviço local, use `init --api http://localhost:3000` antes do login.
+
+## Hosts
+
+| Host | MCP | Boot e guarda | Skills |
+|---|---|---|---|
+| Claude Code | .mcp.json | .claude/settings.json | .claude/skills |
+| Codex | .codex/config.toml | .codex/hooks.json | .agents/skills |
+| Antigravity | .agents/mcp_config.json | .agents/hooks.json | .agents/skills |
+
+Codex exige revisão/confiança dos hooks em /hooks. Instalação não comprova ativação.
+Antigravity usa PreInvocation e mensagem efêmera: política e briefing são consultados
+antes de cada inferência. Sua guarda usa `ask` para respeitar concessões já existentes;
+ela pode acrescentar confirmações. Não amplia permissões automaticamente.
+
+Sem boot válido, a guarda recusa ferramentas cobertas, inclusive shell. Leitura conhecida
+e onboarding controlado continuam possíveis. Os hooks precisam estar ativos: não são
+sandbox nem controlam ferramentas que o aplicativo não encaminha a eles.
+Após boot válido, shell não tem análise de diff antecipada; avisos por âncora cobrem
+edições estruturadas, patches, remoções e renomeações.
+
+Configurações MCP novas levam DD_HARNESS_ROOT explícito. Ao copiar/mover um checkout,
+confira essa raiz com diagnostico. O MCP recusa divergência entre a raiz explícita e
+o projeto identificado no diretório de execução. Corrija a configuração e reinicie o host.
+
+## Uso diário
+
+```sh
+dd-harness politica
+dd-harness buscar "contrato de integração"
+dd-harness ler regras/contrato
+dd-harness gravar memoria.md
+dd-harness editar memoria.md
+dd-harness arquivar regras/contrato --motivo obsoleta
+dd-harness status
+dd-harness skills
+dd-harness roadmap
+dd-harness changelog
+dd-harness --help
+```
+
+`check` mede e grava observações de deriva; `status` só consulta.
+O antigo comando `sync` não faz parte do CLI atual.
+`politica --hook` e `cinto` permanecem como compatibilidade legada;
+use `integrar` para instalar `sessao` e `guarda`.
+
+## Estado e conflitos
+
+- Política/briefing não são materializados. Âncoras/resumos, sessão e manifestos ficam
+  em ~/.dd-harness/repos, isolados por caminho/projeto/credencial quando aplicável.
+- DD_HARNESS_HOME permite isolamento explícito em testes. Nunca aponte testes ao estado pessoal.
+- Uma sessão validada expira em quatro horas. Boot, retomada e compactação revalidam.
+  Alterações locais de política/briefing via MCP invalidam a sessão; reabra depois de editar.
+  Alterações remotas feitas por outro cliente são percebidas no próximo boot/revalidação.
+- Curadoria invalida as âncoras do checkout atual. A próxima edição as consulta novamente.
+- Só ponteiros registrados e intactos são atualizados/removidos. Skills manuais, editadas
+  ou redirecionadas por links são preservadas e aparecem como conflitos.
+- Skills marcadas só por comando não são instaladas para descoberta automática em
+  .agents; use listar_skills/ler_skill após pedido explícito. Metadados próprios do
+  Claude não são prometidos como portáveis.
+- Se há fila e worker local configurado, o boot solicita um lote. O log fica em
+  ~/.dd-harness/worker.log; solicitar não significa que a indexação concluiu.
+
+## Escritas e commits
+
+Só GET/HEAD têm retry automático (até três tentativas, timeout por tentativa).
+POST/PATCH/PUT/DELETE não são repetidos. Falha de conexão, 5xx ou resposta incompleta
+em escrita exige consultar o estado antes de tentar novamente.
+
+A política entregue exige `[IDENTIFICAÇÃO] - tipo: descrição` nos commits de agentes:
+`[CODEX] - feat: ...`, `[CLAUDE] - fix: ...`, `[GEMINI] - docs: ...`.
+Identifique quem realmente commitou, inclusive ao usar outro editor. A regra não altera
+Git author nem concede autorização de commit/push. É regra de trabalho do agente,
+não inferência automática de identidade nem hook que renomeia commits humanos.

package/dist/artefato.d.ts

@@ -6,24 +6,29 @@
  * tenha escrito nela que o CLI existe — e era justamente ela que estava fora de alcance.
  */
 export type TipoDeArtefato = "politica" | "briefing";
+export declare function artefatoDoPayload(payload: Record<string, unknown>, tipo: TipoDeArtefato): {
+    conteudo: string;
+    existe: boolean;
+    atualizadaEm: string | null;
+};
 /**
  * O `GET` devolve o payload inteiro (politica, briefing, pastas e memorias); aqui so o
  * artefato pedido interessa.
  *
- * `null` e `""` significam a mesma coisa para quem le — "ainda nao existe" —, e a diferenca
- * entre elas e detalhe de como a linha foi parar no banco. Quem chama recebe `existe`, que
- * e a pergunta real.
+ * Conteúdo vazio ainda pode ser uma linha existente. A versão é o que distingue esse caso
+ * de um artefato que nunca foi criado e define qual precondição a próxima escrita envia.
  */
 export declare function leArtefato(raiz: string, tipo: TipoDeArtefato): Promise<{
     conteudo: string;
     existe: boolean;
+    atualizadaEm: string | null;
 }>;
 /**
  * Substituicao total, nao append: quem quer acrescentar um paragrafo le, concatena e
  * reenvia. Conteudo vazio e valido e significa "apagar" — a linha fica no banco, guardando
  * quem mexeu por ultimo.
  */
-export declare function escreveArtefato(raiz: string, tipo: TipoDeArtefato, conteudo: string): Promise<{
+export declare function escreveArtefato(raiz: string, tipo: TipoDeArtefato, conteudo: string, atualizadaEm: string | null): Promise<{
     artefato: string;
     criou: boolean;
     tamanho: number;

package/dist/artefato.js

@@ -1,12 +1,17 @@
 import { jsonDaEscrita, cabecalhos, credencial, pede, recusa } from "./api.js";
 import { invalidaContexto } from "./estado-local.js";
+export function artefatoDoPayload(payload, tipo) {
+    const conteudo = typeof payload[tipo] === "string" ? payload[tipo] : "";
+    const versoes = payload.artefatos_atualizados_em;
+    const atualizadaEm = typeof versoes?.[tipo] === "string" ? versoes[tipo] : null;
+    return { conteudo, existe: atualizadaEm !== null || conteudo.length > 0, atualizadaEm };
+}
 /**
  * O `GET` devolve o payload inteiro (politica, briefing, pastas e memorias); aqui so o
  * artefato pedido interessa.
  *
- * `null` e `""` significam a mesma coisa para quem le — "ainda nao existe" —, e a diferenca
- * entre elas e detalhe de como a linha foi parar no banco. Quem chama recebe `existe`, que
- * e a pergunta real.
+ * Conteúdo vazio ainda pode ser uma linha existente. A versão é o que distingue esse caso
+ * de um artefato que nunca foi criado e define qual precondição a próxima escrita envia.
  */
 export async function leArtefato(raiz, tipo) {
     const { config, token } = await credencial(raiz);
@@ -16,20 +21,23 @@ export async function leArtefato(raiz, tipo) {
     const resposta = await pede(url, { headers: cabecalhos(token) });
     if (!resposta.ok)
         await recusa(resposta);
-    const payload = (await resposta.json());
-    const conteudo = typeof payload[tipo] === "string" ? payload[tipo] : "";
-    return { conteudo, existe: conteudo.length > 0 };
+    return artefatoDoPayload((await resposta.json()), tipo);
 }
 /**
  * Substituicao total, nao append: quem quer acrescentar um paragrafo le, concatena e
  * reenvia. Conteudo vazio e valido e significa "apagar" — a linha fica no banco, guardando
  * quem mexeu por ultimo.
  */
-export async function escreveArtefato(raiz, tipo, conteudo) {
+export async function escreveArtefato(raiz, tipo, conteudo, atualizadaEm) {
     const { config, token } = await credencial(raiz);
     const resposta = await pede(`${config.api}/api/v1/artefatos`, {
         method: "PUT",
-        headers: cabecalhos(token, true),
+        headers: {
+            ...cabecalhos(token, true),
+            ...(atualizadaEm
+                ? { "If-Match": atualizadaEm }
+                : { "If-None-Match": "*" }),
+        },
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,

package/dist/brain.d.ts

@@ -11,21 +11,30 @@ export type Ancora = {
     valor: string;
     sha: string | null;
 };
+/**
+ * A memoria como o payload de sessao a entrega — o indice dela, nao o conteudo.
+ *
+ * Sem `corpo` e sem as tres justificativas de proposito: quem precisa do texto integral
+ * busca a memoria individual (`MemoriaDoServico`, em `curar.ts`), e e uma memoria por vez.
+ * Aqui vem TODAS as do projeto a cada abertura de sessao, entao cada campo custa
+ * multiplicado pelo acervo.
+ */
 export type Memoria = {
     pasta: string;
     slug: string;
     titulo: string;
     resumo: string;
-    corpo: string;
+    /**
+     * Sempre `"ativa"` desde que o payload passou a filtrar: as arquivadas viram a contagem
+     * `arquivadas` do `Brain`. O campo fica porque o cache local guarda memorias gravadas na
+     * propria sessao, e `acrescentaAoCache` decide por ele.
+     */
     status: "ativa" | "historico";
     /**
      * `global` = vale para todo projeto do tenant, inclusive os que ainda nao existem.
      * Ausente em payload antigo, e ai a memoria e de projeto — que era o unico escopo.
      */
     escopo?: "projeto" | "global";
-    dano: string;
-    invisibilidade: string;
-    externalidade: string;
     ancoras: Ancora[];
     revisar_ate: string | null;
     /** Observacoes de deriva esperando julgamento. Ausente em payload antigo. */
@@ -48,7 +57,14 @@ export type Brain = {
         slug: string;
         definicao: string;
     }[];
+    /** So as ativas. As arquivadas nao vem na lista — viram o numero `arquivadas`. */
     memorias: Memoria[];
+    /**
+     * Quantas memorias arquivadas o projeto tem. Ausente em payload antigo, e ai o `check`
+     * cai para o calculo velho (lista inteira menos ativas), que dava o mesmo resultado
+     * quando a lista ainda trazia as duas.
+     */
+    arquivadas?: number;
     /**
      * Memorias que excederam as tentativas de indexacao e nao serao mais tentadas. Ficam
      * sem embedding — somem da busca semantica — e so este numero denuncia.

package/dist/check.js

@@ -2,6 +2,7 @@ import { pede } from "./api.js";
 import { leConfigDoRepo, leToken } from "./config.js";
 import { caminhosDoCommit, memoriasTocadas, sugereReancoragem, } from "./diff.js";
 import { mede } from "./medir.js";
+import { corpoComCache, leCacheDoPayload } from "./payload-cache.js";
 /** Separado do IO para poder ser testado sem rede: dado um Brain, o que se mede. */
 export async function medeAsAncoras(raiz, brain) {
     const medicoes = [];
@@ -30,16 +31,27 @@ async function buscaOBrain(raiz) {
         throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
     }
     const parametros = `tenant=${encodeURIComponent(config.tenant)}&projeto=${encodeURIComponent(config.projeto)}`;
+    // Mesmo ETag do hook de sessao: `check` e `status` leem o mesmo payload, e rodar os dois
+    // em sequencia (o que a abertura de sessao faz) nao precisa baixar o acervo duas vezes.
+    const cache = await leCacheDoPayload(raiz);
     const resposta = await pede(`${config.api}/api/v1/artefatos?${parametros}`, {
-        headers: { Authorization: `Bearer ${token}` },
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(cache ? { "If-None-Match": cache.etag } : {}),
+        },
     });
     if (resposta.status === 401) {
         throw new Error("token recusado. Rode `dd-harness login --token <token>`.");
     }
-    if (!resposta.ok) {
+    // `304` nao e `ok`, mas e o caminho feliz: o corpo vem do cache logo abaixo.
+    if (!resposta.ok && resposta.status !== 304) {
         throw new Error(`a API respondeu ${resposta.status} ao buscar as âncoras.`);
     }
-    return { config, token, brain: (await resposta.json()) };
+    const corpo = await corpoComCache(raiz, resposta, cache);
+    if (corpo === null) {
+        throw new Error("o cache local do payload sumiu; rode de novo.");
+    }
+    return { config, token, brain: JSON.parse(corpo) };
 }
 /**
  * Somente leitura, de proposito: e o que roda na ABERTURA da sessao. Medir e reportar
@@ -56,7 +68,9 @@ export async function status(raiz) {
     return {
         acervo: {
             ativas: ativas.length,
-            arquivadas: brain.memorias.length - ativas.length,
+            // O servico manda o numero pronto, porque a lista so traz ativas. O `??` cobre
+            // servico antigo, cujo payload ainda misturava as duas — ali a subtracao valia.
+            arquivadas: brain.arquivadas ?? brain.memorias.length - ativas.length,
             porPasta: [...porPasta]
                 .map(([pasta, quantas]) => ({ pasta, quantas }))
                 .sort((a, b) => a.pasta.localeCompare(b.pasta)),

package/dist/curar.d.ts

@@ -20,6 +20,11 @@ export type MemoriaDoServico = {
     invisibilidade: string;
     externalidade: string;
     revisar_ate: string | null;
+    /**
+     * O carimbo de versão que o PATCH exige como `If-Match`. O tipo continua opcional para
+     * reconhecer uma leitura de serviço antigo e recusá-la com uma mensagem útil.
+     */
+    atualizada_em?: string;
     ancoras: {
         tipo: string;
         valor: string;
@@ -73,7 +78,7 @@ export declare function promove(raiz: string, endereco: string, global: boolean)
  * 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
+ * entao se repete a chamada com a frase de confirmação devolvida. Duas etapas de proposito: DELETE nao
  * tem desfazer, e a cascata e invisivel de fora.
  */
 export declare function apaga(raiz: string, endereco: string, confirmacao?: string): Promise<{

package/dist/curar.js

@@ -30,6 +30,7 @@ export function comoMarkdown(m) {
         `titulo: ${m.titulo}`,
         `description: ${m.resumo}`,
         `pasta: ${m.pasta}`,
+        ...(m.atualizada_em ? [`atualizada-em: ${m.atualizada_em}`] : []),
         ...(m.revisar_ate ? [`revisar-ate: ${m.revisar_ate.slice(0, 10)}`] : []),
         // So aparece quando ha vinculo — omitir e "so este projeto", igual a `gravar` sem
         // `projetos:`. Formato inline (`a, b`), que e o que `interpreta` ja sabe ler.
@@ -53,9 +54,12 @@ export async function edita(raiz, caminho) {
     const cru = await readFile(caminho, "utf8");
     const memoria = interpreta(cru);
     const endereco = `${memoria.pasta}/${memoria.slug}`;
+    if (!memoria.atualizadaEm) {
+        throw new Error("a edição precisa partir de `dd-harness ler`: falta `atualizada-em` no frontmatter.");
+    }
     const resposta = await pede(`${config.api}/api/v1/memorias/${endereco}`, {
         method: "PATCH",
-        headers: cabecalhos(token, true),
+        headers: { ...cabecalhos(token, true), "If-Match": memoria.atualizadaEm },
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,
@@ -121,7 +125,7 @@ export async function promove(raiz, endereco, global) {
  * 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
+ * entao se repete a chamada com a frase de confirmação devolvida. Duas etapas de proposito: DELETE nao
  * tem desfazer, e a cascata e invisivel de fora.
  */
 export async function apaga(raiz, endereco, confirmacao) {

package/dist/escreve-config.js

@@ -140,28 +140,28 @@ export const escreveAgents = (raiz) => escrevePonteiro(raiz, "AGENTS.md");
  * em producao compara para saber se precisa de atualizacao.
  */
 export const VERSAO_DO_MOLDE = "v1.3.0";
-export const SUGESTAO_AGENTS = `## Protocolo do dd-harness
-
-Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
-
-**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
-\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
-de ler código, responder ou planejar.
-
-- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
-  avise o usuário e **não modifique nada** até ele resolver.
-- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
-
-Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
-
-Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
-desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
-válido — não crie fase sem o usuário pedir.
-
-E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
-ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
-já saiu errado, e é tarde.
-
-Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
-frase que antecede pular o procedimento. A política diz quais são obrigatórias
+export const SUGESTAO_AGENTS = `## Protocolo do dd-harness
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  avise o usuário e **não modifique nada** até ele resolver.
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
+
+Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
+desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
+válido — não crie fase sem o usuário pedir.
+
+E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
+ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
+já saiu errado, e é tarde.
+
+Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
+frase que antecede pular o procedimento. A política diz quais são obrigatórias
 e quando.`;

package/dist/gravar.d.ts

@@ -24,6 +24,7 @@ export type MemoriaLida = {
      * vinculo transversal por omissao.
      */
     tambemEmInformado: boolean;
+    atualizadaEm?: string;
 };
 export declare function interpreta(texto: string): MemoriaLida;
 export declare function grava(raiz: string, caminho: string): Promise<{

package/dist/gravar.js

@@ -163,6 +163,7 @@ export function interpreta(texto) {
             .map((s) => s.trim())
             .filter(Boolean),
         tambemEmInformado: campos.has("projetos"),
+        atualizadaEm: campos.get("atualizada-em") || undefined,
     };
 }
 export async function grava(raiz, caminho) {

package/dist/index.js

@@ -80,7 +80,7 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
                                      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>]
+  dd-harness apagar <pasta>/<slug> [--confirmar "<frase devolvida>"]
                                      apaga de vez, em cascata — sem desfazer.
                                      Para tirar de circulação guardando o
                                      conteúdo, use "arquivar"
@@ -691,21 +691,21 @@ async function comandoPromover(argv, global) {
 /**
  * `apagar` — o unico caminho que destroi.
  *
- * Duas etapas, e a segunda pede o nome do espaco digitado. Nao e cerimonia: a cascata leva
+ * Duas etapas, e a segunda pede a frase vinculada à versão atual. 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>]");
+        throw new Error('uso: dd-harness apagar <pasta>/<slug> [--confirmar "<frase devolvida>"]');
     }
     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}`);
+  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.