dd-harness 0.17.0 → 0.19.0

package/dist/escreve-config.js

@@ -107,4 +107,8 @@ 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.`;
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+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.`;

package/dist/index.js

@@ -19,7 +19,7 @@ import { grava } from "./gravar.js";
 import { init, SUGESTAO_AGENTS, SUGESTAO_HOOK, SUGESTAO_MCP } from "./init.js";
 import { pergunta, escolha, fechaPerguntas } from "./pergunta.js";
 import { buscaPolitica } from "./politica.js";
-import { blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
+import { avisoDeOrdem, blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
 import { busca } from "./buscar.js";
 import { arquiva, edita, le } from "./curar.js";
 import { criaPasta } from "./pasta.js";
@@ -155,7 +155,7 @@ async function comandoFase(argv) {
             throw new Error("fase editar exige o slug da fase.");
         const ordemBruta = argumento(opcoes, "ordem");
         const status = statusDoArgv(opcoes);
-        const { fase } = await editaFase(process.cwd(), slug, {
+        const { fase, atras_de } = await editaFase(process.cwd(), slug, {
             titulo: argumento(opcoes, "titulo"),
             conteudo: await conteudoDoArgv(opcoes),
             versao: opcoes.includes("--sem-versao") ? null : argumento(opcoes, "versao"),
@@ -165,7 +165,8 @@ async function comandoFase(argv) {
         console.log(`Fase ${fase.slug} atualizada — ${fase.status}` +
             (fase.versao ? `, versão ${fase.versao}` : "") +
             (status === "concluida" ? " (saiu do roadmap, entrou no changelog)" : "") +
-            ".");
+            "." +
+            avisoDeOrdem(fase, atras_de, ordemBruta !== undefined));
         return;
     }
     throw new Error('uso: dd-harness fase criar --titulo "<t>" [...]  |  dd-harness fase editar <slug> [...]');
@@ -723,7 +724,10 @@ function contextoDaSessao(r, worker) {
                 "que uma fase acabou é o usuário.\n" +
                 "5. Depois de escrever os dois, sobrescreva o `CLAUDE.md` da raiz com um " +
                 "ponteiro curto para a política deste serviço — a verdade passa a morar " +
-                "aqui, e o `CLAUDE.md` local nunca mais precisa ser editado à mão.\n" +
+                "aqui, e o `CLAUDE.md` local nunca mais precisa ser editado à mão. O ponteiro " +
+                "precisa citar `ler_artefato` **e** `ler_roadmap`: quem chega por ele (Codex, " +
+                "Cursor, ou o Claude Code quando o hook não roda) não tem outro jeito de " +
+                "descobrir que há roadmap.\n" +
                 // O momento certo de perguntar: quem acabou de descrever o projeto tem o contexto
                 // fresco para dizer por onde ele vai. Depois disso, ninguem mais pergunta — e uma
                 // feature que so se descobre lendo a lista de ferramentas nao se descobre.

package/dist/roadmap.d.ts

@@ -62,8 +62,17 @@ export declare function criaFase(raiz: string, dados: NovaFase): Promise<{
     fase: Fase;
     criou: boolean;
 }>;
+/**
+ * A fase aberta imediatamente a frente, quando `ordem` foi pedida — `null` se a editada
+ * ficou na frente de todas, e ausente quando `ordem` nem foi mencionada.
+ */
+export type AtrasDe = {
+    slug: string;
+    titulo: string;
+} | null;
 export declare function editaFase(raiz: string, slug: string, dados: EdicaoDeFase): Promise<{
     fase: Fase;
+    atras_de: AtrasDe;
 }>;
 /** Rotulo do grupo de fases concluidas sem versao: o "Unreleased" do Keep a Changelog. */
 export declare const SEM_VERSAO = "Sem vers\u00E3o (ainda n\u00E3o lan\u00E7ado)";
@@ -82,6 +91,19 @@ export declare function blocoDeSessao(r: RoadmapDaSessao | null | undefined): st
  * separa por status. Concluidas nao aparecem aqui — sao changelog.
  */
 export declare function formataRoadmap(fases: Fase[]): string;
+/**
+ * A frase sobre POSICAO que fecha a resposta de `editar_fase` — vazia quando `ordem` nao
+ * foi pedida, porque quem edita texto nao perguntou nada sobre posicao.
+ *
+ * Existe por um achado medido (rodada 005): pedir `ordem: 1` para promover uma fase a
+ * "Agora" quando outra mais antiga ja tem `ordem: 1` grava o valor, responde sucesso e
+ * nao muda nada visivel — a leitura desempata por `created_at`. O comportamento esta
+ * certo; o silencio e que ensinava o agente a seguir achando que promoveu a fase.
+ *
+ * Confirma a ordem aplicada mesmo sem empate: e o unico jeito de quem pediu saber que o
+ * numero pegou, e custa uma linha.
+ */
+export declare function avisoDeOrdem(fase: Pick<Fase, "ordem" | "status">, atrasDe: AtrasDe, pediuOrdem: boolean): string;
 /**
  * O changelog: fases concluidas agrupadas por versao, na ordem em que a API devolveu (mais
  * recente primeiro). Grupo sem versao recebe `SEM_VERSAO`. A ordem dos grupos e a da

package/dist/roadmap.js

@@ -123,6 +123,27 @@ export function formataRoadmap(fases) {
         : "Nenhuma fase concluída ainda.");
     return linhas.join("\n");
 }
+/**
+ * A frase sobre POSICAO que fecha a resposta de `editar_fase` — vazia quando `ordem` nao
+ * foi pedida, porque quem edita texto nao perguntou nada sobre posicao.
+ *
+ * Existe por um achado medido (rodada 005): pedir `ordem: 1` para promover uma fase a
+ * "Agora" quando outra mais antiga ja tem `ordem: 1` grava o valor, responde sucesso e
+ * nao muda nada visivel — a leitura desempata por `created_at`. O comportamento esta
+ * certo; o silencio e que ensinava o agente a seguir achando que promoveu a fase.
+ *
+ * Confirma a ordem aplicada mesmo sem empate: e o unico jeito de quem pediu saber que o
+ * numero pegou, e custa uma linha.
+ */
+export function avisoDeOrdem(fase, atrasDe, pediuOrdem) {
+    if (!pediuOrdem)
+        return "";
+    if (!atrasDe)
+        return ` Ordem ${fase.ordem}${fase.status === "aberta" ? " — é o \"Agora\"" : ""}.`;
+    return (` Ordem ${fase.ordem}, mas ainda atrás de \`${atrasDe.slug}\` (${atrasDe.titulo}) —` +
+        " fases com a mesma ordem desempatam pela mais antiga. Para passar à frente, use uma" +
+        " ordem menor ou mude a ordem da outra.");
+}
 /**
  * O changelog: fases concluidas agrupadas por versao, na ordem em que a API devolveu (mais
  * recente primeiro). Grupo sem versao recebe `SEM_VERSAO`. A ordem dos grupos e a da

package/package.json

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