@spec-wave/cli 0.35.0 → 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 (41) hide show
  1. package/package.json +2 -2
  2. package/src/agent/anthropic-agent.mjs +35 -2
  3. package/src/api/github-rest.mjs +23 -0
  4. package/src/cli.mjs +23 -0
  5. package/src/commands/code-review.mjs +31 -17
  6. package/src/commands/decompose.mjs +75 -4
  7. package/src/commands/doctor.mjs +43 -3
  8. package/src/commands/implement.mjs +39 -6
  9. package/src/commands/init.mjs +147 -29
  10. package/src/commands/merge.mjs +11 -8
  11. package/src/commands/move.mjs +4 -7
  12. package/src/commands/order.mjs +2 -2
  13. package/src/commands/qa.mjs +22 -21
  14. package/src/commands/repair-stage.mjs +2 -5
  15. package/src/commands/story.mjs +2 -2
  16. package/src/commands/task.mjs +2 -2
  17. package/src/commands/triage.mjs +2 -5
  18. package/src/commands/update.mjs +31 -8
  19. package/src/commands/validate.mjs +2 -5
  20. package/src/commands/workspace.mjs +112 -0
  21. package/src/config.mjs +19 -0
  22. package/src/lib/artifact-pr.mjs +1 -1
  23. package/src/lib/claude.mjs +4 -0
  24. package/src/lib/decomposition-doc.mjs +56 -3
  25. package/src/lib/dependency-map.mjs +3 -0
  26. package/src/lib/flow-run.mjs +14 -3
  27. package/src/lib/pr-link.mjs +65 -10
  28. package/src/lib/pr-ready.mjs +6 -2
  29. package/src/lib/project-root.mjs +51 -0
  30. package/src/lib/repo-role.mjs +102 -0
  31. package/src/lib/workspace.mjs +151 -0
  32. package/src/plugin/.claude-plugin/plugin.json +1 -1
  33. package/src/plugin/skills/decompose/SKILL.md +1 -0
  34. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  35. package/src/plugin/skills/implement/SKILL.md +1 -1
  36. package/src/plugin/skills/setup/SKILL.md +12 -0
  37. package/src/setup/files.mjs +35 -13
  38. package/src/templates/skill/SKILL.md +14 -1
  39. package/src/templates/workflows/code/code-review.yml +60 -0
  40. package/src/templates/workflows/code/qa.yml +59 -0
  41. 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.35.0",
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"
@@ -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`.
@@ -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,12 +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
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 };
11
+ import { extractIssueRefs, hubIssueNumbers, resolveLinkMode, sameRepo } from '../lib/pr-link.mjs';
15
12
  import {
16
13
  STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType,
17
14
  LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY, labelNames,
@@ -193,13 +190,15 @@ async function allStoriesReadyForReview(readToken, projToken, project, etapaFiel
193
190
  return { ready: true, stories };
194
191
  }
195
192
 
196
- export async function codeReview({ prNumber, resolveOnly = false }) {
193
+ export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = false }) {
197
194
  const token = await resolveToken();
198
195
  const projectToken = process.env.PROJECT_TOKEN || token;
199
- const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
200
- const { config: cfg } = loadConfig();
201
- const owner = envOwner || cfg?.owner;
202
- 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;
203
202
 
204
203
  if (!owner || !repo) {
205
204
  throw new Error(
@@ -207,18 +206,33 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
207
206
  'Defina GITHUB_REPOSITORY=owner/repo ou rode dentro de um repositório com .spec-wave.json.'
208
207
  );
209
208
  }
209
+ const hub = { owner, repo };
210
+ const prRepo = resolvePrRepo(prRepoOpt, ctx);
211
+ const prNum = parseInt(prNumber, 10);
210
212
 
211
- const pr = await getPR(token, owner, repo, parseInt(prNumber, 10));
213
+ const pr = await getPR(token, prRepo.owner, prRepo.repo, prNum);
212
214
  const linkMode = resolveLinkMode(cfg);
213
215
 
214
216
  // Duas fontes de vínculo, nesta ordem: o que o GitHub reconhece nativamente
215
217
  // (o mesmo que fecha a issue no merge, e que cobre o vínculo feito pela UI) e
216
218
  // o que está escrito no corpo. `Implements #N` só existe na segunda.
