@spec-wave/cli 1.7.5 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +1 -1
  2. package/package.json +1 -1
  3. package/src/agent/errors.mjs +31 -1
  4. package/src/agent/openrouter-agent.mjs +25 -2
  5. package/src/api/github-graphql.mjs +31 -0
  6. package/src/api/github-rest.mjs +20 -0
  7. package/src/cli.mjs +93 -36
  8. package/src/commands/auth-check.mjs +72 -0
  9. package/src/commands/decompose.mjs +14 -2
  10. package/src/commands/doctor.mjs +139 -2
  11. package/src/commands/generate-bug.mjs +6 -6
  12. package/src/commands/generate-plan.mjs +9 -8
  13. package/src/commands/generate-qa-plan.mjs +9 -6
  14. package/src/commands/generate-spec.mjs +12 -7
  15. package/src/commands/init.mjs +2 -2
  16. package/src/commands/preflight.mjs +38 -2
  17. package/src/commands/relink.mjs +105 -0
  18. package/src/commands/report-failure.mjs +99 -0
  19. package/src/commands/retry.mjs +91 -0
  20. package/src/commands/update.mjs +70 -0
  21. package/src/config.mjs +8 -8
  22. package/src/lib/cited-paths.mjs +89 -0
  23. package/src/lib/claude.mjs +4 -2
  24. package/src/lib/cli-line.mjs +153 -0
  25. package/src/lib/cli-ref.mjs +53 -2
  26. package/src/lib/failure-report.mjs +319 -0
  27. package/src/lib/repo-identity.mjs +55 -0
  28. package/src/lib/spec-index.mjs +114 -0
  29. package/src/lib/tech-context.mjs +144 -5
  30. package/src/plugin/.claude-plugin/plugin.json +1 -1
  31. package/src/plugin/skills/plan/SKILL.md +1 -1
  32. package/src/plugin/skills/plan/reference/tech-context.md +12 -4
  33. package/src/plugin/skills/setup/SKILL.md +1 -1
  34. package/src/plugin/skills/spec/model-prompt.md +8 -1
  35. package/src/plugins/scm-github/index.mjs +8 -1
  36. package/src/plugins/tracker-github-projects/index.mjs +11 -4
  37. package/src/ports/tracker.mjs +2 -1
  38. package/src/setup/labels.mjs +5 -3
  39. package/src/setup/project.mjs +5 -3
  40. package/src/templates/config/tech_context.yml +29 -25
  41. package/src/templates/skill/SKILL.md +27 -9
  42. package/src/templates/skill/core.md +25 -7
  43. package/src/templates/workflows/code-review.yml +1 -0
  44. package/src/templates/workflows/critique.yml +11 -0
  45. package/src/templates/workflows/decompose.yml +27 -0
  46. package/src/templates/workflows/generate-bug.yml +26 -0
  47. package/src/templates/workflows/generate-plan.yml +26 -0
  48. package/src/templates/workflows/generate-qa-plan.yml +27 -0
  49. package/src/templates/workflows/generate-spec.yml +26 -0
  50. package/src/templates/workflows/pr-events.yml +11 -1
  51. package/src/templates/workflows/qa.yml +1 -0
  52. package/src/templates/workflows/validate.yml +11 -0
@@ -24,7 +24,7 @@ O plano segue o schema do **RFC-002 §3.2**: **Estratégia Técnica** (com Matri
24
24
 
25
25
  1. **A spec existe?** Verifique `docs/features/<slug>/spec.md` — o plano usa a especificação funcional como contexto. Se não existir, gere a spec primeiro (skill **spec**).
26
26
 
27
- 2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read). **Se não existir, ajude a criar AGORA** — o passo a passo está em `reference/tech-context.md`, ao lado deste arquivo. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
27
+ 2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read) e está **preenchido** — o scaffold do `init` é um formulário em branco aberto pela linha `# spec-wave:template`, e nesse estado o plano sai sem contexto técnico. **Se não existir ou não estiver preenchido, ajude a criar AGORA** — o passo a passo está em `reference/tech-context.md`, ao lado deste arquivo. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
28
28
 
29
29
  3. **Acione**, no modo escolhido:
30
30
  ```bash
@@ -2,11 +2,19 @@
2
2
 
3
3
  Fonte de verdade **estática** da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias e serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes.
4
4
 
5
- O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
5
+ O `npx @spec-wave/cli@latest init` gera um **scaffold em branco** — um formulário, não um exemplo — aberto pela linha `# spec-wave:template`. Use este fluxo quando o arquivo estiver ausente, **não preenchido** ou desatualizado.
6
+
7
+ **Não preenchido** é qualquer um destes três casos, e nos três o `doctor` reprova, o `preflight` bloqueia a rodada e o `generate-plan` gera **sem** contexto técnico estático (avisando na issue):
8
+
9
+ - a linha `# spec-wave:template` ainda abre o arquivo;
10
+ - nenhum campo além de `system_info.name` tem valor (apagar só a linha do marcador não resolve);
11
+ - o arquivo é o **exemplo dos scaffolds antigos** (até a CLI 1.7.x): `name: "Order Management System"` com `backend: "Node.js (NestJS v10)"`. Esse não tem marcador para apagar — o conteúdo é que precisa ser substituído pelo stack real.
6
12
 
7
13
  ## Como ajudar a criar
8
14
 
