@spec-wave/cli 0.24.0 → 0.26.0

package/src/lib/next-step.mjs

@@ -0,0 +1,412 @@
+// Qual é o próximo passo pendente de uma issue — a decisão que a LABEL tomava.
+//
+// No modo `actions` o gatilho é a label: o humano aplica `spec-wave:spec`, o
+// workflow dispara. No modo `local` não há quem escute label, então alguém
+// precisa olhar o estado da issue e dizer o que falta. É este módulo.
+//
+// PURO de propósito: sem fs, sem rede, sem env. Quem coleta as entradas é
+// `commands/run.mjs`; aqui só entra dado já resolvido. É o que permite testar as
+// três tabelas de decisão inteiras sem um único mock de API.
+//
+// A tabela STEPS é o antídoto da divergência entre os dois modos: cada ação
+// declara a label que a dispararia no Actions, e um teste de paridade prova que
+// toda label de gatilho tem exatamente uma ação. Sem essa amarra, um gatilho
+// novo nasceria só de um lado e ninguém notaria.
+
+import {
+  LABEL_SPEC, LABEL_PLAN, LABEL_CRITIQUE, LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY,
+  LABEL_DECOMPOSE_READY, LABEL_DECOMPOSED, LABEL_BUG, LABEL_BUG_APPROVED,
+  LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_PLAN_APPROVED, LABEL_TRIAGED,
+  LABEL_DUPLICATE, LABEL_WONT_FIX, LABEL_READY, labelNames,
+} from '../config.mjs';
+
+/**
+ * @typedef {'local'|'remote'|'missing'|'unknown'} DocState
+ * @typedef {'generate-spec'|'generate-plan'|'critique'|'validate'|'decompose'
+ *          |'decompose-apply'|'generate-bug'|'triage'|'implement'|'none'} StepAction
+ */
+
+/**
+ * Ação → label que a dispararia no Actions, comando da CLI, documentos que ela
+ * lê e escreve, tipos aceitos e se ela CRIA issues (o que exige confirmação).
+ */
+export const STEPS = {
+  'generate-spec': {
+    trigger: LABEL_SPEC, cli: 'generate-spec', writes: 'spec', reads: [],
+    types: ['Feature'], creates: false, ai: true,
+  },
+  'generate-plan': {
+    trigger: LABEL_PLAN, cli: 'generate-plan', writes: 'plan', reads: ['spec'],
+    types: ['Feature'], creates: false, ai: true,
+  },
+  critique: {
+    trigger: LABEL_CRITIQUE, cli: 'critique', writes: null, reads: ['plan'],
+    types: ['Feature'], creates: false, ai: true,
+  },
+  validate: {
+    // `reads` DEPENDE DO TIPO: a validação de Feature abre spec.md e plan.md, a
+    // de Bug abre bug.md. Declarar `[]` aqui desarmava o G6 justamente para o
+    // passo que só lê do disco — um clone atrasado reprovava uma Feature cujo
+    // plan.md existia no remoto, removia `spec-wave:ready` e comentava a falha
+    // na issue. Dano a estado COMPARTILHADO por uma condição puramente local.
+    trigger: LABEL_READY, cli: 'validate', writes: null, reads: [],
+    readsByType: { Feature: ['spec', 'plan'], Bug: ['bug'] },
+    types: ['Feature', 'Bug'], creates: false, ai: false,
+  },
+  decompose: {
+    // O rascunho de Feature é montado a partir de spec.md + plan.md; o de RFC
+    // não usa nenhum dos dois. Com `[]` e o plan só no remoto, o decompose
+    // gerava o rascunho com o plano VAZIO — sem erro, só pior.
+    trigger: LABEL_DECOMPOSE, cli: 'decompose', writes: 'decomposition', reads: [],
+    readsByType: { Feature: ['spec', 'plan'], RFC: [] },
+    types: ['Feature', 'RFC'], creates: false, ai: true,
+  },
+  'decompose-apply': {
+    trigger: LABEL_DECOMPOSE_APPLY, cli: 'decompose --apply', writes: null,
+    reads: ['decomposition'], types: ['Feature', 'RFC'], creates: true, ai: false,
+  },
+  'generate-bug': {
+    trigger: LABEL_BUG, cli: 'generate-bug', writes: 'bug', reads: [],
+    types: ['Bug'], creates: false, ai: true,
+  },
+  // Sem gatilho por label: são decisões humanas, listadas aqui para o `run`
+  // saber dizer qual é o próximo movimento em vez de só "nada pendente".
+  triage: {
+    trigger: null, cli: 'triage accept', writes: null, reads: [],
+    types: ['Bug'], creates: false, ai: false, manual: true,
+  },
+  implement: {
+    trigger: null, cli: 'implement', writes: null, reads: [],
+    types: ['Feature', 'Bug', 'RFC'], creates: false, ai: true, manual: true,
+  },
+};
+
+/**
+ * Documentos que um passo LÊ, para um tipo de item (função PURA).
+ *
+ * Existe porque dois passos leem coisas diferentes conforme o tipo — `validate`
+ * abre spec+plan numa Feature e bug.md num Bug — e o G6 precisa da lista CERTA:
+ * ele é o que impede o passo de rodar contra um clone atrasado. Uma lista
+ * subdeclarada não causa erro visível, causa o passo rodando com o arquivo
+ * errado (ou ausente), que é o modo de falha caro.
+ *
+ * @param {string} action nome da ação em STEPS
+ * @param {string|null} [type] tipo do work item
+ * @returns {string[]} documentos lidos
+ */
+export function stepReads(action, type) {
+  const step = STEPS[action];
+  if (!step) return [];
+  return step.readsByType?.[type] ?? step.reads;
+}
+
+/**
+ * Documentos que um passo TOCA (lê ou escreve), para um tipo (função PURA).
+ *
+ * É a lista que o G6, o aviso de "não deu para consultar o remoto" e a sonda do
+ * `run` precisam — os três erravam junto quando `reads` estava subdeclarado.
+ *
+ * @param {string} action
+ * @param {string|null} [type]
+ * @returns {string[]}
+ */
+export function stepDocs(action, type) {
+  return [STEPS[action]?.writes, ...stepReads(action, type)].filter(Boolean);
+}
+
+/**
+ * Documentos que um tipo usa (função PURA).
+ *
+ * O `run` precisa disto para sondar o remoto quando a decisão veio BLOQUEADA e
+ * o passo é `none` — aí não há `writes`/`reads` de onde tirar a lista, e é
+ * justamente o caso em que o G5 afirma "não está no clone nem no remoto".
+ *
+ * @param {string|null} [type]
+ * @returns {string[]}
+ */
+export function docsForType(type) {
+  return DOCS_BY_TYPE[type] || [];
+}
+
+/** Tipos que o `run` sabe conduzir. Story/Task/Epic/Spike não têm passo de documento. */
+export const RUNNABLE_TYPES = ['Feature', 'Bug', 'RFC'];
+
+const TRIGGERS = Object.values(STEPS).map(s => s.trigger).filter(Boolean);
+
+/** Documentos que cada tipo usa, na ordem em que o fluxo os produz. */
+export const DOCS_BY_TYPE = {
+  Feature: ['spec', 'plan', 'decomposition'],
+  RFC: ['decomposition'],
+  Bug: ['bug'],
+};
+
+const DEFAULT_DOC_PATHS = {
+  spec: 'spec.md', plan: 'plan.md', decomposition: 'decomposition.md', bug: 'bug.md',
+};
+
+function stepCommand(action, { issueNumber }) {
+  const step = STEPS[action];
+  if (!step || action === 'none') return null;
+  return step.manual
+    ? `spec-wave ${step.cli} ${issueNumber}`
+    : `spec-wave ${step.cli} --issue-number ${issueNumber}`;
+}
+
+function docState(docs, name) {
+  return docs?.[name] || 'missing';
+}
+
+// Para a POSIÇÃO no pipeline, o que conta é "o documento existe em algum lugar":
+// `remote` conta (o passo seguinte é `git pull`, não regerar), `unknown` NÃO —
+// não deu para consultar, e travar o fluxo por isso deixaria o usuário sem saída
+// offline. Quem transforma `remote` em portão é o G6.
+function docExists(docs, name) {
+  return ['local', 'remote'].includes(docState(docs, name));
+}
+
+function decided(action, reason, params, blocked = null) {
+  return { action, command: stepCommand(action, params), reason, blocked };
+}
+
+function block(code, message, unblock) {
+  return { code, message, unblock };
+}
+
+/**
+ * Passo forçado por `--step` (função PURA).
+ *
+ * @param {string} step nome da ação (aceita os apelidos curtos: spec, plan, bug, ready)
+ * @param {{type: string|null}} params
+ * @returns {{action: StepAction|null, error: string|null}}
+ */
+export function resolveForcedStep(step, { type }) {
+  const alias = {
+    spec: 'generate-spec', plan: 'generate-plan', bug: 'generate-bug',
+    ready: 'validate', apply: 'decompose-apply',
+  };
+  const action = alias[step] || step;
+  if (!STEPS[action] || STEPS[action].manual) {
+    const nomes = Object.entries(STEPS).filter(([, s]) => !s.manual).map(([a]) => a);
+    return { action: null, error: `Passo desconhecido: "${step}". Use um de: ${nomes.join(', ')}.` };
+  }
+  if (type && !STEPS[action].types.includes(type)) {
+    return {
+      action: null,
+      error: `O passo "${action}" não se aplica a ${type} (só a ${STEPS[action].types.join(', ')}).`,
+    };
+  }
+  return { action, error: null };
+}
+
+/**
+ * O próximo passo pendente do fluxo (função PURA).
+ *
+ * Quando `blocked` vem preenchido, `action` continua sendo o passo que RODARIA —
+ * é isso que permite dizer "o próximo passo é X, mas Y impede" em vez de um
+ * "não posso" mudo.
+ *
+ * @param {object} params
+ * @param {string|null} params.type tipo canônico da issue (detectIssueType)
+ * @param {number|string} params.issueNumber
+ * @param {'open'|'closed'} [params.state]
+ * @param {Array<string|{name:string}>} [params.labels]
+ * @param {Record<string, DocState>} [params.docs] estado de spec/plan/decomposition/bug
+ * @param {Record<string, string>} [params.docPaths] caminhos relativos (só para as mensagens)
+ * @param {StepAction|null} [params.forcedStep] resultado de resolveForcedStep
+ * @param {boolean} [params.confirmed] `--yes`/`--apply` já dados
+ * @param {boolean} [params.boardReady] o board está alcançável (gate do apply)
+ * @param {boolean} [params.force] `--force` fura o portão de gatilho pendente
+ * @returns {{action: StepAction, command: string|null, reason: string,
+ *            blocked: null|{code: string, message: string, unblock: string}}}
+ */
+export function nextStep({
+  type, issueNumber, state = 'open', labels = [], docs = {}, docPaths = {},
+  forcedStep = null, confirmed = false, boardReady = true, force = false,
+} = {}) {
+  const params = { issueNumber };
+  const names = labelNames(labels);
+  const has = label => names.includes(label);
+  const pathOf = doc => docPaths[doc] || DEFAULT_DOC_PATHS[doc] || doc;
+
+  // G0 — issue fechada: não há fluxo a conduzir.
+  if (state === 'closed') {
+    return decided('none', `A issue #${issueNumber} está fechada.`, params);
+  }
+
+  // G1 — tipo fora do fluxo de documentos.
+  if (!type || !RUNNABLE_TYPES.includes(type)) {
+    return decided('none', `Tipo ${type || 'desconhecido'} não tem passo automatizável.`, params,
+      block('unsupported-type',
+        `O fluxo de documentos cobre ${RUNNABLE_TYPES.join(', ')}. Story e Task nascem do decompose.`,
+        'Conduza este item pelo board (`spec-wave move`).'));
+  }
+
+  // G2 — portão humano duro: a crítica esgotou as tentativas.
+  if (has(LABEL_NEEDS_HUMAN)) {
+    return decided('none', 'A crítica reprovou repetidas vezes e parou o fluxo.', params,
+      block('needs-human',
+        `A label \`${LABEL_NEEDS_HUMAN}\` para o fluxo até uma pessoa revisar os documentos.`,
+        `Revise, corrija e remova \`${LABEL_NEEDS_HUMAN}\` (e \`${LABEL_CRITIQUE_FAILED}\`, se houver).`));
+  }
+
+  // G3 — crítica grave pendente. O caminho de retomada é corrigir o documento e
+  // RE-CRITICAR; regerar descartaria a correção (é o erro que a skill documenta).
+  if (has(LABEL_CRITIQUE_FAILED)) {
+    const action = type === 'Feature' ? 'critique' : 'none';
+    return decided(action, 'A crítica adversarial apontou contradições graves.', params,
+      block('critique-failed',
+        'Os achados estão no comentário 🔎 da issue e citam o documento por âncora.',
+        `Corrija o documento, remova \`${LABEL_CRITIQUE_FAILED}\` e rode de novo.`));
+  }
+
+  // G4 — gatilho aplicado: ou um Action está em voo, ou ele falhou e deixou a
+  // label. Rodar por cima gera documento e comentário em duplicata.
+  const pending = TRIGGERS.filter(has);
+  if (pending.length > 0 && !force) {
+    return decided('none', `Label de gatilho pendente na issue: ${pending.join(', ')}.`, params,
+      block('trigger-pending',
+        'A label significa Action em execução (ou que falhou deixando-a para trás).',
+        `Aguarde o run terminar, ou remova a label e repita — \`--force\` ignora este portão.`));
+  }
+
+  const docsOfType = DOCS_BY_TYPE[type] || [];
+
+  // G5 — as labels afirmam um documento que o clone não tem. Título editado
+  // muda o slug (e o diretório); clone velho não tem o arquivo.
+  const claims = [
+    [LABEL_PLAN_APPROVED, 'plan'], [LABEL_DECOMPOSED, 'decomposition'], [LABEL_BUG_APPROVED, 'bug'],
+  ];
+  for (const [label, doc] of claims) {
+    if (has(label) && docsOfType.includes(doc) && docState(docs, doc) === 'missing') {
+      return decided('none', `A label \`${label}\` afirma um documento que não existe aqui.`, params,
+        block('inconsistent-state',
+          `\`${pathOf(doc)}\` não está no clone nem no remoto.`,
+          'O título da issue mudou depois de gerar (o slug vira outro diretório)? Renomeie o diretório ou regenere.'));
+    }
+  }
+
+  const action = forcedStep || pipelineStep({ type, docs, has });
+  if (action === 'none') {
+    return decided('none', nothingPendingReason({ type, has }), params);
+  }
+
+  const step = STEPS[action];
+
+  // Passo manual (triage, implement): existe passo, mas quem o dá é uma pessoa.
+  if (step.manual) {
+    return decided(action, manualReason(action), params,
+      block('manual', 'Este passo é decisão humana — o `run` não o executa.',
+        `Rode \`${stepCommand(action, params)}\` quando decidir.`));
+  }
+
+  // G6 — documento que o passo lê ou escreve existe só no remoto. Gerar por cima
+  // levaria o `pull --rebase` do commit a brigar com o documento bom.
+  for (const doc of stepDocs(action, type)) {
+    if (docState(docs, doc) === 'remote') {
+      return decided(action, `\`${pathOf(doc)}\` existe no repositório mas não no seu clone.`, params,
+        block('stale-checkout',
+          'Seguir agora ignoraria (ou sobrescreveria) o documento já publicado.',
+          'Rode `git pull` e repita.'));
+    }
+  }
+
+  // G7 — o passo cria issues: aplicar é a aprovação humana, nunca automática.
+  if (step.creates && !confirmed) {
+    return decided(action, applyReason({ type }), params,
+      block('needs-confirmation',
+        'Este passo CRIA issues a partir do rascunho revisado — reaplicar depois duplica.',
+        `Revise o rascunho e confirme com \`--apply\`.`));
+  }
+
+  // G8 — sem board não há onde posicionar o que for criado.
+  if (action === 'decompose-apply' && !boardReady) {
+    return decided(action, 'O board não está alcançável.', params,
+      block('board-unreachable',
+        'As issues nasceriam sem Etapa e sumiriam de todas as telas.',
+        'Confira o `project` no .spec-wave.json e o escopo `project` do token (GH_PROJECT_TOKEN).'));
+  }
+
+  // Re-crítica do rascunho: existe arquivo, ninguém liberou, e rodar gasta IA.
+  if (action === 'decompose' && docExists(docs, 'decomposition') && !confirmed) {
+    return decided(action, 'O rascunho já existe e seria RE-CRITICADO (não regerado).', params,
+      block('needs-confirmation',
+        'Uma nova crítica custa uma chamada de IA; o rascunho em si é preservado.',
+        'Confirme com `--yes`, ou apague o arquivo para gerar outro do zero.'));
+  }
+
+  // Passo forçado que sobrescreve documento existente.
+  if (forcedStep && step.writes && docState(docs, step.writes) === 'local' && !confirmed) {
+    return decided(action, `\`${pathOf(step.writes)}\` já existe e seria SOBRESCRITO.`, params,
+      block('needs-confirmation',
+        'Regerar descarta o que foi revisado à mão.',
+        'Confirme com `--yes` se é isso mesmo.'));
+  }
+
+  const incertos = stepDocs(action, type)
+    .filter(doc => docState(docs, doc) === 'unknown');
+  const aviso = incertos.length > 0
+    ? ` (não foi possível consultar o remoto por ${incertos.map(pathOf).join(', ')} — ` +
+      'se já foi gerado, rode `git pull` antes)'
+    : '';
+
+  return decided(action, pipelineReason(action, { pathOf }) + aviso, params);
+}
+
+// A posição no pipeline, depois dos portões (função PURA interna).
+function pipelineStep({ type, docs, has }) {
+  const existe = doc => docExists(docs, doc);
+
+  if (type === 'Feature') {
+    if (!existe('spec')) return 'generate-spec';
+    if (!existe('plan')) return 'generate-plan';
+    if (!has(LABEL_PLAN_APPROVED)) return 'validate';
+    if (has(LABEL_DECOMPOSED)) return 'implement';
+    if (has(LABEL_DECOMPOSE_READY)) return 'decompose-apply';
+    return 'decompose';
+  }
+
+  if (type === 'RFC') {
+    if (has(LABEL_DECOMPOSED)) return 'implement';
+    if (has(LABEL_DECOMPOSE_READY)) return 'decompose-apply';
+    return 'decompose';
+  }
+
+  // Bug: bug.md → validate → triagem (humana) → implement.
+  if (!existe('bug')) return 'generate-bug';
+  if (!has(LABEL_BUG_APPROVED)) return 'validate';
+  if (has(LABEL_DUPLICATE) || has(LABEL_WONT_FIX)) return 'none';
+  if (!has(LABEL_TRIAGED)) return 'triage';
+  return 'implement';
+}
+
+function pipelineReason(action, { pathOf }) {
+  switch (action) {
+    case 'generate-spec': return `\`${pathOf('spec')}\` ainda não existe.`;
+    case 'generate-plan': return `A spec está pronta e \`${pathOf('plan')}\` ainda não existe.`;
+    case 'critique': return 'O plano precisa passar pela crítica adversarial de novo.';
+    case 'validate': return 'Os documentos existem e ainda não foram validados.';
+    case 'decompose': return `O rascunho \`${pathOf('decomposition')}\` ainda não existe.`;
+    case 'decompose-apply': return 'O rascunho foi aprovado pela crítica e espera revisão humana.';
+    case 'generate-bug': return `\`${pathOf('bug')}\` ainda não existe.`;
+    default: return 'Próximo passo do fluxo.';
+  }
+}
+
+function applyReason({ type }) {
+  return type === 'RFC'
+    ? 'O rascunho está pronto para virar Tasks.'
+    : 'O rascunho está pronto para virar Stories e Tasks.';
+}
+
+function manualReason(action) {
+  return action === 'triage'
+    ? 'O bug.md está validado — falta a triagem (aceitar, rejeitar ou marcar duplicado).'
+    : 'O fluxo de documentos terminou; o que falta é implementar.';
+}
+
+function nothingPendingReason({ type, has }) {
+  if (type === 'Bug' && (has(LABEL_DUPLICATE) || has(LABEL_WONT_FIX))) {
+    return 'O bug foi triado para fora do fluxo (duplicado ou não será corrigido).';
+  }
+  return 'Nada pendente no fluxo de documentos.';
+}

