@spec-wave/cli 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-graphql.mjs

@@ -343,6 +343,7 @@ export async function listSubIssues(token, issueNodeId) {
               createdAt
               state
               stateReason
+              milestone { number title }
               labels(first: 20) { nodes { name } }
             }
           }
@@ -363,10 +364,46 @@ export async function listSubIssues(token, issueNodeId) {
     // distinguir "entregue" de "descartada no rescopo".
     state: (n.state || '').toLowerCase() || null,
     stateReason: (n.stateReason || '').toLowerCase() || null,
+    // O `order` compara com o milestone do pai: sub-issue sem milestone (ou em
+    // outro) é tão invisível numa visão de release quanto Etapa vazia no board.
+    milestone: n.milestone ? { number: n.milestone.number, title: n.milestone.title } : null,
     labels: (n.labels?.nodes || []).map(l => l.name),
   }));
 }
 
+/**
+ * Os PRs que o GitHub reconhece como fechadores DESTA issue — o inverso de
+ * listLinkedIssuesForPR, pela mesma fonte de vínculo (`Closes #N` + UI). É como
+ * o `merge` descobre o PR de cada Story sem depender de convenção de nome de
+ * branch. `includeClosedPrs` de propósito: PR já mergeado é o que diz que a
+ * Story está entregue.
+ *
+ * @returns {Promise<Array<{number, state, merged, isDraft, baseRefName, headRefName}>>}
+ */
+export async function listIssuePullRequests(token, issueNodeId) {
+  const client = makeClient(token);
+  const result = await client(`
+    query IssuePRs($id: ID!) {
+      node(id: $id) {
+        ... on Issue {
+          closedByPullRequestsReferences(first: 20, includeClosedPrs: true) {
+            nodes { number state merged isDraft baseRefName headRefName }
+          }
+        }
+      }
+    }
+  `, { id: issueNodeId });
+  const nodes = result.node?.closedByPullRequestsReferences?.nodes || [];
+  return nodes.map(n => ({
+    number: n.number,
+    state: (n.state || '').toLowerCase(), // open | closed | merged
+    merged: Boolean(n.merged),
+    isDraft: Boolean(n.isDraft),
+    baseRefName: n.baseRefName || null,
+    headRefName: n.headRefName || null,
+  }));
+}
+
 /**
  * Issues que o GitHub reconhece como fechadas por este PR
  * (`Closes #N` e o vínculo feito pela UI). É a MESMA lista que fecha as issues

package/src/api/github-rest.mjs

@@ -294,6 +294,33 @@ export async function createIssue(token, owner, repo, title, body, labels, { mil
   return { number: res.data.number, nodeId: res.data.node_id, url: res.data.html_url, id: res.data.id };
 }
 
+// Milestones do repositório (abertas e fechadas).
+//
+// O usuário fala o TÍTULO da milestone ("v06"), a API de issues filtra pelo
+// NÚMERO. A tradução mora aqui — e a lista completa também serve para a
+// mensagem de erro: "milestone não encontrada" sem dizer quais existem manda o
+// usuário adivinhar entre nome errado e API fora do ar.
+export async function listMilestones(token, owner, repo) {
+  const octokit = makeOctokit(token);
+  return await octokit.paginate(octokit.rest.issues.listMilestones, {
+    owner, repo, state: 'all', per_page: 100,
+  });
+}
+
+// Issues de uma milestone (pelo NÚMERO dela), abertas e fechadas.
+//
+// `state: 'all'` de propósito: uma Feature fechada continua contando para o
+// inventário — o que muda é que ela não entra na lista do que gerar.
+export async function listIssuesByMilestone(token, owner, repo, milestoneNumber) {
+  const octokit = makeOctokit(token);
+  const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
+    owner, repo, milestone: String(milestoneNumber), state: 'all', per_page: 100,
+  });
+  // `listForRepo` devolve Pull Requests junto — eles são issues para a API, e
+  // não para o fluxo.
+  return issues.filter(i => !i.pull_request);
+}
+
 export async function getIssue(token, owner, repo, issueNumber) {
   const octokit = makeOctokit(token);
   const res = await octokit.rest.issues.get({ owner, repo, issue_number: issueNumber });
@@ -484,6 +511,27 @@ export async function getFileContent(token, owner, repo, path, ref) {
   }
 }
 
+// Reaponta a BASE de um PR aberto. Usado pelo `merge` numa pilha de Stories:
+// depois que o PR anterior mergeia, o dependente é reapontado para a default
+// ANTES de qualquer branch ser apagada — apagar primeiro foi o que fechou um
+// PR empilhado sem volta.
+export async function updatePRBase(token, owner, repo, prNumber, base) {
+  const octokit = makeOctokit(token);
+  await octokit.rest.pulls.update({ owner, repo, pull_number: prNumber, base });
+}
+
+// Mergeia um PR. `merge` (commit de merge) é o método da pilha de Stories:
+// squash reescreveria o merge-base dos dependentes e o retarget deixaria de
+// ser limpo. O GitHub recusa (405) draft, check obrigatório pendente e
+// conflito — o chamador decide o que fazer com a fila.
+export async function mergePR(token, owner, repo, prNumber, { method = 'merge' } = {}) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.pulls.merge({
+    owner, repo, pull_number: prNumber, merge_method: method,
+  });
+  return { merged: Boolean(res.data.merged), sha: res.data.sha || null };
+}
+
 export async function listPullRequestReviews(token, owner, repo, prNumber) {
   const octokit = makeOctokit(token);
   return await octokit.paginate(octokit.rest.pulls.listReviews, {

package/src/cli.mjs

@@ -147,7 +147,7 @@ export function buildProgram() {
     .command('run')
     .description('Executa LOCALMENTE o próximo passo do fluxo (o que a label dispararia no Actions)')
     .argument('[issue]', 'Número da issue (Feature, Bug ou RFC)')
-    .option('--pr <n>', 'Modo PR: decide entre code-review e qa pelo estado das reviews')
+    .option('--pr <n>', 'Modo PR: decide entre code-review e qa pelo estado das reviews e do merge')
     .option('--dry-run', 'Decide e explica sem executar nada')
     .option('--yes', 'Confirma o passo que exige confirmação')
     .option('--apply', 'Autoriza especificamente o decompose-apply (erra se o passo pendente for outro)')
@@ -162,6 +162,27 @@ export function buildProgram() {
       await run(issue, options).catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  program
+    .command('preflight')
+    .description('Confere, antes de gerar, tudo que decide uma rodada de specs de uma milestone')
+    .requiredOption('--milestone <nome>', 'Título da milestone a inventariar')
+    .option('--json', 'Imprime o relatório em JSON')
+    .action(async (options) => {
+      const { preflight } = await import('./commands/preflight.mjs');
+      await preflight(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('audit')
+    .description('Cruza as specs de uma milestone: dependência órfã, bloqueante em milestone posterior, sobreposição com código')
+    .requiredOption('--milestone <nome>', 'Título da milestone a auditar')
+    .option('--critique', 'Roda também a crítica adversarial de conjunto (uma chamada de modelo por milestone)')
+    .option('--json', 'Imprime o relatório em JSON')
+    .action(async (options) => {
+      const { audit } = await import('./commands/audit.mjs');
+      await audit(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
   program
     .command('mode')
     .description('Mostra ou alterna o modo de execução: `actions` (workflows) ou `local` (esta máquina)')
@@ -188,6 +209,8 @@ export function buildProgram() {
     .option('--branch [nome]', 'Envia os arquivos do repo como Pull Request numa branch, em um único commit (sem valor: spec-wave/update-v<versão>)')
     .option('--config-in-pr', 'Força incluir o .spec-wave.json no Pull Request')
     .option('--no-config-in-pr', 'Força manter o .spec-wave.json fora do Pull Request')
+    .option('--skill-in-pr', 'Força incluir a skill dos agentes no Pull Request')
+    .option('--no-skill-in-pr', 'Força manter a skill dos agentes fora do Pull Request')
     .option('--dry-run', 'Mostra o que seria atualizado sem alterar nada')
     .option('--yes', 'Aplica sem pedir confirmação')
     .action(async (options) => {
@@ -297,7 +320,7 @@ export function buildProgram() {
 
   program
     .command('qa')
-    .description('Move Feature para QA ao aprovar um PR (usado pelo GitHub Action)')
+    .description('Move Feature para QA ao aprovar ou mergear um PR (usado pelo GitHub Action)')
     .requiredOption('--pr-number <n>', 'Número do Pull Request')
     .action(async (options) => {
       const { qa } = await import('./commands/qa.mjs');
@@ -324,6 +347,18 @@ export function buildProgram() {
       await order({ feature }).catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  program
+    .command('merge')
+    .description('Mergeia os PRs empilhados das Stories de uma Feature na ordem topológica e move o board até QA')
+    .argument('<feature>', 'Número da issue da Feature, ex.: 12 ou #12')
+    .option('--yes', 'Executa os merges (sem isso, só mostra o plano)')
+    .option('--dry-run', 'Mostra o plano e sai')
+    .option('--keep-branches', 'Não apaga as branches das Stories depois do merge')
+    .action(async (feature, options) => {
+      const { merge } = await import('./commands/merge.mjs');
+      await merge({ feature, ...options }).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
   program
     .command('task')
     .description('Gerencia uma Task no board: start (Status "In Progress") ou done (Done)')
@@ -396,5 +431,19 @@ export function buildProgram() {
       await doctor().catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  // O mapa por tema no fim do --help: 29 comandos em lista plana dizem O QUE
+  // cada um faz, mas não POR ONDE começar nem em que ordem o fluxo anda.
+  program.addHelpText('after', `
+Fluxo típico (cada tema, na ordem):
+  configurar     init · doctor · mode <actions|local> · update
+  especificar    preflight --milestone → specs (label ou run) → audit --milestone [--critique]
+  planejar       run <issue> (plan → critique → validate) → move <n> ready
+  decompor       run <issue> (decompose → --apply) → order <feature>
+  implementar    implement <issue> · task start/done · story review
+  entregar       merge <feature> (PRs empilhados, na ordem) · run --pr <n> (board até QA)
+  acompanhar     info · order · move · repair-stage
+
+Docs: https://astratech-net-br.github.io/spec-wave-cli/  ·  spec-wave <comando> --help`);
+
   return program;
 }

package/src/commands/audit.mjs

@@ -0,0 +1,280 @@
+// Auditoria de dependências de uma milestone — o passo entre "as specs estão
+// mergeadas" e "vamos gerar os planos".
+//
+// A crítica adversarial roda por Feature; este comando cruza as specs COMO
+// CONJUNTO e responde as três perguntas que hoje só apareciam se alguém lesse
+// as dez juntas: alguma dependência declarada não é criada por ninguém? Alguma
+// bloqueante vive em milestone posterior à de quem depende dela? Alguma spec
+// descreve o que já existe em código?
+//
+// Toda a decisão mora em `lib/spec-audit.mjs` (puro); aqui é só coleta: as
+// Features de todas as milestones (o catálogo do que uma spec pode citar), o
+// conteúdo da spec de cada Feature-alvo nas quatro camadas (loadArtifact — uma
+// spec em PR aberto também é auditável), e a lista de arquivos do repositório
+// para a heurística de código.
+//
+// Comando LOCAL, fora da tabela STEPS de propósito: ele é por milestone, não
+// por issue — não há label que o dispare nem lugar para ela no fluxo.
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, getRepoDefaultBranch, listMilestones, listIssuesByMilestone,
+} from '../api/github-rest.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { featureDocPaths } from '../lib/doc-paths.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { runCritique } from '../lib/critique.mjs';
+import { slugify } from '../lib/slugify.mjs';
+import { loadStaticTechContext, TECH_CONTEXT_PATH } from '../lib/tech-context.mjs';
+import {
+  auditMilestone, auditVerdict, dependencySection, issueRefs,
+} from '../lib/spec-audit.mjs';
+import { resolveMilestone } from './preflight.mjs';
+
+// A heurística de código procura componente/rota, não texto: docs/ casaria com
+// o próprio slug da spec, e um README citando a feature não é implementação.
+const IGNORED_DIRS = new Set([
+  'node_modules', 'dist', 'build', 'coverage', 'vendor', 'target', 'tmp', 'docs',
+]);
+const IGNORED_EXTS = new Set(['.md', '.txt', '.lock', '.log', '.svg', '.png', '.jpg']);
+const MAX_FILES = 20000;
+
+/**
+ * Caminhos relativos dos arquivos do repositório (I/O — nunca lança).
+ * Profundidade e volume limitados: é insumo de heurística, não um índice.
+ */
+export function listRepoFiles(root, { maxFiles = MAX_FILES, maxDepth = 8 } = {}) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > maxDepth || out.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= maxFiles) return;
+      if (e.name.startsWith('.') || IGNORED_DIRS.has(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) walk(abs, depth + 1);
+      else if (e.isFile() && !IGNORED_EXTS.has(path.extname(e.name).toLowerCase())) {
+        out.push(path.relative(root, abs));
+      }
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+export async function audit({ milestone: milestoneArg, critique = false, json = false } = {}) {
+  const falhar = (msg) => {
+    if (json) console.log(JSON.stringify({ erro: msg }, null, 2));
+    else p.log.error(msg);
+    process.exitCode = 1;
+  };
+
+  if (!json) p.intro(chalk.bold('spec-wave audit — dependências da milestone'));
+
+  const { config, root, error: configError } = loadConfig();
+  if (configError || !config?.owner || !config?.repo) {
+    return falhar(`${configError || `${CONFIG_FILE} sem owner/repo`} — rode \`spec-wave init\` antes.`);
+  }
+  const { owner, repo } = config;
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    return falhar(`Sem token utilizável para ${owner}/${repo}: ${err.message}`);
+  }
+
+  const s = json ? null : p.spinner();
+  s?.start('Montando o catálogo de Features...');
+
+  let base;
+  let milestones;
+  try {
+    base = await getRepoDefaultBranch(token, owner, repo);
+    milestones = await listMilestones(token, owner, repo);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível ler o repositório ${owner}/${repo}: ${err.message}`);
+  }
+  const { milestone, error: msError } = resolveMilestone(milestones, milestoneArg);
+  if (msError) {
+    s?.stop('');
+    return falhar(msError);
+  }
+
+  // O catálogo vem de TODAS as milestones: a inversão de sequenciamento é
+  // exatamente uma dependência que resolve para FORA da milestone-alvo.
+  const catalog = [];
+  let targetIssues = [];
+  try {
+    for (const m of milestones) {
+      const issues = await listIssuesByMilestone(token, owner, repo, m.number);
+      if (m.number === milestone.number) targetIssues = issues;
+      for (const i of issues) {
+        if (detectIssueType(i) !== 'Feature') continue;
+        catalog.push({
+          number: i.number,
+          title: i.title,
+          slug: slugify(i.title),
+          closed: i.state === 'closed',
+          milestone: { number: m.number, title: m.title, due_on: m.due_on ?? null },
+        });
+      }
+    }
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível listar as issues por milestone: ${err.message}`);
+  }
+
+  // A spec de cada Feature-alvo, nas quatro camadas (disco, base, branch, PR) —
+  // em série pelo mesmo motivo do preflight: rate limit secundário.
+  const features = [];
+  for (const issue of targetIssues) {
+    if (detectIssueType(issue) !== 'Feature' || issue.state === 'closed') continue;
+    const docs = featureDocPaths(root, issue, 'Feature');
+    const { content } = await loadArtifact({
+      token, owner, repo, root, base,
+      pathRel: docs.spec.rel, doc: 'spec', issueNumber: issue.number,
+    });
+    features.push({
+      number: issue.number,
+      title: issue.title,
+      slug: slugify(issue.title),
+      milestone: { number: milestone.number, title: milestone.title, due_on: milestone.due_on ?? null },
+      spec: content,
+    });
+  }
+
+  if (features.length === 0) {
+    s?.stop('');
+    return falhar(`Nenhuma Feature aberta na milestone "${milestone.title}".`);
+  }
+
+  // Referências `#N` que o catálogo não conhece: issue sem milestone, Story de
+  // outra Feature, ou número que não existe. A API é quem diferencia.
+  const conhecidas = new Set(catalog.map(f => f.number));
+  const desconhecidas = new Set();
+  for (const f of features) {
+    const section = f.spec ? dependencySection(f.spec) : null;
+    for (const n of issueRefs(section || '')) {
+      if (!conhecidas.has(n)) desconhecidas.add(n);
+    }
+  }
+  const missingRefs = [];
+  for (const n of desconhecidas) {
+    const issue = await getIssue(token, owner, repo, n).catch(() => null);
+    if (!issue) { missingRefs.push(n); continue; }
+    catalog.push({
+      number: issue.number,
+      title: issue.title,
+      slug: slugify(issue.title),
+      closed: issue.state === 'closed',
+      milestone: issue.milestone
+        ? { number: issue.milestone.number, title: issue.milestone.title, due_on: issue.milestone.due_on ?? null }
+        : null,
+    });
+  }
+
+  // As decisões de modelagem do tech_context entram na auditoria: recurso
+  // compartilhado com `criada_por: SEM DONO` é pendência de planejamento, não
+  // nota perdida num YAML. Falha de parse é aviso — o arquivo é do usuário.
+  const { context: techContext, error: techError } = loadStaticTechContext(root);
+  if (techError && !json) {
+    p.log.warn(`${TECH_CONTEXT_PATH} não parseou (${techError}) — decisões de modelagem fora da auditoria.`);
+  }
+
+  const resultado = auditMilestone({
+    features, catalog, missingRefs, files: listRepoFiles(root), techContext,
+  });
+  const veredito = auditVerdict(resultado);
+  s?.stop(`Milestone "${milestone.title}": ${features.length} Feature(s) auditada(s).`);
+
+  // A crítica de conjunto: UMA chamada de modelo sobre todas as specs juntas,
+  // atrás do que o determinístico não pega — a mesma regra contada de dois
+  // jeitos. Grave é material (é contradição entre requisitos, por definição);
+  // e falhar aqui falha o comando: quem pediu --critique não pode receber um
+  // "ok" que só cobriu a metade barata.
+  let critica = null;
+  if (critique) {
+    const comSpec = features.filter(f => f.spec);
+    if (comSpec.length < 2) {
+      veredito.avisos.push(
+        `Crítica de conjunto não rodou: ${comSpec.length} spec(s) disponível(is) — conjunto de um não tem par.`
+      );
+    } else {
+      const sc = json ? null : p.spinner();
+      sc?.start(`Crítica de conjunto sobre ${comSpec.length} specs...`);
+      try {
+        critica = await runCritique({
+          kind: 'conjunto',
+          specs: comSpec.map(f => ({ number: f.number, title: f.title, content: f.spec })),
+          cwd: root,
+          standalone: true,
+        });
+      } catch (err) {
+        sc?.stop('');
+        return falhar(`A crítica de conjunto falhou: ${err.message}`);
+      }
+      sc?.stop(`Crítica de conjunto: ${critica.findings.length} finding(s) (modelo ${critica.model}).`);
+      for (const f of critica.findings) {
+        const onde = (f.features || []).map(n => `#${n}`).join(' × ');
+        const linha = `crítica de conjunto${onde ? ` [${onde}]` : ''}: ${f.text}`;
+        if (f.severity === 'grave') veredito.materiais.push(linha);
+        else veredito.avisos.push(linha);
+      }
+      if (veredito.materiais.length) veredito.status = 'problema';
+      else if (veredito.avisos.length) veredito.status = 'aviso';
+    }
+  }
+
+  const saida = {
+    milestone: { title: milestone.title, number: milestone.number },
+    features: features.map(f => ({ number: f.number, title: f.title, temSpec: !!f.spec })),
+    auditoria: resultado,
+    // `markdown` é o comentário pronto para a issue — quem posta (nas DUAS
+    // pontas de cada finding) é o agente que dirige o comando, não a CLI.
+    critica: critica
+      ? { model: critica.model, findings: critica.findings, markdown: critica.markdown }
+      : null,
+    veredito,
+  };
+
+  if (json) {
+    console.log(JSON.stringify(saida, null, 2));
+    if (veredito.status === 'problema') process.exitCode = 1;
+    return saida;
+  }
+
+  const grafoLinhas = resultado.grafo.map(g => {
+    const deps = g.dependsOn.length ? ` ← depende de ${g.dependsOn.map(d => `#${d}`).join(', ')}` : '';
+    return `  #${g.number}${deps}`;
+  });
+  if (grafoLinhas.length) {
+    p.note(grafoLinhas.join('\n'), 'Dependências entre Features (extraídas das specs)');
+  }
+
+  for (const a of veredito.avisos) p.log.warn(a);
+  for (const m of veredito.materiais) p.log.error(m);
+
+  if (veredito.status === 'problema') {
+    p.outro(`${veredito.materiais.length} achado(s) material(is). Decida antes de gerar os planos.`);
+    process.exitCode = 1;
+    return saida;
+  }
+  p.outro(veredito.status === 'aviso'
+    ? 'Nada material — confira os avisos antes de seguir.'
+    : 'Dependências da milestone fecham. Siga para os planos.');
+  return saida;
+}

