@spec-wave/cli 0.30.0 → 0.32.0

package/src/commands/qa-run.mjs

@@ -33,8 +33,9 @@ import { featureDocPaths, bugDocPaths } from '../lib/doc-paths.mjs';
 import { parseQaPlanDoc, resolveTargetScenarios } from '../lib/qa-plan-doc.mjs';
 import {
   qaExecutionGate, greenTargetStage, storyCanAdvance, featureCanAdvanceQa,
-  extractRegressionSection, renderQaCommand, buildQaContext,
+  extractRegressionSection, renderQaCommand, buildQaContext, qaProcessEnv,
 } from '../lib/qa-exec.mjs';
+import { pushWithRebase } from '../lib/git-retry.mjs';
 import {
   aggregateVerdict, validateQaResults, combineWithPrevious, parseLastQaReport,
   renderQaReport, renderQaBugDoc, qaOriginMarker, matchesQaOrigin, shortSha,
@@ -426,7 +427,10 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
     execSync(command, {
       stdio: 'inherit',
       cwd: root || process.cwd(),
-      env: { ...process.env, ...(config?.qa?.env || {}) },
+      // §3.1 da spec-qa-lead: a env do PROCESSO vence a `qa.env`, chave a chave
+      // — é assim que o `qa-lead` injeta o endereço real de cada container sem
+      // mexer no arquivo versionado.
+      env: qaProcessEnv(config?.qa?.env, process.env),
     });
   } catch (err) {
     executorFailed = err;
@@ -455,13 +459,33 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
     return { verdict: null, error: 'resultados-invalidos' };
   }
 
+  // D-QAL5: plano que MUDOU durante a execução invalida a corrida — o veredito
+  // seria de cenários que já não são os do arquivo. A checagem é da CLI (re-lê
+  // o plano do disco), não do executor: não depende de cooperação de agente.
+  {
+    const planAbs = path.join(root || process.cwd(), qaPlanRel);
+    let planNow = null;
+    try {
+      planNow = readFileSync(planAbs, 'utf-8');
+    } catch { /* ausente agora — cai no erro abaixo */ }
+    if (planNow === null || shortSha(planNow) !== shortSha(planContent)) {
+      process.exitCode = 1;
+      console.error(chalk.red(
+        `\n\`${qaPlanRel}\` mudou durante a execução (planSha ${shortSha(planContent)} → ` +
+        `${planNow === null ? 'arquivo ausente' : shortSha(planNow)}) — o veredito seria de um plano ` +
+        'que não existe mais. Nada foi movido, nenhum Bug criado. Rode de novo com o plano estável.'
+      ));
+      return { verdict: null, error: 'plano-mudou' };
+    }
+  }
+
   // ── Estado acumulado e veredito ────────────────────────────────────────────
   const { combined, pendingNumbers } = combineWithPrevious({
     executed: results,
     previous: previous.results,
     allNumbers: scenarios.map(s => s.numero),
   });
-  const verdict = aggregateVerdict(combined);
+  let verdict = aggregateVerdict(combined);
   const planSha = shortSha(planContent);
   const headSha = headShaOf(root);
   const byNumero = new Map(scenarios.map(s => [s.numero, s]));
@@ -473,11 +497,38 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
     featureStories,
   };
 