9
- 1. **Confirme a ausência:** tente `Read .github/config/tech_context.yml`. Se já existir, confirme com o usuário se reflete a stack atual e pule para o fim.
15
+ 1. **Leia o que existe:** tente `Read .github/config/tech_context.yml`.
16
+ - **Ausente ou não preenchido** (ver acima) → siga os passos abaixo.
17
+ - **Preenchido** → confirme com o usuário se reflete a stack atual e pule para o fim.
10
18
 
11
19
  2. **Detecte a stack lendo os arquivos do repositório** (use Read — **não invente**):
12
20
 
@@ -20,7 +28,7 @@ O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve se
20
28
  | `Dockerfile` / `docker-compose.yml` / charts Helm | `infra` |
21
29
  | enums de RBAC no código | `security.rbac_roles` |
22
30
 
23
- 3. **Rascunhe** o YAML seguindo EXATAMENTE este schema. Preencha só o que conseguir confirmar; deixe `# TODO` no que faltar:
31
+ 3. **Rascunhe** o YAML seguindo EXATAMENTE este schema. Preencha só o que conseguir confirmar; deixe `# TODO` no que faltar, e **apague** a chave que não se aplica ao sistema (valor vazio ou "N/A" é lido como tecnologia):
24
32
 
25
33
  ```yaml
26
34
  system_info:
@@ -53,7 +61,7 @@ O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve se
53
61
 
54
62
  4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar — ele conhece serviços internos e roles que o código pode não revelar.
55
63
 
56
- 5. **Grave** com Write em `.github/config/tech_context.yml`.
64
+ 5. **Grave** com Write em `.github/config/tech_context.yml` — **sem** a linha `# spec-wave:template` do scaffold. Ela é o que marca o arquivo como não preenchido; mantê-la bloqueia o `preflight` mesmo com os campos certos.
57
65
 
58
66
  6. **Oriente a commitar e pushar antes de seguir** — o Action lê do repositório, não do disco local. Sugira ao usuário rodar, via prefixo `!`:
59
67
 
@@ -93,7 +93,7 @@ Sem essas envs nada muda (instalação normal por `npm install -g`). Com elas, o
93
93
 
94
94
  7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava o `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
95
95
 
96
- 8. **Adapte o `tech_context.yml`** — o scaffold vem com dados de exemplo e a qualidade do `plan.md` depende dele. Ofereça ajustá-lo agora; o passo a passo está na skill **plan** (`reference/tech-context.md`).
96
+ 8. **Preencha o `tech_context.yml`** — o scaffold é um **formulário em branco** aberto pela linha `# spec-wave:template`, e a qualidade do `plan.md` depende dele. Enquanto essa linha existir (ou os campos estiverem vazios) o arquivo conta como **não preenchido**: o `doctor` reprova, o `preflight` bloqueia a rodada e o `generate-plan` gera sem contexto técnico. Ofereça preenchê-lo agora — com o stack real e **sem** a linha do marcador; o passo a passo está na skill **plan** (`reference/tech-context.md`).
97
97
 
