@spec-wave/cli 1.0.3 → 1.0.5

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 (32) hide show
  1. package/package.json +1 -1
  2. package/src/api/auth.mjs +29 -1
  3. package/src/commands/decompose.mjs +1 -1
  4. package/src/commands/doctor.mjs +54 -20
  5. package/src/commands/generate-bug.mjs +1 -0
  6. package/src/commands/generate-plan.mjs +1 -0
  7. package/src/commands/generate-qa-plan.mjs +1 -0
  8. package/src/commands/generate-spec.mjs +1 -0
  9. package/src/commands/init.mjs +4 -1
  10. package/src/commands/run.mjs +16 -0
  11. package/src/commands/workspace.mjs +5 -1
  12. package/src/lib/claude.mjs +14 -0
  13. package/src/lib/workspace.mjs +49 -0
  14. package/src/plugin/.claude-plugin/plugin.json +1 -1
  15. package/src/plugin/skills/bug/model-prompt.md +2 -0
  16. package/src/plugin/skills/decompose/model-prompt.feature.md +2 -0
  17. package/src/plugin/skills/decompose/model-prompt.rfc.md +2 -0
  18. package/src/plugin/skills/plan/model-prompt.md +2 -0
  19. package/src/plugin/skills/qa/model-prompt.md +2 -0
  20. package/src/plugin/skills/setup/SKILL.md +9 -0
  21. package/src/plugin/skills/spec/model-prompt.md +2 -0
  22. package/src/templates/skill/SKILL.md +9 -0
  23. package/src/templates/workflows/code/code-review.yml +25 -7
  24. package/src/templates/workflows/code/qa.yml +24 -6
  25. package/src/templates/workflows/code-review.yml +16 -1
  26. package/src/templates/workflows/decompose.yml +30 -2
  27. package/src/templates/workflows/generate-bug.yml +27 -1
  28. package/src/templates/workflows/generate-plan.yml +27 -1
  29. package/src/templates/workflows/generate-qa-plan.yml +28 -2
  30. package/src/templates/workflows/generate-spec.yml +27 -1
  31. package/src/templates/workflows/pr-events.yml +35 -8
  32. package/src/templates/workflows/qa.yml +15 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "1.0.3",
3
+ "version": "1.0.5",
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": {
package/src/api/auth.mjs CHANGED
@@ -225,9 +225,37 @@ export function describeTokenSource(cwd = process.cwd()) {
225
225
  return 'gh auth token (conta ativa)';
226
226
  }
227
227
 
