@spec-wave/cli 0.29.0 → 0.32.0

package/src/commands/run.mjs

@@ -137,7 +137,7 @@ function localDocStates(issue, type, root) {
   const paths = featureDocPaths(root, issue, type);
   const docs = {};
   const docPaths = {};
-  for (const nome of ['spec', 'plan', 'decomposition']) {
+  for (const nome of ['spec', 'plan', 'decomposition', 'qa-plan']) {
     docs[nome] = existsSync(paths[nome].abs) ? 'local' : 'missing';
     docPaths[nome] = paths[nome].rel;
   }
@@ -305,6 +305,10 @@ async function dispatch(action, { issueNumber }) {
       const { generateBug } = await import('./generate-bug.mjs');
       return await generateBug({ issueNumber });
     }
+    case 'generate-qa-plan': {
+      const { generateQaPlan } = await import('./generate-qa-plan.mjs');
+      return await generateQaPlan({ issueNumber });
+    }
     default:
       throw new Error(`Passo sem despacho: ${action}`);
   }

package/src/config.mjs

@@ -54,7 +54,7 @@ export const DEFAULT_PROVIDER = 'anthropic';
 // Ações de IA que podem ter modelo próprio no .spec-wave.json (bloco
 // `ai.models`, ex.: { "critique": "claude-opus-4-1" }). Resolvidas em runtime
 // por resolveAiConfig() em src/lib/claude.mjs.
-export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique', 'bug'];
+export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique', 'bug', 'qa'];
 
 // Override de modelo POR EXECUÇÃO: a label `spec-wave:model:<apelido>` na issue
 // aponta para uma entrada de `ai.modelAliases` do .spec-wave.json. Serve para
@@ -346,6 +346,32 @@ export const LABEL_DEV_AGENT = 'spec-wave:dev-agent';
 export const LABEL_BUG = 'spec-wave:bug';
 export const LABEL_BUG_APPROVED = 'spec-wave:bug-approved';
 
+// Fluxo de QA (rfc/spec-qa-skill.md). O gatilho gera (ou re-critica) o
+// qa-plan.md; as duas de estado são gravadas pelas automações, nunca à mão.
+//
+// ⚠️ `spec-wave:qa-ready` NÃO é `spec-wave:ready`: a primeira é ESTADO do plano
+// de QA (passou na crítica, espera revisão humana — o portão do D-QA4); a
+// segunda é o GATILHO da validação de spec/plan. Nenhuma checagem pode usar
+// prefixo (`startsWith('spec-wave:ready')`) para distinguir as duas.
+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';
@@ -432,6 +458,9 @@ export const TRIGGER_LABELS = [
   { name: LABEL_DEV_AGENT,           color: '5319E7', description: 'Enfileira a issue para o dev-agent autônomo' },
   { name: LABEL_BUG,                 color: 'BFD4F2', description: 'Gerar bug.md via GitHub Action' },
   { name: LABEL_BUG_APPROVED,        color: '0E8A16', description: 'bug.md validado (reprodução, causa raiz e teste de regressão)' },
+  { name: LABEL_QA,                  color: 'BFD4F2', description: 'Gerar/re-criticar o plano de QA (qa-plan.md) via GitHub Action' },
+  { name: LABEL_QA_READY,            color: '0E8A16', description: 'Plano de QA aprovado pela crítica — revise-o e rode `spec-wave qa <n>`' },
+  { name: LABEL_QA_APPROVED,         color: '0E8A16', description: 'Execução do QA passou em todos os cenários' },
   { name: LABEL_TRIAGED,             color: '0E8A16', description: 'Bug triado pelo PM (severidade, origem e pai definidos)' },
   { name: LABEL_DUPLICATE,           color: 'EDEDED', description: 'Duplicata de outra issue (o corpo aponta qual)' },
   { name: LABEL_WONT_FIX,            color: 'EDEDED', description: 'Rejeitado na triagem — não será corrigido' },
@@ -515,6 +544,7 @@ export const WORKFLOW_FILES = [
   'generate-spec.yml',
   'validate.yml',
   'decompose.yml',
+  'generate-qa-plan.yml',
   'code-review.yml',
   'qa.yml',
 ];
@@ -535,6 +565,7 @@ export const ARTIFACT_WORKFLOW_FILES = [
   'generate-plan.yml',
   'generate-bug.yml',
   'decompose.yml',
+  'generate-qa-plan.yml',
 ];
 
 export const ISSUE_TEMPLATE_FILES = [

package/src/lib/artifact-pr.mjs

@@ -34,6 +34,7 @@ export const ARTIFACT_DOCS = {
   bug: { suffix: 'bug', file: 'bug.md' },
   decomposition: { suffix: 'decompose', file: 'decomposition.md' },
   'decomposition-apply': { suffix: 'decompose-apply', file: 'decomposition.md' },
+  'qa-plan': { suffix: 'qa-plan', file: 'qa-plan.md' },
 };
 
 /** Nomes aceitos em `doc`, na ordem do fluxo. */
@@ -102,6 +103,7 @@ const DOC_LABEL = {
   bug: 'documento de bug',
   decomposition: 'rascunho de decomposição',
   'decomposition-apply': 'registro das issues criadas',
+  'qa-plan': 'plano de QA',
 };
 
 /**

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/critique.mjs

@@ -44,7 +44,7 @@ export const CRITIQUE_TOOL_NAME = 'registrar_findings';
 // Rótulo do artefato auditado, por contexto — usado no cabeçalho do comentário.
 const KIND_LABEL = {
   plan: 'plan.md', stories: 'decomposition.md', bug: 'bug.md', spec: 'spec.md',
-  conjunto: 'specs da milestone (conjunto)',
+  conjunto: 'specs da milestone (conjunto)', qa: 'qa-plan.md',
 };
 
 // Prompt por tipo de auditoria. 'plan' audita o plan.md contra a spec;
@@ -53,7 +53,7 @@ const KIND_LABEL = {
 // relação entre documentos, não um documento.
 const KIND_PROMPT = {
   plan: 'plan/critique', stories: 'decompose/critique', bug: 'bug/critique', spec: 'spec/critique',
-  conjunto: 'audit/critique',
+  conjunto: 'audit/critique', qa: 'qa/critique',
 };
 
 // A decomposição virou arquivo revisável (decomposition.md): um finding só é
@@ -66,6 +66,13 @@ const ANCHOR_RULE = `Cada finding DEVE citar, no campo "anchor", o trecho audita
 - "geral" quando o problema for da decomposição como um todo (ex.: requisito da spec que nenhuma Story cobre).
 Use EXATAMENTE os números que aparecem nos títulos "## Story N — ..." e "### Task N.M — ..." do documento.`;
 
+// O qa-plan.md tem a mesma necessidade da decomposição: o finding precisa dizer
+// QUAL cenário está errado, e o título "## Cenário N" é a âncora estável.
+const QA_ANCHOR_RULE = `Cada finding DEVE citar, no campo "anchor", o trecho auditado:
+- "Cenário N" para um problema no Cenário N (ex.: "Cenário 3");
+- "geral" quando o problema for do plano como um todo (ex.: critério de aceite da spec que nenhum cenário cobre).
+Use EXATAMENTE os números que aparecem nos títulos "## Cenário N — Story #X" do documento.`;
+
 // No conjunto o achado vive ENTRE documentos: sem dizer quais, o leitor relê a
 // milestone inteira procurando o par. O campo é validado como array de números
 // de issue — é o equivalente da âncora "Story N" para este contexto.
@@ -91,6 +98,7 @@ visto à luz das outras). Use EXATAMENTE os números que aparecem nos títulos "
 function buildSystemPrompt(kind, cwd) {
   const prompt = loadPrompt(KIND_PROMPT[kind] || KIND_PROMPT.plan, ...(cwd ? [{ cwd }] : []));
   const anchor = kind === 'stories' ? `\n\n${ANCHOR_RULE}`
+    : kind === 'qa' ? `\n\n${QA_ANCHOR_RULE}`
     : kind === 'conjunto' ? `\n\n${FEATURES_RULE}` : '';
 
   const contract = `## Contrato de saída
@@ -146,6 +154,13 @@ function critiqueJsonSchema(kind) {
     };
     required.push('anchor');
   }
+  if (kind === 'qa') {
+    properties.anchor = {
+      type: 'string',
+      description: 'Âncora do trecho auditado: "Cenário N" ou "geral".',
+    };
+    required.push('anchor');
+  }
   if (kind === 'conjunto') {
     properties.features = {
       type: 'array',
@@ -195,14 +210,14 @@ function describe(value) {
   return typeof value === 'object' ? 'um objeto' : `${typeof value} (${JSON.stringify(value).slice(0, 60)})`;
 }
 
-const ANCHOR_RE = /^(story|task)[ \t]*(\d+(?:\.\d+)?)$/i;
+const ANCHOR_RE = /^(story|task|cen[aá]rio)[ \t]*(\d+(?:\.\d+)?)$/i;
 
 /**
  * Normaliza a âncora de um finding (função PURA).
  *
- * Aceita "Story 3", "story3", "TASK 3.2". Qualquer outra coisa — inclusive
- * "geral" — vira ausência de âncora: melhor não citar do que citar errado e
- * mandar o humano para o trecho errado do documento.
+ * Aceita "Story 3", "story3", "TASK 3.2", "Cenário 2" (com ou sem acento).
+ * Qualquer outra coisa — inclusive "geral" — vira ausência de âncora: melhor
+ * não citar do que citar errado e mandar o humano para o trecho errado.
  *
  * @param {*} value valor cru do campo `anchor`
  * @returns {string} âncora normalizada, ou '' quando não há
@@ -210,7 +225,9 @@ const ANCHOR_RE = /^(story|task)[ \t]*(\d+(?:\.\d+)?)$/i;
 export function normalizeAnchor(value) {
   const m = ANCHOR_RE.exec(String(value ?? '').trim());
   if (!m) return '';
-  return `${m[1].toLowerCase() === 'task' ? 'Task' : 'Story'} ${m[2]}`;
+  const kind = m[1].toLowerCase();
+  const nome = kind === 'task' ? 'Task' : kind === 'story' ? 'Story' : 'Cenário';
+  return `${nome} ${m[2]}`;
 }
 
 /**
@@ -758,6 +775,11 @@ const KIND_TRAILER = {
       'até ser removida. Um bug com causa raiz errada produz correção errada — corrija o ' +
       '`bug.md` e reaplique `spec-wave:bug`.'
     : '_Findings menores não bloqueiam a triagem._'),
+  qa: (graves) => (graves
+    ? '⛔ Há findings **graves**: a label `spec-wave:critique-failed` impede o `qa run` ' +
+      'até ser removida. Corrija o `qa-plan.md` (as âncoras acima apontam para ele), ' +
+      'remova a label e reaplique `spec-wave:qa` para uma nova crítica.'
+    : '_Findings menores não bloqueiam a execução do QA._'),
   // O conjunto roda fora do ciclo de tentativas e não aplica label: o achado é
   // decisão de PO entre duas specs, e o destino dele é a issue das duas pontas.
   conjunto: (graves) => (graves
@@ -897,7 +919,7 @@ export function renderCritiqueMarkdown({
  * @returns {Promise<{grave, findings, markdown, attempt, model}>}
  */
 export async function runCritique({
-  kind, spec, specs, plan, techContextYaml, decomposition, bugDoc, bugReport,
+  kind, spec, specs, plan, techContextYaml, decomposition, qaPlan, bugDoc, bugReport,
   attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
   model, labels = [], usage, cwd, decisions = null, standalone = false,
 } = {}) {
@@ -917,6 +939,13 @@ export async function runCritique({
       `## Decomposição proposta (decomposition.md)\n\n\`\`\`\`markdown\n${decomposition}\n\`\`\`\``
     );
   }
+  // Mesma cerca de quatro crases da decomposição, pelo mesmo motivo: o plano
+  // pode conter blocos de código de três.
+  if (qaPlan) {
+    sections.push(
+      `## Plano de QA auditado (qa-plan.md)\n\n\`\`\`\`markdown\n${qaPlan}\n\`\`\`\``
+    );
+  }
   // O relato é a fonte contra a qual o bug.md é auditado: a causa raiz proposta
   // tem que explicar OS SINTOMAS RELATADOS, não sintomas plausíveis quaisquer.
   if (bugReport) sections.push(`## Relato original (issue e comentários)\n\n${bugReport}`);
@@ -953,7 +982,7 @@ export async function runCritique({
   // sustenta não deve entrar no contador de tentativas nem bloquear o Action.
   const findings = downgradeUnsupportedFindings(
     report.value.findings,
-    [spec, ...(specs || []).map(s => s.content), plan, decomposition, bugDoc, techContextYaml]
+    [spec, ...(specs || []).map(s => s.content), plan, decomposition, qaPlan, bugDoc, techContextYaml]
       .filter(Boolean),
   );
   const grave = findings.some(f => f.severity === 'grave');

package/src/lib/decomposition-doc.mjs

@@ -69,8 +69,12 @@ function invalid(reason) {
  * Regras do CommonMark que importam aqui: a cerca tem 3+ caracteres, o
  * fechamento usa o mesmo caractere e comprimento >= o da abertura, e uma cerca
  * de crase não aceita crase na info string.
+ *
+ * Exportado porque o qa-plan.md (lib/qa-plan-doc.mjs) espelha as MESMAS regras
+ * de parsing deste documento — duplicar o rastreador seria duas cópias para
+ * divergir.
  */
-function fenceScanner() {
+export function fenceScanner() {
   let open = null;
   return {
     // true quando a linha pertence a um bloco de código (abertura, conteúdo ou

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

@@ -30,12 +30,12 @@ export function resolveDocDir(root, issue, type) {
 }
 
 /**
- * Caminhos dos três documentos de uma Feature/RFC (função PURA).
+ * Caminhos dos documentos de uma Feature/RFC (função PURA).
  *
  * @param {string|null} root
  * @param {{title?: string}} issue
  * @param {string|null} [type]
- * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition}} cada documento com {rel, abs}
+ * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition, 'qa-plan'}} cada documento com {rel, abs}
  */
 export function featureDocPaths(root, issue, type) {
   const { slug, rel, dir } = resolveDocDir(root, issue, type);
@@ -47,5 +47,12 @@ export function featureDocPaths(root, issue, type) {
     spec: doc('spec.md'),
     plan: doc('plan.md'),
     decomposition: doc('decomposition.md'),
+    // 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'),
   };
 }