98
98
  9. **Secret de IA:** instrua a adicionar em Settings → Secrets → Actions a credencial do provider escolhido: `ANTHROPIC_API_KEY` (Anthropic), `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max — gere com `claude setup-token`) ou `OPENROUTER_API_KEY` (OpenRouter).
99
99
 
@@ -3,7 +3,7 @@ name: spec
3
3
  action: spec
4
4
  description: Gera a especificação funcional (spec.md) de uma Feature a partir da issue do GitHub.
5
5
  tools: [Read, Glob, Grep]
6
- maxTurns: 30
6
+ maxTurns: 40
7
7
  ---
8
8
 
9
9
  # Geração de spec.md
@@ -24,6 +24,13 @@ Você recebe um payload JSON com:
24
24
 
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
+ **Orçamento de exploração.** Os turnos são limitados, e cada chamada de ferramenta gasta um. Um run que explora até o fim do orçamento falha sem entregar nada — pior que uma spec com `[TODO]`.
28
+
29
+ - Quando a entrada trouxer o **Índice das specs existentes**, comece por ele: o objetivo e as dependências de cada spec já estão ali. Abra só as que o índice indica como relacionadas a esta Feature.
30
+ - `Grep` antes de `Read`: procure o termo de domínio e abra apenas os arquivos que casaram.
31
+ - No máximo **12 arquivos lidos por inteiro**. Para arquivo grande, use `Read` com `offset`/`limit` na região que interessa.
32
+ - Quando já souber o suficiente para as seções obrigatórias, pare de explorar e escreva. O que faltar vira `[TODO: requer esclarecimento do PO]`.
33
+
27
34
  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
35
 
29
36
  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.
@@ -38,6 +38,7 @@ import {
38
38
  getRequiredStatusChecks,
39
39
  listActionsSecretNames,
40
40
  getActionsCanCreatePullRequests,
41
+ getOwnerPlan,
41
42
  isRepoInitialized,
42
43
  listPullRequestCommitMessages,
43
44
  listPullRequestReviews,
@@ -237,7 +238,7 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
237
238
  getPRClosingIssues, getRateLimit, listIssuePullRequests, listOpenPullRequests,
238
239
  markPullRequestReadyForReview,
239
240
  getRepoInfo, getRequiredStatusChecks, listActionsSecretNames,
240
- getActionsCanCreatePullRequests, getFileBytes,
241
+ getActionsCanCreatePullRequests, getOwnerPlan, getFileBytes,
241
242
  ...api,
242
243
  };
243
244
 
@@ -316,6 +317,12 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
316
317
  } catch {
317
318
  facts.automationCanOpenPullRequest = null; // exige administration:read
318
319
  }
320
+ try {
321
+ // Plano da org: decide se secrets de ORGANIZAÇÃO chegam a repo privado.
322
+ facts.ownerPlan = await a.getOwnerPlan(token, owner);
323
+ } catch {
324
+ facts.ownerPlan = null;
325
+ }
319
326
  }
320
327
 
321
328
  const quota = (await a.getRateLimit(token)) || {};
@@ -64,6 +64,7 @@ import {
64
64
  getItemTextValue,
65
65
  setItemText,
66
66
  getProjectSnapshot,
67
+ getProjectIdByUrl,
67
68
  getRateLimit,
68
69
  linkProjectToRepo,
69
70
  listProjectItems,
@@ -184,7 +185,7 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
184
185
  setIssueMilestone, setIssueState, updateComment, updateIssue, updateLabel, updateMilestone,
185
186
  updateMilestoneDescription, getOwnerNodeId, getRepoNodeId,
186
187
  addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
187
- getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
188
+ getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getProjectIdByUrl, getRateLimit,
188
189
  linkProjectToRepo, listProjectItems, listSubIssues, setItemSingleSelect, setItemText,
189
190
  resolveField, getOrgMembershipState, listIssuesByLabel,
190
191
  ...api,
@@ -241,15 +242,21 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
241
242
  kind: TRACKER_KIND,
242
243
  capabilities: GITHUB_TRACKER_CAPABILITIES,
243
244
 
244
- async setup({ provision = true, title, log } = {}) {
245
+ async setup({ provision = true, title, log, boardUrl = null } = {}) {
245
246
  // `provision: false` é LEITURA: devolve o bloco de config que descreve o
246
247
  // board como ele está agora. É o que o `refresh --config` precisa, e é a
247
248
  // mesma pergunta que um tracker `map-only` responderia relendo os
248
249
  // statuses do site — por isso não virou operação separada.
249
250
  if (!provision) {
250
- const snap = await a.getProjectSnapshot(ptk, project?.id);
251
+ // `boardUrl`: lê OUTRO board, apontado pela URL — é o `relink` de um
252
+ // repositório transferido, cujo config ainda guarda o id do board antigo.
253
+ const alvo = boardUrl ? await a.getProjectIdByUrl(ptk, boardUrl) : project?.id;
254
+ if (!alvo) {
255
+ return { config: null, warnings: [`Project ${boardUrl} não encontrado, ou o token não o enxerga.`] };
256
+ }
257
+ const snap = await a.getProjectSnapshot(ptk, alvo);
251
258
  if (!snap) {
252
- return { config: null, warnings: [`Project ${project?.id} não encontrado. Ele pode ter sido excluído.`] };
259
+ return { config: null, warnings: [`Project ${alvo} não encontrado. Ele pode ter sido excluído.`] };
253
260
  }
254
261
  return {
255
262
  config: {
@@ -60,7 +60,8 @@ import { checkCapabilityKeys } from './capabilities.mjs';
60
60
  *
61
61
  * ── SEMPRE ────────────────────────────────────────────────────────────────
62
62
  *
63
- * @property {(o?: {provision?: boolean, log?: Function}) => Promise<{config: object, warnings: string[]}>} setup
63
+ * @property {(o?: {provision?: boolean, log?: Function, boardUrl?: string}) => Promise<{config: object, warnings: string[]}>} setup
64
+ * `boardUrl` (só com `provision: false`): lê o board apontado pela URL em vez do do config — o `relink`.
64
65
  * Provisiona (`boardProvisioning: 'create'`) ou mapeia (`'map-only'`) o board.
65
66
  * Devolve o bloco a gravar no `.spec-wave.json` — **nunca escreve o arquivo**:
66
67
  * quem serializa é `lib/config-file.mjs`, byte-exato, porque o `update` faz
@@ -1,5 +1,5 @@
1
1
  import { allLabelsFor } from '../config.mjs';
2
- import { requireTracker } from '../ports/index.mjs';
2
+ import { DEFAULT_TRACKER_KIND, requireTracker } from '../ports/index.mjs';
3
3
 
4
4
  /**
5
5
  * Pausa entre criações de label.
@@ -16,8 +16,10 @@ const DELAY_MS = 120;
16
16
  // vale para `devAgent` e as filas extra do dev-agent. No `init` os dois vêm
17
17
  // vazios (o config ainda nem foi gravado) e o conjunto é só o do fluxo; quem
18
18
  // cria as de modelo/fila depois é o `update`, que já lê o config do repo.
19
- export async function setupLabels(token, owner, repo, spinner, fileAi, devAgent, { port } = {}) {
20
- const tracker = await requireTracker({ token, owner, repo, deps: { tracker: port } });
19
+ export async function setupLabels(token, owner, repo, spinner, fileAi, devAgent, { port, kind = DEFAULT_TRACKER_KIND } = {}) {
20
+ // `kind` explícito: no `init` ainda não existe `.spec-wave.json` para o
21
+ // loader descobrir o fornecedor (ver getTracker em ports/index.mjs).
22
+ const tracker = await requireTracker({ token, owner, repo, kind, deps: { tracker: port } });
21
23
  const labels = allLabelsFor(fileAi, devAgent);
22
24
  await tracker.ensureTags({
23
25
  tags: labels,
@@ -13,7 +13,7 @@
13
13
  // a chama com um spinner do Clack, e trocar o formato do progresso do `init`
14
14
  // seria mudança de comportamento numa fase que promete não ter nenhuma.
15
15
 
16
- import { requireTracker } from '../ports/index.mjs';
16
+ import { DEFAULT_TRACKER_KIND, requireTracker } from '../ports/index.mjs';
17
17
 
18
18
  /**
19
19
  * Cria o GitHub Project e os campos do RFC-001.
@@ -26,8 +26,10 @@ import { requireTracker } from '../ports/index.mjs';
26
26
  * @param {{port?: object}} [opts] injeção da porta, para teste
27
27
  * @returns {Promise<{projectId, projectNumber, projectUrl, fields, linkWarning?}>}
28
28
  */
29
- export async function setupProject(token, owner, repo, projectTitle, spinner, { port } = {}) {
30
- const tracker = await requireTracker({ token, owner, repo, deps: { tracker: port } });
29
+ export async function setupProject(token, owner, repo, projectTitle, spinner, { port, kind = DEFAULT_TRACKER_KIND } = {}) {
30
+ // `kind` explícito: no `init` ainda não existe `.spec-wave.json` para o
31
+ // loader descobrir o fornecedor (ver getTracker em ports/index.mjs).
32
+ const tracker = await requireTracker({ token, owner, repo, kind, deps: { tracker: port } });
31
33
  const { config, warnings } = await tracker.setup({
32
34
  provision: true,
33
35
  title: projectTitle,
@@ -1,3 +1,9 @@
1
+ # spec-wave:template — APAGUE ESTA LINHA depois de preencher o arquivo com o stack REAL.
2
+ #
3
+ # Enquanto esta linha existir, o arquivo é tratado como NÃO PREENCHIDO: o
4
+ # `doctor` e o `preflight` reprovam, e o `generate-plan` não o injeta no prompt
5
+ # (um stack de exemplo lido como verdade produz plano para o sistema errado).
6
+ #
1
7
  # tech_context.yml — Fonte de verdade estática do sistema (RFC-002 §4)
2
8
  #
3
9
  # O comando `generate-plan` lê este arquivo para embasar o plano técnico, usando
@@ -7,39 +13,37 @@
7
13
  # migrations recentes e as versões exatas de pacotes (package.json) em tempo de
8
14
  # execução. Para desvios pontuais, adicione uma seção `## Tech Override` no corpo