package/src/lib/pr-step.mjs

@@ -0,0 +1,102 @@
+// O que rodar para um Pull Request, quando não há evento do GitHub para escutar.
+//
+// No Actions o gatilho é o evento: `pull_request: [opened]` chama o
+// `code-review`, `pull_request_review: [submitted]` com `state == 'approved'`
+// chama o `qa`. Localmente o sinal equivalente é o ESTADO das reviews.
+//
+// PURO: sem rede. Quem busca PR e reviews é `commands/run.mjs`.
+
+/**
+ * Veredito das reviews (função PURA).
+ *
+ * `approved` espelha exatamente o `if:` do qa.yml: basta existir uma review
+ * `APPROVED` — o Actions não checa se alguém pediu mudanças depois. Mas essa
+ * informação vai separada em `changesRequestedAfterApproval`, para o `run`
+ * exigir confirmação num caso em que o runner seguiria em frente calado.
+ *
+ * Uma review `DISMISSED` posterior derruba a aprovação anterior do MESMO autor —
+ * é o que "dismiss" significa na UI.
+ *
+ * @param {Array<{state?: string, user?: {login?: string}, author?: string, submitted_at?: string}>} reviews
+ * @returns {{approved: boolean, approvers: string[], changesRequestedAfterApproval: boolean}}
+ */
+export function reviewVerdict(reviews = []) {
+  const relevant = ['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED'];
+  const porAutor = new Map();
+
+  for (const review of reviews) {
+    const state = String(review?.state || '').toUpperCase();
+    if (!relevant.includes(state)) continue; // COMMENTED/PENDING não são veredito
+    const autor = review?.user?.login || review?.author || '(desconhecido)';
+    porAutor.set(autor, state);
+  }
+
+  const approvers = [...porAutor].filter(([, state]) => state === 'APPROVED').map(([autor]) => autor);
+  const mudancasPedidas = [...porAutor.values()].includes('CHANGES_REQUESTED');
+
+  return {
+    approved: approvers.length > 0,
+    approvers,
+    changesRequestedAfterApproval: approvers.length > 0 && mudancasPedidas,
+  };
+}
+
+/**
+ * Quais comandos rodar para este PR (função PURA).
+ *
+ * A ordem importa e é sempre a mesma: `code-review` antes de `qa`. Num repo em
+ * modo local o `code-review` nunca rodou na abertura do PR, e o `qa` sozinho
+ * mexe só na Feature/Bug — as Tasks ficariam fora de 🎉 Done e as Stories fora
+ * de 👀 Code Review. Os dois são board-only, sem IA e idempotentes
+ * (`advanceToStage` nunca retrocede), então encadeá-los não tem o custo que
+ * justifica o "um passo por vez" do modo issue.
+ *
+ * @param {object} params
+ * @param {'open'|'closed'} params.state
+ * @param {boolean} [params.draft]
+ * @param {boolean} [params.merged]
+ * @param {boolean} [params.approved]
+ * @param {boolean} [params.changesRequestedAfterApproval]
+ * @param {string|null} [params.only] 'code-review' | 'qa'
+ * @returns {{steps: string[], reason: string, warnings: string[],
+ *            blocked: null|{code: string, message: string, unblock: string}}}
+ */
+export function nextPrStep({
+  state, draft = false, merged = false, approved = false,
+  changesRequestedAfterApproval = false, only = null,
+} = {}) {
+  const warnings = [];
+
+  if (draft) {
+    return {
+      steps: [], warnings, reason: 'PR em rascunho.',
+      blocked: {
+        code: 'draft',
+        message: 'Nem o code-review.yml dispara para rascunho.',
+        unblock: 'Marque o PR como pronto para revisão.',
+      },
+    };
+  }
+
+  if (state === 'closed' && !merged) {
+    return { steps: [], warnings, reason: 'PR fechado sem merge.', blocked: null };
+  }
+
+  if (merged) warnings.push('PR já mergeado — o board é atualizado como se o review tivesse acabado agora.');
+  if (merged && !approved) warnings.push('Mergeado sem review aprovada: o `qa` não roda (o qa.yml também não rodaria).');
+  if (changesRequestedAfterApproval) {
+    warnings.push('Há aprovação E pedido de mudanças: o Actions moveria assim mesmo — confirme com `--yes`.');
+  }
+
+  let steps = approved ? ['code-review', 'qa'] : ['code-review'];
+  if (only) steps = steps.filter(s => s === only);
+
+  return {
+    steps,
+    warnings,
+    reason: approved
+      ? 'PR com review aprovada: board até 🧪 QA.'
+      : 'PR sem review aprovada: board até 👀 Code Review.',
+    blocked: null,
+  };
+}

