@spec-wave/cli 0.30.0 → 0.32.0

package/src/commands/order.mjs

@@ -1,33 +1,44 @@
 // Ordena as Stories pelas dependências (topológica, Kahn —
-// ver orderStories em src/lib/dependencies.mjs). As dependências vêm de duas
-// fontes, mescladas: a linha "Depende de: #N" no corpo da Story e a relação
-// nativa blocked_by do GitHub.
+// ver orderStories em src/lib/dependencies.mjs).
 //
-// Dependência para FORA da Feature não entra na ordenação (não há como saber
-// onde a Story de outra Feature entra nesta sequência), mas é EXIBIDA: era lida,
-// descartada em silêncio por orderStories e ignorada de novo no aviso de
-// fora-de-ordem. Quem montava o mapa de trabalho de dois devs tinha que
-// reconstruir isso à mão, lendo os decomposition.md.
+// De onde vêm as ARESTAS (lib/story-graph.mjs): do dependency-map.json
+// commitado (escrito pelo decompose --apply), do decomposition.md aplicado e
+// das linhas "Depende de: #N" do corpo das sub-issues — fontes locais/grátis,
+// sempre unidas. `--remote` acrescenta o blocked_by nativo da API (1 chamada
+// por Story — a única fonte que enxerga aresta criada só pela UI); `--sync`
+// grava essa leitura de volta no decomposition.md e regenera o mapa, para que
+// as consultas seguintes voltem a ser locais.
 //
-// Dois escopos: `order <feature>` (uma Feature) e `order` sem argumento — o
-// mapa de TODAS as Features com trabalho no board, onde as dependências entre
-// Features deixam de ser "externas" e entram no mesmo grafo.
+// A Etapa de cada Story vem de UM `listProjectItems` paginado, cacheado com
+// TTL (staleness sempre visível) — nunca mais do par addProjectItem +
+// getItemSingleSelectValue por Story, que além de custar 2 chamadas por item
+// era MUTAÇÃO em caminho de leitura.
 //
-// Comando LOCAL — rodado pelo dev no terminal. owner/repo vêm da env
-// GITHUB_REPOSITORY quando existir, senão do .spec-wave.json (gravado pelo init).
+// Dois escopos: `order <feature>` (uma Feature) e `order` sem argumento — o
+// mapa de TODAAS as Features com trabalho no board (`--milestone` filtra).
+// `--json` emite o contrato estável de lib/dependency-map.mjs para consumo
+// programático (dev-agent e afins), sem ANSI para filtrar.
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, listBlockedBy } from '../api/github-rest.mjs';
-import {
-  addProjectItem, listSubIssues, getItemSingleSelectValue, listProjectItems,
-} from '../api/github-graphql.mjs';
+import { listSubIssues } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
+import { loadProjectConfig, selectOpenFeatures } from '../lib/board.mjs';
+import { resolveRepoContext, loadConfig } from '../lib/project-root.mjs';
+import { featureDocPaths } from '../lib/doc-paths.mjs';
+import { parseDecompositionDoc, renderDecompositionDoc } from '../lib/decomposition-doc.mjs';
 import {
-  loadProjectConfig, resolveField, indexBoardItems, selectOpenFeatures,
-} from '../lib/board.mjs';
-import { resolveRepoContext } from '../lib/project-root.mjs';
+  buildDependencyMap, syncDocDependencies, mergeDependencyEdges,
+  filterItemsByMilestone, renderOrderJson, stalenessNotice,
+} from '../lib/dependency-map.mjs';
+import { loadFeatureStories, loadBoardSnapshot, externalIssueInfo } from '../lib/story-graph.mjs';
+import { resolveCacheTtl } from '../lib/net-cache.mjs';
+import { pushWithRebase } from '../lib/git-retry.mjs';
 import { CONFIG_FILE, STAGE_ORDER, STAGE_DEVELOPMENT, STAGE_DONE } from '../config.mjs';
 
 /**
@@ -96,18 +107,26 @@ export function renderBoardOrder({ sorted, byNumber, featureOf, stageOf }) {
   }).join('\n');
 }
 
+// A nota de origem das arestas: quem lê a saída precisa saber SE o blocked_by
+// só-de-UI entrou — é a única aresta que as fontes locais não enxergam.
+function edgesNote(origins, { remote }) {
+  const fontes = [...new Set(origins)].join(' · ');
+  if (remote) return `Arestas: ${fontes} (inclui blocked_by remoto).`;
+  return `Arestas: ${fontes} — blocked_by criado SÓ pela UI não entra (use --remote, ou --sync para gravá-lo no doc).`;
+}
+
 /**
  * `spec-wave order` sem argumento: o grafo de TODAS as Features com trabalho.
  *
  * Fonte do conjunto é o BOARD, não os arquivos — `decomposition.md` registra o
- * que foi proposto, a issue é o que existe. Uma query paginada de itens do
- * project resolve Etapa e tipo de todo mundo de uma vez, no lugar do laço de
- * duas chamadas por Story que o modo de uma Feature ainda usa.
+ * que foi proposto, a issue é o que existe. (As ARESTAS, essas sim, vêm dos
+ * artefatos locais — ver o cabeçalho.) Uma query paginada de itens do project
+ * resolve Etapa e tipo de todo mundo de uma vez.
  */