9
15
  # da issue da Feature — ela é mesclada (deep-merge) sobre esta config.
16
+ #
17
+ # Preencha só o que existe. Chave que não se aplica ao sistema: apague-a
18
+ # (não deixe "N/A" — o modelo lê o valor como tecnologia).
10
19
 
11
20
  system_info:
12
- name: "Order Management System"
21
+ name: "" # ex.: "Gestão de Pedidos"
13
22
  stack:
14
- backend: "Node.js (NestJS v10)"
15
- frontend: "React 18 with Vite"
16
- database: "PostgreSQL 15"
17
- cache: "Redis 7"
18
- messaging: "RabbitMQ"
19
- infra: "Kubernetes (EKS) + Helm"
20
- architecture: "Microservices via API Gateway"
23
+ backend: "" # ex.: "Node.js (NestJS v10)", "Kotlin (Ktor)", "AWS Amplify Gen 2 (Lambda)"
24
+ frontend: "" # ex.: "React 18 com Vite", "Compose Multiplatform"
25
+ database: "" # ex.: "PostgreSQL 15", "DynamoDB"
26
+ infra: "" # ex.: "Kubernetes (EKS) + Helm", "AWS Amplify"
27
+ architecture: "" # ex.: "Monólito modular", "Microsserviços via API Gateway"
21
28
 
22
29
  security:
23
- auth_protocol: "JWT (Access/Refresh)"
24
- rbac_roles: ["ADMIN", "MANAGER", "GARCOM", "COZINHA"]
30
+ auth_protocol: "" # ex.: "JWT (Access/Refresh)", "Amazon Cognito"
31
+ rbac_roles: [] # ex.: ["ADMIN", "OPERADOR"]
25
32
 
26
- database_schemas:
27
- - table: "users"
28
- columns: "id, name, email, role, password_hash"
29
- - table: "tables"
30
- columns: "id, number, status, capacity"
31
- - table: "products"
32
- columns: "id, name, category, price, stock"
33
+ # Tabelas/coleções que as features costumam tocar (opcional).
34
+ # database_schemas:
35
+ # - table: "users"
36
+ # columns: "id, name, email, role"
33
37
 
34
- existing_services:
35
- - name: "Inventory API"
36
- endpoint: "/api/inventory/{productId}/availability"
37
- auth: "mTLS"
38
- docs: "https://docs.internal/inventory"
38
+ # Serviços existentes que as features podem consumir (opcional).
39
+ # existing_services:
40
+ # - name: "Inventory API"
41
+ # endpoint: "/api/inventory/{productId}/availability"
42
+ # auth: "mTLS"
39
43
 
40
- internal_libraries:
41
- - "shared-logger"
42
- - "db-client (TypeORM)"
44
+ # Bibliotecas internas (opcional).
45
+ # internal_libraries:
46
+ # - "shared-logger"
43
47
 
44
48
  # Decisões de modelagem de recursos COMPARTILHADOS entre features (opcional).
45
49
  #
@@ -243,6 +243,14 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
243
243
  > - `generate-spec` / `generate-plan` → **apenas Features**. Para **Spike, RFC e Bug** a geração é **pulada** (o Action remove a label e comenta) — esses tipos não usam spec/plan.
244
244
  > - `decompose` → **Feature** (gera Stories + Tasks) e **RFC** (gera **Tasks** diretamente, sem Stories). Para outros tipos, o Action recusa.
245
245
 