package/src/commands/doctor.mjs

@@ -1083,10 +1083,15 @@ export function inspectPrPublishing({
   return { status, notes };
 }
 
-async function checkPrPublishing(ctx) {
-  const name = 'Publicação por Pull Request';
-  const dir = path.join(ctx.root || ctx.cwd, '.github', 'workflows');
-
+/**
+ * Permissões de PR declaradas nos workflows instalados (I/O — nunca lança).
+ *
+ * O job MAIS RESTRITIVO manda: basta um sem a permissão para o fluxo quebrar.
+ *
+ * @param {string} dir diretório `.github/workflows`
+ * @returns {Record<string, {contents?: string, pullRequests?: string}>}
+ */
+export function readWorkflowPrPermissions(dir) {
   const workflowPerms = {};
   for (const file of ARTIFACT_WORKFLOW_FILES) {
     const caminho = path.join(dir, file);
@@ -1097,7 +1102,6 @@ async function checkPrPublishing(ctx) {
     } catch {
       continue; // YAML ilegível é problema de outro check
     }
-    // O job mais restritivo manda: basta um sem a permissão para o fluxo quebrar.
     for (const job of Object.values(wf?.jobs || {})) {
       const atual = workflowPerms[file];
       const perm = {
@@ -1109,20 +1113,29 @@ async function checkPrPublishing(ctx) {
       }
     }
   }
+  return workflowPerms;
+}
 
-  if (Object.keys(workflowPerms).length === 0) {
-    return { name, status: 'warn', detail: 'Workflows não encontrados — rode `init` ou `update`.' };
-  }
-
-  const cfg = ctx.cfg || {};
-  const owner = cfg.owner;
-  const repo = cfg.repo;
+/**
+ * Coleta o contexto que `inspectPrPublishing` julga (I/O — nunca lança).
+ *
+ * Separado do check para o `preflight` poder fazer a MESMA pergunta sem
+ * reimplementá-la: as três consultas têm cada uma o seu motivo para falhar sem
+ * que isso signifique "está errado", e duplicar esse tratamento em dois comandos
+ * é como as duas respostas passam a divergir.
+ *
+ * @param {{token?: string, owner?: string, repo?: string, root?: string}} params
+ * @returns {Promise<{canCreatePr: boolean|null, workflowPerms: object,
+ *                    requiredChecks: string[]|null, prTokenPresent: boolean|null}>}
+ */
+export async function readPrPublishingContext({ token, owner, repo, root }) {
+  const workflowPerms = readWorkflowPrPermissions(path.join(root || process.cwd(), '.github', 'workflows'));
 
   let canCreatePr = null;
   let requiredChecks = null;
   let prTokenPresent = null;
-  if (ctx.token && owner && repo) {
-    const octokit = makeOctokit(ctx.token);
+  if (token && owner && repo) {
+    const octokit = makeOctokit(token);
     try {
       const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets',
         { owner, repo });
@@ -1146,10 +1159,21 @@ async function checkPrPublishing(ctx) {
       requiredChecks = null; // sem proteção (404) ou sem permissão — nos dois casos, não afirmar
     }
   }
+  return { canCreatePr, workflowPerms, requiredChecks, prTokenPresent };
+}
 
-  const { status, notes } = inspectPrPublishing({
-    canCreatePr, workflowPerms, requiredChecks, prTokenPresent,
+async function checkPrPublishing(ctx) {
+  const name = 'Publicação por Pull Request';
+  const cfg = ctx.cfg || {};
+  const contexto = await readPrPublishingContext({
+    token: ctx.token, owner: cfg.owner, repo: cfg.repo, root: ctx.root || ctx.cwd,
   });
+
+  if (Object.keys(contexto.workflowPerms).length === 0) {
+    return { name, status: 'warn', detail: 'Workflows não encontrados — rode `init` ou `update`.' };
+  }
+
+  const { status, notes } = inspectPrPublishing(contexto);
   return { name, status, detail: notes.join('\n  ') };
 }
 

package/src/commands/implement.mjs

@@ -215,7 +215,12 @@ function buildContext({
     lines.push('');
     lines.push(`3. **Ao concluir TODA a Story** (todas as Tasks na Etapa ${STAGE_DONE}):`);
     lines.push('   1. Faça o **commit** de todas as mudanças da implementação.');
-    lines.push(`   2. Abra o **Pull Request** da Story #${issue.number}.`);
+    // Draft de propósito: numa pilha de Stories (um PR baseado no anterior),
+    // cada rebase em cascata dispararia o CI inteiro em PRs que ninguém vai
+    // mergear naquele estado. Rascunho não mergeia (o GitHub bloqueia) e o
+    // required check continua valendo: quem revisa marca o PR como pronto, o
+    // `ready_for_review` dispara o CI, e só então o merge destrava.
+    lines.push(`   2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`) — o CI não roda em rascunho; quem revisa marca o PR como pronto e é aí que os checks disparam.`);
     lines.push(
       `   3. **Avance a Etapa da Story #${issue.number} para ${STAGE_CODE_REVIEW}** ` +
       `(reinicie o Status para ${PROGRESS_TODO}). As Tasks já estão em ${STAGE_DONE}.`
@@ -398,7 +403,7 @@ export function buildFeatureContext({
   lines.push(`   1. **Ao começar:** Status da Task → **${PROGRESS_IN_PROGRESS}** (a Etapa continua ${STAGE_DEVELOPMENT}).`);
   lines.push('   2. **Implemente** a Task por completo.');
   lines.push(`   3. **Ao concluir:** **avance a Task para a Etapa ${STAGE_DONE}** com Status **${PROGRESS_DONE}**.`);
-  lines.push(`3. **Ao concluir TODAS as Tasks da Story:** faça o **commit**, abra o **Pull Request** da Story e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`);
+  lines.push(`3. **Ao concluir TODAS as Tasks da Story:** faça o **commit**, abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\` — o CI não roda em rascunho; quem revisa marca o PR como pronto e os checks disparam) e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`);
   lines.push('4. Só então inicie a próxima Story.');
   lines.push('');
   lines.push(
@@ -407,6 +412,18 @@ export function buildFeatureContext({
     `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.`
   );
   lines.push('');
+  // O trecho pós-implementação era o único do fluxo inteiramente manual — e o
+  // merge de PRs empilhados é ordem-dependente (apagar a branch do primeiro já
+  // fechou o segundo). O contexto termina apontando o comando que encapsula a
+  // sequência segura, em vez de deixar a mecânica por conta de quem mergeia.
+  lines.push(
+    '**Ao terminar, informe no relatório final:** os PRs ficam **empilhados** (cada um baseado no anterior) — ' +
+    'o merge é **ordem-dependente**. Depois da revisão humana (marcar cada PR como pronto), o merge é ' +
+    `\`npx @spec-wave/cli@latest merge ${feature.number}\`: ele mergeia na ordem das dependências, ` +
+    'reaponta as bases, move o board até 🧪 QA e só apaga as branches no fim. ' +
+    '**NUNCA** mergeie um PR da pilha com `--delete-branch` à mão — apagar a branch antes de reapontar o dependente fecha o PR seguinte.'
+  );
+  lines.push('');
   lines.push(boardRuleBlockquote());
 
   if (skipped.length > 0) {

package/src/commands/install-skill.mjs

@@ -141,18 +141,28 @@ export function renderContent(format, parsed, version) {
   }
 }
 
-// Insere/atualiza o bloco spec-wave num arquivo compartilhado (AGENTS.md),
-// preservando o restante do conteúdo. Idempotente via marcadores.
-export function mergeAgentsFile(destPath, block) {
-  const existing = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
+// Insere/atualiza o bloco spec-wave num texto de arquivo compartilhado
+// (AGENTS.md), preservando o restante do conteúdo. Idempotente via marcadores.
+//
+// Versão PURA, separada da que lê o disco porque o modo `--branch` do update
+// precisa mesclar o bloco no conteúdo da BASE, não no do arquivo local: o
+// AGENTS.md do desenvolvedor pode ter edições ainda não commitadas, e arrastá-las
+// para dentro do Pull Request seria enviar o que ninguém pediu para revisar.
+export function mergeAgentsContent(existing, block) {
+  const atual = existing || '';
   const blockRe = new RegExp(
     `${escapeRe(BLOCK_START)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n?`,
   );
-  if (blockRe.test(existing)) {
-    return existing.replace(blockRe, block);
+  if (blockRe.test(atual)) {
+    return atual.replace(blockRe, block);
   }
-  if (existing.trim() === '') return block;
-  return `${existing.trimEnd()}\n\n${block}`;
+  if (atual.trim() === '') return block;
+  return `${atual.trimEnd()}\n\n${block}`;
+}
+
+// Mesmo merge, lendo o arquivo de destino do disco.
+export function mergeAgentsFile(destPath, block) {
+  return mergeAgentsContent(existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '', block);
 }
 
 function escapeRe(s) {