217
- const linked = await getPRClosingIssues(token, owner, repo, parseInt(prNumber, 10)).catch(err => {
218
- console.warn(`Não foi possível ler os vínculos nativos do PR: ${err.message}`);
219
- return [];
220
- });
221
- 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
+ }
222
236
 
223
237
  if (issueNums.length === 0) {
224
238
  console.log(
@@ -412,7 +426,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
412
426
  `\`npx @spec-wave/cli@latest code-review --pr-number ${prNumber}\`.`
413
427
  );
414
428
  }
415
- 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(() => {});
416
430
  }
417
431
 
418
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
@@ -15,9 +15,10 @@ import {
15
15
  tokenMismatchWarning, parseActiveAccount,
16
16
  } from '../api/auth.mjs';
17
17
  import { getProjectSnapshot, listProjectItems, getRateLimit } from '../api/github-graphql.mjs';
18
- import { getRepoVariable } from '../api/github-rest.mjs';
18
+ import { getRepoVariable, getOwnerType } from '../api/github-rest.mjs';
19
+ import { configuredRole } from '../lib/repo-role.mjs';
19
20
  import {
20
- CONFIG_FILE, WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
21
+ CONFIG_FILE, WORKFLOW_FILES, CODE_WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
21
22
  AI_PROVIDERS, STATUS_OPTIONS,
22
23
  RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, LABEL_QA_READY, MODEL_LABEL_PREFIX,
23
24
  DEV_AGENT_QUEUE_PREFIX,
@@ -248,6 +249,33 @@ async function checkGhAccount(ctx) {
248
249
  };
249
250
  }
250
251
 
