@spec-wave/cli 0.34.2 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "0.34.2",
3
+ "version": "0.35.0",
4
4
  "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
5
5
  "type": "module",
6
6
  "bin": {
@@ -29,6 +29,15 @@
29
29
  "type": "string",
30
30
  "description": "Evidência bruta (comando, saída, código de status). OBRIGATÓRIA e não vazia em `fail` (vira o bug.md determinístico) e em `blocked` com `blockedReason: outro`."
31
31
  },
32
+ "evidenceFiles": {
33
+ "type": "array",
34
+ "description": "OPCIONAL (aditivo ao v1). Evidência VISUAL do cenário — vídeo/foto gravados por Maestro (mobile) ou Playwright (web). Nomes de arquivo (sem diretório) que o executor gravou em `<evidenceDir>/cenario-<n>/`; a CLI os publica em `docs/features/<slug>/qa/cenario-<n>/` (ou `docs/bugs/<slug>/qa/`). Só extensões mp4, webm, mov, png, jpg, jpeg, gif, webp; teto de 4 MB por arquivo (acima disso a CLI avisa e não publica). Nunca substitui `evidencia` (texto), que continua obrigatória nas mesmas regras.",
35
+ "items": {
36
+ "type": "string",
37
+ "pattern": "^[A-Za-z0-9_-][A-Za-z0-9._-]*\\.(mp4|webm|mov|png|jpg|jpeg|gif|webp)$"
38
+ },
39
+ "uniqueItems": true
40
+ },
32
41
  "blockedReason": {
33
42
  "enum": [
34
43
  "ambiente",
@@ -383,7 +383,7 @@ export async function listSubIssues(token, issueNodeId) {
383
383
  * branch. `includeClosedPrs` de propósito: PR já mergeado é o que diz que a
384
384
  * Story está entregue.
385
385
  *
386
- * @returns {Promise<Array<{number, state, merged, isDraft, baseRefName, headRefName}>>}
386
+ * @returns {Promise<Array<{id, number, state, merged, isDraft, baseRefName, headRefName}>>}
387
387
  */
388
388
  export async function listIssuePullRequests(token, issueNodeId) {
389
389
  const client = makeClient(token);
@@ -392,7 +392,7 @@ export async function listIssuePullRequests(token, issueNodeId) {
392
392
  node(id: $id) {
393
393
  ... on Issue {
394
394
  closedByPullRequestsReferences(first: 20, includeClosedPrs: true) {
395
- nodes { number state merged isDraft baseRefName headRefName }
395
+ nodes { id number state merged isDraft baseRefName headRefName }
396
396
  }
397
397
  }
398
398
  }
@@ -400,6 +400,7 @@ export async function listIssuePullRequests(token, issueNodeId) {
400
400
  `, { id: issueNodeId });
401
401
  const nodes = result.node?.closedByPullRequestsReferences?.nodes || [];
402
402
  return nodes.map(n => ({
403
+ id: n.id,
403
404
  number: n.number,
404
405
  state: (n.state || '').toLowerCase(), // open | closed | merged
405
406
  merged: Boolean(n.merged),
@@ -409,6 +410,63 @@ export async function listIssuePullRequests(token, issueNodeId) {
409
410
  }));
410
411
  }
411
412
 
413
+ /**
414
+ * Todos os PRs ABERTOS do repositório, com corpo — o plano B do `merge` quando
415
+ * o vínculo nativo falha. O GitHub só registra closedByPullRequestsReferences
416
+ * quando a base do PR é a branch default; numa pilha, só o PR de baixo tem, e
417
+ * os demais ficam invisíveis para listIssuePullRequests até o retarget. O corpo
418
+ * (`Closes #N`) é o que o autor declarou, então o merge parseia daqui.
419
+ *
420
+ * @returns {Promise<Array<{id, number, state, merged, isDraft, baseRefName, headRefName, body}>>}
421
+ */
422
+ export async function listOpenPullRequests(token, owner, repo) {
423
+ const client = makeClient(token);
424
+ const result = await client(`
425
+ query OpenPRs($owner: String!, $repo: String!) {
426
+ repository(owner: $owner, name: $repo) {
427
+ pullRequests(states: OPEN, first: 100, orderBy: { field: CREATED_AT, direction: DESC }) {
428
+ nodes { id number state merged isDraft baseRefName headRefName body }
429
+ }
430
+ }
431
+ }
432
+ `, { owner, repo });
433
+ const nodes = result.repository?.pullRequests?.nodes || [];
434
+ return nodes.map(n => ({
435
+ id: n.id,
436
+ number: n.number,
437
+ state: (n.state || '').toLowerCase(),
438
+ merged: Boolean(n.merged),
439
+ isDraft: Boolean(n.isDraft),
440
+ baseRefName: n.baseRefName || null,
441
+ headRefName: n.headRefName || null,
442
+ body: n.body || '',
443
+ }));
444
+ }
445
+
446
+ /**
447
+ * Tira um PR do rascunho. Só existe em GraphQL — a REST não expõe a transição
448
+ * draft → ready (o PATCH de `draft` é ignorado em silêncio, que é pior).
449
+ *
450
+ * Marcar como pronto é o SINAL de que o trabalho acabou: enquanto o dev-agent
451
+ * implementa as Stories de uma Feature, os PRs ficam em rascunho para que
452
+ * ninguém revise nem mergeie uma feature pela metade; quando a última Story
453
+ * entra em Code Review, o `implement` marca todos como prontos de uma vez.
454
+ *
455
+ * Idempotente do lado de cá: um PR já pronto devolve erro do GitHub, então o
456
+ * chamador filtra por `isDraft` antes (ver planPrsToReady).
457
+ */
458
+ export async function markPullRequestReadyForReview(token, pullRequestId) {
459
+ const client = makeClient(token);
460
+ const result = await client(`
461
+ mutation ReadyForReview($id: ID!) {
462
+ markPullRequestReadyForReview(input: { pullRequestId: $id }) {
463
+ pullRequest { number isDraft }
464
+ }
465
+ }
466
+ `, { id: pullRequestId });
467
+ return result.markPullRequestReadyForReview?.pullRequest || null;
468
+ }
469
+
412
470
  /**
413
471
  * Issues que o GitHub reconhece como fechadas por este PR
414
472
  * (`Closes #N` e o vínculo feito pela UI). É a MESMA lista que fecha as issues
@@ -7,6 +7,11 @@ import {
7
7
  import { detectIssueType } from '../lib/issue-type.mjs';
8
8
  import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
9
9
  import { loadConfig } from '../lib/project-root.mjs';
10
+ import { markFeaturePrsReady } from '../lib/pr-ready.mjs';
11
+ import { extractIssueNumbers, resolveLinkMode } from '../lib/pr-link.mjs';
12
+ // O parser mudou para lib/pr-link.mjs (ver o cabeçalho de lá); merge.mjs e os
13
+ // testes importam `extractIssueNumbers` daqui desde antes.
14
+ export { extractIssueNumbers };
10
15
  import {
11
16
  STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType,
12
17
  LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY, labelNames,
@@ -19,45 +24,6 @@ const DONE_STAGE = STAGE_DONE;
19
24
  const TODO_STATUS = PROGRESS_TODO;
20
25
  const DONE_STATUS = PROGRESS_DONE;
21
26
 
22
- // Vínculo EXPLÍCITO: o verbo é obrigatório. `Relacionado: #10` e `#10` solto
23
- // deixaram de contar — referência cruzada em PR é prática comum (uma PR de
24
- // documentação citando três Features moveu as três para 👀 Code Review, e uma
25
- // delas nem plano tinha). Aceita `#N`, `owner/repo#N` e a URL completa da issue.
26
- const EXPLICIT_LINK_RE =
27
- /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|implement(?:s|ed)?)\b\s*:?\s+(?:https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/(\d+)|[\w.-]+\/[\w.-]+#(\d+)|#(\d+))/gi;
28
-
29
- // Forma antiga, atrás do knob `codeReview.linkMode: "any-mention"`.
30
- const ANY_MENTION_RE = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
31
-
32
- // Blocos de código não são vínculo: um `Closes #12` dentro de um exemplo de
33
- // commit message é documentação, não promessa.
34
- function stripCodeBlocks(body) {
35
- return String(body)
36
- .replace(/^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1[ \t]*$/gm, '\n')
37
- .replace(/`[^`\n]*`/g, ' ');
38
- }
39
-
40
- /**
41
- * Números de issues que o PR declara implementar (função PURA — testável).
42
- *
43
- * @param {string} body corpo do PR
44
- * @param {object} [opts]
45
- * @param {'explicit'|'any-mention'} [opts.linkMode='explicit']
46
- * @returns {number[]} na ordem em que aparecem, sem repetição
47
- */
48
- export function extractIssueNumbers(body, { linkMode = 'explicit' } = {}) {
49
- if (!body) return [];
50
- const nums = new Set();
51
- const text = stripCodeBlocks(body);
52
- const re = linkMode === 'any-mention' ? ANY_MENTION_RE : EXPLICIT_LINK_RE;
53
- re.lastIndex = 0;
54
- for (const m of text.matchAll(re)) {
55
- const n = parseInt(m.slice(1).find(Boolean) || '', 10);
56
- if (n) nums.add(n);
57
- }
58
- return [...nums];
59
- }
60
-
61
27
  /**
62
28
  * Recorte temporal da subárvore (função PURA — testável).
63
29
  *
@@ -207,19 +173,24 @@ async function collectReviewUnit(token, owner, repo, issueNumber, { notAfter = n
207
173
 
208
174
  // A Feature só avança quando TODAS as suas Stories já estiverem em Code Review
209
175
  // (ou etapa posterior). readToken lê as issues; projToken opera no Project.
176
+ //
177
+ // Devolve também as Stories: quem chama usa a mesma lista para tirar os PRs da
178
+ // Feature do rascunho, sem repetir o listSubIssues.
210
179
  async function allStoriesReadyForReview(readToken, projToken, project, etapaField, featureNodeId) {
211
- if (!etapaField?.id) return true; // sem campo Etapa não há como checar — assume ok
212
180
  const subs = await listSubIssues(readToken, featureNodeId).catch(() => []);
213
- const stories = subs.filter(s => detectIssueType({ title: s.title }) === 'Story');
214
- if (stories.length === 0) return true;
181
+ const stories = subs
182
+ .filter(s => detectIssueType({ title: s.title }) === 'Story')
183
+ .map(s => ({ number: s.number, nodeId: s.nodeId }));
184
+ if (!etapaField?.id) return { ready: true, stories }; // sem campo Etapa não há como checar — assume ok
185
+ if (stories.length === 0) return { ready: true, stories };
215
186
  const tgtIdx = STAGE_ORDER.indexOf(CODE_REVIEW_STAGE);
216
187
  for (const st of stories) {
217
188
  const itemId = await addProjectItem(projToken, project.id, st.nodeId);
218
189
  const current = await getItemSingleSelectValue(projToken, itemId, etapaField.id).catch(() => null);
219
190
  const idx = current ? STAGE_ORDER.indexOf(current) : -1;
220
- if (idx === -1 || idx < tgtIdx) return false; // há Story pendente
191
+ if (idx === -1 || idx < tgtIdx) return { ready: false, stories }; // há Story pendente
221
192
  }
222
- return true;
193
+ return { ready: true, stories };
223
194
  }
224
195
 
225
196
  export async function codeReview({ prNumber, resolveOnly = false }) {
@@ -238,7 +209,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
238
209
  }
239
210
 
240
211
  const pr = await getPR(token, owner, repo, parseInt(prNumber, 10));
241
- const linkMode = cfg?.codeReview?.linkMode === 'any-mention' ? 'any-mention' : 'explicit';
212
+ const linkMode = resolveLinkMode(cfg);
242
213
 
243
214
  // Duas fontes de vínculo, nesta ordem: o que o GitHub reconhece nativamente
244
215
  // (o mesmo que fecha a issue no merge, e que cobre o vínculo feito pela UI) e
@@ -291,6 +262,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
291
262
  const featuresChecked = new Set();
292
263
  const deferred = new Set();
293
264
  const ignored = [];
265
+ const prontos = []; // PRs que saíram do rascunho porque a Feature terminou
294
266
 
295
267
  // Regras ao abrir o PR: Tasks → 🎉 Done (implementação concluída);
296
268
  // Stories → 👀 Code Review; Feature → Code Review só quando TODAS as suas
@@ -371,7 +343,8 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
371
343
  if (feature && !featuresChecked.has(feature.number)) {
372
344
  featuresChecked.add(feature.number);
373
345
  try {
374
- const ready = await allStoriesReadyForReview(token, projectToken, project, etapaField, feature.nodeId);
346
+ const { ready, stories: featureStories } = await allStoriesReadyForReview(
347
+ token, projectToken, project, etapaField, feature.nodeId);
375
348
  if (!ready) {
376
349
  console.log(`Feature #${feature.number} mantida em desenvolvimento — ainda há Stories pendentes (fora de "${CODE_REVIEW_STAGE}").`);
377
350
  } else if (!seen.has(feature.number)) {
@@ -385,6 +358,20 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
385
358
  } else {
386
359
  console.log(`Feature #${feature.number} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior.`);
387
360
  }
361
+ // Plano B do desrascunho. O caminho normal é o `implement` marcar os
362
+ // PRs ao concluir a última Story; se ele não chegou lá (execução
363
+ // interrompida, PR aberto depois), a Feature avançaria de Etapa aqui
364
+ // com os PRs ainda em rascunho — pronta para review no board e
365
+ // impossível de mergear no GitHub. Best-effort, como o resto.
366
+ const marcados = await markFeaturePrsReady({
367
+ token, owner, repo, feature, stories: featureStories, linkMode,
368
+ // `updated` vira a lista "Board atualizado" no comentário do PR;
369
+ // desrascunhar não é movimento de board e ganha parágrafo próprio.
370
+ log: { info: console.log, success: console.log, warn: console.warn },
371
+ });
372
+ if (marcados.length > 0) {
373
+ prontos.push(...marcados);
374
+ }
388
375
  }
389
376
  } catch (err) {
390
377
  console.warn(`Falha ao avaliar a Feature #${feature.number}: ${err.message}`);
@@ -392,7 +379,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
392
379
  }
393
380
  }
394
381
 
395
- if (updated.length > 0 || deferred.size > 0) {
382
+ if (updated.length > 0 || deferred.size > 0 || prontos.length > 0) {
396
383
  const partes = [];
397
384
  if (updated.length > 0) {
398
385
  partes.push(
@@ -401,6 +388,16 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
401
388
  updated.map(f => `- ${f}`).join('\n')
402
389
  );
403
390
  }
391
+ // Quem revisa precisa saber POR QUE os PRs saíram do rascunho de uma vez:
392
+ // é o sinal de que a feature inteira acabou e pode ser revisada.
393
+ if (prontos.length > 0) {
394
+ partes.push(
395
+ `✅ **Feature concluída — PRs prontos para revisão:** ` +
396
+ `${[...new Set(prontos)].sort((a, b) => a - b).map(n => `#${n}`).join(', ')}.\n\n` +
397
+ 'Todas as Stories terminaram, então os PRs saíram do rascunho juntos. ' +
398
+ 'Enquanto uma feature está em desenvolvimento, os PRs dela ficam em rascunho de propósito.'
399
+ );
400
+ }
404
401
  // O que ficou de fora precisa ser dito: silêncio aqui vira "o board está
405
402
  // certo" na cabeça de quem lê, que é exatamente o erro que se quer evitar.
406
403
  if (ignored.length > 0) {
@@ -29,6 +29,7 @@ import { cachedSubIssues } from '../lib/story-graph.mjs';
29
29
  import { affordCheck } from '../lib/rate-budget.mjs';
30
30
  import { resolveCacheTtl } from '../lib/net-cache.mjs';
31
31
  import { QA_PLAN_FILE } from '../lib/qa-plan-doc.mjs';
32
+ import { resolveQaEvidenceConfig } from '../lib/qa-exec.mjs';
32
33
  import { findConfigPath } from '../lib/project-root.mjs';
33
34
  import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
34
35
  import { unguardedWorkflows } from './mode.mjs';
@@ -1117,12 +1118,64 @@ export function inspectQaLead({ lead = null, dockerOk = null, schemasOk = true }
1117
1118
  return { warn, notes };
1118
1119
  }
1119
1120
 
1121
+ /**
1122
+ * Checks da evidência visual do QA (função PURA — testável sem PATH).
1123
+ *
1124
+ * `qa.platform` ausente é `web` (compatibilidade); a ferramenta configurada
1125
+ * mas fora do PATH é AVISO, não erro — o `qa` roda igual e só deixa de gravar
1126
+ * vídeo/foto (o executor omite `evidenceFiles`). Quando a evidência existe só
1127
+ * por default (nada declarado), ferramenta ausente é NOTA, não aviso: um
1128
+ * repositório que nunca configurou isso não pode passar a ver um `!` no doctor.
1129
+ *
1130
+ * @param {object} params
1131
+ * @param {{platform:string, tool:string|null, appId?:string|null, explicit?:boolean}} params.evidence saída de resolveQaEvidenceConfig()
1132
+ * @param {(tool: string) => boolean|null} [params.hasTool] a ferramenta está no PATH? (null = não verificável)
1133
+ * @returns {{ warn: boolean, notes: string[] }}
1134
+ */
1135
+ export function inspectQaEvidence({ evidence, hasTool = () => null } = {}) {
1136
+ const notes = [];
1137
+ let warn = false;
1138
+ const platform = evidence?.platform || 'web';
1139
+ const tool = evidence?.tool || null;
1140
+ if (!tool) {
1141
+ notes.push(`Evidência visual: plataforma ${platform}, gravação desligada (qa.${platform}.evidence = none).`);
1142
+ return { warn, notes };
1143
+ }
1144
+ if (platform === 'mobile' && !evidence?.appId) {
1145
+ warn = true;
1146
+ notes.push('Evidência visual: `qa.mobile.appId` ausente — o executor precisa dele para abrir o app no Maestro.');
1147
+ }
1148
+ const found = hasTool(tool);
1149
+ if (found === false) {
1150
+ if (evidence?.explicit) warn = true;
1151
+ notes.push(
1152
+ `Evidência visual: plataforma ${platform}, ferramenta ${tool}${evidence?.explicit ? '' : ' (padrão)'} ` +
1153
+ `NÃO encontrada no PATH — o \`qa\` executa igual, só sem vídeo/foto. Instale-a ou desligue com ` +
1154
+ `"qa": { "${platform}": { "evidence": "none" } }.`
1155
+ );
1156
+ } else {
1157
+ notes.push(`Evidência visual: plataforma ${platform}, ferramenta ${tool}${found ? ' (no PATH)' : ''} — publica em docs/…/qa/cenario-<n>/ (teto 4 MB por arquivo).`);
1158
+ }
1159
+ return { warn, notes };
1160
+ }
1161
+
1162
+ // A ferramenta de gravação está no PATH (ou no node_modules do projeto)?
1163
+ function evidenceToolOnPath(root, tool) {
1164
+ try {
1165
+ if (tool === 'playwright' && root && existsSync(path.join(root, 'node_modules', '.bin', 'playwright'))) return true;
1166
+ execSync(`command -v ${tool}`, { stdio: ['ignore', 'pipe', 'pipe'], shell: '/bin/sh' });
1167
+ return true;
1168
+ } catch {
1169
+ return false;
1170
+ }
1171
+ }
1172
+
1120
1173
  // QA (rfc/spec-qa-skill.md + rfc/spec-qa-lead.md): executor configurado,
1121
1174
  // Features em 🧪 QA com plano, e a configuração do orquestrador de trilha.
1122
1175
  // As labels novas e o workflow generate-qa-plan.yml são cobertos pelos checks
1123
1176
  // existentes (higiene de labels e workflows), que leem as listas do config.mjs.
1124
1177
  async function checkQa(ctx) {
1125
- const name = 'QA (qa.command, planos das Features em 🧪 QA e qa-lead)';
1178
+ const name = 'QA (qa.command, evidência visual, planos das Features em 🧪 QA e qa-lead)';
1126
1179
  const notes = [];
1127
1180
  let status = 'ok';
1128
1181
 
@@ -1147,6 +1200,14 @@ async function checkQa(ctx) {
1147
1200
  );
1148
1201
  }
1149
1202
 
1203
+ // Evidência visual (vídeo/foto por cenário): plataforma + ferramenta no PATH.
1204
+ const evidenceCheck = inspectQaEvidence({
1205
+ evidence: resolveQaEvidenceConfig(ctx.cfg?.qa),
1206
+ hasTool: tool => evidenceToolOnPath(ctx.root, tool),
1207
+ });
1208
+ if (evidenceCheck.warn) status = 'warn';
1209
+ notes.push(...evidenceCheck.notes);
1210
+
1150
1211
  if (ctx.token && ctx.cfg?.project?.id && ctx.root) {
1151
1212
  try {
1152
1213
  const items = await listProjectItems(ctx.token, ctx.cfg.project.id);
@@ -20,6 +20,8 @@ import { slugify } from '../lib/slugify.mjs';
20
20
  import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
21
21
  import { loadProjectConfig } from '../lib/board.mjs';
22
22
  import { planBoardMoves, applyBoardMoves } from '../lib/implement-board.mjs';
23
+ import { markFeaturePrsReady } from '../lib/pr-ready.mjs';
24
+ import { resolveLinkMode } from '../lib/pr-link.mjs';
23
25
  import { extractPathsFromPlan, buildCodeDigest } from '../lib/code-digest.mjs';
24
26
  import { findConfigPath, resolveFromRoot, loadConfig } from '../lib/project-root.mjs';
25
27
  import { loadFeatureStories, loadBoardSnapshot, cachedSubIssues } from '../lib/story-graph.mjs';
@@ -245,9 +247,10 @@ export function buildContext({
245
247
  // Draft de propósito: numa pilha de Stories (um PR baseado no anterior),
246
248
  // cada rebase em cascata dispararia o CI inteiro em PRs que ninguém vai
247
249
  // mergear naquele estado. Rascunho não mergeia (o GitHub bloqueia) e o
248
- // required check continua valendo: quem revisa marca o PR como pronto, o
249
- // `ready_for_review` dispara o CI, e só então o merge destrava.
250
- 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.`);
250
+ // required check continua valendo. Quem tira do rascunho é o próprio
251
+ // implement, quando a ÚLTIMA Story da Feature entra em Code Review (ver
252
+ // lib/pr-ready.mjs): até lá o rascunho diz "feature em andamento".
253
+ lines.push(` 2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`), **com \`Closes #${issue.number}\` no corpo** — é esse vínculo que localiza o PR da Story. Deixe em rascunho: o \`spec-wave implement\` marca TODOS os PRs da Feature como prontos de uma vez quando a última Story concluir, e é aí que os checks disparam. **Não marque como pronto manualmente.**`);
251
254
  }
252
255
  lines.push(
253
256
  ` 3. **Avance a Etapa da Story #${issue.number} para ${STAGE_CODE_REVIEW}** ` +
@@ -447,8 +450,9 @@ export function buildFeatureContext({
447
450
  } else {
448
451
  lines.push(
449
452
  `3. **Ao concluir TODAS as Tasks da Story:** faça o **commit** (assunto livre; rodapé com os trailers abaixo), ` +
450
- `abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\` — o CI não roda em rascunho; ` +
451
- `quem revisa marca o PR como pronto e os checks disparam) e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`
453
+ `abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\`), **com \`Closes #<story>\` no corpo** — ` +
454
+ `é esse vínculo que o \`merge\`, o \`code-review\` e o desrascunho usam para achar o PR da Story — ` +
455
+ `e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`
452
456
  );
453
457
  }
454
458
  lines.push(' ```');
@@ -459,7 +463,13 @@ export function buildFeatureContext({
459
463
  lines.push(
460
464
  `**Feature #${feature.number}:** avance-a para a Etapa **${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}) ` +
461
465
  `**somente após concluir a ÚLTIMA Story da lista**${skipped.length > 0 ? ' (as Stories já implementadas listadas abaixo não precisam ser refeitas)' : ''}. ` +
462
- `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.`
466
+ `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.` +
467
+ // Só na pilha existem PRs de Story para deixar em rascunho; no modo agent o
468
+ // único PR é o do daemon, aberto por ele mesmo depois de tudo pronto.
469
+ (mode === 'agent' ? '' :
470
+ ' Os PRs ficam **em rascunho até o fim**: quando a última Story concluir, o próprio ' +
471
+ '`spec-wave implement` marca todos como prontos para revisão de uma vez — ' +
472
+ '**não tire nenhum PR do rascunho manualmente**, é esse rascunho que avisa que a feature ainda está em andamento.')
463
473
  );
464
474
  lines.push('');
465
475
  if (mode === 'agent') {
@@ -718,6 +728,14 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
718
728
  await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {
719
729
  feature: { nodeId: feature.node_id, number: feature.number },
720
730
  }) });
731
+ // Mesmo destravamento do lado dos PRs: a Feature está pronta para review,
732
+ // então nenhum PR dela tem motivo para continuar em rascunho.
733
+ await markFeaturePrsReady({
734
+ token, owner, repo, dryRun,
735
+ feature: { nodeId: feature.node_id, number: feature.number },
736
+ stories: enriched,
737
+ linkMode: resolveLinkMode(config),
738
+ });
721
739
  p.outro(`Todas as ${stories.length} story(ies) da Feature #${feature.number} já estão implementadas — nada a fazer.`);
722
740
  return;
723
741
  }
@@ -863,6 +881,16 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
863
881
  await applyBoardMoves({ token, moves: planBoardMoves('success', {
864
882
  feature: { nodeId: feature.node_id, number: feature.number },
865
883
  }) });
884
+ // A Feature avançou de Etapa; os PRs precisam contar a mesma história.
885
+ // Enquanto as Stories eram implementadas, cada PR nasceu em rascunho para
886
+ // dizer "ainda estou trabalhando" — agora todos saem juntos, e a feature
887
+ // inteira fica revisável no mesmo instante.
888
+ await markFeaturePrsReady({
889
+ token, owner, repo,
890
+ feature: { nodeId: feature.node_id, number: feature.number },
891
+ stories: enriched,
892
+ linkMode: resolveLinkMode(config),
893
+ });
866
894
  },
867
895
  });
868
896
  }
@@ -1109,6 +1137,17 @@ export async function implement({
1109
1137
  await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {
1110
1138
  feature: { nodeId: feature.nodeId, number: feature.number },
1111
1139
  }) });
1140
+ // Chegou aqui = era a última Story pendente. É ESTE o momento que o
1141
+ // rascunho dos PRs estava esperando: enquanto o dev-agent ia de Story em
1142
+ // Story, cada PR aberto em rascunho sinalizava "feature em andamento, não
1143
+ // revise nem mergeie ainda". Com a feature completa, todos saem do
1144
+ // rascunho de uma vez e a review pode começar pela pilha inteira.
1145
+ await markFeaturePrsReady({
1146
+ token, owner, repo, dryRun,
1147
+ feature: { nodeId: feature.nodeId, number: feature.number },
1148
+ stories: [...siblingStories, { number: issue.number, nodeId: issue.node_id }],
1149
+ linkMode: resolveLinkMode(config),
1150
+ });
1112
1151
  },
1113
1152
  });
1114
1153
  }