-async function orderBoard({ token, owner, repo }) {
+async function orderBoard({ token, owner, repo, root, ttlSec, opts }) {
   const { project, error: projectError } = loadProjectConfig();
   if (projectError) {
-    p.log.error(
+    emitError(opts,
       `${projectError} — sem board não há como saber quais Features têm trabalho. ` +
       'Use `spec-wave order <feature>` para ordenar uma Feature específica.'
     );
@@ -115,50 +134,60 @@ async function orderBoard({ token, owner, repo }) {
     return;
   }
 
-  let itens;
+  let snapshot;
   try {
-    itens = await listProjectItems(token, project.id);
+    snapshot = await loadBoardSnapshot({ token, project, root, refresh: opts.refresh, ttlSec });
   } catch (err) {
-    p.log.error(`Não foi possível ler os itens do Project: ${err.message}`);
+    emitError(opts, `Não foi possível ler os itens do Project: ${err.message}`);
     process.exitCode = 1;
     return;
   }
-  const indice = indexBoardItems(itens);
-  const features = selectOpenFeatures(itens);
+
+  let features = selectOpenFeatures(snapshot.items);
+  if (opts.milestone) {
+    features = filterItemsByMilestone(features, opts.milestone);
+    if (features.length === 0) {
+      emitInfo(opts, `Nenhuma Feature aberta na milestone "${opts.milestone}" — nada a ordenar.`);
+      return;
+    }
+  }
   if (features.length === 0) {
-    p.log.info(`Nenhuma Feature aberta fora de "${STAGE_DONE}" no board — nada a ordenar.`);
-    p.outro('Nada a fazer.');
+    emitInfo(opts, `Nenhuma Feature aberta fora de "${STAGE_DONE}" no board — nada a ordenar.`);
     return;
   }
 
+  const indice = snapshot.index;
   const enriched = [];
   const featureOf = new Map();
   const stageOf = new Map();
   const semStories = [];
+  const origins = new Set();
+  const warnings = [];
   for (const feature of features) {
-    const subs = await listSubIssues(token, feature.nodeId).catch(() => []);
-    const stories = subs.filter(sub =>
-      detectIssueType({ title: sub.title, labels: sub.labels }) === 'Story');
-    if (stories.length === 0) { semStories.push(feature); continue; }
-    for (const story of stories) {
+    let carga;
+    try {
+      carga = await loadFeatureStories({
+        token, owner, repo, root, feature,
+        remote: opts.remote, refresh: opts.refresh, ttlSec,
+      });
+    } catch (err) {
+      warnings.push(`Stories da Feature #${feature.number} não legíveis: ${err.message}.`);
+      continue;
+    }
+    origins.add(carga.origin.edges);
+    warnings.push(...carga.warnings);
+    if (carga.stories.length === 0) { semStories.push(feature); continue; }
+    for (const story of carga.stories) {
       // Story concluída não entra: o mapa é do que falta fazer.
       if (indice.get(story.number)?.fields?.Etapa === STAGE_DONE) continue;
-      const fromBody = parseDependencies(story.body);
-      const fromBlockedBy = (await listBlockedBy(token, owner, repo, story.number).catch(() => []))
-        .map(b => b.number);
-      enriched.push({
-        number: story.number,
-        title: story.title,
-        dependsOn: [...new Set([...fromBody, ...fromBlockedBy])],
-      });
+      enriched.push({ number: story.number, title: story.title, dependsOn: story.dependsOn });
       featureOf.set(story.number, feature);
       stageOf.set(story.number, indice.get(story.number)?.fields?.Etapa || null);
     }
   }
 
   if (enriched.length === 0) {
-    p.log.info(`${features.length} Feature(s) aberta(s), nenhuma com Story pendente.`);
-    p.outro('Nada a fazer.');
+    emitInfo(opts, `${features.length} Feature(s) aberta(s), nenhuma com Story pendente.`);
     return;
   }
 
@@ -166,6 +195,21 @@ async function orderBoard({ token, owner, repo }) {
   const { order: sorted, cycle, external } = orderStories(
     enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
 
+  const stale = snapshot.fromCache ? stalenessNotice(snapshot.fetchedAt) : null;
+
+  if (opts.json) {
+    console.log(JSON.stringify(renderOrderJson({
+      sorted, byNumber, featureOf, stageOf, external, cycle,
+      meta: {
+        edges: [...origins].join(','),
+        stages: snapshot.fromCache ? 'cache' : 'board',
+        fetchedAt: snapshot.fetchedAt,
+        warnings: [...warnings, ...(stale ? [stale] : [])],
+      },
+    }), null, 2));
+    return;
+  }
+
   if (cycle.length > 0) {
     p.log.warn(
       chalk.yellow.bold('⚠ CICLO DE DEPENDÊNCIAS detectado!') + '\n' +
@@ -194,57 +238,94 @@ async function orderBoard({ token, owner, repo }) {
   if (semStories.length > 0) {
     p.log.info(`Sem Stories (ainda não decompostas): ${semStories.map(f => `#${f.number}`).join(', ')}.`);
   }
+  for (const w of warnings) p.log.warn(w);
+  p.log.info(chalk.dim(edgesNote(origins, opts)));
+  if (stale) p.log.warn(chalk.yellow(stale));
   p.outro(`${chalk.green('✓')} ${sorted.length} de ${enriched.length} story(ies) ordenada(s).`);
 }
 
-export async function order({ feature: featureArg } = {}) {
+// Saída de erro/info compatível com --json (que não pode misturar clack com o
+// contrato): em json, erros vão para stderr e o stdout fica só com o JSON.
+function emitError(opts, message) {
+  if (opts.json) console.error(message);
+  else p.log.error(message);
+}
+function emitInfo(opts, message) {
+  if (opts.json) {
+    console.log(JSON.stringify(renderOrderJson({ meta: { warnings: [message] } }), null, 2));
+  } else {
+    p.log.info(message);
+    p.outro('Nada a fazer.');
+  }
+}
+
+export async function order({
+  feature: featureArg, json = false, milestone = null, remote = false,
+  refresh = false, sync = false,
+} = {}) {
   const semArgumento = featureArg === undefined || featureArg === null
     || String(featureArg).trim() === '';
   const featureNumber = parseInt(String(featureArg).replace('#', ''), 10);
+  const opts = { json, milestone, remote, refresh, sync };
   if (!semArgumento && (!Number.isInteger(featureNumber) || featureNumber <= 0)) {
-    p.log.error(`Feature inválida: "${featureArg}". Use o número da issue, ex.: 12 ou #12.`);
+    emitError(opts, `Feature inválida: "${featureArg}". Use o número da issue, ex.: 12 ou #12.`);
     process.exitCode = 1;
     return;
   }
 
   const { owner, repo } = resolveRepoContext();
   if (!owner || !repo) {
-    p.log.error(
+    emitError(opts,
       'Não foi possível determinar owner/repo.\n' +
       `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`) ou defina GITHUB_REPOSITORY=owner/repo.`
     );
     process.exitCode = 1;
     return;
   }
+  const { config, root } = loadConfig();
+  const ttlSec = resolveCacheTtl(config);
 
   let token;
   try {
     token = await resolveToken();
   } catch (err) {
-    p.log.error(err.message);
+    emitError(opts, err.message);
     process.exitCode = 1;
     return;
   }
 
+  if (sync) {
+    if (!root) {
+      emitError(opts, `--sync precisa de um clone com ${CONFIG_FILE} (o doc é reescrito no disco).`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!json) p.intro(chalk.bold('spec-wave order --sync — dependências da API de volta ao doc'));
+    return await syncDependencies({
+      token, owner, repo, root, opts,
+      featureNumber: semArgumento ? null : featureNumber,
+    });
+  }
+
   if (semArgumento) {
-    p.intro(chalk.bold('spec-wave order — todas as Features com trabalho'));
-    return await orderBoard({ token, owner, repo });
+    if (!json) p.intro(chalk.bold('spec-wave order — todas as Features com trabalho'));
+    return await orderBoard({ token, owner, repo, root, ttlSec, opts });
   }
 
-  p.intro(chalk.bold(`spec-wave order #${featureNumber}`));
+  if (!json) p.intro(chalk.bold(`spec-wave order #${featureNumber}`));
 
-  // 1. Lê a Feature e valida o tipo.
+  // 1. Lê a Feature e valida o tipo (1 chamada — a issue-alvo nunca vem de cache).
   let featureIssue;
   try {
     featureIssue = await getIssue(token, owner, repo, featureNumber);
   } catch (err) {
-    p.log.error(`Não foi possível ler a issue #${featureNumber}: ${err.message}`);
+    emitError(opts, `Não foi possível ler a issue #${featureNumber}: ${err.message}`);
     process.exitCode = 1;
     return;
   }
   const type = detectIssueType(featureIssue);
   if (type !== 'Feature') {
-    p.log.error(
+    emitError(opts,
       `\`spec-wave order\` só aceita issues do tipo Feature. ` +
       `Issue #${featureNumber} é do tipo ${type || 'desconhecido'} (${featureIssue.title}).`
     );
@@ -252,53 +333,47 @@ export async function order({ feature: featureArg } = {}) {
     return;
   }
 
-  // 2. Sub-issues da Feature → só as Stories entram na ordenação.
-  let subs;
+  // 2-3. Stories + arestas — fontes locais (mapa/doc/body), `--remote` opcional.
+  let carga;
   try {
-    subs = await listSubIssues(token, featureIssue.node_id);
+    carga = await loadFeatureStories({
+      token, owner, repo, root,
+      feature: { number: featureNumber, nodeId: featureIssue.node_id, title: featureIssue.title },
+      remote, refresh, ttlSec,
+    });
   } catch (err) {
-    p.log.error(`Não foi possível listar as sub-issues da Feature #${featureNumber}: ${err.message}`);
+    emitError(opts, `Não foi possível listar as sub-issues da Feature #${featureNumber}: ${err.message}`);
     process.exitCode = 1;
     return;
   }
-  const stories = subs.filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+  const stories = carga.stories;
   if (stories.length === 0) {
-    p.log.info(`Feature #${featureNumber} não tem Stories (sub-issues) — nada a ordenar. Rode \`spec-wave decompose\` antes.`);
-    p.outro('Nada a fazer.');
+    emitInfo(opts, `Feature #${featureNumber} não tem Stories (sub-issues) — nada a ordenar. Rode \`spec-wave decompose\` antes.`);
     return;
   }
-
-  // 3. Dependências de cada Story: linha "Depende de: #N" do corpo (buscando o
-  // corpo via getIssue quando listSubIssues não o trouxer) mesclada com a
-  // relação nativa blocked_by (falha na API → sem bloqueios, não interrompe).
-  const enriched = await Promise.all(stories.map(async (s) => {
-    let body = s.body;
-    if (!body) {
-      body = (await getIssue(token, owner, repo, s.number).catch(() => null))?.body || '';
-    }
-    const fromBody = parseDependencies(body);
-    const fromBlockedBy = (await listBlockedBy(token, owner, repo, s.number).catch(() => []))
-      .map(b => b.number);
-    const dependsOn = [...new Set([...fromBody, ...fromBlockedBy])];
-    return { number: s.number, title: s.title, nodeId: s.nodeId, dependsOn };
+  const enriched = stories.map(s => ({
+    number: s.number, title: s.title, nodeId: s.nodeId, dependsOn: s.dependsOn,
   }));
 
-  // 4. Etapa atual de cada Story no board (falha em qualquer leitura → '—').
+  // 4. Etapa de cada Story — snapshot único do board, com TTL (nunca mais a
+  // mutação addProjectItem por Story: além do custo, ADICIONAVA a issue ao
+  // Project como efeito colateral de uma leitura).
   const stageOf = new Map();
+  let boardMeta = { stages: null, fetchedAt: null, stale: null };
   const { project, error: projectError } = loadProjectConfig();
   if (projectError) {
-    p.log.warn(`${projectError} — Etapas do board não consultadas.`);
+    if (!json) p.log.warn(`${projectError} — Etapas do board não consultadas.`);
   } else {
-    const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
-    if (etapaField?.id) {
-      await Promise.all(enriched.map(async (s) => {
-        try {
-          const itemId = await addProjectItem(token, project.id, s.nodeId);
-          stageOf.set(s.number, await getItemSingleSelectValue(token, itemId, etapaField.id));
-        } catch {
-          stageOf.set(s.number, null);
-        }
-      }));
+    try {
+      const snapshot = await loadBoardSnapshot({ token, project, root, refresh, ttlSec });
+      for (const s of enriched) stageOf.set(s.number, snapshot.index.get(s.number)?.fields?.Etapa ?? null);
+      boardMeta = {
+        stages: snapshot.fromCache ? 'cache' : 'board',
+        fetchedAt: snapshot.fetchedAt,
+        stale: snapshot.fromCache ? stalenessNotice(snapshot.fetchedAt) : null,
+      };
+    } catch (err) {
+      if (!json) p.log.warn(`Etapas do board não consultáveis agora: ${err.message}`);
     }
   }
 
@@ -307,17 +382,34 @@ export async function order({ feature: featureArg } = {}) {
   const { order: sorted, cycle, external } = orderStories(
     enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
 
-  // Uma leitura por issue externa DISTINTA — o estado dela é o que diz se o
-  // bloqueio ainda vale.
+  // Uma leitura por issue externa DISTINTA — cacheada (`issue-<n>`): é exibição,
+  // não decisão de escrita.
   const foraDoConjunto = [...new Set([...external.values()].flat())];
   const externasInfo = new Map();
   await Promise.all(foraDoConjunto.map(async (n) => {
-    const issue = await getIssue(token, owner, repo, n).catch(() => null);
-    externasInfo.set(n, issue
-      ? { title: issue.title, state: issue.state, aberta: issue.state === 'open' }
-      : { title: '(não foi possível ler)', state: null, aberta: true });
+    externasInfo.set(n, await externalIssueInfo({ token, owner, repo, root, number: n, refresh, ttlSec }));
   }));
 
+  if (opts.json) {
+    console.log(JSON.stringify(renderOrderJson({
+      sorted,
+      byNumber,
+      featureOf: new Map(enriched.map(s => [s.number, { number: featureNumber, title: featureIssue.title }])),
+      stageOf, external, cycle,
+      meta: {
+        edges: carga.origin.edges,
+        stages: boardMeta.stages,
+        fetchedAt: boardMeta.fetchedAt,
+        warnings: [
+          ...carga.warnings,
+          ...milestoneMismatches(featureIssue.milestone, stories),
+          ...(boardMeta.stale ? [boardMeta.stale] : []),
+        ],
+      },
+    }), null, 2));
+    return;
+  }
+
   if (cycle.length > 0) {
     p.log.warn(
       chalk.yellow.bold('⚠ CICLO DE DEPENDÊNCIAS detectado!') + '\n' +
@@ -341,7 +433,8 @@ export async function order({ feature: featureArg } = {}) {
       const detalhe = deps.map(d => {
         const info = externasInfo.get(d);
         const marca = info?.aberta ? chalk.yellow('aberta') : chalk.green('fechada');
-        return `#${d} (${marca}) ${info?.title || ''}`.trim();
+        const cacheTag = info?.fromCache ? chalk.dim(' (cache)') : '';
+        return `#${d} (${marca}${cacheTag}) ${info?.title || ''}`.trim();
       }).join('\n      ');
       return `  #${n} ${byNumber.get(n)?.title || ''}\n    ← ${detalhe}`;
     });
@@ -392,5 +485,166 @@ export async function order({ feature: featureArg } = {}) {
     );
   }
 
+  for (const w of carga.warnings) p.log.warn(w);
+  p.log.info(chalk.dim(edgesNote([carga.origin.edges], opts)));
+  if (boardMeta.stale) p.log.warn(chalk.yellow(boardMeta.stale));
   p.outro(`${chalk.green('✓')} ${sorted.length} de ${enriched.length} story(ies) ordenada(s).`);
 }
+
+// ── `order --sync`: API → decomposition.md + dependency-map.json ────────────
+
+// Commit LOCAL escopado aos artefatos reescritos + push com retry — mesmo
+// padrão do bug.md do qa (git-retry). Falha de push degrada para aviso: os
+// arquivos já estão certos no disco.
+function commitSyncedFiles(root, filesRel, featureNumber) {
+  try {
+    for (const rel of filesRel) {
+      execSync(`git add -- ${JSON.stringify(rel)}`, { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    execSync(
+      `git commit -m ${JSON.stringify(`docs: sync de dependências da Feature #${featureNumber} [spec-wave]`)} ` +
+      filesRel.map(r => `-- ${JSON.stringify(r)}`).join(' '),
+      { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
+    return true;
+  } catch (err) {
+    p.log.warn(`⚠️  Arquivos escritos, mas o commit falhou (${String(err.message).split('\n')[0]}) — commite-os você mesmo.`);
+    return false;
+  }
+}
+
+async function syncDependencies({ token, owner, repo, root, opts, featureNumber }) {
+  // Alvos: a Feature pedida, ou as Features abertas do board (--milestone filtra).
+  let targets = [];
+  if (featureNumber) {
+    const issue = await getIssue(token, owner, repo, featureNumber).catch((err) => {
+      emitError(opts, `Não foi possível ler a issue #${featureNumber}: ${err.message}`);
+      return null;
+    });
+    if (!issue) { process.exitCode = 1; return; }
+    if (detectIssueType(issue) !== 'Feature') {
+      emitError(opts, `--sync só aceita Feature. Issue #${featureNumber} é ${detectIssueType(issue) || 'de tipo desconhecido'}.`);
+      process.exitCode = 1;
+      return;
+    }
+    targets = [{ number: featureNumber, nodeId: issue.node_id, title: issue.title }];
+  } else {
+    const { project, error } = loadProjectConfig();
+    if (error) {
+      emitError(opts, `${error} — sem board não há como enumerar as Features. Use \`order <feature> --sync\`.`);
+      process.exitCode = 1;
+      return;
+    }
+    // Sync é reconciliação: sempre parte de um snapshot FRESCO.
+    const snapshot = await loadBoardSnapshot({ token, project, root, refresh: true });
+    let features = selectOpenFeatures(snapshot.items);
+    if (opts.milestone) features = filterItemsByMilestone(features, opts.milestone);
+    targets = features;
+  }
+
+  let synced = 0;
+  let untouched = 0;
+  for (const feature of targets) {
+    const resultado = await syncOneFeature({ token, owner, repo, root, feature });
+    if (resultado === 'synced') synced += 1;
+    else if (resultado === 'unchanged') untouched += 1;
+  }
+  p.outro(`${chalk.green('✓')} sync: ${synced} Feature(s) atualizada(s), ${untouched} já em dia.`);
+}
+
+async function syncOneFeature({ token, owner, repo, root, feature }) {
+  let paths;
+  try {
+    paths = featureDocPaths(root, { title: feature.title }, 'Feature');
+  } catch {
+    p.log.warn(`#${feature.number}: título sem slug utilizável — pulada.`);
+    return 'skipped';
+  }
+  const docAbs = path.join(root, paths.decomposition.rel);
+  if (!existsSync(docAbs)) {
+    p.log.info(chalk.dim(`#${feature.number}: sem ${paths.decomposition.rel} — nada a sincronizar.`));
+    return 'skipped';
+  }
+  let doc;
+  try {
+    doc = parseDecompositionDoc(readFileSync(docAbs, 'utf-8'));
+  } catch (err) {
+    p.log.warn(`#${feature.number}: ${paths.decomposition.rel} ilegível (${err.message}) — pulada.`);
+    return 'skipped';
+  }
+  if (!doc.appliedAt || doc.kind !== 'stories') {
+    p.log.info(chalk.dim(`#${feature.number}: decomposition.md ainda é proposta (ou é de RFC) — nada a sincronizar.`));
+    return 'skipped';
+  }
+
+  // Leitura VIVA: body ∪ blocked_by, sempre frescos — sync que lê cache
+  // reconciliaria o doc com ele mesmo.
+  const subs = (await listSubIssues(token, feature.nodeId || feature.node_id))
+    .filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+  const remoteEdges = [];
+  for (const s of subs) {
+    const blockedBy = (await listBlockedBy(token, owner, repo, s.number).catch(() => []))
+      .map(b => b.number);
+    remoteEdges.push({ number: s.number, dependsOn: blockedBy });
+  }
+  const liveDeps = mergeDependencyEdges(
+    subs.map(s => ({ number: s.number, dependsOn: parseDependencies(s.body) })),
+    remoteEdges,
+  );
+
+  const { doc: updated, changed, changes } = syncDocDependencies(doc, liveDeps);
+
+  // O mapa é SEMPRE regenerado ("forçar update dos artefatos"): mesmo sem
+  // aresta nova, ele pode nem existir ainda (repo de antes desta versão).
+  const mapRel = paths['dependency-map'].rel;
+  const mapAbs = path.join(root, mapRel);
+  const generatedAt = new Date().toISOString();
+  const mapStories = (updated.stories || []).map((s, i) => ({
+    number: s.issue,
+    title: s.title,
+    dependsOn: [...new Set([
+      ...(s.dependsOn || []).map(idx => updated.stories[idx]?.issue).filter(Number.isInteger),
+      ...(s.dependsOnIssues || []),
+    ])],
+    tasks: (s.tasks || []).map(t => t.issue).filter(Number.isInteger),
+  }));
+  const mapAntes = existsSync(mapAbs) ? readFileSync(mapAbs, 'utf-8') : null;
+  const mapConteudo = `${JSON.stringify(buildDependencyMap({
+    featureNumber: feature.number, stories: mapStories, source: 'sync', generatedAt,
+  }), null, 2)}\n`;
+  // Compara sem o generatedAt: regravar SÓ por causa do timestamp criaria um
+  // commit de ruído por sync.
+  const semTimestamp = (txt) => String(txt ?? '').replace(/"generatedAt": "[^"]*"/, '"generatedAt": "-"')
+    .replace(/"source": "[^"]*"/, '"source": "-"');
+  const mapMudou = semTimestamp(mapAntes) !== semTimestamp(mapConteudo);
+
+  if (!changed && !mapMudou) {
+    p.log.info(chalk.dim(`#${feature.number}: dependências já em dia.`));
+    return 'unchanged';
+  }
+
+  const escritos = [];
+  if (changed) {
+    writeFileSync(docAbs, renderDecompositionDoc(updated));
+    escritos.push(paths.decomposition.rel);
+    for (const c of changes) {
+      p.log.info(
+        `#${feature.number} · Story #${c.story}: Depende de ` +
+        `${c.before.map(n => `#${n}`).join(', ') || '—'} → ${c.after.map(n => `#${n}`).join(', ') || '—'}`
+      );
+    }
+  }
+  if (mapMudou) {
+    writeFileSync(mapAbs, mapConteudo);
+    escritos.push(mapRel);
+  }
+
+  const committed = commitSyncedFiles(root, escritos, feature.number);
+  if (committed) {
+    const push = await pushWithRebase({ cwd: root });
+    if (!push.ok) {
+      p.log.warn(`⚠️  Sync commitado, mas o push falhou: ${String(push.error).split('\n')[0]} — pushe manualmente.`);
+    }
+  }
+  p.log.success(`#${feature.number}: ${escritos.join(' + ')} atualizado(s).`);
+  return 'synced';
+}