@spec-wave/cli 1.7.6 → 1.9.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 (56) 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 +103 -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/implement.mjs +21 -0
  16. package/src/commands/init.mjs +2 -2
  17. package/src/commands/preflight.mjs +38 -2
  18. package/src/commands/progress.mjs +144 -0
  19. package/src/commands/relink.mjs +105 -0
  20. package/src/commands/report-failure.mjs +99 -0
  21. package/src/commands/retry.mjs +91 -0
  22. package/src/commands/task.mjs +5 -0
  23. package/src/commands/update.mjs +70 -0
  24. package/src/config.mjs +8 -8
  25. package/src/lib/cited-paths.mjs +89 -0
  26. package/src/lib/claude.mjs +4 -2
  27. package/src/lib/cli-line.mjs +153 -0
  28. package/src/lib/cli-ref.mjs +53 -2
  29. package/src/lib/failure-report.mjs +319 -0
  30. package/src/lib/progress-events.mjs +46 -0
  31. package/src/lib/repo-identity.mjs +55 -0
  32. package/src/lib/spec-index.mjs +114 -0
  33. package/src/lib/tech-context.mjs +144 -5
  34. package/src/plugin/.claude-plugin/plugin.json +1 -1
  35. package/src/plugin/skills/plan/SKILL.md +1 -1
  36. package/src/plugin/skills/plan/reference/tech-context.md +12 -4
  37. package/src/plugin/skills/setup/SKILL.md +1 -1
  38. package/src/plugin/skills/spec/model-prompt.md +8 -1
  39. package/src/plugins/scm-github/index.mjs +8 -1
  40. package/src/plugins/tracker-github-projects/index.mjs +11 -4
  41. package/src/ports/tracker.mjs +2 -1
  42. package/src/setup/labels.mjs +5 -3
  43. package/src/setup/project.mjs +5 -3
  44. package/src/templates/config/tech_context.yml +29 -25
  45. package/src/templates/skill/SKILL.md +27 -9
  46. package/src/templates/skill/core.md +25 -7
  47. package/src/templates/workflows/code-review.yml +1 -0
  48. package/src/templates/workflows/critique.yml +11 -0
  49. package/src/templates/workflows/decompose.yml +27 -0
  50. package/src/templates/workflows/generate-bug.yml +26 -0
  51. package/src/templates/workflows/generate-plan.yml +26 -0
  52. package/src/templates/workflows/generate-qa-plan.yml +27 -0
  53. package/src/templates/workflows/generate-spec.yml +26 -0
  54. package/src/templates/workflows/pr-events.yml +5 -0
  55. package/src/templates/workflows/qa.yml +1 -0
  56. package/src/templates/workflows/validate.yml +11 -0