246
+ ### `@spec-wave/cli retry <issue>` — dispara de novo a etapa que falhou (comando LOCAL)
247
+ | Flag | Tipo | Descrição |
248
+ |------|------|-----------|
249
+ | `--label <label>` | string | Label de gatilho a reaplicar. Obrigatória quando a issue não tem nenhuma aplicada (o comando que falhou a removeu). |
250
+ | `--force` | flag | Aceita reaplicar `spec-wave:decompose-apply` (pode duplicar issues já criadas). |
251
+
252
+ > Quando um workflow falha, o comentário ❌ na issue traz a **causa provável** (auth, max_turns, provider…), qual secret trocar e o próximo passo. Depois de corrigir, use `retry` — **não** `gh run rerun`, que reexecuta o commit ORIGINAL e ignora correções já mergeadas (um override de prompt, um workflow atualizado). O `retry` remove e reaplica a label, e o run novo usa a branch default atual. Em modo local o caminho é `run`.
253
+
246
254
  ### `@spec-wave/cli implement` — aciona o spec-kit para uma Feature, Story ou Task (comando LOCAL)
247
255
  | Flag/Arg | Tipo | Descrição |
248
256
  |----------|------|-----------|
@@ -440,11 +448,11 @@ Cada ação de IA (`spec`, `plan`, `decompose`, `critique`) pode usar um modelo
440
448
  "plan": "claude-opus-4-1",
441
449
  "critique": "claude-opus-4-1"
442
450
  },
443
- "escalationModel": "claude-opus-5",
451
+ "escalationModel": "claude-opus-5-5",
444
452
  "maxCritiqueAttempts": 3,
445
453
  "modelAliases": {
446
- "opus": "claude-opus-5",
447
- "haiku": "claude-haiku-4-5"
454
+ "opus": "claude-opus-5-5",
455
+ "haiku": "claude-haiku-5-5"
448
456
  }
449
457
  }
450
458
  }
@@ -617,7 +625,7 @@ Sem essas envs nada muda (instalação normal por `npm install -g`). Com elas, o
617
625
 
618
626
  7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava o `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
619
627
 
620
- 8. **Adapte o `tech_context.yml`** — o scaffold vem com dados de exemplo e a qualidade do `plan.md` depende dele. Ofereça ajustá-lo agora; o passo a passo está na seção **Tech Context** deste documento.
628
+ 8. **Preencha o `tech_context.yml`** — o scaffold é um **formulário em branco** aberto pela linha `# spec-wave:template`, e a qualidade do `plan.md` depende dele. Enquanto essa linha existir (ou os campos estiverem vazios) o arquivo conta como **não preenchido**: o `doctor` reprova, o `preflight` bloqueia a rodada e o `generate-plan` gera sem contexto técnico. Ofereça preenchê-lo agora — com o stack real e **sem** a linha do marcador; o passo a passo está na seção **Tech Context** deste documento.
621
629
 
622
630
  9. **Secret de IA:** instrua a adicionar em Settings → Secrets → Actions a credencial do provider escolhido: `ANTHROPIC_API_KEY` (Anthropic), `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max — gere com `claude setup-token`) ou `OPENROUTER_API_KEY` (OpenRouter).
623
631
 
@@ -861,7 +869,7 @@ O plano segue o schema do **RFC-002 §3.2**: **Estratégia Técnica** (com Matri
861
869
 
862
870
  1. **A spec existe?** Verifique `docs/features/<slug>/spec.md` — o plano usa a especificação funcional como contexto. Se não existir, gere a spec primeiro (skill **spec**).
863
871
 
864
- 2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read). **Se não existir, ajude a criar AGORA** — o passo a passo está na seção **Tech Context** deste documento. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
872
+ 2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read) e está **preenchido** — o scaffold do `init` é um formulário em branco aberto pela linha `# spec-wave:template`, e nesse estado o plano sai sem contexto técnico. **Se não existir ou não estiver preenchido, ajude a criar AGORA** — o passo a passo está na seção **Tech Context** deste documento. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
865
873
 
866
874
  3. **Acione**, no modo escolhido:
867
875
  ```bash
@@ -1587,11 +1595,21 @@ utilitários de board estão flag a flag na *Referência da CLI* acima. Rode
1587
1595
 
1588
1596
  ## Tech Context (`.github/config/tech_context.yml`)
1589
1597
 
1590
- Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes. O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
1598
+ Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes.
1599
+
1600
+ O `npx @spec-wave/cli@latest init` gera um **scaffold em branco** — um formulário, não um exemplo — aberto pela linha `# spec-wave:template`. Use este fluxo quando o arquivo estiver ausente, **não preenchido** ou desatualizado.
1601
+
1602
+ **Não preenchido** é qualquer um destes três casos, e nos três o `doctor` reprova, o `preflight` bloqueia a rodada e o `generate-plan` gera **sem** contexto técnico estático (avisando na issue):
1603
+
1604
+ - a linha `# spec-wave:template` ainda abre o arquivo;
1605
+ - nenhum campo além de `system_info.name` tem valor (apagar só a linha do marcador não resolve);
1606
+ - o arquivo é o **exemplo dos scaffolds antigos** (até a CLI 1.7.x): `name: "Order Management System"` com `backend: "Node.js (NestJS v10)"`. Esse não tem marcador para apagar — o conteúdo é que precisa ser substituído pelo stack real.
1591
1607
 
1592
- **Como ajudar a criar (quando não existir):**
1608
+ **Como ajudar a criar (quando não existir ou não estiver preenchido):**
1593
1609
 