@@ -24,7 +24,7 @@ import {
24
24
  getIssue, getPR, getRepoDefaultBranch, updatePRBase, mergePR, deleteBranch,
25
25
  listPullRequestCommitMessages,
26
26
  } from '../api/github-rest.mjs';
27
- import { listIssuePullRequests } from '../api/github-graphql.mjs';
27
+ import { listIssuePullRequests, listOpenPullRequests } from '../api/github-graphql.mjs';
28
28
  import { missingTrailers } from '../lib/commit-trailers.mjs';
29
29
  import { detectIssueType } from '../lib/issue-type.mjs';
30
30
  import { orderStories } from '../lib/dependencies.mjs';
@@ -33,7 +33,7 @@ import { loadFeatureStories } from '../lib/story-graph.mjs';
33
33
  import { resolveCacheTtl, invalidateCache } from '../lib/net-cache.mjs';
34
34
  import { CONFIG_FILE } from '../config.mjs';
35
35
  import { acquireLock, releaseLock } from './run.mjs';
36
- import { codeReview } from './code-review.mjs';
36
+ import { codeReview, extractIssueNumbers } from './code-review.mjs';
37
37
  import { qa } from './qa.mjs';
38
38
 
39
39
  /**
@@ -112,6 +112,39 @@ export function planMerge({ sorted = [], byNumber = new Map(), prsByStory = new
112
112
  return { fila, concluidas, semPr, bloqueios, avisos };
113
113
  }
114
114
 
115
+ /**
116
+ * Complementa o vínculo nativo com o parse do corpo (função PURA — testável).
117
+ *
118
+ * O GitHub só cria closedByPullRequestsReferences quando a base do PR é a
119
+ * default — numa pilha, só o PR de baixo tem, e as Stories dos demais chegavam
120
+ * aqui "sem PR" e ficavam fora da fila. O corpo (`Closes #N`, mesmo parser do
121
+ * code-review) preenche exatamente esse vão. Só Stories SEM vínculo nativo
122
+ * recebem PRs do corpo — quando o GitHub conhece o PR, a fonte nativa vence e
123
+ * uma menção redundante no corpo de outro PR não cria ambiguidade.
124
+ *
125
+ * @param {object} params
126
+ * @param {number[]} params.sorted ordem topológica (números de Story)
127
+ * @param {Map<number, Array>} params.prsByStory vínculos nativos já coletados
128
+ * @param {Array<{number, body}>} params.openPrs PRs abertos do repositório
129
+ * @param {'explicit'|'any-mention'} [params.linkMode]
130
+ * @returns {{ prsByStory: Map<number, Array>, adicionados: Array<{story:number, pr:number}> }}
131
+ */
132
+ export function complementWithBodyLinks({ sorted = [], prsByStory = new Map(), openPrs = [], linkMode = 'explicit' } = {}) {
133
+ const out = new Map(prsByStory);
134
+ const adicionados = [];
135
+ const faltantes = new Set(sorted.filter(s => (out.get(s) || []).length === 0));
136
+ if (faltantes.size === 0) return { prsByStory: out, adicionados };
137
+
138
+ for (const pr of openPrs) {
139
+ for (const n of extractIssueNumbers(pr.body || '', { linkMode })) {
140
+ if (!faltantes.has(n)) continue;
141
+ out.set(n, [...(out.get(n) || []), pr]);
142
+ adicionados.push({ story: n, pr: pr.number });
143
+ }
144
+ }
145
+ return { prsByStory: out, adicionados };
146
+ }
147
+
115
148
  export async function merge({
116
149
  feature: featureArg, yes = false, dryRun = false, keepBranches = false,
117
150
  remote = false, refresh = false,
@@ -226,11 +259,27 @@ export async function merge({
226
259
  return;
227
260
  }
228
261
 
229
- const prsByStory = new Map();
262
+ let prsByStory = new Map();
230
263
  for (const story of sorted) {
231
264
  prsByStory.set(story, await listIssuePullRequests(token, byNumber.get(story).nodeId).catch(() => []));
232
265
  }
233
266
 
267
+ // Vínculo nativo só existe com base na default — numa pilha, só o PR de
268
+ // baixo. Para as Stories que ficaram sem nada, o corpo dos PRs abertos
269
+ // (`Closes #N`) é a fonte que o autor de fato escreveu.
270
+ if (sorted.some(story => (prsByStory.get(story) || []).length === 0)) {
271
+ const abertos = await listOpenPullRequests(token, owner, repo).catch(() => []);
272
+ const linkMode = fileConfig?.codeReview?.linkMode === 'any-mention' ? 'any-mention' : 'explicit';
273
+ const comp = complementWithBodyLinks({ sorted, prsByStory, openPrs: abertos, linkMode });
274
+ prsByStory = comp.prsByStory;
275
+ if (comp.adicionados.length > 0) {
276
+ p.log.info(chalk.dim(
277
+ comp.adicionados.map(({ story, pr }) => `Story #${story} ← PR #${pr}`).join(' · ') +
278
+ ' — vínculo pelo corpo (Closes #N); o GitHub só registra o nativo quando a base é a default.'
279
+ ));
280
+ }
281
+ }
282
+
234
283
  const plano = planMerge({ sorted, byNumber, prsByStory, defaultBranch });
235
284
  s.stop(`${plano.fila.length} PR(s) a mergear · ${plano.concluidas.length} já mergeado(s).`);
236
285