+  let bugs = [];
   if (verdict === 'fail') {
     // Reprovar o re-teste de um BUG não abre outro Bug: o vermelho significa
     // que o fix não segurou — o defeito é o mesmo, e o registro é o relatório.
     const failed = type === 'Bug' ? [] : results.filter(r => r.verdict === 'fail');
-    const bugs = await openBugsForFailures({ ...outcome, failed, byNumero, severity, headSha, qaPlanRel });
+    const opened = await openBugsForFailures({ ...outcome, failed, byNumero, severity, headSha, qaPlanRel });
+    bugs = opened.bugs;
+    // §3.2 da spec-qa-lead: NUNCA reporte `fail` sem o Bug correspondente. O
+    // push do bug.md rejeitado após o teto de retries degrada o cenário para
+    // `blocked`/`outro` — o defeito pode existir, mas sem o registro publicado
+    // ele viraria um vermelho sem Bug, que a próxima execução recriaria.
+    if (opened.pushFailures.length > 0) {
+      for (const pf of opened.pushFailures) {
+        const idx = combined.findIndex(r => r.numero === pf.numero && !r.carried);
+        if (idx !== -1) {
+          combined[idx] = {
+            ...combined[idx],
+            verdict: 'blocked',
+            blockedReason: 'outro',
+            evidencia: `commit do bug.md rejeitado: ${pf.error}`.slice(0, 400),
+          };
+        }
+      }
+      verdict = aggregateVerdict(combined);
+      console.log(chalk.yellow(
+        `Cenário(s) ${opened.pushFailures.map(f => f.numero).join(', ')} degradado(s) para ` +
+        `blocked/outro (push do bug.md rejeitado) — veredito recalculado: ${chalk.bold(verdict)}.`
+      ));
+    }
+  }
+
+  if (verdict === 'fail') {
     await stayInQa(outcome);
     await postReport({
       ...outcome, run, verdict, planSha, headSha, combined, pendingNumbers, bugs,
@@ -551,13 +602,21 @@ async function stayInQa({ projectToken, board, issue }) {
 }
 
 // Vermelho: um Bug por cenário reprovado — filho da STORY dona do cenário
-// (nunca da Feature), com bug.md determinístico commitado e `bug-approved`
-// aplicada (exceção documentada — spec §2.1).
+// (nunca da Feature), com bug.md determinístico commitado E PUBLICADO (push com
+// retry — §3.2 da spec-qa-lead) e `bug-approved` aplicada (exceção documentada
+// — spec §2.1). O bug.md vai para o remoto ANTES de a issue nascer: rodando num
+// container do `qa-lead`, um commit que fica local morre com o container, e um
+// Bug sem bug.md quebra o guard de idempotência da próxima corrida.
+//
+// Devolve também `pushFailures`: cenários cujo bug.md não pôde ser publicado —
+// o chamador os degrada para `blocked`/`outro`, porque `fail` sem Bug é o
+// estado que a spec proíbe.
 async function openBugsForFailures({
   token, projectToken, owner, repo, root, board,
   failed, byNumero, severity, headSha, qaPlanRel, feature, type, number,
 }) {
   const bugs = [];
+  const pushFailures = [];
   for (const r of failed) {
     const scenario = byNumero.get(r.numero);
     if (!scenario) continue;
@@ -568,6 +627,7 @@ async function openBugsForFailures({
       story = await getIssue(token, owner, repo, storyNumber);
     } catch (err) {
       console.warn(chalk.yellow(`⚠️  Não consegui ler a Story #${storyNumber} (${err.message}) — Bug do cenário ${r.numero} NÃO criado.`));
+      pushFailures.push({ numero: r.numero, error: `Story #${storyNumber} ilegível: ${err.message}` });
       continue;
     }
 
@@ -607,11 +667,43 @@ async function openBugsForFailures({
     const milestone = story.milestone?.number ?? undefined; // herda do pai (D5)
     const labels = ['[BUG]', severity, bugOriginLabel('qa')].filter(Boolean);
 
+    // bug.md determinístico, escrito, commitado e PUBLICADO antes de a issue
+    // nascer (§3.2): se o push não segura nem com retry, o Bug NÃO é criado e o
+    // cenário será degradado para blocked/outro pelo chamador.
+    const { fileRel, fileAbs, dirAbs } = bugDocPaths(title, root);
+    try {
+      mkdirSync(dirAbs, { recursive: true });
+      writeFileSync(fileAbs, renderQaBugDoc({
+        title: resumo, scenario, evidence: r.evidencia, severity, headSha,
+        featureNumber: feature?.number ?? null,
+      }));
+    } catch (err) {
+      console.warn(chalk.yellow(`⚠️  Não consegui escrever ${fileRel}: ${err.message} — Bug do cenário ${scenario.numero} NÃO criado.`));
+      pushFailures.push({ numero: r.numero, error: `escrita do ${fileRel} falhou: ${err.message}` });
+      continue;
+    }
+    const committed = commitLocalFile(root, fileRel,
+      `docs: gera ${fileRel} (reprovação de QA, cenário ${scenario.numero} da Story #${storyNumber}) [spec-wave]`);
+    if (!committed) {
+      pushFailures.push({ numero: r.numero, error: `commit do ${fileRel} falhou` });
+      continue;
+    }
+    const push = await pushWithRebase({ cwd: root || process.cwd() });
+    if (!push.ok) {
+      console.warn(chalk.yellow(
+        `⚠️  Push do ${fileRel} rejeitado após ${push.attempts} tentativa(s): ` +
+        `${String(push.error).split('\n')[0]} — Bug do cenário ${scenario.numero} NÃO criado.`
+      ));
+      pushFailures.push({ numero: r.numero, error: String(push.error).split('\n')[0] });
+      continue;
+    }
+
     let created;
     try {
       created = await createIssue(token, owner, repo, title, bodyLines.join('\n'), labels, { milestone });
     } catch (err) {
       console.warn(chalk.yellow(`⚠️  Falha ao criar o Bug do cenário ${scenario.numero}: ${err.message}`));
+      pushFailures.push({ numero: r.numero, error: `criação da issue falhou: ${err.message}` });
       continue;
     }
     console.log(`Bug #${created.number} criado para o cenário ${scenario.numero} (filho da Story #${storyNumber}).`);
@@ -638,34 +730,21 @@ async function openBugsForFailures({
       }
     }
 
-    // bug.md determinístico, escrito e COMMITADO localmente (exceção §2.1) +
-    // `bug-approved`: reprodução, esperado/obtido e regressão são a execução
-    // observada — regerar por IA só introduziria alucinação.
-    const { fileRel, fileAbs, dirAbs } = bugDocPaths(created.title || title, root);
-    try {
-      mkdirSync(dirAbs, { recursive: true });
-      writeFileSync(fileAbs, renderQaBugDoc({
-        title: resumo, scenario, evidence: r.evidencia, severity, headSha,
-        featureNumber: feature?.number ?? null,
-      }));
-      commitLocalFile(root, fileRel,
-        `docs: gera ${fileRel} (reprovação de QA, issue ${created.number}) [spec-wave]`);
-    } catch (err) {
-      console.warn(chalk.yellow(`⚠️  Não consegui escrever ${fileRel}: ${err.message}`));
-    }
+    // `bug-approved` direto: reprodução, esperado/obtido e regressão são a
+    // execução observada — regerar por IA só introduziria alucinação.
     await addLabel(token, owner, repo, created.number, LABEL_BUG_APPROVED).catch(() => {});
 
     await commentOnIssue(token, owner, repo, created.number,
       `🧪 **Bug aberto pela reprovação de QA** — ${scenario.anchor} da Story #${storyNumber}.\n\n` +
-      `📄 \`${fileRel}\` foi escrito e commitado com as seis seções preenchidas a partir do cenário ` +
-      'e da saída real da execução (exceção documentada à regra do `spec-wave:bug` — conteúdo ' +
-      'determinístico de uma execução observada, sem IA).\n\n' +
+      `📄 \`${fileRel}\` foi escrito, commitado e publicado com as seis seções preenchidas a partir ` +
+      'do cenário e da saída real da execução (exceção documentada à regra do `spec-wave:bug` — ' +
+      'conteúdo determinístico de uma execução observada, sem IA).\n\n' +
       `Após o fix, re-teste: \`npx @spec-wave/cli@latest qa ${storyNumber} --only ${scenario.numero}\``
     ).catch(() => {});
 
     bugs.push({ number: created.number, cenario: scenario.numero, existing: false });
   }
-  return bugs;
+  return { bugs, pushFailures };
 }
 
 // Verde: aprova e move — Story → 📋 Homologação, Bug → 🚀 Deploy, Feature

package/src/config.mjs

@@ -357,6 +357,21 @@ export const LABEL_QA = 'spec-wave:qa';
 export const LABEL_QA_READY = 'spec-wave:qa-ready';
 export const LABEL_QA_APPROVED = 'spec-wave:qa-approved';
 
+// Motivos de bloqueio de um cenário de QA (rfc/spec-qa-lead.md, D-QAL6).
+// Enum FECHADO: o executor escolhe um destes no `blockedReason` do arquivo de
+// resultados; `outro` exige evidência em texto livre não vazia. O agregado por
+// motivo (`blockedByReason` do relatório de trilha) é o que diz se o problema
+// é ambiente, massa de dados ou dependência — por isso não aceita texto livre.
+export const QA_BLOCKED_REASONS = [
+  'ambiente',
+  'setup-falhou',
+  'massa-de-dados',
+  'dependencia-nao-entregue',
+  'bloqueado-por-bug',
+  'credencial',
+  'outro',
+];
+
 // Desfecho da triagem do PM (RFC-004 §4.1). São mutuamente exclusivas: um bug
 // triado foi aceito, rejeitado ou marcado como duplicata.
 export const LABEL_TRIAGED = 'spec-wave:triaged';

package/src/lib/artifact-publish.mjs

@@ -85,7 +85,7 @@ export function isStaleArtifactBranch(status, openPr) {
  */
 export async function publishArtifact({
   token, owner, repo, doc, issueNumber, issueTitle = '', issueUrl = '',
-  pathRel, content, base = null, nextLabel = null, deps = {},
+  pathRel, content, base = null, nextLabel = null, extraFiles = [], deps = {},
 }) {
   const api = {
     getRepoDefaultBranch, compareBranches, findOpenPR, commitFilesToBranch,
@@ -123,7 +123,10 @@ export async function publishArtifact({
     commit = await api.commitFilesToBranch(token, owner, repo, {
       branch,
       base: alvo,
-      files: [{ path: pathRel, content }],
+      // `extraFiles`: derivados que viajam no MESMO commit do documento (ex.: o
+      // dependency-map.json do apply) — dois commits/PRs para um só evento
+      // dariam dois estados intermediários para o mesmo fato.
+      files: [{ path: pathRel, content }, ...extraFiles],
       message: artifactCommitMessage({ doc, issueNumber, pathRel }),
     });
   } catch (err) {

package/src/lib/board.mjs

@@ -4,6 +4,16 @@
 import { addProjectItem, setItemSingleSelect, getSingleSelectField, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { CONFIG_FILE, STAGE_ORDER, STATUS_OPTIONS, WORK_ITEM_TYPES, STAGE_DONE } from '../config.mjs';
 import { loadConfig } from './project-root.mjs';
+import { invalidateCache } from './net-cache.mjs';
+
+// Toda ESCRITA de board passa por advanceToStage/setItemStage/setItemStatus —
+// invalidar aqui cobre todos os comandos de uma vez (move, qa, code-review,
+// merge, implement…): o snapshot cacheado (`board-items`, lib/net-cache.mjs)
+// não pode sobreviver a uma Etapa que acabou de mudar. Best-effort por
+// construção: o invalidate nunca lança.
+function dropBoardCache() {
+  invalidateCache(loadConfig().root, 'board-items');
+}
 
 /**
  * Carrega o bloco `project` do .spec-wave.json, procurando-o a partir de `cwd`
@@ -229,6 +239,7 @@ export async function advanceToStage(
       );
     }
     await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
+    dropBoardCache();
   }
   if (statusField?.id && targetStatus) {
     const optionId = statusField.options?.[targetStatus];
@@ -239,6 +250,7 @@ export async function advanceToStage(
       );
     }
     await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+    dropBoardCache();
   }
   return true;
 }
@@ -288,6 +300,7 @@ export async function setItemStage(
     const statusOption = statusField.options?.[targetStatus];
     if (statusOption) await setItemSingleSelect(token, project.id, itemId, statusField.id, statusOption);
   }
+  dropBoardCache();
   return { from };
 }
 
@@ -308,5 +321,6 @@ export async function setItemStatus(token, project, statusField, nodeId, status)
   if (!optionId) return false;
   const itemId = await addProjectItem(token, project.id, nodeId);
   await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+  dropBoardCache();
   return true;
 }

package/src/lib/dependency-map.mjs

@@ -0,0 +1,300 @@
+// Dependency map pré-computado de uma Feature (módulo PURO — sem I/O).
+//
+// Montar a ordem das Stories consultava a API por Story (`listBlockedBy` + o
+// par addProjectItem/getItemSingleSelectValue) em QUATRO comandos diferentes —
+// e estourava rate limit. O grafo, porém, já nasce pronto: o `decompose
+// --apply` conhece todas as arestas quando cria as issues. Este módulo define o
+// artefato COMMITADO `docs/features/<slug>/dependency-map.json` (escrito pelo
+// apply, atualizado pelo `order --sync`) e as decisões puras de consumo:
+// validade do artefato, união de fontes de aresta, frescor de cache e o JSON
+// que o `order --json` entrega a agentes.
+//
+// O que o artefato NÃO carrega, de propósito: Etapa e estado open/closed — são
+// do board, mudam a cada `move`, e commitá-los seria gravar mentira com hora
+// marcada. Quem precisa deles paga UMA chamada paginada (`listProjectItems`),
+// cacheada com TTL (ver lib/net-cache.mjs e lib/story-graph.mjs).
+
+import { orderStories } from './dependencies.mjs';
+
+/** Nome do artefato dentro do diretório da feature. */
+export const DEPENDENCY_MAP_FILE = 'dependency-map.json';
+
+// Versão do formato. Maior que a conhecida → parse recusa e o chamador cai no
+// fallback (decomposition.md/body) — nunca interpretar errado em silêncio.
+export const DEPENDENCY_MAP_VERSION = 1;
+
+/**
+ * Monta o objeto do artefato (função PURA).
+ *
+ * `order`/`cycle` são conveniência derivada de `dependsOn` (a mesma
+ * `orderStories` do comando) — consumidores podem recalcular, mas um agente
+ * lendo o JSON não deveria precisar reimplementar Kahn.
+ *
+ * @param {object} params
+ * @param {number} params.featureNumber
+ * @param {Array<{number:number, title?:string, dependsOn?:number[], tasks?:number[]}>} params.stories
+ * @param {'apply'|'sync'} [params.source]
+ * @param {string} [params.generatedAt] ISO — injetável nos testes
+ * @returns {object} o dependency-map.json (v1)
+ */
+export function buildDependencyMap({ featureNumber, stories = [], source = 'apply', generatedAt } = {}) {
+  const clean = stories
+    .filter(s => Number.isInteger(s?.number) && s.number > 0)
+    .map(s => ({
+      number: s.number,
+      title: String(s.title ?? ''),
+      dependsOn: [...new Set((s.dependsOn || [])
+        .filter(d => Number.isInteger(d) && d > 0 && d !== s.number))]
+        .sort((a, b) => a - b),
+      tasks: (s.tasks || []).filter(t => Number.isInteger(t) && t > 0),
+    }));
+  const { order, cycle } = orderStories(clean);
+  return {
+    version: DEPENDENCY_MAP_VERSION,
+    feature: featureNumber,
+    generatedAt: generatedAt || new Date().toISOString(),
+    source,
+    stories: clean,
+    order,
+    cycle,
+  };
+}
+
+/**
+ * Valida um dependency-map.json lido do disco (função PURA).
+ *
+ * Inválido nunca é erro do comando — é `{ ok: false, reason }` e o chamador
+ * cai no fallback (decomposition.md ∪ body).
+ *
+ * @param {*} value objeto já parseado do JSON
+ * @returns {{ ok: boolean, reason: string|null, map: object|null }}
+ */
+export function parseDependencyMap(value) {
+  const bad = (reason) => ({ ok: false, reason, map: null });
+  if (!value || typeof value !== 'object') return bad('não é um objeto JSON');
+  if (value.version !== DEPENDENCY_MAP_VERSION) {
+    return bad(`version ${JSON.stringify(value.version)} (esta CLI entende v${DEPENDENCY_MAP_VERSION})`);
+  }
+  if (!Number.isInteger(value.feature) || value.feature <= 0) return bad('campo "feature" ausente/inválido');
+  if (!Array.isArray(value.stories)) return bad('campo "stories" ausente');
+  for (const [i, s] of value.stories.entries()) {
+    if (!Number.isInteger(s?.number) || s.number <= 0) return bad(`stories[${i}].number inválido`);
+    if (s.dependsOn != null && !Array.isArray(s.dependsOn)) return bad(`stories[${i}].dependsOn inválido`);
+  }
+  return { ok: true, reason: null, map: value };
+}
+
+/**
+ * Converte um decomposition.md APLICADO em Stories com arestas por número de
+ * issue (função PURA) — o fallback quando o dependency-map.json não existe.
+ *
+ * `ok: false` quando o doc não serve de fonte: proposta ainda não aplicada
+ * (números não existem), kind=tasks (RFC não tem Stories) ou apply parcial
+ * (Story sem `issue` — grafo não confiável).
+ *
+ * @param {object} doc saída de parseDecompositionDoc
+ * @returns {{ ok: boolean, reason: string|null,
+ *             stories: Array<{number:number, title:string, dependsOn:number[], tasks:number[]}> }}
+ */
+export function storiesFromAppliedDoc(doc) {
+  const bad = (reason) => ({ ok: false, reason, stories: [] });
+  if (!doc || typeof doc !== 'object') return bad('documento ilegível');
+  if (!doc.appliedAt) return bad('decomposition.md ainda é proposta (sem applied=) — os números não existem');
+  if (doc.kind !== 'stories') return bad(`kind=${doc.kind || '?'} não tem Stories`);
+  const stories = doc.stories || [];
+  const semIssue = stories.filter(s => !Number.isInteger(s?.issue) || s.issue <= 0);
+  if (semIssue.length > 0) {
+    return bad(`${semIssue.length} Story(ies) sem "**Issue:** #N" — apply parcial, grafo não confiável`);
+  }
+  return {
+    ok: true,
+    reason: null,
+    stories: stories.map((s, i) => ({
+      number: s.issue,
+      title: s.title || '',
+      dependsOn: [...new Set([
+        // irmãs por índice 0-based → número da issue da irmã
+        ...(s.dependsOn || []).map(idx => stories[idx]?.issue).filter(n => Number.isInteger(n)),
+        ...(s.dependsOnIssues || []),
+      ])].filter(n => n !== s.issue).sort((a, b) => a - b),
+      tasks: (s.tasks || []).map(t => t.issue).filter(n => Number.isInteger(n) && n > 0),
+      index: i,
+    })),
+  };
+}
+
+/**
+ * União de arestas por Story, vindas de fontes diferentes (função PURA).
+ *
+ * Cada fonte é um array `[{number, dependsOn}]`; a união deduplica, remove
+ * self-loop e ordena — duas escritas do mesmo conteúdo dão o mesmo resultado.
+ *
+ * @param {...Array<{number:number, dependsOn?:number[]}>} sources
+ * @returns {Map<number, number[]>} number da Story → dependências
+ */
+export function mergeDependencyEdges(...sources) {
+  const out = new Map();
+  for (const source of sources) {
+    for (const s of source || []) {
+      if (!Number.isInteger(s?.number)) continue;
+      if (!out.has(s.number)) out.set(s.number, new Set());
+      for (const d of s.dependsOn || []) {
+        if (Number.isInteger(d) && d > 0 && d !== s.number) out.get(s.number).add(d);
+      }
+    }
+  }
+  return new Map([...out.entries()].map(([n, deps]) => [n, [...deps].sort((a, b) => a - b)]));
+}
+
+// ── frescor de cache ─────────────────────────────────────────────────────────
+
+/**
+ * A entrada de cache ainda vale? (função PURA)
+ *
+ * `ttlSec <= 0` desliga o cache (nunca fresco). `fetchedAt` no futuro conta
+ * como fresco — relógio torto não pode transformar cache válido em refetch em
+ * loop.
+ *
+ * @param {{fetchedAt?: string}|null} entry
+ * @param {number} ttlSec
+ * @param {number} [nowMs]
+ */
+export function isFresh(entry, ttlSec, nowMs = Date.now()) {
+  if (!entry?.fetchedAt || !Number.isFinite(ttlSec) || ttlSec <= 0) return false;
+  const fetched = Date.parse(entry.fetchedAt);
+  if (!Number.isFinite(fetched)) return false;
+  return nowMs - fetched < ttlSec * 1000;
+}
+
+/**
+ * Aviso de staleness para a saída (função PURA).
+ *
+ * Dados com menos de 60s não geram aviso — poluir toda saída fresca ensinaria
+ * a ignorar a linha. `null` também para timestamp ilegível.
+ *
+ * @param {string} fetchedAt ISO
+ * @param {number} [nowMs]
+ * @returns {string|null}
+ */
+export function stalenessNotice(fetchedAt, nowMs = Date.now()) {
+  const fetched = Date.parse(fetchedAt || '');
+  if (!Number.isFinite(fetched)) return null;
+  const ageSec = Math.floor((nowMs - fetched) / 1000);
+  if (ageSec < 60) return null;
+  const idade = ageSec < 3600
+    ? `${Math.floor(ageSec / 60)} min`
+    : `${Math.floor(ageSec / 3600)}h${String(Math.floor((ageSec % 3600) / 60)).padStart(2, '0')}`;
+  return `dados do board de ${idade} atrás — use --refresh para reconsultar`;
+}
+
+// ── filtros e saída ──────────────────────────────────────────────────────────
+
+/**
+ * Filtra itens do board por milestone (função PURA) — `order --milestone`.
+ *
+ * `ref` aceita número ("3"/"#3") ou título (case-insensitive, comparação
+ * exata). Exige o campo `milestone` no shape de listProjectItems.
+ *
+ * @param {Array<{milestone?: {number:number, title:string}|null}>} items
+ * @param {string|number} ref
+ * @returns {Array} os itens da milestone
+ */
+export function filterItemsByMilestone(items = [], ref) {
+  const text = String(ref ?? '').trim();
+  if (/^#?\d+$/.test(text)) {
+    const number = parseInt(text.replace('#', ''), 10);
+    return items.filter(i => i?.milestone?.number === number);
+  }
+  const alvo = text.toLowerCase();
+  return items.filter(i => String(i?.milestone?.title || '').toLowerCase() === alvo);
+}
+
+/**
+ * A saída de `order --json` (função PURA) — contrato para agentes.
+ *
+ * Shape estável de propósito: é o que o dev-agent e outros consumidores
+ * programáticos leem no lugar de parsear o texto com ANSI.
+ *
+ * @param {object} params
+ * @param {number[]} params.sorted ordem topológica
+ * @param {Map<number, {title?:string, dependsOn?:number[]}>} params.byNumber
+ * @param {Map<number, object>} [params.featureOf] Story → Feature dona
+ * @param {Map<number, string|null>} [params.stageOf]
+ * @param {Map<number, number[]>} [params.external]
+ * @param {number[]} [params.cycle]
+ * @param {{edges?:string, stages?:string|null, fetchedAt?:string|null,
+ *          generatedAt?:string, warnings?:string[]}} [params.meta]
+ * @returns {object}
+ */
+export function renderOrderJson({
+  sorted = [], byNumber = new Map(), featureOf = new Map(), stageOf = new Map(),
+  external = new Map(), cycle = [], meta = {},
+} = {}) {
+  return {
+    version: 1,
+    generatedAt: meta.generatedAt || new Date().toISOString(),
+    source: {
+      edges: meta.edges || 'remote',
+      stages: meta.stages ?? null,
+      fetchedAt: meta.fetchedAt ?? null,
+    },
+    order: sorted.map((n, i) => {
+      const s = byNumber.get(n) || {};
+      const feature = featureOf.get(n) || null;
+      return {
+        position: i + 1,
+        number: n,
+        title: s.title || '',
+        feature: feature ? { number: feature.number, title: feature.title || '' } : null,
+        stage: stageOf.get(n) ?? null,
+        dependsOn: (s.dependsOn || []).slice().sort((a, b) => a - b),
+      };
+    }),
+    external: [...external.entries()].map(([number, dependsOn]) => ({ number, dependsOn })),
+    cycle: cycle.slice(),
+    warnings: meta.warnings || [],
+  };
+}
+
+// ── sync API → doc (`order --sync`) ──────────────────────────────────────────
+
+/**
+ * Reescreve as dependências de um decomposition.md APLICADO a partir do estado
+ * VIVO das issues (função PURA) — a metade de decisão do `order --sync`.
+ *
+ * `liveDeps` é a união body ∪ blocked_by por Story (a mesma que o `order`
+ * remoto usa). Cada Story do doc passa a declarar exatamente essas arestas:
+ * irmã ANTERIOR vira `Story N` (a forma legível, que a gramática exige "só
+ * para trás"); irmã posterior ou issue de fora vira `#N`. Dependência que
+ * sumiu do GitHub sai do doc — sync é espelho, não união.
+ *
+ * @param {object} doc saída de parseDecompositionDoc (aplicado, kind=stories)
+ * @param {Map<number, number[]>} liveDeps número da Story → deps vivas
+ * @returns {{ doc: object, changed: boolean,
+ *             changes: Array<{story:number, before:number[], after:number[]}> }}
+ */
+export function syncDocDependencies(doc, liveDeps = new Map()) {
+  const indexOfIssue = new Map((doc.stories || []).map((s, i) => [s.issue, i]));
+  const changes = [];
+  const stories = (doc.stories || []).map((story, i) => {
+    if (!liveDeps.has(story.issue)) return story; // sem leitura viva → não toca
+    const before = [...new Set([
+      ...(story.dependsOn || []).map(idx => doc.stories[idx]?.issue).filter(Number.isInteger),
+      ...(story.dependsOnIssues || []),
+    ])].sort((a, b) => a - b);
+    const after = [...new Set(liveDeps.get(story.issue) || [])]
+      .filter(n => Number.isInteger(n) && n > 0 && n !== story.issue)
+      .sort((a, b) => a - b);
+    if (before.join(',') === after.join(',')) return story;
+    changes.push({ story: story.issue, before, after });
+    const siblings = [];
+    const issues = [];
+    for (const dep of after) {
+      const idx = indexOfIssue.get(dep);
+      if (idx !== undefined && idx < i) siblings.push(idx);
+      else issues.push(dep);
+    }
+    return { ...story, dependsOn: siblings, dependsOnIssues: issues };
+  });
+  return { doc: { ...doc, stories }, changed: changes.length > 0, changes };
+}

package/src/lib/doc-paths.mjs

@@ -50,5 +50,9 @@ export function featureDocPaths(root, issue, type) {
     // A chave leva o hífen do nome do documento (ARTIFACT_DOCS) de propósito:
     // é o mesmo id que o resto do fluxo usa para este artefato.
     'qa-plan': doc('qa-plan.md'),
+    // Grafo de dependências pré-computado (lib/dependency-map.mjs) — escrito
+    // pelo decompose --apply, atualizado pelo `order --sync`, lido por
+    // order/implement/merge/qa-lead no lugar de N chamadas de API.
+    'dependency-map': doc('dependency-map.json'),
   };
 }