@spec-wave/cli 0.34.2 → 1.0.1

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.
Files changed (52) hide show
  1. package/package.json +2 -2
  2. package/protocol/qa-result.v1.json +9 -0
  3. package/src/agent/anthropic-agent.mjs +35 -2
  4. package/src/api/github-graphql.mjs +60 -2
  5. package/src/api/github-rest.mjs +23 -0
  6. package/src/cli.mjs +23 -0
  7. package/src/commands/code-review.mjs +71 -60
  8. package/src/commands/decompose.mjs +75 -4
  9. package/src/commands/doctor.mjs +105 -4
  10. package/src/commands/implement.mjs +82 -10
  11. package/src/commands/init.mjs +147 -29
  12. package/src/commands/merge.mjs +56 -4
  13. package/src/commands/move.mjs +4 -7
  14. package/src/commands/order.mjs +2 -2
  15. package/src/commands/qa-run.mjs +140 -19
  16. package/src/commands/qa.mjs +22 -21
  17. package/src/commands/repair-stage.mjs +2 -5
  18. package/src/commands/story.mjs +2 -2
  19. package/src/commands/task.mjs +2 -2
  20. package/src/commands/triage.mjs +2 -5
  21. package/src/commands/update.mjs +31 -8
  22. package/src/commands/validate.mjs +2 -5
  23. package/src/commands/workspace.mjs +112 -0
  24. package/src/config.mjs +19 -0
  25. package/src/lib/artifact-pr.mjs +1 -1
  26. package/src/lib/bug-doc.mjs +6 -1
  27. package/src/lib/claude.mjs +4 -0
  28. package/src/lib/decomposition-doc.mjs +56 -3
  29. package/src/lib/dependency-map.mjs +3 -0
  30. package/src/lib/doc-paths.mjs +6 -1
  31. package/src/lib/flow-run.mjs +14 -3
  32. package/src/lib/pr-link.mjs +109 -0
  33. package/src/lib/pr-ready.mjs +146 -0
  34. package/src/lib/project-root.mjs +51 -0
  35. package/src/lib/qa-exec.mjs +73 -0
  36. package/src/lib/qa-report.mjs +172 -8
  37. package/src/lib/repo-role.mjs +102 -0
  38. package/src/lib/workspace.mjs +151 -0
  39. package/src/plugin/.claude-plugin/plugin.json +1 -1
  40. package/src/plugin/skills/decompose/SKILL.md +1 -0
  41. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  42. package/src/plugin/skills/implement/SKILL.md +2 -2
  43. package/src/plugin/skills/merge/SKILL.md +3 -2
  44. package/src/plugin/skills/qa/SKILL.md +6 -1
  45. package/src/plugin/skills/qa-executor/SKILL.md +43 -1
  46. package/src/plugin/skills/setup/SKILL.md +12 -0
  47. package/src/setup/files.mjs +35 -13
  48. package/src/templates/skill/SKILL.md +27 -5
  49. package/src/templates/skill/core.md +5 -1
  50. package/src/templates/workflows/code/code-review.yml +60 -0
  51. package/src/templates/workflows/code/qa.yml +59 -0
  52. package/src/templates/workflows/pr-events.yml +116 -0
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "0.34.2",
3
+ "version": "1.0.1",
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": {
7
- "spec-wave": "./bin/spec-wave.mjs"
7
+ "spec-wave": "bin/spec-wave.mjs"
8
8
  },