228
+ /**
229
+ * Token de INSTALAÇÃO de GitHub App (`ghs_…`): não tem `GET /user` nem
230
+ * `x-oauth-scopes` — as permissões vêm da App, não de escopos. É o token que
231
+ * o init server-side da UI e o step `actions/create-github-app-token` usam.
232
+ */
233
+ export function isInstallationToken(token) {
234
+ return /^ghs_/.test(String(token || ''));
235
+ }
236
+
228
237
  export async function verifyTokenScopes(token) {
229
238
  const { Octokit } = await import('@octokit/rest');
230
239
  const octokit = new Octokit({ auth: token });
240
+ if (isInstallationToken(token)) {
241
+ // Verificação FUNCIONAL: a única chamada que um token de instalação
242
+ // sempre responde. Escopos não existem aqui — o que a App pode fazer foi
243
+ // decidido nas permissões dela (Issues, Contents, Pull requests, Projects);
244
+ // uma permissão faltando aparece na primeira chamada que precisar dela.
245
+ try {
246
+ const res = await octokit.request('GET /installation/repositories', { per_page: 1 });
247
+ const total = res.data?.total_count ?? 0;
248
+ return {
249
+ login: 'GitHub App (token de instalação)',
250
+ kind: 'app',
251
+ hasProject: true, hasRepo: true, hasWorkflow: true,
252
+ scopes: [],
253
+ installationRepos: total,
254
+ };
255
+ } catch (err) {
256
+ throw new Error(`Token de instalação inválido ou expirado: ${err.message}`);
257
+ }
258
+ }
231
259
  try {
232
260
  const response = await octokit.request('GET /user');
233
261
  const scopes = response.headers['x-oauth-scopes'] || '';
@@ -237,7 +265,7 @@ export async function verifyTokenScopes(token) {
237
265
  const hasRepo = scopeList.includes('repo') || scopeList.includes('public_repo');
238
266
  // `workflow` is required to create/update files under .github/workflows/
239
267
  const hasWorkflow = scopeList.includes('workflow');
240
- return { login: response.data.login, hasProject, hasRepo, hasWorkflow, scopes: scopeList };
268
+ return { login: response.data.login, kind: 'user', hasProject, hasRepo, hasWorkflow, scopes: scopeList };
241
269
  } catch (err) {
242
270
  throw new Error(`Token verification failed: ${err.message}`);
243
271
  }
@@ -385,7 +385,7 @@ async function draftDecomposition(ctx) {
385
385
  const generated = parseModelJson(await generateDocument(
386
386
  systemPromptWithTools(decomposePrompt),
387
387
  userContent,
388
- { action: 'decompose', labels, usage, maxTurns: decomposePrompt.maxTurns }
388
+ { action: 'decompose', labels, usage, maxTurns: decomposePrompt.maxTurns, issueNumber, cwd: root }
389
389
  ));
390
390
 
391
391
  markdown = renderDecompositionDoc({
@@ -129,6 +129,25 @@ async function checkRateLimit(ctx) {
129
129
  };
130
130
  }
131
131
 
132
+ /**
133
+ * Nomes dos secrets do Actions visíveis ao repo: os do repositório e os da
134
+ * organização compartilhados com ele (é onde a GitHub App da org costuma
135
+ * viver). Só NOMES — a API nunca expõe valores. Lança se nem os do repo forem
136
+ * legíveis; os de org são best-effort (a listagem exige permissão a mais).
137
+ */
138
+ async function listActionsSecretNames(token, owner, repo) {
139
+ const octokit = makeOctokit(token);
140
+ const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets', { owner, repo });
141
+ const names = (res.data.secrets || []).map((s) => s.name);
142
+ try {
143
+ const org = await octokit.request('GET /repos/{owner}/{repo}/actions/organization-secrets', { owner, repo });
144
+ for (const s of org.data.secrets || []) if (!names.includes(s.name)) names.push(s.name);
145
+ } catch {
146
+ // repo de usuário ou sem permissão para ver os da org — fica só com os do repo
147
+ }
148
+ return names;
149
+ }
150
+
132
151
  async function checkScopes(ctx) {
133
152
  const name = 'Escopos do token';
134
153
  if (!ctx.token) {
@@ -185,18 +204,21 @@ async function checkScopes(ctx) {
185
204
  // acesso ao project não confirmado — segue sem ele
186
205
  }
187
206
  }
207
+ // Token de instalação de GitHub App (`ghs_`) cai aqui também: as permissões
208
+ // são da App, não escopos — o que dá para afirmar é o acesso funcional.
209
+ const tipo = info.kind === 'app' ? 'token de instalação de GitHub App' : 'fine-grained PAT?';
188
210
  if (functional.length > 0) {
189
211
  return {
190
212
  name,
191
213
  status: 'ok',
192
- detail: `Escopos não legíveis (fine-grained PAT?), mas acesso confirmado: ${functional.join(' e ')}.`,
214
+ detail: `Escopos não legíveis (${tipo}), mas acesso confirmado: ${functional.join(' e ')}.`,
193
215
  };
194
216
  }
195
217
  return {
196
218
  name,
197
219
  status: 'warn',
198
220
  detail:
199
- 'Escopos não legíveis (fine-grained PAT?) e sem acesso confirmável a repo/project ' +
221
+ `Escopos não legíveis (${tipo}) e sem acesso confirmável a repo/project ` +
200
222
  `(${CONFIG_FILE} ausente ou acesso negado). Confirme as permissões do token manualmente.`,
201
223
  };
202
224
  }
@@ -825,12 +847,21 @@ async function checkAi(ctx) {
825
847
  // Se o token permitir, confere os secrets do Actions no repo.
826
848
  if (ctx.token && cfg?.owner && cfg?.repo) {
827
849
  try {
828
- const res = await makeOctokit(ctx.token).request('GET /repos/{owner}/{repo}/actions/secrets', {
829
- owner: cfg.owner,
830
- repo: cfg.repo,
831
- });
832
- const secretNames = (res.data.secrets || []).map((s) => s.name);
833
- const required = [provider.secret, 'GH_PROJECT_TOKEN'];
850
+ const secretNames = await listActionsSecretNames(ctx.token, cfg.owner, cfg.repo);
851
+ // Dois modos de autenticação nos workflows: GitHub App da org
852
+ // (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY, App antes do PAT) ou os
853
+ // PATs. Com a App presente, o GH_PROJECT_TOKEN vira fallback opcional.
854
+ const appPresent = secretNames.includes('SPEC_WAVE_APP_PRIVATE_KEY') && secretNames.includes('SPEC_WAVE_APP_ID');
855
+ const appPartial = !appPresent && (secretNames.includes('SPEC_WAVE_APP_PRIVATE_KEY') || secretNames.includes('SPEC_WAVE_APP_ID'));
856
+ if (appPartial) {
857
+ status = 'warn';
858
+ notes.push('GitHub App configurada pela metade: SPEC_WAVE_APP_ID e SPEC_WAVE_APP_PRIVATE_KEY precisam existir juntos — os workflows vão cair no PAT.');
859
+ }
860
+ ctx.appSecretsPresent = appPresent;
861
+ notes.push(appPresent
862
+ ? 'Autenticação dos workflows: GitHub App da organização (SPEC_WAVE_APP_*); os PATs, se existirem, são fallback.'
863
+ : 'Autenticação dos workflows: PATs (GH_PROJECT_TOKEN, GH_PR_TOKEN). Uma GitHub App da org (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY) os substitui sem depender de uma pessoa.');
864
+ const required = appPresent ? [provider.secret] : [provider.secret, 'GH_PROJECT_TOKEN'];
834
865
  const missing = required.filter((s) => !secretNames.includes(s));
835
866
  if (missing.length > 0) {
836
867
  status = 'warn';
@@ -1404,15 +1435,16 @@ export function inspectPrPublishing({
1404
1435
  notes.push(
1405
1436
  'O GitHub Actions está proibido de criar Pull Requests neste repositório. ' +
1406
1437
  'Ligue Settings → Actions → General → "Allow GitHub Actions to create and approve ' +
1407
- `pull requests", ou defina o secret \`${prTokenSecret}\` com um PAT.`
1438
+ `pull requests", configure a GitHub App da org (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY) ` +
1439
+ `ou defina o secret \`${prTokenSecret}\` com um PAT.`
1408
1440
  );
1409
1441
  } else if (canCreatePr === false) {
1410
- // Mitigado: o PR é aberto com o PAT, não com o GITHUB_TOKEN. Continuar
1411
- // pedindo a configuração que a pessoa ACABOU de fazer é o jeito mais rápido
1412
- // de ensinar que o doctor pode ser ignorado.
1442
+ // Mitigado: o PR é aberto com a App ou o PAT, não com o GITHUB_TOKEN.
1443
+ // Continuar pedindo a configuração que a pessoa ACABOU de fazer é o jeito
1444
+ // mais rápido de ensinar que o doctor pode ser ignorado.
1413
1445
  notes.push(
1414
- `O Actions não pode abrir PR com o GITHUB_TOKEN, mas \`${prTokenSecret}\` está ` +
1415
- 'definido e é ele que será usado — só o NOME é verificável daqui, não o valor ' +
1446
+ `O Actions não pode abrir PR com o GITHUB_TOKEN, mas a GitHub App ou \`${prTokenSecret}\` está ` +
1447
+ 'definido e é esse token que será usado — só o NOME é verificável daqui, não o valor ' +
1416
1448
  'nem as permissões.'
1417
1449
  );
1418
1450
  } else if (canCreatePr === null) {
@@ -1428,12 +1460,12 @@ export function inspectPrPublishing({
1428
1460
  `A branch default exige status check(s) obrigatório(s): ${requiredChecks.join(', ')}. ` +
1429
1461
  'Pull Request aberto pelo GITHUB_TOKEN NÃO dispara workflow, então esses checks ' +
1430
1462
  'nunca ficam verdes e nenhum PR de documento se torna mergeável — o fluxo trava no ' +
1431
- `primeiro passo. Use um PAT no secret \`${prTokenSecret}\` (PR aberto por PAT dispara ` +
1432
- 'os workflows), ou dispense os checks para as branches `spec-wave/*`.'
1463
+ `primeiro passo. Configure a GitHub App da org (SPEC_WAVE_APP_*) ou um PAT no secret \`${prTokenSecret}\` ` +
1464
+ '(PR aberto por App ou PAT dispara os workflows), ou dispense os checks para as branches `spec-wave/*`.'
1433
1465
  );
1434
1466
  } else if (requiredChecks?.length) {
1435
1467
  notes.push(
1436
- `A branch default exige ${requiredChecks.join(', ')}; como o PR é aberto por ` +
1468
+ `A branch default exige ${requiredChecks.join(', ')}; como o PR é aberto pela GitHub App ou por ` +
1437
1469
  `\`${prTokenSecret}\`, os workflows disparam e os checks podem ficar verdes.`
1438
1470
  );
1439
1471
  }
@@ -1498,9 +1530,11 @@ export async function readPrPublishingContext({ token, owner, repo, root }) {
1498
1530
  if (token && owner && repo) {
1499
1531
  const octokit = makeOctokit(token);
1500
1532
  try {
1501
- const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets',
1502
- { owner, repo });
1503
- prTokenPresent = (res.data.secrets || []).some(sec => sec.name === 'GH_PR_TOKEN');
1533
+ // A GitHub App da org também abre PR que dispara workflows — com ela
1534
+ // presente, o GH_PR_TOKEN deixa de ser necessário.
1535
+ const names = await listActionsSecretNames(token, owner, repo);
1536
+ prTokenPresent = names.includes('GH_PR_TOKEN') ||
1537
+ (names.includes('SPEC_WAVE_APP_PRIVATE_KEY') && names.includes('SPEC_WAVE_APP_ID'));
1504
1538
  } catch {
1505
1539
  prTokenPresent = null; // sem permissão de ler secrets — não afirmar ausência
1506
1540
  }
@@ -101,6 +101,7 @@ export async function generateBug({ issueNumber }) {
101
101
  const systemPrompt = systemPromptWithTools(bugPrompt);
102
102
  const { content: bruto } = await generateDocument(systemPrompt, userContent, {
103
103
  action: 'bug',
104
+ issueNumber, cwd: root,
104
105
  maxTurns: bugPrompt.maxTurns,
105
106
  labels: issueLabels,
106
107
  lint: { lang: TARGET_LANGUAGE },
@@ -216,6 +216,7 @@ export async function generatePlan({ issueNumber }) {
216
216
  const systemPrompt = systemPromptWithTools(planPrompt);
217
217
  const { content: bruto, lintFindings } = await generateDocument(systemPrompt, userContent, {
218
218
  action: 'plan',
219
+ issueNumber, cwd: root,
219
220
  maxTurns: planPrompt.maxTurns,
220
221
  labels: issueLabels,
221
222
  lint: { lang: TARGET_LANGUAGE },
@@ -249,6 +249,7 @@ async function runDraftOrCritique(ctx) {
249
249
  userContent,
250
250
  {
251
251
  action: 'qa', maxTurns: qaPrompt.maxTurns, labels, usage,
252
+ issueNumber, cwd: root,
252
253
  lint: { lang: TARGET_LANGUAGE }, withReport: true,
253
254
  }
254
255
  );
@@ -82,6 +82,7 @@ export async function generateSpec({ issueNumber }) {
82
82
  const systemPrompt = systemPromptWithTools(specPrompt);
83
83
  const { content: bruto, lintFindings } = await generateDocument(systemPrompt, userContent, {
84
84
  action: 'spec',
85
+ issueNumber, cwd: root,
85
86
  maxTurns: specPrompt.maxTurns,
86
87
  labels: issueLabels,
87
88
  lint: { lang: TARGET_LANGUAGE },
@@ -312,7 +312,7 @@ export async function init(options) {
312
312
  `\n${chalk.green('✓')} ${owner}/${repo} configurado como repositório de código do hub ${hub.owner}/${hub.repo}.\n\n` +
313
313
  ` Próximos passos:\n` +
314
314
  (configWritten ? ` 1. Commite o ${CONFIG_FILE} (git add ${CONFIG_FILE} && git commit) — os despachantes o leem em runtime\n` : '') +
315
- ` ${configWritten ? '2' : '1'}. Adicione o secret ${HUB_DISPATCH_SECRET} neste repositório: um token com escrita em Contents no hub\n` +
315
+ ` ${configWritten ? '2' : '1'}. Autenticação do despacho para o hub: a GitHub App da org (secrets SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY, App instalada nos dois repos) ou o secret ${HUB_DISPATCH_SECRET} com um token de escrita em Contents no hub\n` +
316
316
  ` ${configWritten ? '3' : '2'}. No hub, rode \`npx @spec-wave/cli@latest update\` para instalar o pr-events.yml (recebe os despachos)\n` +
317
317
  ` ${configWritten ? '4' : '3'}. Registre este repo no hub: \`repositories: [{ "slug": "<slug>", "owner": "${owner}", "repo": "${repo}" }]\` no ${CONFIG_FILE} do hub\n` +
318
318
  ` ${chalk.dim('(o slug vai na label repo:<slug> das Stories — minúsculas, [a-z0-9-], até 39 caracteres, e não muda depois)')}\n\n` +
@@ -338,6 +338,9 @@ export async function init(options) {
338
338
  ? ` 1. Commite o ${CONFIG_FILE} quando quiser (git add ${CONFIG_FILE} && git commit)\n`
339
339
  : '') +
340
340
  ` ${configWritten ? '2' : '1'}. Adicione ${providerMeta.secret} como secret no repositório (provider: ${providerMeta.label})\n` +
341
+ // Dois modos de autenticação dos workflows: a App da org não depende de
342
+ // uma pessoa; os PATs continuam valendo como fallback.
343
+ ` ${chalk.dim('Autenticação dos workflows: GitHub App da org (secrets SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY) ou os PATs GH_PROJECT_TOKEN/GH_PR_TOKEN')}\n` +
341
344
  // O valor do token da assinatura não é copiável de lugar nenhum: só existe
342
345
  // depois de rodar o comando que o gera.
343
346
  (providerMeta.secret === 'CLAUDE_CODE_OAUTH_TOKEN'
@@ -275,7 +275,23 @@ export function renderRunJson({ issueNumber, type, ultimaDecisao, passos = [] })
275
275
  );
276
276
  }
277
277
 
278
+ // Passos que chamam o modelo com Read/Glob/Grep: antes deles, o workspace
279
+ // multi-repo (RFC-005 §7.2) — o mesmo passo que o Action do hub roda. Local,
280
+ // resolve irmãos/override e clona o que faltar; best-effort, porque no
281
+ // mono-repo não há nada a montar e um aviso já diz o que faltou.
282
+ const ACTIONS_COM_CODIGO = new Set(['generate-spec', 'generate-plan', 'decompose', 'generate-bug', 'generate-qa-plan']);
283
+
284
+ async function prepareWorkspaceFor(issueNumber) {
285
+ try {
286
+ const { workspace } = await import('./workspace.mjs');
287
+ await workspace({ action: 'prepare', issue: issueNumber });
288
+ } catch (err) {
289
+ console.warn(`Workspace multi-repo não montado (${err.message}) — o modelo lê só o hub.`);
290
+ }
291
+ }
292
+
278
293
  async function dispatch(action, { issueNumber }) {
294
+ if (ACTIONS_COM_CODIGO.has(action)) await prepareWorkspaceFor(issueNumber);
279
295
  switch (action) {
280
296
  case 'generate-spec': {
281
297
  const { generateSpec } = await import('./generate-spec.mjs');
@@ -14,7 +14,7 @@ import { resolveCacheTtl } from '../lib/net-cache.mjs';
14
14
  import { codeRepositories } from '../lib/repo-role.mjs';
15
15
  import {
16
16
  slugsForItem, resolveWorkspaceLayout, readWorkspaceOverride, prepareWorkspace, renderRepoDirs,
17
- WORKSPACE_OVERRIDE_FILE,
17
+ writeWorkspaceManifest, WORKSPACE_OVERRIDE_FILE,
18
18
  } from '../lib/workspace.mjs';
19
19
  import { CONFIG_FILE } from '../config.mjs';
20
20
 
@@ -87,6 +87,10 @@ export async function workspace({ action, issue: issueArg, json = false, dryRun
87
87
  const { cloned, missing } = await prepareWorkspace({
88
88
  layout, token: isActions ? token : null, shallow: isActions, log,
89
89
  });
90
+ // O manifesto é o que os prompts leem (generateDocument anexa a seção
91
+ // "Workspace multi-repo" a partir dele) — por issue, para não vazar o
92
+ // workspace de uma Feature na geração de outra.
93
+ writeWorkspaceManifest(root, issueNumber, layout);
90
94
  if (!json) {
91
95
  for (const r of layout.repos) {
92
96
  p.log.success(`${r.slug} → ${chalk.cyan(r.dir)} (${cloned.includes(r.slug) ? 'clonado' : r.source})`);
@@ -1,5 +1,6 @@
1
1
  import Anthropic from '@anthropic-ai/sdk';
2
2
  import { readFileSync } from 'node:fs';
3
+ import path from 'node:path';
3
4
  import {
4
5
  getProvider, DEFAULT_PROVIDER, MODEL_LABEL_PREFIX,
5
6
  DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
@@ -9,6 +10,7 @@ import { runAgent } from '../agent/index.mjs';
9
10
  import { TruncatedOutputError, MaxTurnsError, isTruncationReason } from '../agent/errors.mjs';
10
11
  import { computeCost } from './usage-report.mjs';
11
12
  import { findConfigPath } from './project-root.mjs';
13
+ import { readWorkspaceManifest, workspacePromptSection } from './workspace.mjs';
12
14
 
13
15
  // Teto de saída padrão. O valor anterior (8192) truncava specs reais: um
14
16
  // documento de ~20 KB em pt-BR já custa ~6k tokens, e modelos com raciocínio
@@ -285,6 +287,18 @@ export function supportsStrictSchema(model) {
285
287
  // soma tokens/custo na MESMA entrada).
286
288
  export async function generateDocument(systemPrompt, userContent, opts = {}) {
287
289
  const ai = resolveAi(opts.action, { labels: opts.labels });
290
+ // Multi-repo (RFC-005 §7.2): se `workspace prepare` rodou para esta issue,
291
+ // a entrada ganha os diretórios dos repos de código — sem eles o modelo
292
+ // "lê o repositório", acha só markdown e escreve um plano sem ver código.
293
+ if (opts.issueNumber) {
294
+ const configPath = findConfigPath();
295
+ const root = opts.cwd ?? (configPath ? path.dirname(configPath) : process.cwd());
296
+ const secao = workspacePromptSection(readWorkspaceManifest(root, opts.issueNumber));
297
+ if (secao) {
298
+ userContent = `${userContent}\n${secao}`;
299
+ console.log('Workspace multi-repo anexado à entrada do modelo (.spec-wave/workspace-' + opts.issueNumber + '.json).');
300
+ }
301
+ }
288
302
  const temperature = opts.temperature ?? 0.2;
289
303
  // Modelos de reasoning (ex.: deepseek-r1, Opus 4.7+) consomem tokens
290
304
  // "pensando" antes da resposta, então o teto precisa cobrir raciocínio +
@@ -117,6 +117,55 @@ export function renderRepoDirs(repos = []) {
117
117
  return repos.map(r => `${r.slug}=${r.dir}`).join(' ');
118
118
  }
119
119
 
120
+ /** Manifesto do workspace de uma issue — o elo entre `workspace prepare` e os prompts. */
121
+ export function workspaceManifestPath(root, issueNumber) {
122
+ return path.join(root, '.spec-wave', `workspace-${issueNumber}.json`);
123
+ }
124
+
125
+ export function writeWorkspaceManifest(root, issueNumber, layout) {
126
+ const file = workspaceManifestPath(root, issueNumber);
127
+ mkdirSync(path.dirname(file), { recursive: true });
128
+ writeFileSync(file, `${JSON.stringify({
129
+ issue: issueNumber,
130
+ preparedAt: new Date().toISOString(),
131
+ workspaceDir: layout.workspaceDir,
132
+ hubDir: layout.hubDir,
133
+ repos: layout.repos.map(r => ({ slug: r.slug, owner: r.owner, repo: r.repo, dir: r.dir, present: r.present })),
134
+ }, null, 2)}\n`);
135
+ return file;
136
+ }
137
+
138
+ export function readWorkspaceManifest(root, issueNumber) {
139
+ try {
140
+ const parsed = JSON.parse(readFileSync(workspaceManifestPath(root, issueNumber), 'utf-8'));
141
+ return parsed && Array.isArray(parsed.repos) ? parsed : null;
142
+ } catch {
143
+ return null;
144
+ }
145
+ }
146
+
147
+ /**
148
+ * Seção "Workspace multi-repo" anexada à entrada do modelo (função PURA sobre
149
+ * o manifesto). Os clones ficam sob um `.gitignore` com `*`, e o Glob do
150
+ * backend anthropic respeita gitignore a partir da raiz do hub: sem os
151
+ * caminhos explícitos o modelo procuraria o código e não acharia nada —
152
+ * exatamente o plano plausível escrito sem ver uma linha (§7.2).
153
+ *
154
+ * @returns {string} '' quando não há repo presente
155
+ */
156
+ export function workspacePromptSection(manifest) {
157
+ const presentes = (manifest?.repos || []).filter(r => r.present && r.dir);
158
+ if (presentes.length === 0) return '';
159
+ return [
160
+ '',
161
+ '## Workspace multi-repo',
162
+ 'Este hub guarda só documentação. O código desta issue está nos repositórios abaixo, ' +
163
+ 'já clonados — aponte `Glob`/`Grep`/`Read` para esses diretórios (parâmetro `path`, caminho absoluto): ' +
164
+ 'a partir da raiz do hub eles ficam fora da busca.',
165
+ ...presentes.map(r => `- \`${r.slug}\` (${r.owner}/${r.repo}): \`${r.dir}\``),
166
+ ].join('\n');
167
+ }
168
+
120
169
  function cloneUrl({ owner, repo }, token) {
121
170
  // Token na URL só no Action, onde o clone é descartável; localmente o git
122
171
  // usa o credential helper do dev (o do gh, normalmente).
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.0.3",
4
+ "version": "1.0.5",
5
5
  "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
6
6
  "author": {
7
7
  "name": "Astratech",
@@ -33,6 +33,8 @@ Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para transformar sinto
33
33
  3. Procure o teste que deveria ter pego isto. A ausência dele é um achado, e vira a seção **Teste de Regressão**.
34
34
 
35
35
  Cite arquivo e função nas seções **Causa Raiz** e **Escopo do Fix**. Um `bug.md` sem referência a código é um relato reescrito, não uma investigação.
36
+
37
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca — e diga em qual repositório está a causa.
36
38
  <!-- /requires-tools -->
37
39
 
38
40
  ## Estrutura obrigatória
@@ -25,6 +25,8 @@ Quando um dos dois documentos não existir, a entrada diz isso explicitamente. D
25
25
  ## Exploração antes de decompor
26
26
 
27
27
  Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para dimensionar as tasks contra o código que existe de verdade: uma task "criar endpoint X" é diferente conforme o controller já exista ou não. Ancore os títulos técnicos nos caminhos e nomes reais que encontrar.
28
+
29
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca — e diga em cada task em qual repositório ela acontece.
28
30
  <!-- /requires-tools -->
29
31
 
30
32
  ## Contrato de saída
@@ -24,6 +24,8 @@ Um RFC não passa por spec/plan — ele é a proposta em si. Por isso não há c
24
24
  ## Exploração antes de decompor
25
25
 
26
26
  Você tem `Read`, `Glob` e `Grep` no repositório. Um RFC quase sempre descreve mudança em algo que já existe — localize esse algo antes de listar tasks, e nomeie na `body` os arquivos e áreas que cada task vai tocar.
27
+
28
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca.
27
29
  <!-- /requires-tools -->
28
30
  ## Contrato de saída
29
31
 
@@ -26,6 +26,8 @@ Você recebe um payload JSON com:
26
26
  Você tem `Read`, `Glob` e `Grep` no repositório de destino. Use-os: localize os módulos, endpoints, migrations e componentes que esta Feature vai tocar, e ancore o plano nos **caminhos e nomes reais** que encontrar. Um plano que cita `src/services/pedido.ts` porque leu o arquivo vale muito mais que um que inventa `PedidoService`.
27
27
 
28
28
  O `tech_context` continua sendo a fronteira do que você pode propor — explorar o repositório serve para ser preciso dentro dela, não para ampliá-la.
29
+
30
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca — e, no detalhamento por camada, diga em qual repositório cada mudança acontece.
29
31
  <!-- /requires-tools -->
30
32
  ## Estrutura obrigatória
31
33
 
@@ -59,6 +59,8 @@ Regras do formato:
59
59
  ## Exploração antes de escrever
60
60
 
61
61
  Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para ancorar os passos no que existe de verdade: os endpoints reais (rotas registradas), os comandos reais (scripts do package.json, Makefile), os seeds/fixtures disponíveis. Um passo `GET /api/pedidos` só vale se essa rota existe com esse nome. Não gaste mais do que o necessário: explore o suficiente para os passos serem executáveis, e então escreva o documento completo.
62
+
63
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca — e diga em qual repositório cada cenário roda.
62
64
  <!-- /requires-tools -->
63
65
 
64
66
  ## O que NÃO fazer
@@ -45,6 +45,15 @@ npx @spec-wave/cli@latest repo list
45
45
 
46
46
  `repo link` grava `{ slug, owner, repo }` em `repositories[]` do `.spec-wave.json` local do hub (commite depois — os workflows leem a branch default) e cria a label `repo:<slug>`. Slug em `[a-z0-9-]`, até 39 caracteres, **imutável** depois do primeiro vínculo; `repo unlink <slug>` remove a entrada sem tocar nas labels já aplicadas. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
47
47
 
48
+ ### Autenticação dos workflows: GitHub App ou PATs
49
+
50
+ Os workflows precisam de um token que atravesse repositórios e mexa no Project. Dois modos, e o `doctor` diz qual está em uso:
51
+
52
+ - **GitHub App da organização** (preferido): secrets `SPEC_WAVE_APP_ID` e `SPEC_WAVE_APP_PRIVATE_KEY` (PEM completo) no hub **e** nos repos de código, com a App instalada em todos eles. Permissões mínimas para os workflows: Issues RW, Contents RW, Pull requests RW, Metadata R, Projects (org) RW. Se a App também for usada para rodar `init`/`update` (token `ghs_` gravando `.github/workflows/` pela Contents API), acrescente **Workflows: write** — sem ela o GitHub responde 422 "refusing to allow a GitHub App to create or update workflow … without workflows permission". Cada workflow gera um token por run (`actions/create-github-app-token`) — quem sai da org não derruba o fluxo, e `GH_PR_TOKEN` deixa de ser necessário (PR aberto por App dispara workflows).
53
+ - **PATs** (modo original): `GH_PROJECT_TOKEN` (escopos `repo` + `project`), `GH_PR_TOKEN` quando a org proíbe o `GITHUB_TOKEN` de abrir PR, e `SPEC_WAVE_HUB_TOKEN` no repo de código. Com a App configurada, esses viram fallback.
54
+
55
+ `init` e `doctor` aceitam token de instalação de App (`ghs_…`) — sem escopos legíveis, a verificação é funcional (acesso ao repo e ao Project).
56
+
48
57
  ## Passos
49
58
 
50
59
  1. **Já configurado?** Leia `.spec-wave.json` (Read) ou rode `npx @spec-wave/cli@latest info`. Se existir, mostre `project.url` e `version` e **confirme com o usuário** antes de reconfigurar.
@@ -25,6 +25,8 @@ Você recebe um payload JSON com:
25
25
  Você tem `Read`, `Glob` e `Grep` no repositório de destino. Antes de escrever qualquer seção, procure o que já existe: specs de features vizinhas em `docs/features/`, modelos de domínio, endpoints e telas relacionados. Uma spec ancorada no que o sistema já faz vale mais que uma escrita no vácuo.
26
26
 
27
27
  Isso **não** autoriza inventar regras a partir do código: o código mostra o que existe, não o que o negócio quer. Continue marcando lacunas de negócio com `[TODO: requer esclarecimento do PO]`.
28
+
29
+ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está neste repositório (o hub só guarda documentação): está nos diretórios listados ali, um por repositório de código. Aponte `Glob`/`Grep`/`Read` para esses caminhos absolutos (parâmetro `path`) — a partir da raiz do hub eles ficam fora da busca. As specs vizinhas continuam em `docs/features/` do hub.
28
30
  <!-- /requires-tools -->
29
31
 
30
32
  ## Estrutura obrigatória
@@ -569,6 +569,15 @@ npx @spec-wave/cli@latest repo list
569
569
 
570
570
  `repo link` grava `{ slug, owner, repo }` em `repositories[]` do `.spec-wave.json` local do hub (commite depois — os workflows leem a branch default) e cria a label `repo:<slug>`. Slug em `[a-z0-9-]`, até 39 caracteres, **imutável** depois do primeiro vínculo; `repo unlink <slug>` remove a entrada sem tocar nas labels já aplicadas. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
571
571
 
572
+ ##### Autenticação dos workflows: GitHub App ou PATs
573
+
574
+ Os workflows precisam de um token que atravesse repositórios e mexa no Project. Dois modos, e o `doctor` diz qual está em uso:
575
+
576
+ - **GitHub App da organização** (preferido): secrets `SPEC_WAVE_APP_ID` e `SPEC_WAVE_APP_PRIVATE_KEY` (PEM completo) no hub **e** nos repos de código, com a App instalada em todos eles. Permissões mínimas para os workflows: Issues RW, Contents RW, Pull requests RW, Metadata R, Projects (org) RW. Se a App também for usada para rodar `init`/`update` (token `ghs_` gravando `.github/workflows/` pela Contents API), acrescente **Workflows: write** — sem ela o GitHub responde 422 "refusing to allow a GitHub App to create or update workflow … without workflows permission". Cada workflow gera um token por run (`actions/create-github-app-token`) — quem sai da org não derruba o fluxo, e `GH_PR_TOKEN` deixa de ser necessário (PR aberto por App dispara workflows).
577
+ - **PATs** (modo original): `GH_PROJECT_TOKEN` (escopos `repo` + `project`), `GH_PR_TOKEN` quando a org proíbe o `GITHUB_TOKEN` de abrir PR, e `SPEC_WAVE_HUB_TOKEN` no repo de código. Com a App configurada, esses viram fallback.
578
+
579
+ `init` e `doctor` aceitam token de instalação de App (`ghs_…`) — sem escopos legíveis, a verificação é funcional (acesso ao repo e ao Project).
580
+
572
581
  #### Passos
573
582
 
574
583
  1. **Já configurado?** Leia `.spec-wave.json` (Read) ou rode `npx @spec-wave/cli@latest info`. Se existir, mostre `project.url` e `version` e **confirme com o usuário** antes de reconfigurar.
@@ -12,9 +12,11 @@ name: Code Review
12
12
  # template empacotado, e um hub embutido o marcaria como desatualizado para
13
13
  # sempre.
14
14
  #
15
- # Precisa do secret SPEC_WAVE_HUB_TOKEN: um token com permissão de escrita em
16
- # Contents no hub (é o que o repository_dispatch exige). GITHUB_TOKEN não
17
- # serve — ele só enxerga este repositório.
15
+ # Token para despachar (o repository_dispatch exige escrita em Contents NO
16
+ # HUB; o GITHUB_TOKEN só enxerga este repositório): a GitHub App da
17
+ # organização (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY, instalada nos
18
+ # dois repos) emite um token restrito ao hub; sem ela, o secret
19
+ # SPEC_WAVE_HUB_TOKEN (PAT) continua valendo.
18
20
  on:
19
21
  pull_request:
20
22
  types: [opened, reopened]
@@ -23,6 +25,10 @@ concurrency:
23
25
  group: spec-wave-dispatch-${{ github.event.pull_request.number }}
24
26
  cancel-in-progress: false
25
27
 
28
+ # `secrets` não entra em `if`; a presença da GitHub App vira env.
29
+ env:
30
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
31
+
26
32
  jobs:
27
33
  dispatch:
28
34
  # PR de documento (`spec-wave/*`) não é PR de implementação.
@@ -37,12 +43,24 @@ jobs:
37
43
  - id: hub
38
44
  name: Lê o hub do .spec-wave.json
39
45
  run: |
40
- hub="$(jq -r '"\(.hub.owner // "")/\(.hub.repo // "")"' .spec-wave.json)"
41
- if [ "$hub" = "/" ]; then
46
+ owner="$(jq -r '.hub.owner // ""' .spec-wave.json)"
47
+ name="$(jq -r '.hub.repo // ""' .spec-wave.json)"
48
+ if [ -z "$owner" ] || [ -z "$name" ]; then
42
49
  echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@latest init --role code --repo ${{ github.repository }} --hub <owner/repo>"
43
50
  exit 1
44
51
  fi
45
- echo "repo=$hub" >> "$GITHUB_OUTPUT"
52
+ echo "owner=$owner" >> "$GITHUB_OUTPUT"
53
+ echo "name=$name" >> "$GITHUB_OUTPUT"
54
+ echo "repo=$owner/$name" >> "$GITHUB_OUTPUT"
55
+
56
+ - id: app
57
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
58
+ uses: actions/create-github-app-token@v2
59
+ with:
60
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
61
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
62
+ owner: ${{ steps.hub.outputs.owner }}
63
+ repositories: ${{ steps.hub.outputs.name }}
46
64
 
47
65
  - name: Avisa o hub (repository_dispatch)
48
66
  run: |
@@ -57,4 +75,4 @@ jobs:
57
75
  }
58
76
  PAYLOAD
59
77
  env:
60
- GH_TOKEN: ${{ secrets.SPEC_WAVE_HUB_TOKEN }}
78
+ GH_TOKEN: ${{ steps.app.outputs.token || secrets.SPEC_WAVE_HUB_TOKEN }}
@@ -6,8 +6,10 @@ name: QA
6
6
  # de review e de merge acontecem SÓ aqui, no repo do PR.
7
7
  #
8
8
  # O hub é lido do .spec-wave.json em tempo de execução (ver code-review.yml,
9
- # que explica por que o YAML não pode carimbá-lo). Precisa do secret
10
- # SPEC_WAVE_HUB_TOKEN com escrita em Contents no hub.
9
+ # que explica por que o YAML não pode carimbá-lo). Token para despachar: a
10
+ # GitHub App da organização (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY),
11
+ # quando configurada; senão o secret SPEC_WAVE_HUB_TOKEN (PAT com escrita em
12
+ # Contents no hub).
11
13
  on:
12
14
  pull_request_review:
13
15
  types: [submitted]
@@ -18,6 +20,10 @@ concurrency:
18
20
  group: spec-wave-dispatch-qa-${{ github.event.pull_request.number }}
19
21
  cancel-in-progress: false
20
22
 
23
+ # `secrets` não entra em `if`; a presença da GitHub App vira env.
24
+ env:
25
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
26
+
21
27
  jobs:
22
28
  dispatch:
23
29
  # PR de documento (`spec-wave/*`) não é PR de implementação, e aprovar o
@@ -36,12 +42,24 @@ jobs:
36
42
  - id: hub
37
43
  name: Lê o hub do .spec-wave.json
38
44
  run: |
39
- hub="$(jq -r '"\(.hub.owner // "")/\(.hub.repo // "")"' .spec-wave.json)"
40
- if [ "$hub" = "/" ]; then
45
+ owner="$(jq -r '.hub.owner // ""' .spec-wave.json)"
46
+ name="$(jq -r '.hub.repo // ""' .spec-wave.json)"
47
+ if [ -z "$owner" ] || [ -z "$name" ]; then
41
48
  echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@latest init --role code --repo ${{ github.repository }} --hub <owner/repo>"
42
49
  exit 1
43
50
  fi
44
- echo "repo=$hub" >> "$GITHUB_OUTPUT"
51
+ echo "owner=$owner" >> "$GITHUB_OUTPUT"
52
+ echo "name=$name" >> "$GITHUB_OUTPUT"
53
+ echo "repo=$owner/$name" >> "$GITHUB_OUTPUT"
54
+
55
+ - id: app
56
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
57
+ uses: actions/create-github-app-token@v2
58
+ with:
59
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
60
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
61
+ owner: ${{ steps.hub.outputs.owner }}
62
+ repositories: ${{ steps.hub.outputs.name }}
45
63
 
46
64
  - name: Avisa o hub (repository_dispatch)
47
65
  run: |
@@ -56,4 +74,4 @@ jobs:
56
74
  }
57
75
  PAYLOAD
58
76
  env:
59
- GH_TOKEN: ${{ secrets.SPEC_WAVE_HUB_TOKEN }}
77
+ GH_TOKEN: ${{ steps.app.outputs.token || secrets.SPEC_WAVE_HUB_TOKEN }}
@@ -67,6 +67,9 @@ jobs:
67
67
  issues: write
68
68
  pull-requests: write
69
69
  contents: read
70
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
71
+ env:
72
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
70
73
 
71
74
  steps:
72
75
  - uses: actions/checkout@v5
@@ -78,9 +81,21 @@ jobs:
78
81
  - name: Instala a CLI
79
82
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
80
83
 
84
+ # Token de GitHub App da organização, quando configurada
85
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
86
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
87
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
88
+ # valendo pelo `||` abaixo.
89
+ - id: app
90
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
91
+ uses: actions/create-github-app-token@v2
92
+ with:
93
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
94
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
95
+
81
96
  - name: Move Feature to Code Review
82
97
  run: spec-wave code-review --pr-number ${{ github.event.pull_request.number }}
83
98
  env:
84
99
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
85
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
100
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
86
101
  GITHUB_REPOSITORY: ${{ github.repository }}
@@ -68,6 +68,9 @@ jobs:
68
68
  # approve pull requests" estiver ligado (Settings → Actions → General) —
69
69
  # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
70
70
  pull-requests: write
71
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
72
+ env:
73
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
71
74
 
72
75
  steps:
73
76
  - uses: actions/checkout@v5
@@ -81,6 +84,31 @@ jobs:
81
84
  - name: Instala a CLI
82
85
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
83
86
 
87
+ # Token de GitHub App da organização, quando configurada
88
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
89
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
90
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
91
+ # valendo pelo `||` abaixo.
92
+ - id: app
93
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
94
+ uses: actions/create-github-app-token@v2
95
+ with:
96
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
97
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
98
+
99
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
100
+ # de código que a issue declara (labels repo:<slug>; a Feature agrega as
101
+ # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Só no
102
+ # RASCUNHO — o apply não chama o modelo. Sem repo declarado só avisa. O
103
+ # GITHUB_TOKEN só enxerga este repositório — para clonar os outros vai o
104
+ # GH_PROJECT_TOKEN, quando existir.
105
+ - name: Monta o workspace multi-repo
106
+ if: github.event.label.name != 'spec-wave:decompose-apply'
107
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
108
+ env:
109
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
110
+ GITHUB_REPOSITORY: ${{ github.repository }}
111
+
84
112
  - name: Decompose into Stories and Tasks
85
113
  run: >
86
114
  spec-wave decompose
@@ -88,8 +116,8 @@ jobs:
88
116
  ${{ github.event.label.name == 'spec-wave:decompose-apply' && '--apply' || '' }}
89
117
  env:
90
118
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
91
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
92
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
119
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
120
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
93
121
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
94
122
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
95
123
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -52,6 +52,9 @@ jobs:
52
52
  # approve pull requests" estiver ligado (Settings → Actions → General) —
53
53
  # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
54
54
  pull-requests: write
55
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
56
+ env:
57
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
55
58
 
56
59
  steps:
57
60
  - uses: actions/checkout@v5
@@ -65,11 +68,34 @@ jobs:
65
68
  - name: Instala a CLI
66
69
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
67
70
 
71
+ # Token de GitHub App da organização, quando configurada
72
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
73
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
74
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
75
+ # valendo pelo `||` abaixo.
76
+ - id: app
77
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
78
+ uses: actions/create-github-app-token@v2
79
+ with:
80
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
81
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
82
+
83
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
84
+ # de código que a issue declara (labels repo:<slug>), para o modelo ler
85
+ # CÓDIGO e não só o markdown do hub. Sem repo declarado só avisa. O
86
+ # GITHUB_TOKEN só enxerga este repositório — para clonar os outros vai o
87
+ # GH_PROJECT_TOKEN, quando existir.
88
+ - name: Monta o workspace multi-repo
89
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
90
+ env:
91
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
92
+ GITHUB_REPOSITORY: ${{ github.repository }}
93
+
68
94
  - name: Generate bug.md
69
95
  run: spec-wave generate-bug --issue-number ${{ github.event.issue.number }}
70
96
  env:
71
97
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
72
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
98
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
73
99
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
74
100
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
75
101
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -62,6 +62,9 @@ jobs:
62
62
  # approve pull requests" estiver ligado (Settings → Actions → General) —
63
63
  # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
64
64
  pull-requests: write
65
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
66
+ env:
67
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
65
68
 
66
69
  steps:
67
70
  - uses: actions/checkout@v5
@@ -75,11 +78,34 @@ jobs:
75
78
  - name: Instala a CLI
76
79
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
77
80
 
81
+ # Token de GitHub App da organização, quando configurada
82
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
83
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
84
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
85
+ # valendo pelo `||` abaixo.
86
+ - id: app
87
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
88
+ uses: actions/create-github-app-token@v2
89
+ with:
90
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
91
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
92
+
93
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
94
+ # de código que a issue declara (labels repo:<slug>; a Feature agrega as
95
+ # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Sem repo
96
+ # declarado só avisa. O GITHUB_TOKEN só enxerga este repositório — para
97
+ # clonar os outros vai o GH_PROJECT_TOKEN, quando existir.
98
+ - name: Monta o workspace multi-repo
99
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
100
+ env:
101
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
102
+ GITHUB_REPOSITORY: ${{ github.repository }}
103
+
78
104
  - name: Generate plan.md
79
105
  run: spec-wave generate-plan --issue-number ${{ github.event.issue.number }}
80
106
  env:
81
107
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
82
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
108
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
83
109
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
84
110
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
85
111
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -39,6 +39,9 @@ jobs:
39
39
  # `pull-requests: write` o commit existe e o PR não.
40
40
  contents: write
41
41
  pull-requests: write
42
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
43
+ env:
44
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
42
45
 
43
46
  steps:
44
47
  - uses: actions/checkout@v5
@@ -52,12 +55,35 @@ jobs:
52
55
  - name: Instala a CLI
53
56
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
54
57
 
58
+ # Token de GitHub App da organização, quando configurada
59
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
60
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
61
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
62
+ # valendo pelo `||` abaixo.
63
+ - id: app
64
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
65
+ uses: actions/create-github-app-token@v2
66
+ with:
67
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
68
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
69
+
70
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
71
+ # de código que a issue declara (labels repo:<slug>; a Feature agrega as
72
+ # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Sem repo
73
+ # declarado só avisa. O GITHUB_TOKEN só enxerga este repositório — para
74
+ # clonar os outros vai o GH_PROJECT_TOKEN, quando existir.
75
+ - name: Monta o workspace multi-repo
76
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
77
+ env:
78
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
79
+ GITHUB_REPOSITORY: ${{ github.repository }}
80
+
55
81
  - name: Generate QA plan
56
82
  run: spec-wave generate-qa-plan --issue-number ${{ github.event.issue.number }}
57
83
  env:
58
84
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
59
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
60
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
85
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
86
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
61
87
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
62
88
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
63
89
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -62,6 +62,9 @@ jobs:
62
62
  # approve pull requests" estiver ligado (Settings → Actions → General) —
63
63
  # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
64
64
  pull-requests: write
65
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
66
+ env:
67
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
65
68
 
66
69
  steps:
67
70
  - uses: actions/checkout@v5
@@ -75,11 +78,34 @@ jobs:
75
78
  - name: Instala a CLI
76
79
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
77
80
 
81
+ # Token de GitHub App da organização, quando configurada
82
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
83
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
84
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
85
+ # valendo pelo `||` abaixo.
86
+ - id: app
87
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
88
+ uses: actions/create-github-app-token@v2
89
+ with:
90
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
91
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
92
+
93
+ # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
94
+ # de código que a issue declara (labels repo:<slug>; a Feature agrega as
95
+ # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Sem repo
96
+ # declarado só avisa. O GITHUB_TOKEN só enxerga este repositório — para
97
+ # clonar os outros vai o GH_PROJECT_TOKEN, quando existir.
98
+ - name: Monta o workspace multi-repo
99
+ run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
100
+ env:
101
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
102
+ GITHUB_REPOSITORY: ${{ github.repository }}
103
+
78
104
  - name: Generate spec.md
79
105
  run: spec-wave generate-spec --issue-number ${{ github.event.issue.number }}
80
106
  env:
81
107
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
82
- GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
108
+ GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
83
109
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
84
110
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
85
111
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
@@ -8,9 +8,11 @@ name: PR Events
8
8
  # nunca dispara e não custa nada.
9
9
  #
10
10
  # Tokens: GITHUB_TOKEN só enxerga este repositório, e o PR está noutro. Por
11
- # isso a CLI recebe o GH_PROJECT_TOKEN (PAT com repo + project) também como
12
- # GITHUB_TOKEN — é ele que lê o PR e comenta nele. Sem o secret, cai no
13
- # GITHUB_TOKEN, que ainda lê PR de repo público mas não comenta.
11
+ # isso a CLI recebe um token que atravessa repositórios também como
12
+ # GITHUB_TOKEN — o da GitHub App da organização (SPEC_WAVE_APP_ID +
13
+ # SPEC_WAVE_APP_PRIVATE_KEY), quando configurada, senão o GH_PROJECT_TOKEN
14
+ # (PAT com repo + project). Sem nenhum dos dois, cai no GITHUB_TOKEN, que
15
+ # ainda lê PR de repo público mas não comenta.
14
16
  on:
15
17
  repository_dispatch:
16
18
  types: [spec-wave-pr]
@@ -21,6 +23,10 @@ concurrency:
21
23
  group: spec-wave-pr-${{ github.event.client_payload.pr_repo }}-${{ github.event.client_payload.pr_number }}
22
24
  cancel-in-progress: false
23
25
 
26
+ # `secrets` não entra em `if`; a presença da GitHub App vira env.
27
+ env:
28
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
29
+
24
30
  jobs:
25
31
  # Descobre a Feature-alvo ANTES de tocar no board, para dar a chave de
26
32
  # concurrency ao job seguinte — mesmo desenho do code-review.yml local.
@@ -44,6 +50,13 @@ jobs:
44
50
  - name: Instala a CLI
45
51
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
46
52
 
53
+ - id: app
54
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
55
+ uses: actions/create-github-app-token@v2
56
+ with:
57
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
58
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
59
+
47
60
  - id: resolve
48
61
  run: >
49
62
  spec-wave code-review
@@ -51,7 +64,7 @@ jobs:
51
64
  --pr-repo ${{ github.event.client_payload.pr_repo }}
52
65
  --resolve-only
53
66
  env:
54
- GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
67
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
55
68
  GITHUB_REPOSITORY: ${{ github.repository }}
56
69
 
57
70
  move:
@@ -79,14 +92,21 @@ jobs:
79
92
  - name: Instala a CLI
80
93
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
81
94
 
95
+ - id: app
96
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
97
+ uses: actions/create-github-app-token@v2
98
+ with:
99
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
100
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
101
+
82
102
  - name: Move Feature to Code Review
83
103
  run: >
84
104
  spec-wave code-review
85
105
  --pr-number ${{ github.event.client_payload.pr_number }}
86
106
  --pr-repo ${{ github.event.client_payload.pr_repo }}
87
107
  env:
88
- GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
89
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
108
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
109
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
90
110
  GITHUB_REPOSITORY: ${{ github.repository }}
91
111
 
92
112
  qa:
@@ -105,12 +125,19 @@ jobs:
105
125
  - name: Instala a CLI
106
126
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
107
127
 
128
+ - id: app
129
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
130
+ uses: actions/create-github-app-token@v2
131
+ with:
132
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
133
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
134
+
108
135
  - name: Move Feature to QA
109
136
  run: >
110
137
  spec-wave qa
111
138
  --pr-number ${{ github.event.client_payload.pr_number }}
112
139
  --pr-repo ${{ github.event.client_payload.pr_repo }}
113
140
  env:
114
- GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
115
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
141
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
142
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
116
143
  GITHUB_REPOSITORY: ${{ github.repository }}
@@ -42,6 +42,9 @@ jobs:
42
42
  issues: write
43
43
  pull-requests: write
44
44
  contents: read
45
+ # `secrets` não entra em `if`; a presença da GitHub App vira env do job.
46
+ env:
47
+ SPEC_WAVE_APP_PRESENT: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY != '' }}
45
48
 
46
49
  steps:
47
50
  - uses: actions/checkout@v5
@@ -53,10 +56,21 @@ jobs:
53
56
  - name: Instala a CLI
54
57
  run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
55
58
 
59
+ # Token de GitHub App da organização, quando configurada
60
+ # (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY): substitui os PATs
61
+ # pessoais — quem sai da org não derruba o fluxo. Sem os secrets o step
62
+ # é pulado, `steps.app.outputs.token` fica vazio e os PATs continuam
63
+ # valendo pelo `||` abaixo.
64
+ - id: app
65
+ if: env.SPEC_WAVE_APP_PRESENT == 'true'
66
+ uses: actions/create-github-app-token@v2
67
+ with:
68
+ app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
69
+ private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
56
70
 
57
71
  - name: Move Feature to QA
58
72
  run: spec-wave qa --pr-number ${{ github.event.pull_request.number }}
59
73
  env:
60
74
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
61
- PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
75
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
62
76
  GITHUB_REPOSITORY: ${{ github.repository }}