package/src/lib/repo-links.mjs

@@ -0,0 +1,84 @@
+// Links para os documentos gerados, apontando para a REF que de fato os recebeu.
+//
+// Os comentários das issues traziam `blob/main/...` fixo. No runner isso é quase
+// sempre verdade (o push vai para a branch default), mas o modo local publica da
+// branch corrente — e aí o link nasce 404 até o merge, ou para sempre. Com o
+// `run` industrializando a execução local, o defeito deixaria de ser eventual.
+//
+// Decisão pura (`blobUrl`, `resolveDocRef`), I/O isolado em `currentGitBranch`.
+
+import { execSync } from 'node:child_process';
+
+/**
+ * URL de um arquivo no GitHub (função PURA).
+ *
+ * A ref não é escapada: nome de branch com `/` (feat/x) funciona cru na URL do
+ * GitHub, e `encodeURIComponent` o quebraria.
+ *
+ * @param {{owner: string, repo: string, ref: string, pathRel: string}} params
+ * @returns {string}
+ */
+export function blobUrl({ owner, repo, ref, pathRel }) {
+  return `https://github.com/${owner}/${repo}/blob/${ref}/${pathRel}`;
+}
+
+/**
+ * Qual ref o link deve citar (função PURA).
+ *
+ * No Actions, `GITHUB_REF_NAME` é a branch do evento. Localmente, a branch
+ * corrente é a que `commitGenerated` acabou de publicar. `main` é o último
+ * recurso — o mesmo valor que estava hardcoded, então nunca piora.
+ *
+ * @param {object} params
+ * @param {'actions'|'local'} params.mode
+ * @param {object} [params.env]
+ * @param {string|null} [params.gitBranch] branch corrente (modo local)
+ * @param {object|null} [params.config] `.spec-wave.json` (campo `defaultBranch`)
+ * @returns {string}
+ */
+export function resolveDocRef({ mode, env = {}, gitBranch = null, config = null }) {
+  const fallback = config?.defaultBranch || 'main';
+  if (mode === 'actions') return env.GITHUB_REF_NAME || fallback;
+  return gitBranch || fallback;
+}
+
+/**
+ * Branch corrente do clone. Best-effort — NUNCA lança.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null} null em detached HEAD ou fora de um repositório git
+ */
+export function currentGitBranch(cwd = process.cwd()) {
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return branch && branch !== 'HEAD' ? branch : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * URL do documento gerado, resolvendo a ref pelo modo de execução.
+ *
+ * @param {object} params
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.pathRel
+ * @param {'actions'|'local'} params.mode
+ * @param {string|null} [params.root] raiz do repo (para ler a branch corrente)
+ * @param {object|null} [params.config]
+ * @returns {string}
+ */
+export function docBlobUrl({ owner, repo, pathRel, mode, root = null, config = null }) {
+  const ref = resolveDocRef({
+    mode,
+    env: process.env,
+    gitBranch: mode === 'actions' ? null : currentGitBranch(root || process.cwd()),
+    config,
+  });
+  return blobUrl({ owner, repo, ref, pathRel });
+}

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",

package/src/plugin/skills/doctor/SKILL.md

@@ -44,6 +44,7 @@ npx @spec-wave/cli@latest doctor
    - `.spec-wave.json` dessincronizado → `npx @spec-wave/cli@latest refresh --config`
    - workflows/labels divergentes → skill **update**
    - secret de IA ausente → Settings → Secrets → Actions (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` ou `OPENROUTER_API_KEY`, conforme o provider)
+   - modo de execução divergente (config diz `local` e a variável `SPEC_WAVE_EXECUTION` não está setada, ou vice-versa) → `npx @spec-wave/cli@latest mode local|actions` — veja a skill **run**
    - `specKit.command` ausente → configure antes de usar a skill **implement**
 3. Trate `!` como "não deu para verificar", não como falha.
 4. Se tudo passar e o problema original persistir, aí sim investigue a superfície específica (Action, issue, board).