9
9
  "publishConfig": {
10
10
  "access": "public"
@@ -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",
@@ -43,6 +43,38 @@ export function withoutBlankCredentials(env) {
43
43
  return copy;
44
44
  }
45
45
 
46
+ /**
47
+ * Ambiente do subprocesso com UMA credencial: a que o provider escolheu
48
+ * (função PURA).
49
+ *
50
+ * Os providers `anthropic` e `claude-oauth` rodam neste mesmo backend e diferem
51
+ * SÓ na credencial — mas o Claude Code não lê o `.spec-wave.json`: ele resolve
52
+ * credencial por conta própria, e nessa ordem `ANTHROPIC_API_KEY` vem ANTES do
53
+ * token da assinatura. Com as duas no ambiente, quem escolheu `claude-oauth`
54
+ * era silenciosamente atendido pela chave de API, e a falha aparecia como um
55
+ * erro da conta errada (foi "Credit balance is too low" de uma conta de API
56
+ * zerada, num repo que tinha assinatura válida).
57
+ *
58
+ * Por isso a decisão não pode ficar com o Claude Code: quem sabe qual credencial
59
+ * vale é o config, e `credentialVar` é como essa decisão chega até aqui. O
60
+ * backend continua sem saber o que é `claude-oauth` — ele recebe o NOME da
61
+ * variável, não o provider.
62
+ *
63
+ * Sem `credentialVar` o comportamento é o de antes (só o saneamento de vazias):
64
+ * é o caso de quem chama o motor direto, sem config resolvido.
65
+ *
66
+ * @param {object} env
67
+ * @param {string|null} [credentialVar] nome da variável a preservar
68
+ */
69
+ export function credentialEnvFor(env, credentialVar = null) {
70
+ const copy = withoutBlankCredentials(env);
71
+ if (!credentialVar) return copy;
72
+ for (const key of CREDENTIAL_VARS) {
73
+ if (key !== credentialVar) delete copy[key];
74
+ }
75
+ return copy;
76
+ }
77
+
46
78
  /** Base de comparação da allowlist: absoluto resolvido, minúsculo no win32. */
47
79
  function normalizeWritePath(p) {
48
80
  const resolved = path.resolve(p);
@@ -142,8 +174,9 @@ export async function runAnthropicAgent(prompt, options) {
142
174
  // (PATH, HOME). O saneamento existe porque `${{ secrets.X }}` de um
143
175
  // secret inexistente injeta string VAZIA: um CLAUDE_CODE_OAUTH_TOKEN=""
144
176
  // chegando ao CLI é ambiguidade gratuita entre "não configurado" e
145
- // "configurado errado".
146
- env: withoutBlankCredentials(process.env),
177
+ // "configurado errado". E `credentialVar` deixa passar SÓ a credencial
178
+ // do provider escolhido — ver credentialEnvFor.
179
+ env: credentialEnvFor(process.env, options.credentialVar ?? null),
147
180
  // Desliga o carregamento de settings do filesystem (~/.claude,
148
181
  // .claude/settings.json) para o subprocesso não herdar hooks ou
149
182
  // permissões de fora deste `queryOptions`.
@@ -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
@@ -24,6 +24,29 @@ export async function getOwnerNodeId(token, owner) {
24
24
  }
25
25
  }
26
26
 
27
+ // GitHub Projects v2 só é acessível pelo GitHub App do spec-wave quando o
28
+ // owner é uma organização — Projects v2 de conta pessoal não são suportados
29
+ // pela instalação do App. Usado por `init` (bloqueia antes de criar repo/project)
30
+ // e por `doctor` (diagnóstico de instalações já configuradas).
31
+ export async function getOwnerType(token, owner) {
32
+ const octokit = makeOctokit(token);
33
+ try {
34
+ await octokit.rest.orgs.get({ org: owner });
35
+ return 'Organization';
36
+ } catch (err) {
37
+ if (err.status !== 404) throw err;
38
+ }
39
+ try {
40
+ await octokit.rest.users.getByUsername({ username: owner });
41
+ return 'User';
42
+ } catch (err) {
43
+ if (err.status === 404) {
44
+ throw new Error(`Owner "${owner}" não encontrado no GitHub.`);
45
+ }
46
+ throw err;
47
+ }
48
+ }
49
+
27
50
  export async function getRepoNodeId(token, owner, repo) {
28
51
  const octokit = makeOctokit(token);
29
52
  const res = await octokit.rest.repos.get({ owner, repo });
package/src/cli.mjs CHANGED
@@ -45,6 +45,8 @@ export function buildProgram() {
45
45
  .description('Configura spec-wave em um repositório GitHub')
46
46
  .option('--dry-run', 'Simula a configuração sem fazer alterações')
47
47
  .option('--repo <owner/repo>', 'Repositório GitHub (ignora o wizard interativo)')
48
+ .option('--role <role>', 'Papel do repositório no Project (RFC-005): hub (issues, docs e workflows — padrão) ou code (só branch e PR)')
49
+ .option('--hub <owner/repo>', 'Com --role code: o repositório hub do Project a que este repo de código pertence')
48
50
  .option('--project-title <title>', 'Nome do GitHub Project (padrão: "<repo> — Spec Wave")')
49
51
  .option('--skip-project', 'Pula a criação do GitHub Project (use se já foi criado)')
50
52
  .option('--skip-labels', 'Pula a criação das labels')
@@ -313,6 +315,7 @@ export function buildProgram() {
313
315
  .command('code-review')
314
316
  .description('Move Feature para Code Review ao abrir um PR (usado pelo GitHub Action)')
315
317
  .requiredOption('--pr-number <n>', 'Número do Pull Request')
318
+ .option('--pr-repo <owner/repo>', 'Repositório onde o PR foi aberto, quando não é o hub (multi-repo, RFC-005)')
316
319
  .option('--resolve-only', 'Só descobre a Feature-alvo e imprime feature=<n>, sem tocar no board')
317
320
  .action(async (options) => {
318
321
  const { codeReview } = await import('./commands/code-review.mjs');
@@ -324,6 +327,7 @@ export function buildProgram() {
324
327
  .description('Executa o plano de QA de uma issue (Feature/Story/Bug) localmente; com --pr-number, move a Feature para QA (usado pelo GitHub Action)')
325
328
  .argument('[issue]', 'Número da issue (Feature, Story ou Bug), ex.: 12 ou #12')
326
329
  .option('--pr-number <n>', 'Modo Action: move a Feature/Bug do PR aprovado ou mergeado para 🧪 QA')
330
+ .option('--pr-repo <owner/repo>', 'Com --pr-number: repositório onde o PR foi aberto, quando não é o hub (multi-repo, RFC-005)')
327
331
  .option('--only <n[,m]>', 'Executa só o(s) cenário(s) indicado(s) — número POSICIONAL no plano')
328
332
  .option('--severity <p>', 'Severidade dos Bugs abertos na reprova: P0, P1, P2 ou P3 (default: qa.defaultBugPriority ou P2)')
329
333
  .option('--dry-run', 'Monta o contexto e imprime cenários e comando — ZERO escrita no GitHub')
@@ -368,6 +372,25 @@ Re-teste após o fix: qa <story> --only <cenário> (não duplica Bug — comenta
368
372
 
369
373
  Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
370
374
 
375
+ program
376
+ .command('workspace')
377
+ .description('Monta o workspace multi-repo de uma issue (RFC-005): mapeia ou clona, ao lado do hub, os repositórios que ela declara com repo:<slug>')
378
+ .argument('<acao>', 'prepare')
379
+ .requiredOption('--issue <n>', 'Feature (agrega os repos das Stories), Story ou Task')
380
+ .option('--json', 'Imprime o layout em JSON (workspaceDir, repos[], repoDirs) — para o Action e para scripts')
381
+ .option('--dry-run', 'Resolve o layout e imprime; não clona nada')
382
+ .option('--refresh', 'Ignora o cache de sub-issues ao agregar os repos de uma Feature')
383
+ .action(async (acao, options) => {
384
+ const { workspace } = await import('./commands/workspace.mjs');
385
+ await workspace({ action: acao, ...options })
386
+ .catch(err => { console.error(err.message); process.exit(1); });
387
+ })
388
+ .addHelpText('after', `
389
+ Ordem de resolução por slug: override em .spec-wave/workspace.json ({ "dirs": { "<slug>": "<caminho>" } })
390
+ → irmão do hub (<pai do hub>/<slug>) → clone gerenciado em <hub>/.spec-wave/repos/<slug>.
391
+ Irmãos e overrides são seus: nunca são clonados nem tocados. O implement lê o mesmo layout
392
+ para preencher {workspaceDir} e {repoDirs} no comando do spec-kit.`);
393
+
371
394
  program
372
395
  .command('qa-lead')
373
396
  .description('Orquestra o QA de uma trilha (milestone): prepara os planos (plan), executa o ciclo em containers paralelos (run) e reimprime relatórios (report)')
@@ -6,7 +6,9 @@ import {
6
6
  } from '../api/github-graphql.mjs';
7
7
  import { detectIssueType } from '../lib/issue-type.mjs';
8
8
  import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
9
- import { loadConfig } from '../lib/project-root.mjs';
9
+ import { resolveHubContext, resolvePrRepo } from '../lib/project-root.mjs';
10
+ import { markFeaturePrsReady } from '../lib/pr-ready.mjs';
11
+ import { extractIssueRefs, hubIssueNumbers, resolveLinkMode, sameRepo } from '../lib/pr-link.mjs';
10
12
  import {
11
13
  STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType,
12
14
  LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY, labelNames,
@@ -19,45 +21,6 @@ const DONE_STAGE = STAGE_DONE;
19
21
  const TODO_STATUS = PROGRESS_TODO;
20
22
  const DONE_STATUS = PROGRESS_DONE;
21
23
 
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
24
  /**
62
25
  * Recorte temporal da subárvore (função PURA — testável).
63
26
  *
@@ -207,28 +170,35 @@ async function collectReviewUnit(token, owner, repo, issueNumber, { notAfter = n
207
170
 
208
171
  // A Feature só avança quando TODAS as suas Stories já estiverem em Code Review
209
172
  // (ou etapa posterior). readToken lê as issues; projToken opera no Project.
173
+ //
174
+ // Devolve também as Stories: quem chama usa a mesma lista para tirar os PRs da
175
+ // Feature do rascunho, sem repetir o listSubIssues.
210
176
  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
177
  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;
178
+ const stories = subs
179
+ .filter(s => detectIssueType({ title: s.title }) === 'Story')
180
+ .map(s => ({ number: s.number, nodeId: s.nodeId }));
181
+ if (!etapaField?.id) return { ready: true, stories }; // sem campo Etapa não há como checar — assume ok
182
+ if (stories.length === 0) return { ready: true, stories };
215
183
  const tgtIdx = STAGE_ORDER.indexOf(CODE_REVIEW_STAGE);
216
184
  for (const st of stories) {
217
185
  const itemId = await addProjectItem(projToken, project.id, st.nodeId);
218
186
  const current = await getItemSingleSelectValue(projToken, itemId, etapaField.id).catch(() => null);
219
187
  const idx = current ? STAGE_ORDER.indexOf(current) : -1;
220
- if (idx === -1 || idx < tgtIdx) return false; // há Story pendente
188
+ if (idx === -1 || idx < tgtIdx) return { ready: false, stories }; // há Story pendente
221
189
  }
222
- return true;
190
+ return { ready: true, stories };
223
191
  }
224
192
 
225
- export async function codeReview({ prNumber, resolveOnly = false }) {
193
+ export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = false }) {
226
194
  const token = await resolveToken();
227
195
  const projectToken = process.env.PROJECT_TOKEN || token;
228
- const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
229
- const { config: cfg } = loadConfig();
230
- const owner = envOwner || cfg?.owner;
231
- const repo = envRepo || cfg?.repo;
196
+ // Dois repositórios, que só coincidem no mono-repo: o hub (dono das issues e
197
+ // do board) e o repositório onde o PR foi aberto. O comando roda SEMPRE no
198
+ // hub (RFC-005 §7.1) — o repo de código não executa a CLI — então
199
+ // GITHUB_REPOSITORY/config dão o hub, e `--pr-repo` diz onde está o PR.
200
+ const ctx = resolveHubContext();
201
+ const { owner, repo, config: cfg } = ctx;
232
202
 
233
203
  if (!owner || !repo) {
234
204
  throw new Error(
@@ -236,18 +206,33 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
236
206
  'Defina GITHUB_REPOSITORY=owner/repo ou rode dentro de um repositório com .spec-wave.json.'
237
207
  );
238
208
  }
209
+ const hub = { owner, repo };
210
+ const prRepo = resolvePrRepo(prRepoOpt, ctx);
211
+ const prNum = parseInt(prNumber, 10);
239
212
 
240
- const pr = await getPR(token, owner, repo, parseInt(prNumber, 10));
241
- const linkMode = cfg?.codeReview?.linkMode === 'any-mention' ? 'any-mention' : 'explicit';
213
+ const pr = await getPR(token, prRepo.owner, prRepo.repo, prNum);
214
+ const linkMode = resolveLinkMode(cfg);
242
215
 
243
216
  // Duas fontes de vínculo, nesta ordem: o que o GitHub reconhece nativamente
244
217
  // (o mesmo que fecha a issue no merge, e que cobre o vínculo feito pela UI) e
245
218
  // o que está escrito no corpo. `Implements #N` só existe na segunda.
246
- const linked = await getPRClosingIssues(token, owner, repo, parseInt(prNumber, 10)).catch(err => {
247
- console.warn(`Não foi possível ler os vínculos nativos do PR: ${err.message}`);
248
- return [];
249
- });
250
- const issueNums = [...new Set([...linked, ...extractIssueNumbers(pr.body || '', { linkMode })])];
219
+ // O vínculo nativo é sempre do repositório do PR — cross-repo o GitHub não
220
+ // popula (RFC-005 §4) — então só conta quando o PR está no próprio hub.
221
+ const linked = sameRepo(prRepo, hub)
222
+ ? await getPRClosingIssues(token, prRepo.owner, prRepo.repo, prNum).catch(err => {
223
+ console.warn(`Não foi possível ler os vínculos nativos do PR: ${err.message}`);
224
+ return [];
225
+ })
226
+ : [];
227
+ const refs = extractIssueRefs(pr.body || '', { prRepo, linkMode });
228
+ const issueNums = [...new Set([...linked, ...hubIssueNumbers(refs, hub)])];
229
+ const foraDoHub = refs.filter(r => !sameRepo(r, hub));
230
+ if (foraDoHub.length > 0) {
231
+ console.log(
232
+ `Ignorando vínculo com issue de outro repositório: ${foraDoHub.map(r => `${r.owner}/${r.repo}#${r.number}`).join(', ')} ` +
233
+ `(o board é de ${owner}/${repo}).`
234
+ );
235
+ }
251
236
 
252
237
  if (issueNums.length === 0) {
253
238
  console.log(
@@ -291,6 +276,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
291
276
  const featuresChecked = new Set();
292
277
  const deferred = new Set();
293
278
  const ignored = [];
279
+ const prontos = []; // PRs que saíram do rascunho porque a Feature terminou
294
280
 
295
281
  // Regras ao abrir o PR: Tasks → 🎉 Done (implementação concluída);
296
282
  // Stories → 👀 Code Review; Feature → Code Review só quando TODAS as suas
@@ -371,7 +357,8 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
371
357
  if (feature && !featuresChecked.has(feature.number)) {
372
358
  featuresChecked.add(feature.number);
373
359
  try {
374
- const ready = await allStoriesReadyForReview(token, projectToken, project, etapaField, feature.nodeId);
360
+ const { ready, stories: featureStories } = await allStoriesReadyForReview(
361
+ token, projectToken, project, etapaField, feature.nodeId);
375
362
  if (!ready) {
376
363
  console.log(`Feature #${feature.number} mantida em desenvolvimento — ainda há Stories pendentes (fora de "${CODE_REVIEW_STAGE}").`);
377
364
  } else if (!seen.has(feature.number)) {
@@ -385,6 +372,20 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
385
372
  } else {
386
373
  console.log(`Feature #${feature.number} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior.`);
387
374
  }
375
+ // Plano B do desrascunho. O caminho normal é o `implement` marcar os
376
+ // PRs ao concluir a última Story; se ele não chegou lá (execução
377
+ // interrompida, PR aberto depois), a Feature avançaria de Etapa aqui
378
+ // com os PRs ainda em rascunho — pronta para review no board e
379
+ // impossível de mergear no GitHub. Best-effort, como o resto.
380
+ const marcados = await markFeaturePrsReady({
381
+ token, owner, repo, feature, stories: featureStories, linkMode,
382
+ // `updated` vira a lista "Board atualizado" no comentário do PR;
383
+ // desrascunhar não é movimento de board e ganha parágrafo próprio.
384
+ log: { info: console.log, success: console.log, warn: console.warn },
385
+ });
386
+ if (marcados.length > 0) {
387
+ prontos.push(...marcados);
388
+ }
388
389
  }
389
390
  } catch (err) {
390
391
  console.warn(`Falha ao avaliar a Feature #${feature.number}: ${err.message}`);
@@ -392,7 +393,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
392
393
  }
393
394
  }
394
395
 
395
- if (updated.length > 0 || deferred.size > 0) {
396
+ if (updated.length > 0 || deferred.size > 0 || prontos.length > 0) {
396
397
  const partes = [];
397
398
  if (updated.length > 0) {
398
399
  partes.push(
@@ -401,6 +402,16 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
401
402
  updated.map(f => `- ${f}`).join('\n')
402
403
  );
403
404
  }
405
+ // Quem revisa precisa saber POR QUE os PRs saíram do rascunho de uma vez:
406
+ // é o sinal de que a feature inteira acabou e pode ser revisada.
407
+ if (prontos.length > 0) {
408
+ partes.push(
409
+ `✅ **Feature concluída — PRs prontos para revisão:** ` +
410
+ `${[...new Set(prontos)].sort((a, b) => a - b).map(n => `#${n}`).join(', ')}.\n\n` +
411
+ 'Todas as Stories terminaram, então os PRs saíram do rascunho juntos. ' +
412
+ 'Enquanto uma feature está em desenvolvimento, os PRs dela ficam em rascunho de propósito.'
413
+ );
414
+ }
404
415
  // O que ficou de fora precisa ser dito: silêncio aqui vira "o board está
405
416
  // certo" na cabeça de quem lê, que é exatamente o erro que se quer evitar.
406
417
  if (ignored.length > 0) {
@@ -415,7 +426,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
415
426
  `\`npx @spec-wave/cli@latest code-review --pr-number ${prNumber}\`.`
416
427
  );
417
428
  }
418
- await commentOnIssue(token, owner, repo, parseInt(prNumber, 10), partes.join('\n\n')).catch(() => {});
429
+ await commentOnIssue(token, prRepo.owner, prRepo.repo, prNum, partes.join('\n\n')).catch(() => {});
419
430
  }
420
431
 
421
432
  console.log(`code-review: ${updated.length} item(ns) atualizado(s) no board.`);
@@ -19,9 +19,10 @@
19
19
  import { execSync } from 'node:child_process';
20
20
  import { resolveToken } from '../api/auth.mjs';
21
21
  import {
22
- getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
22
+ getIssue, createIssue, createLabel, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
23
23
  getRepoDefaultBranch,
24
24
  } from '../api/github-rest.mjs';
25
+ import { codeRepositories, repoLabel } from '../lib/repo-role.mjs';
25
26
  import { addSubIssue, listSubIssues, getProjectSnapshot } from '../api/github-graphql.mjs';
26
27
  import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
27
28
  import { generateDocument } from '../lib/claude.mjs';
@@ -282,6 +283,23 @@ async function publishFile(ctx, { doc, pathRel, content, nextLabel = null, extra
282
283
  // Etapa 1: rascunho (label spec-wave:decompose)
283
284
  // ---------------------------------------------------------------------------
284
285
 
286
+ /**
287
+ * Seção "Repositórios de código" da entrada do modelo (função PURA). Só existe
288
+ * no multi-repo: sem ela o prompt manda omitir `repos`, e é isso que mantém o
289
+ * rascunho do mono-repo idêntico ao de antes da RFC-005.
290
+ *
291
+ * @returns {string} '' no mono-repo
292
+ */
293
+ export function codeReposPromptSection(config) {
294
+ const repos = codeRepositories(config);
295
+ if (repos.length === 0) return '';
296
+ return [
297
+ '\n## Repositórios de código',
298
+ 'Este Project tem mais de um repositório. Cada Story precisa declarar em `repos` os slugs dos repositórios que ela toca, EXATAMENTE como listados:',
299
+ ...repos.map(r => `- \`${r.slug}\` — ${r.owner}/${r.repo}`),
300
+ ].join('\n');
301
+ }
302
+
285
303
  async function draftDecomposition(ctx) {
286
304
  const {
287
305
  token, owner, repo, issue, issueNumber, type, labels, usage, root, runMode,
@@ -357,7 +375,8 @@ async function draftDecomposition(ctx) {
357
375
  `Issue #${issueNumber}`,
358
376
  `\n## spec.md\n${specContent || '(spec.md não encontrado)'}`,
359
377
  `\n## plan.md\n${planContent || '(plan.md não encontrado)'}`,
360
- ].join('\n');
378
+ codeReposPromptSection(ctx.config),
379
+ ].filter(Boolean).join('\n');
361
380
 
362
381
  const decomposePrompt = loadPrompt(
363
382
  type === 'RFC' ? 'decompose/rfc' : 'decompose/feature',
@@ -770,6 +789,49 @@ async function resolveExternalDeps({ token, owner, repo }, doc) {
770
789
  return resolvidas;
771
790
  }
772
791
 
792
+ /**
793
+ * Labels `repo:<slug>` que cada Story vai receber (RFC-005 §3.3), validadas
794
+ * ANTES da primeira criação — mesma razão do resolveExternalDeps: um slug que
795
+ * não está em `repositories[]` do hub é erro de escrita do rascunho, e o lugar
796
+ * de reprovar é antes de criar metade das Stories.
797
+ *
798
+ * As labels são criadas no hub best-effort (R4): `createIssue` recusa label
799
+ * inexistente com 422, e a UI cria a label ao vincular o repo, mas um hub
800
+ * editado à mão não passou por lá.
801
+ *
802
+ * @returns {Promise<Map<string, string[]>>} anchor da Story → labels
803
+ */
804
+ async function resolveRepoLabels({ token, owner, repo, config }, doc) {
805
+ const porStory = new Map();
806
+ const slugs = [...new Set((doc.stories || []).flatMap(s => s.repos || []))].sort();
807
+ if (slugs.length === 0) return porStory;
808
+
809
+ const conhecidos = new Set(codeRepositories(config).map(r => r.slug));
810
+ const desconhecidos = slugs.filter(s => !conhecidos.has(s));
811
+ if (desconhecidos.length > 0) {
812
+ throw new Error(
813
+ `o rascunho declara repositório(s) que o hub não conhece: ${desconhecidos.join(', ')}. ` +
814
+ 'Em "**Repos:**" só valem os slugs de `repositories[]` do .spec-wave.json' +
815
+ (conhecidos.size ? ` (${[...conhecidos].sort().join(', ')})` : ' — que está vazio: vincule o repo de código primeiro') +
816
+ '. Corrija o decomposition.md.'
817
+ );
818
+ }
819
+
820
+ for (const slug of slugs) {
821
+ const name = repoLabel(slug);
822
+ try {
823
+ // createLabel já engole o 422 de "já existe".
824
+ await createLabel(token, owner, repo, { name, color: '0e8a16', description: `Story toca o repositório ${slug}` });
825
+ } catch (err) {
826
+ console.warn(` Não consegui garantir a label ${name}: ${err.message}`);
827
+ }
828
+ }
829
+ for (const story of doc.stories || []) {
830
+ porStory.set(story.anchor, (story.repos || []).map(repoLabel));
831
+ }
832
+ return porStory;
833
+ }
834
+
773
835
  async function createStoriesFromDoc(ctx, doc) {
774
836
  const { token, projectToken, owner, repo, issue, issueNumber, project, docRel } = ctx;
775
837
  const fields = { etapaField: ctx.etapaField, statusField: ctx.statusField, typeField: ctx.typeField };
@@ -780,6 +842,7 @@ async function createStoriesFromDoc(ctx, doc) {
780
842
  // Antes da primeira criação: rascunho que aponta para issue inexistente é
781
843
  // erro de escrita, e o lugar de reprovar é aqui.
782
844
  const externas = await resolveExternalDeps(ctx, doc);
845
+ const repoLabels = await resolveRepoLabels(ctx, doc);
783
846
  const created = [];
784
847
  const createdStories = []; // issues criadas, na ordem dos índices das stories
785
848
  const generatedTexts = []; // títulos+corpos para o lint de idioma final
@@ -806,7 +869,10 @@ async function createStoriesFromDoc(ctx, doc) {
806
869
  const depLine = formatDependencyLine(depIssues.map(d => d.number));
807
870
  if (depLine) storyBody += `\n\n${depLine}`;
808
871
 
809
- const createdStory = await createIssue(token, owner, repo, storyTitle, storyBody, ['[STORY]'], { milestone });
872
+ // `repo:<slug>` já na criação (RFC-005 §6.2 item 6) — a label é a fonte de
873
+ // verdade de quais repositórios a Story toca; o campo do board é só espelho.
874
+ const labelsDoRepo = repoLabels.get(story.anchor) || [];
875
+ const createdStory = await createIssue(token, owner, repo, storyTitle, storyBody, ['[STORY]', ...labelsDoRepo], { milestone });
810
876
  ctx.createdItems.push(createdStory.number);
811
877
  // Anota no doc em memória: é daqui que sai o `**Issue:** #N` gravado no
812
878
  // arquivo no fim do apply.
@@ -840,7 +906,9 @@ async function createStoriesFromDoc(ctx, doc) {
840
906
  console.log(` Criando task: ${task.title}`);
841
907
  const taskTitle = `[TASK] ${task.title}`;
842
908
  const taskBody = `${task.body}\n\n_Story pai: ${createdStory.url}_`;
843
- const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]'], { milestone });
909
+ // A Task herda os repos da Story (RFC-005 §5.2, `effectiveRepoSlugs`) —
910
+ // gravado na label em vez de inferido, para `order`/`implement` lerem direto.
911
+ const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]', ...labelsDoRepo], { milestone });
844
912
  ctx.createdItems.push(createdTask.number);
845
913
  task.issue = createdTask.number;
846
914
  generatedTexts.push(taskTitle, taskBody);
@@ -1166,6 +1234,9 @@ export async function decompose({ issueNumber, apply }) {
1166
1234
  // com o applyCtx: o catch externo precisa saber se houve criação para não
1167
1235
  // aconselhar um retry que duplicaria itens.
1168
1236
  createdItems: [],
1237
+ // `repositories[]` do hub: é contra ela que o apply valida os slugs de
1238
+ // "**Repos:**" antes de criar qualquer issue.
1239
+ config,
1169
1240
  escalationModel: config?.ai?.escalationModel || null,
1170
1241
  maxCritiqueAttempts:
1171
1242
  Number.isInteger(config?.ai?.maxCritiqueAttempts) && config.ai.maxCritiqueAttempts > 0