@@ -0,0 +1,114 @@
1
+ // Índice das specs vizinhas, entregue PRONTO ao modelo do `generate-spec`.
2
+ //
3
+ // Existe por causa de um padrão medido: num hub com ~24 specs em
4
+ // `docs/features/`, três Features falharam 12 vezes com `error_max_turns`
5
+ // (Read×27–29, Glob×5–12, nenhuma escrita). O prompt mandava "procurar specs
6
+ // vizinhas" e o modelo tentava ler TODAS antes de escrever a primeira linha.
7
+ // O que ele procurava em cada uma era quase sempre o mesmo: do que aquela
8
+ // Feature trata e de quem ela depende. Isso cabe num índice — e o índice custa
9
+ // zero turnos.
10
+ //
11
+ // O índice NÃO substitui a leitura: é o mapa para o modelo escolher as poucas
12
+ // specs que valem um `Read` inteiro.
13
+
14
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
15
+ import path from 'node:path';
16
+
17
+ import { dependencySection } from './spec-audit.mjs';
18
+
19
+ export const SPEC_INDEX_DIR = 'docs/features';
20
+
21
+ // Tetos: o índice é para caber no prompt sem competir com a issue.
22
+ const MAX_ENTRIES = 80;
23
+ const MAX_OBJETIVO = 240;
24
+ const MAX_DEPS = 600;
25
+
26
+ /**
27
+ * Objetivo declarado na Visão Geral (função PURA): a linha do bullet
28
+ * "Objetivo", ou o primeiro parágrafo da seção quando o bullet não existe.
29
+ *
30
+ * @param {string} markdown
31
+ * @returns {string}
32
+ */
33
+ export function specObjective(markdown = '') {
34
+ const linhas = String(markdown).split('\n');
35
+ const bullet = linhas.find(l => /^\s*[-*]\s*\**objetivo\**\s*:?/i.test(l));
36
+ if (bullet) return compactar(bullet.replace(/^\s*[-*]\s*\**objetivo\**\s*:?\**\s*/i, ''), MAX_OBJETIVO);
37
+ const inicio = linhas.findIndex(l => /^#\s+vis[aã]o geral/i.test(l.trim()));
38
+ if (inicio === -1) return '';
39
+ const corpo = [];
40
+ for (const l of linhas.slice(inicio + 1)) {
41
+ if (/^#{1,6}\s/.test(l)) break;
42
+ if (!l.trim()) { if (corpo.length) break; continue; }
43
+ corpo.push(l.trim());
44
+ }
45
+ return compactar(corpo.join(' '), MAX_OBJETIVO);
46
+ }
47
+
48
+ function compactar(texto, max) {
49
+ const limpo = String(texto).replace(/\s+/g, ' ').trim();
50
+ return limpo.length > max ? `${limpo.slice(0, max - 1)}…` : limpo;
51
+ }
52
+
53
+ /**
54
+ * Entradas do índice a partir do disco. Nunca lança: diretório ausente ou
55
+ * arquivo ilegível somem do índice (o modelo ainda tem `Glob` para achar).
56
+ *
57
+ * @param {string} root raiz do hub
58
+ * @param {{excludeSlug?: string}} [opts] a própria Feature fica de fora
59
+ * @returns {Array<{path: string, objetivo: string, dependencias: string}>}
60
+ */
61
+ export function collectSpecIndex(root, { excludeSlug = null } = {}) {
62
+ const base = path.join(root || process.cwd(), SPEC_INDEX_DIR);
63
+ if (!existsSync(base)) return [];
64
+ let slugs;
65
+ try {
66
+ slugs = readdirSync(base).filter(s => s !== excludeSlug).sort();
67
+ } catch {
68
+ return [];
69
+ }
70
+ const entradas = [];
71
+ for (const slug of slugs) {
72
+ const abs = path.join(base, slug, 'spec.md');
73
+ try {
74
+ if (!statSync(abs).isFile()) continue;
75
+ const md = readFileSync(abs, 'utf-8');
76
+ const deps = dependencySection(md);
77
+ entradas.push({
78
+ path: `${SPEC_INDEX_DIR}/${slug}/spec.md`,
79
+ objetivo: specObjective(md),
80
+ dependencias: deps == null ? '' : compactar(deps.replace(/^#{1,6}\s+/gm, ''), MAX_DEPS),
81
+ });
82
+ } catch {
83
+ // spec.md ausente ou ilegível nesta Feature — segue sem ela
84
+ }
85
+ }
86
+ return entradas;
87
+ }
88
+
89
+ /**
90
+ * Seção markdown do índice para o prompt (função PURA). Vazio quando não há
91
+ * spec vizinha — aí a seção nem aparece.
92
+ *
93
+ * @param {Array<{path: string, objetivo: string, dependencias: string}>} entradas
94
+ * @returns {string}
95
+ */
96
+ export function renderSpecIndex(entradas = []) {
97
+ if (!entradas.length) return '';
98
+ const mostradas = entradas.slice(0, MAX_ENTRIES);
99
+ const linhas = [
100
+ '## Índice das specs existentes',
101
+ '',
102
+ `${entradas.length} spec(s) em \`${SPEC_INDEX_DIR}/\`. Use este índice para decidir quais ` +
103
+ 'poucas valem um `Read` — não abra todas.',
104
+ '',
105
+ ];
106
+ for (const e of mostradas) {
107
+ linhas.push(`- \`${e.path}\` — ${e.objetivo || '(sem objetivo declarado)'}`);
108
+ if (e.dependencias) linhas.push(` - Dependências: ${e.dependencias}`);
109
+ }
110
+ if (entradas.length > mostradas.length) {
111
+ linhas.push('', `(+${entradas.length - mostradas.length} spec(s) fora do índice — use \`Grep\` para achá-las.)`);
112
+ }
113
+ return linhas.join('\n');
114
+ }
@@ -21,6 +21,135 @@ const MIGRATION_DIRS = [
21
21
 
22
22
  const MAX_MIGRATIONS = 10;
23
23
 
24
+ // Marcador do scaffold. O `init` grava o template com ele na primeira linha, e
25
+ // enquanto ele existir o arquivo é um FORMULÁRIO, não a descrição do sistema.
26
+ export const TECH_CONTEXT_TEMPLATE_MARKER = 'spec-wave:template';
27
+
28
+ // O marcador só vale ONDE o scaffold o grava: como comentário que abre o
29
+ // arquivo. Casar a string em qualquer lugar bloqueava um arquivo preenchido que
30
+ // apenas a citasse ("# removi o spec-wave:template em 03/11").
31
+ const MARKER_LINE = new RegExp(`^#\\s*${TECH_CONTEXT_TEMPLATE_MARKER}(?![\\w-])`);
32
+
33
+ function hasTemplateMarker(raw) {
34
+ const primeira = String(raw).replace(/^/, '').split(/\r?\n/)
35
+ .find((l) => l.trim() !== '' && l.trim() !== '---');
36
+ return primeira !== undefined && MARKER_LINE.test(primeira.trim());
37
+ }
38
+
39
+ // Algum valor de verdade no YAML? String em branco, lista vazia e null não
40
+ // contam. `system_info.name` também não: o nome do sistema sozinho não descreve
41
+ // stack nenhum, e é o primeiro (às vezes o único) campo que alguém preenche.
42
+ function hasContent(value, caminho = '') {
43
+ if (value == null) return false;
44
+ if (typeof value === 'string') return value.trim() !== '';
45
+ if (Array.isArray(value)) return value.some((v) => hasContent(v, `${caminho}[]`));
46
+ if (typeof value === 'object') {
47
+ return Object.entries(value).some(([k, v]) => {
48
+ const filho = caminho ? `${caminho}.${k}` : k;
49
+ return filho !== 'system_info.name' && hasContent(v, filho);
50
+ });
51
+ }
52
+ return true; // número, booleano, data
53
+ }
54
+
55
+ /**
56
+ * Por que o tech_context não conta como preenchido — ou `null` se conta.
57
+ * (função PURA)
58
+ *
59
+ * Três formas de não estar preenchido, e as três aconteceram ou são um passo
60
+ * óbvio de quem segue a instrução do próprio scaffold:
61
+ * • `marker` — a linha `# spec-wave:template` ainda abre o arquivo;
62
+ * • `legacy-example` — o EXEMPLO dos scaffolds anteriores, "Order Management
63
+ * System" em NestJS, PostgreSQL e Redis. Ele era sintaticamente perfeito, e
64
+ * foi lido como verdade: num cliente cujo stack é Kotlin Multiplatform +
65
+ * Amplify, as specs e os planos saíram falando de Postgres, Redis e
66
+ * microsserviços, porque ninguém editou o arquivo e nada avisou;
67
+ * • `empty` — nenhum campo além do nome tem valor. É o que sobra quando só a
68
+ * linha do marcador é apagada: sem este critério, `backend: ""` e
69
+ * `rbac_roles: []` entravam no prompt como contexto com autoridade.
70
+ *
71
+ * Um arquivo PREENCHIDO pelo time que por acaso mantenha um valor do exemplo
72
+ * não é template: o critério do exemplo é o par nome + backend, que só
73
+ * coincide se ninguém tocou na seção.
74
+ *
75
+ * @param {string|null} raw texto do arquivo
76
+ * @param {object|null} [parsed] o YAML já parseado (evita parsear duas vezes)
77
+ * @returns {'marker'|'legacy-example'|'empty'|null}
78
+ */
79
+ export function techContextTemplateReason(raw, parsed = undefined) {
80
+ if (raw == null) return null;
81
+ if (hasTemplateMarker(raw)) return 'marker';
82
+ let ctx = parsed;
83
+ if (ctx === undefined) {
84
+ try { ctx = yaml.load(String(raw)); } catch { return null; }
85
+ }
86
+ const info = ctx?.system_info;
87
+ if (info?.name === 'Order Management System' &&
88
+ info?.stack?.backend === 'Node.js (NestJS v10)') return 'legacy-example';
89
+ return hasContent(ctx) ? null : 'empty';
90
+ }
91
+
92
+ /** O tech_context ainda é o template do scaffold? Ver `techContextTemplateReason`. */
93
+ export function isTechContextTemplate(raw, parsed = undefined) {
94
+ return techContextTemplateReason(raw, parsed) !== null;
95
+ }
96
+
97
+ // Uma leitura, um parse: estado + conteúdo. `inspectTechContext` devolve só o
98
+ // estado; `readStaticContext` aproveita o `context` em vez de reler o arquivo.
99
+ function readTechContext(cwd) {
100
+ const base = { path: TECH_CONTEXT_PATH, reason: null, error: null, context: null };
101
+ const filePath = path.join(cwd, TECH_CONTEXT_PATH);
102
+ if (!existsSync(filePath)) return { ...base, state: 'missing' };
103
+ let raw;
104
+ let parsed;
105
+ try {
106
+ raw = readFileSync(filePath, 'utf-8');
107
+ parsed = yaml.load(raw);
108
+ } catch (err) {
109
+ return { ...base, state: 'invalid', error: err.message };
110
+ }
111
+ const reason = techContextTemplateReason(raw, parsed);
112
+ if (reason) return { ...base, state: 'template', reason };
113
+ return { ...base, state: 'filled', context: parsed };
114
+ }
115
+
116
+ /**
117
+ * Estado do tech_context no disco: `missing` | `invalid` | `template` | `filled`.
118
+ * `reason` só vem em `template` (ver `techContextTemplateReason`). Nunca lança.
119
+ *
120
+ * @param {string} [cwd]
121
+ * @returns {{state: 'missing'|'invalid'|'template'|'filled', path: string,
122
+ * reason: 'marker'|'legacy-example'|'empty'|null, error: string|null}}
123
+ */
124
+ export function inspectTechContext(cwd = process.cwd()) {
125
+ const { state, path: p, reason, error } = readTechContext(cwd);
126
+ return { state, path: p, reason, error };
127
+ }
128
+
129
+ /**
130
+ * Texto de orientação quando o arquivo não está preenchido (uma fonte só).
131
+ * O que fazer depende do motivo: mandar apagar a linha do marcador num arquivo
132
+ * antigo, que nunca a teve, deixa o usuário procurando o que não existe.
133
+ *
134
+ * @param {'marker'|'legacy-example'|'empty'|null} [reason]
135
+ */
136
+ export function techContextTemplateHint(reason = 'marker') {
137
+ const stack = 'o stack REAL do sistema (backend, frontend, banco, infra, autenticação)';
138
+ const fim = ' Enquanto isso, spec e plan são gerados SEM contexto técnico estático — ' +
139
+ 'o conteúdo do template nunca é injetado.';
140
+ if (reason === 'legacy-example') {
141
+ return `${TECH_CONTEXT_PATH} ainda traz o EXEMPLO dos scaffolds antigos ` +
142
+ `("Order Management System" em NestJS) (não preenchido): substitua-o por ${stack}.` + fim;
143
+ }
144
+ if (reason === 'empty') {
145
+ return `${TECH_CONTEXT_PATH} está com os campos em branco (não preenchido): ` +
146
+ `descreva ${stack} — só o nome do sistema não basta.` + fim;
147
+ }
148
+ return `${TECH_CONTEXT_PATH} ainda é o template do scaffold (não preenchido): ` +
149
+ `descreva ${stack} e apague a linha \`# ${TECH_CONTEXT_TEMPLATE_MARKER}\` ` +
150
+ 'que abre o arquivo.' + fim;
151
+ }
152
+
24
153
  // Leitura SILENCIOSA da fonte estática — para quem só consulta (o `audit` lê
25
154
  // as decisões de modelagem e ausência não é problema dele). `context: null`
26
155
  // distingue "não existe" de "existe vazio"; `error` só em falha de parse.
@@ -35,15 +164,21 @@ export function loadStaticTechContext(cwd = process.cwd()) {
35
164
  }
36
165
 
37
166
  // §4.1 — Fonte de verdade estática. Ausência não é erro: segue com {} e avisa.
167
+ // Template não preenchido também vira {} — injetar o exemplo é pior que nada.
168
+ // Devolve também o motivo, para quem monta o aviso na issue.
38
169
  function readStaticContext(cwd) {
39
- const { context, error } = loadStaticTechContext(cwd);
40
- if (context) return context;
41
- console.warn(error
170
+ const { state, reason, error, context } = readTechContext(cwd);
171
+ if (state === 'filled') return { context, reason: null };
172
+ if (state === 'template') {
173
+ console.warn(`⚠️ ${techContextTemplateHint(reason)}`);
174
+ return { context: {}, reason };
175
+ }
176
+ console.warn(state === 'invalid'
42
177
  ? `⚠️ Falha ao parsear ${TECH_CONTEXT_PATH}: ${error}. Ignorando.`
43
178
  : `⚠️ ${TECH_CONTEXT_PATH} não encontrado. ` +
44
179
  `O plano será gerado sem contexto técnico estático. ` +
45
180
  `Rode \`spec-wave init\` para gerar o scaffold.`);
46
- return {};
181
+ return { context: {}, reason: null };
47
182
  }
48
183
 
49
184
  // §4.2 — Augmentação dinâmica: migrations recentes + versões exatas de pacotes.
@@ -132,7 +267,7 @@ function isPlainObject(v) {
132
267
 
133
268
  // Monta o tech context completo. `cwd` default = process.cwd() (checkout do Action).
134
269
  export function buildTechContext({ issueBody = '', cwd = process.cwd() } = {}) {
135
- const staticContext = readStaticContext(cwd);
270
+ const { context: staticContext, reason: unfilledReason } = readStaticContext(cwd);
136
271
  const dynamic = readDynamicContext(cwd);
137
272
  const overrides = parseTechOverride(issueBody);
138
273
  const merged = deepMerge(staticContext, overrides);
@@ -142,6 +277,10 @@ export function buildTechContext({ issueBody = '', cwd = process.cwd() } = {}) {
142
277
  dynamic,
143
278
  overrides,
144
279
  merged,
280
+ // O arquivo existe mas é o template: quem gera o documento avisa na issue.
281
+ // `unfilledReason` diz por quê (marcador, exemplo antigo ou campos em branco).
282
+ unfilled: unfilledReason !== null,
283
+ unfilledReason,
145
284
  // String pronta para injetar no prompt: contexto efetivo + efêmeros.
146
285
  yaml: yaml.dump({ ...merged, _dynamic: dynamic }, { lineWidth: 120 }),
147
286
  };
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.7.6",
4
+ "version": "1.9.0",
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",
@@ -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
  #