252
+ async function checkOwnerType(ctx) {
253
+ const name = 'Owner é organização';
254
+ const owner = ctx.cfg?.owner;
255
+ if (!owner) {
256
+ return { name, status: 'ok', detail: `Sem owner no ${CONFIG_FILE} para verificar.` };
257
+ }
258
+ if (!ctx.token) {
259
+ return { name, status: 'warn', detail: 'Sem token resolvido — verificação pulada.' };
260
+ }
261
+ try {
262
+ const type = await getOwnerType(ctx.token, owner);
263
+ if (type === 'Organization') {
264
+ return { name, status: 'ok', detail: `${owner} é uma organização.` };
265
+ }
266
+ return {
267
+ name,
268
+ status: 'fail',
269
+ detail:
270
+ `${owner} é uma conta pessoal do GitHub, não uma organização. ` +
271
+ 'O GitHub App do spec-wave só acessa Projects v2 de organizações — transfira o ' +
272
+ `repositório e o Project para uma organização e rode \`init\` novamente apontando para ela.`,
273
+ };
274
+ } catch (err) {
275
+ return { name, status: 'warn', detail: `Não foi possível verificar o tipo de conta de ${owner}: ${err.message}` };
276
+ }
277
+ }
278
+
251
279
  async function checkConfig(ctx) {
252
280
  const name = `Configuração (${CONFIG_FILE})`;
253
281
  if (!ctx.configPath) {
@@ -1523,7 +1551,11 @@ async function checkWorkflows(ctx) {
1523
1551
  };
1524
1552
  }
1525
1553
  const present = readdirSync(dir);
1526
- const missing = WORKFLOW_FILES.filter((f) => !present.includes(f));
1554
+ // Repo de código (RFC-005): só os despachantes, que não chamam a CLI — as
1555
+ // checagens de versão fixada e de secret de IA abaixo são do hub.
1556
+ const role = configuredRole(ctx.cfg);
1557
+ const expected = role === 'code' ? CODE_WORKFLOW_FILES : WORKFLOW_FILES;
1558
+ const missing = expected.filter((f) => !present.includes(f));
1527
1559
  if (missing.length > 0) {
1528
1560
  return {
1529
1561
  name,
@@ -1531,6 +1563,13 @@ async function checkWorkflows(ctx) {
1531
1563
  detail: `Workflows faltando em .github/workflows/: ${missing.join(', ')} — rode \`npx @spec-wave/cli@latest update\`.`,
1532
1564
  };
1533
1565
  }
1566
+ if (role === 'code') {
1567
+ return {
1568
+ name,
1569
+ status: 'ok',
1570
+ detail: `Despachantes presentes (${CODE_WORKFLOW_FILES.join(', ')}); o fluxo roda no hub ${ctx.cfg?.hub?.owner ?? '?'}/${ctx.cfg?.hub?.repo ?? '?'}.`,
1571
+ };
1572
+ }
1534
1573
 
1535
1574
  // Versão da CLI fixada nos workflows: um `@latest` deixa uma release mudar o
1536
1575
  // comportamento de pipelines já em andamento.
@@ -1605,6 +1644,7 @@ export async function doctor(options = {}) {
1605
1644
  checkRateLimit,
1606
1645
  checkScopes,
1607
1646
  checkGhAccount,
1647
+ checkOwnerType,
1608
1648
  checkConfig,
1609
1649
  checkRepoAccess,
1610
1650
  checkBoardHygiene,
@@ -31,6 +31,8 @@ import { renderTrailers, missingTrailers, readLocalCommitMessages } from '../lib
31
31
  import { currentGitBranch } from '../lib/repo-links.mjs';
32
32
 
33
33
  // Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
34
+ import { slugsForItem, resolveWorkspaceLayout, readWorkspaceOverride, renderRepoDirs } from '../lib/workspace.mjs';
35
+
34
36
  const WORK_DIR = '.spec-wave';
35
37
 
36
38
  // Caps dos comentários anexados ao contexto (por issue).
@@ -176,9 +178,17 @@ function pushDigestSpecPlan(lines, { codeDigest, spec, plan, specPath, planPath
176
178
  }
177
179
 
178
180
  // Monta o markdown de contexto que será entregue ao spec-kit implement.
181
+ // Referência de fechamento no corpo do PR. Qualificada com o hub (RFC-005
182
+ // §3.4): um PR num repo de código com `Closes #12` apontaria para a issue 12
183
+ // DESSE repo, e a forma `owner/hub#12` é a única que o hub reconhece. No
184
+ // mono-repo a forma qualificada continua válida para o GitHub.
185
+ export function closesRef(hub, number) {
186
+ return hub?.owner && hub?.repo ? `${hub.owner}/${hub.repo}#${number}` : `#${number}`;
187
+ }
188
+
179
189
  export function buildContext({
180
190
  type, issue, tasks, feature, siblingStories = [], spec, plan, specPath, planPath,
181
- comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack',
191
+ comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack', hub = null,
182
192
  }) {
183
193
  const lines = [];
184
194
  lines.push(`# Contexto de implementação — ${type} #${issue.number}`);
@@ -250,7 +260,7 @@ export function buildContext({
250
260
  // required check continua valendo. Quem tira do rascunho é o próprio
251
261
  // implement, quando a ÚLTIMA Story da Feature entra em Code Review (ver
252
262
  // 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.**`);
263
+ lines.push(` 2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`), **com \`Closes ${closesRef(hub, 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.**`);
254
264
  }
255
265
  lines.push(
256
266
  ` 3. **Avance a Etapa da Story #${issue.number} para ${STAGE_CODE_REVIEW}** ` +
@@ -403,7 +413,7 @@ export function planFeatureImplementation(stories, {
403
413
  export function buildFeatureContext({
404
414
  feature, stories, skipped = [],
405
415
  spec, plan, specPath, planPath,
406
- comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack',
416
+ comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack', hub = null,
407
417
  }) {
408
418
  const lines = [];
409
419
  lines.push(`# Contexto de implementação — Feature #${feature.number}`);
@@ -450,7 +460,7 @@ export function buildFeatureContext({
450
460
  } else {
451
461
  lines.push(
452
462
  `3. **Ao concluir TODAS as Tasks da Story:** faça o **commit** (assunto livre; rodapé com os trailers abaixo), ` +
453
- `abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\`), **com \`Closes #<story>\` no corpo** — ` +
463
+ `abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\`), **com \`Closes ${closesRef(hub, '<story>')}\` no corpo** — ` +
454
464
  `é esse vínculo que o \`merge\`, o \`code-review\` e o desrascunho usam para achar o PR da Story — ` +
455
465
  `e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`
456
466
  );
@@ -840,9 +850,11 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
840
850
  codeDigest,
841
851
  blockedByWarnings,
842
852
  mode,
853
+ hub: { owner, repo },
843
854
  });
844
855
  await writeContextAndRunSpecKit({
845
856
  config,
857
+ repoSlugs: slugsForItem({ labels: feature.labels || [], children: pending }),
846
858
  issueNumber: feature.number,
847
859
  type: 'Feature',
848
860
  title: feature.title,
@@ -1097,11 +1109,13 @@ export async function implement({
1097
1109
  const context = buildContext({
1098
1110
  type, issue, tasks, feature, siblingStories, ...specPlan,
1099
1111
  comments, codeDigest, blockedByWarnings, mode,
1112
+ hub: { owner, repo },
1100
1113
  });
1101
1114
  await writeContextAndRunSpecKit({
1102
1115
  config, issueNumber, type, title: issue.title, specPlan, context, dryRun,
1103
1116
  mode, repoRoot, expectedBranch: currentBranch,
1104
1117
  verifyCommits,
1118
+ repoSlugs: slugsForItem({ labels: issue.labels, children: tasks }),
1105
1119
  expectedTrailers: {
1106
1120
  stories: type === 'Story' ? [issue.number] : [],
1107
1121
  tasks: tasks.map(t => t.number),
@@ -1157,13 +1171,30 @@ export async function implement({
1157
1171
  async function writeContextAndRunSpecKit({
1158
1172
  config, issueNumber, type, title, specPlan, context, dryRun, outroSuccess, onSuccess,
1159
1173
  mode = 'pr-stack', repoRoot = null, expectedBranch = null,
1160
- verifyCommits = false, expectedTrailers = null,
1174
+ verifyCommits = false, expectedTrailers = null, repoSlugs = [],
1161
1175
  }) {
1162
1176
  mkdirSync(WORK_DIR, { recursive: true });
1163
1177
  const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
1164
1178
  writeFileSync(tasksFile, context);
1165
1179
  p.log.success(`Contexto montado em ${chalk.cyan(tasksFile)}.`);
1166
1180
 
1181
+ // Multi-repo (RFC-005): o mesmo layout do `workspace prepare`, sem clonar —
1182
+ // aqui só se lê; repo ausente vira aviso apontando o comando que o cria.
1183
+ const hubRoot = repoRoot || process.cwd();
1184
+ const layout = resolveWorkspaceLayout({
1185
+ root: hubRoot, config, slugs: repoSlugs, override: readWorkspaceOverride(hubRoot),
1186
+ });
1187
+ const ausentes = layout.repos.filter(r => !r.present);
1188
+ if (layout.unknown.length > 0) {
1189
+ p.log.warn(`Repositório(s) declarado(s) na issue e desconhecido(s) do hub: ${layout.unknown.join(', ')} — registre em repositories[] do ${CONFIG_FILE}.`);
1190
+ }
1191
+ if (ausentes.length > 0) {
1192
+ p.log.warn(
1193
+ `Repositório(s) ausente(s) no workspace: ${ausentes.map(r => `${r.slug} (${r.dir})`).join(', ')} — ` +
1194
+ `rode \`spec-wave workspace prepare --issue ${issueNumber}\` antes.`
1195
+ );
1196
+ }
1197
+
1167
1198
  const template = process.env.SPEC_WAVE_IMPLEMENT_CMD || config.specKit?.command;
1168
1199
  const vars = {
1169
1200
  tasksFile,
@@ -1172,6 +1203,8 @@ async function writeContextAndRunSpecKit({
1172
1203
  issue: String(issueNumber),
1173
1204
  type,
1174
1205
  title,
1206
+ workspaceDir: layout.workspaceDir,
1207
+ repoDirs: renderRepoDirs(layout.repos),
1175
1208
  };
1176
1209
 
1177
1210
  // O dry-run é decidido ANTES do early return de "spec-kit não configurado":
@@ -1195,7 +1228,7 @@ async function writeContextAndRunSpecKit({
1195
1228
  `Configure em ${CONFIG_FILE}:\n` +
1196
1229
  ` "specKit": { "command": "<comando do spec-kit com placeholders>" }\n` +
1197
1230
  'ou defina a env SPEC_WAVE_IMPLEMENT_CMD.\n\n' +
1198
- 'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title}',
1231
+ 'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title} {workspaceDir} {repoDirs}',
1199
1232
  'Como acionar o spec-kit'
1200
1233
  );
1201
1234
  p.outro(`Contexto pronto em ${tasksFile}. Acione o spec-kit manualmente com esse arquivo.`);