1594
- 1. **Confirme a ausência:** tente `Read .github/config/tech_context.yml`. Se já existir, apenas confirme com o usuário se reflete a stack atual e pule para o fim.
1610
+ 1. **Leia o que existe:** tente `Read .github/config/tech_context.yml`.
1611
+ - **Ausente ou não preenchido** (ver acima) → siga os passos abaixo.
1612
+ - **Preenchido** → confirme com o usuário se reflete a stack atual e pule para o fim.
1595
1613
  2. **Detecte a stack** lendo os arquivos do repositório (use Read; não invente):
1596
1614
  - `package.json` → backend/frontend e libs (ex.: `@nestjs/core`, `next`, `react`, `@prisma/client`, `express`).
1597
1615
  - `pom.xml` / `build.gradle` (Java), `requirements.txt` / `pyproject.toml` (Python), `go.mod` (Go).
@@ -1622,7 +1640,7 @@ Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan`
1622
1640
  - "<lib interna>"
1623
1641
  ```
1624
1642
  4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar (ele conhece serviços internos e roles que o código pode não revelar).
1625
- 5. **Grave** com Write em `.github/config/tech_context.yml`.
1643
+ 5. **Grave** com Write em `.github/config/tech_context.yml` — **sem** a linha `# spec-wave:template` do scaffold. Ela é o que marca o arquivo como não preenchido; mantê-la bloqueia o `preflight` mesmo com os campos certos.
1626
1644
  6. **Oriente a commitar e pushar** antes de seguir (o Action lê do repo). Sugira ao usuário rodar, via prefixo `!`:
1627
1645
  ```bash
1628
1646
  !git add .github/config/tech_context.yml && git commit -m "chore: tech_context.yml [spec-wave]" && git push
@@ -239,6 +239,14 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
239
239
  > - `generate-spec` / `generate-plan` → **apenas Features**. Para **Spike, RFC e Bug** a geração é **pulada** (o Action remove a label e comenta) — esses tipos não usam spec/plan.
240
240
  > - `decompose` → **Feature** (gera Stories + Tasks) e **RFC** (gera **Tasks** diretamente, sem Stories). Para outros tipos, o Action recusa.
241
241
 
242
+ ### `@spec-wave/cli retry <issue>` — dispara de novo a etapa que falhou (comando LOCAL)
243
+ | Flag | Tipo | Descrição |
244
+ |------|------|-----------|
245
+ | `--label <label>` | string | Label de gatilho a reaplicar. Obrigatória quando a issue não tem nenhuma aplicada (o comando que falhou a removeu). |
246
+ | `--force` | flag | Aceita reaplicar `spec-wave:decompose-apply` (pode duplicar issues já criadas). |
247
+
248
+ > Quando um workflow falha, o comentário ❌ na issue traz a **causa provável** (auth, max_turns, provider…), qual secret trocar e o próximo passo. Depois de corrigir, use `retry` — **não** `gh run rerun`, que reexecuta o commit ORIGINAL e ignora correções já mergeadas (um override de prompt, um workflow atualizado). O `retry` remove e reaplica a label, e o run novo usa a branch default atual. Em modo local o caminho é `run`.
249
+
242
250
  ### `@spec-wave/cli implement` — aciona o spec-kit para uma Feature, Story ou Task (comando LOCAL)
243
251
  | Flag/Arg | Tipo | Descrição |
244
252
  |----------|------|-----------|
@@ -436,11 +444,11 @@ Cada ação de IA (`spec`, `plan`, `decompose`, `critique`) pode usar um modelo
436
444
  "plan": "claude-opus-4-1",
437
445
  "critique": "claude-opus-4-1"
438
446
  },
439
- "escalationModel": "claude-opus-5",
447
+ "escalationModel": "claude-opus-5-5",
440
448
  "maxCritiqueAttempts": 3,
441
449
  "modelAliases": {
442
- "opus": "claude-opus-5",
443
- "haiku": "claude-haiku-4-5"
450
+ "opus": "claude-opus-5-5",
451
+ "haiku": "claude-haiku-5-5"
444
452
  }
445
453
  }
446
454
  }
@@ -496,11 +504,21 @@ O `validate` também recusa documento com sinal objetivo de corte (bloco de cód
496
504
 
497
505
  ## Tech Context (`.github/config/tech_context.yml`)
498
506
 
499
- Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes. O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
507
+ Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes.
508
+
509
+ O `npx @spec-wave/cli@latest init` gera um **scaffold em branco** — um formulário, não um exemplo — aberto pela linha `# spec-wave:template`. Use este fluxo quando o arquivo estiver ausente, **não preenchido** ou desatualizado.
510
+
511
+ **Não preenchido** é qualquer um destes três casos, e nos três o `doctor` reprova, o `preflight` bloqueia a rodada e o `generate-plan` gera **sem** contexto técnico estático (avisando na issue):
512
+
513
+ - a linha `# spec-wave:template` ainda abre o arquivo;
514
+ - nenhum campo além de `system_info.name` tem valor (apagar só a linha do marcador não resolve);
515
+ - o arquivo é o **exemplo dos scaffolds antigos** (até a CLI 1.7.x): `name: "Order Management System"` com `backend: "Node.js (NestJS v10)"`. Esse não tem marcador para apagar — o conteúdo é que precisa ser substituído pelo stack real.
500
516
 
501
- **Como ajudar a criar (quando não existir):**
517
+ **Como ajudar a criar (quando não existir ou não estiver preenchido):**
502
518
 
503
- 1. **Confirme a ausência:** tente `Read .github/config/tech_context.yml`. Se já existir, apenas confirme com o usuário se reflete a stack atual e pule para o fim.
519
+ 1. **Leia o que existe:** tente `Read .github/config/tech_context.yml`.
520
+ - **Ausente ou não preenchido** (ver acima) → siga os passos abaixo.
521
+ - **Preenchido** → confirme com o usuário se reflete a stack atual e pule para o fim.
504
522
  2. **Detecte a stack** lendo os arquivos do repositório (use Read; não invente):
505
523
  - `package.json` → backend/frontend e libs (ex.: `@nestjs/core`, `next`, `react`, `@prisma/client`, `express`).
506
524
  - `pom.xml` / `build.gradle` (Java), `requirements.txt` / `pyproject.toml` (Python), `go.mod` (Go).
@@ -531,7 +549,7 @@ Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan`
531
549
  - "<lib interna>"
532
550
  ```
533
551
  4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar (ele conhece serviços internos e roles que o código pode não revelar).
534
- 5. **Grave** com Write em `.github/config/tech_context.yml`.
552
+ 5. **Grave** com Write em `.github/config/tech_context.yml` — **sem** a linha `# spec-wave:template` do scaffold. Ela é o que marca o arquivo como não preenchido; mantê-la bloqueia o `preflight` mesmo com os campos certos.
535
553
  6. **Oriente a commitar e pushar** antes de seguir (o Action lê do repo). Sugira ao usuário rodar, via prefixo `!`:
536
554
  ```bash
537
555
  !git add .github/config/tech_context.yml && git commit -m "chore: tech_context.yml [spec-wave]" && git push
@@ -98,4 +98,5 @@ jobs:
98
98
  env:
99
99
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
100
100
  PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
101
+ SPEC_WAVE_PROJECT_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || 'GH_PROJECT_TOKEN' }}
101
102
  GITHUB_REPOSITORY: ${{ github.repository }}
@@ -58,3 +58,14 @@ jobs:
58
58
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
59
59
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
60
60
  GITHUB_REPOSITORY: ${{ github.repository }}
61
+
62
+ # A falha chega à issue: causa classificada (auth, max_turns, provider…),
63
+ # qual secret trocar e o próximo passo. Quando o próprio comando já
64
+ # comentou, o registro em $RUNNER_TEMP diz isso e nada se repete. Também
65
+ # remove a label de gatilho — com ela aplicada, reaplicá-la não dispara.
66
+ - name: Reporta a falha na issue
67
+ if: failure()
68
+ run: spec-wave report-failure --issue ${{ github.event.issue.number }} --label "${{ github.event.label.name }}" --step critique
69
+ env:
70
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
71
+ GITHUB_REPOSITORY: ${{ github.repository }}
@@ -96,6 +96,19 @@ jobs:
96
96
  app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
97
97
  private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
98
98
 
99
+ # Testa as credenciais DE VERDADE antes de qualquer trabalho: lê a issue
100
+ # com o token deste passo e o Project com o PROJECT_TOKEN. O doctor só vê
101
+ # o NOME dos secrets; um PAT expirado só aparecia como 401 no meio do run,
102
+ # sem dizer qual. Falhou aqui → o passo report-failure diz qual trocar.
103
+ - name: Verifica as credenciais
104
+ run: spec-wave auth check --issue ${{ github.event.issue.number }}
105
+ env:
106
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
107
+ SPEC_WAVE_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || secrets.GH_PROJECT_TOKEN && 'GH_PROJECT_TOKEN' || 'GITHUB_TOKEN' }}
108
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
109
+ SPEC_WAVE_PROJECT_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || 'GH_PROJECT_TOKEN' }}
110
+ GITHUB_REPOSITORY: ${{ github.repository }}
111
+
99
112
  # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
100
113
  # de código que a issue declara (labels repo:<slug>; a Feature agrega as
101
114
  # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Só no
@@ -107,6 +120,7 @@ jobs:
107
120
  run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
108
121
  env:
109
122
  GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
123
+ SPEC_WAVE_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || secrets.GH_PROJECT_TOKEN && 'GH_PROJECT_TOKEN' || 'GITHUB_TOKEN' }}
110
124
  GITHUB_REPOSITORY: ${{ github.repository }}
111
125
 
112
126
  - name: Decompose into Stories and Tasks
@@ -117,8 +131,21 @@ jobs:
117
131
  env:
118
132
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
119
133
  GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
134
+ SPEC_WAVE_PR_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || 'GH_PR_TOKEN' }}
120
135
  PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
136
+ SPEC_WAVE_PROJECT_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || 'GH_PROJECT_TOKEN' }}
121
137
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
122
138
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
123
139
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
124
140
  GITHUB_REPOSITORY: ${{ github.repository }}
141
+
142
+ # A falha chega à issue: causa classificada (auth, max_turns, provider…),
143
+ # qual secret trocar e o próximo passo. Quando o próprio comando já
144
+ # comentou, o registro em $RUNNER_TEMP diz isso e nada se repete. Também
145
+ # remove a label de gatilho — com ela aplicada, reaplicá-la não dispara.
146
+ - name: Reporta a falha na issue
147
+ if: failure()
148
+ run: spec-wave report-failure --issue ${{ github.event.issue.number }} --label "${{ github.event.label.name }}" --step decompose
149
+ env:
150
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
151
+ GITHUB_REPOSITORY: ${{ github.repository }}
@@ -80,6 +80,19 @@ jobs:
80
80
  app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
81
81
  private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
82
82
 
83
+ # Testa as credenciais DE VERDADE antes de qualquer trabalho: lê a issue
84
+ # com o token deste passo e o Project com o PROJECT_TOKEN. O doctor só vê
85
+ # o NOME dos secrets; um PAT expirado só aparecia como 401 no meio do run,
86
+ # sem dizer qual. Falhou aqui → o passo report-failure diz qual trocar.
87
+ - name: Verifica as credenciais
88
+ run: spec-wave auth check --issue ${{ github.event.issue.number }}
89
+ env:
90
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
91
+ SPEC_WAVE_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || secrets.GH_PROJECT_TOKEN && 'GH_PROJECT_TOKEN' || 'GITHUB_TOKEN' }}
92
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
93
+ SPEC_WAVE_PROJECT_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || 'GH_PROJECT_TOKEN' }}
94
+ GITHUB_REPOSITORY: ${{ github.repository }}
95
+
83
96
  # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
84
97
  # de código que a issue declara (labels repo:<slug>), para o modelo ler
85
98
  # CÓDIGO e não só o markdown do hub. Sem repo declarado só avisa. O
@@ -89,6 +102,7 @@ jobs:
89
102
  run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
90
103
  env:
91
104
  GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
105
+ SPEC_WAVE_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || secrets.GH_PROJECT_TOKEN && 'GH_PROJECT_TOKEN' || 'GITHUB_TOKEN' }}
92
106
  GITHUB_REPOSITORY: ${{ github.repository }}
93
107
 
94
108
  - name: Generate bug.md
@@ -96,7 +110,19 @@ jobs:
96
110
  env:
97
111
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
98
112
  GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
113
+ SPEC_WAVE_PR_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || 'GH_PR_TOKEN' }}
99
114
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
100
115
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
101
116
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
102
117
  GITHUB_REPOSITORY: ${{ github.repository }}
118
+
119
+ # A falha chega à issue: causa classificada (auth, max_turns, provider…),
120
+ # qual secret trocar e o próximo passo. Quando o próprio comando já
121
+ # comentou, o registro em $RUNNER_TEMP diz isso e nada se repete. Também
122
+ # remove a label de gatilho — com ela aplicada, reaplicá-la não dispara.
123
+ - name: Reporta a falha na issue
124
+ if: failure()
125
+ run: spec-wave report-failure --issue ${{ github.event.issue.number }} --label "${{ github.event.label.name }}" --step generate-bug
126
+ env:
127
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
128
+ GITHUB_REPOSITORY: ${{ github.repository }}
@@ -90,6 +90,19 @@ jobs:
90
90
  app-id: ${{ secrets.SPEC_WAVE_APP_ID }}
91
91
  private-key: ${{ secrets.SPEC_WAVE_APP_PRIVATE_KEY }}
92
92
 
93
+ # Testa as credenciais DE VERDADE antes de qualquer trabalho: lê a issue
94
+ # com o token deste passo e o Project com o PROJECT_TOKEN. O doctor só vê
95
+ # o NOME dos secrets; um PAT expirado só aparecia como 401 no meio do run,
96
+ # sem dizer qual. Falhou aqui → o passo report-failure diz qual trocar.
97
+ - name: Verifica as credenciais
98
+ run: spec-wave auth check --issue ${{ github.event.issue.number }}
99
+ env:
100
+ GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
101
+ SPEC_WAVE_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || secrets.GH_PROJECT_TOKEN && 'GH_PROJECT_TOKEN' || 'GITHUB_TOKEN' }}
102
+ PROJECT_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN }}
103
+ SPEC_WAVE_PROJECT_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || 'GH_PROJECT_TOKEN' }}
104
+ GITHUB_REPOSITORY: ${{ github.repository }}
105
+
93
106
  # Multi-repo (RFC-005 §7.2): clona em .spec-wave/repos/<slug>/ os repos
94
107
  # de código que a issue declara (labels repo:<slug>; a Feature agrega as
95
108
  # Stories), para o modelo ler CÓDIGO e não só o markdown do hub. Sem repo
@@ -99,6 +112,7 @@ jobs:
99
112
  run: spec-wave workspace prepare --issue ${{ github.event.issue.number }}
100
113
  env:
101
114
  GITHUB_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
115
+ SPEC_WAVE_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || secrets.GH_PROJECT_TOKEN && 'GH_PROJECT_TOKEN' || 'GITHUB_TOKEN' }}
102
116
  GITHUB_REPOSITORY: ${{ github.repository }}
103
117
 
104
118
  - name: Generate plan.md
@@ -106,7 +120,19 @@ jobs:
106
120
  env:
107
121
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
108
122
  GH_PR_TOKEN: ${{ steps.app.outputs.token || secrets.GH_PR_TOKEN }}
123
+ SPEC_WAVE_PR_TOKEN_SOURCE: ${{ steps.app.outputs.token && 'GitHub App (SPEC_WAVE_APP_*)' || 'GH_PR_TOKEN' }}
109
124
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
110
125
  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
111
126
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
112
127
  GITHUB_REPOSITORY: ${{ github.repository }}
128
+
129
+ # A falha chega à issue: causa classificada (auth, max_turns, provider…),
130
+ # qual secret trocar e o próximo passo. Quando o próprio comando já
131
+ # comentou, o registro em $RUNNER_TEMP diz isso e nada se repete. Também
132
+ # remove a label de gatilho — com ela aplicada, reaplicá-la não dispara.
133
+ - name: Reporta a falha na issue
134
+ if: failure()
135
+ run: spec-wave report-failure --issue ${{ github.event.issue.number }} --label "${{ github.event.label.name }}" --step generate-plan
136
+ env:
137
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
138
+ GITHUB_REPOSITORY: ${{ github.repository }}