@spec-wave/cli 0.34.1 → 0.35.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.
@@ -14,6 +14,116 @@ export const QA_REPORT_VERSION = 1;
14
14
  /** Vereditos aceitos por cenário. */
15
15
  export const QA_VERDICTS = ['pass', 'fail', 'blocked'];
16
16
 
17
+ // ── Evidência visual (vídeo/foto) — CONTRATO com a UI do SpecWave ──────────
18
+ //
19
+ // A UI lê `docs/features/<slug>/qa/cenario-<n>/` (ou `docs/bugs/<slug>/qa/`)
20
+ // direto da branch default e serve cada arquivo por uma Lambda síncrona: o
21
+ // nome precisa casar o padrão abaixo (o server responde 400 fora dele), só as
22
+ // extensões listadas aparecem na tela, e acima do teto ela mostra "sem prévia".
23
+ // Por isso a validação é ESTRITA aqui: publicar um arquivo que a UI recusa é
24
+ // gastar espaço no repositório sem ganhar nada.
25
+
26
+ /** Extensões de mídia que a UI serve. */
27
+ export const QA_EVIDENCE_IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp'];
28
+ export const QA_EVIDENCE_VIDEO_EXTENSIONS = ['mp4', 'webm', 'mov'];
29
+ export const QA_EVIDENCE_EXTENSIONS = [...QA_EVIDENCE_VIDEO_EXTENSIONS, ...QA_EVIDENCE_IMAGE_EXTENSIONS];
30
+
31
+ /** Teto DURO por arquivo (Lambda síncrona de 6 MB, corpo em base64 +33%). */
32
+ export const QA_EVIDENCE_MAX_BYTES = 4 * 1024 * 1024;
33
+
34
+ /** Nome de arquivo aceito pela UI: sem espaço, sem barra, sem dotfile. */
35
+ export const QA_EVIDENCE_NAME_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
36
+
37
+ /** Subpasta de um cenário dentro do diretório de evidência. */
38
+ export function evidenceScenarioDir(numero) {
39
+ return `cenario-${numero}`;
40
+ }
41
+
42
+ /**
43
+ * Tipo de mídia pela extensão (função PURA).
44
+ *
45
+ * @param {string} file nome ou caminho do arquivo
46
+ * @returns {'image'|'video'|null} null = extensão fora do contrato
47
+ */
48
+ export function evidenceMediaKind(file) {
49
+ const ext = String(file || '').toLowerCase().split('.').pop();
50
+ if (QA_EVIDENCE_IMAGE_EXTENSIONS.includes(ext)) return 'image';
51
+ if (QA_EVIDENCE_VIDEO_EXTENSIONS.includes(ext)) return 'video';
52
+ return null;
53
+ }
54
+
55
+ /**
56
+ * URL pública de um arquivo de evidência publicado (função PURA).
57
+ *
58
+ * Imagem → raw.githubusercontent.com (o GitHub a EMBUTE no comentário);
59
+ * vídeo → página blob do GitHub (o raw de um .webm só baixa; a página blob
60
+ * toca inline). O `sha` é o commit que PUBLICOU a evidência, não o HEAD
61
+ * testado — a re-execução sobrescreve o mesmo caminho, e um link por branch
62
+ * passaria a apontar para a corrida seguinte.
63
+ *
64
+ * @param {string} owner
65
+ * @param {string} repo
66
+ * @param {string} sha commit (curto ou longo) ou branch
67
+ * @param {string} pathRel caminho relativo à raiz do repositório
68
+ * @returns {string}
69
+ */
70
+ export function evidenceMediaUrl(owner, repo, sha, pathRel) {
71
+ const encoded = String(pathRel || '').split('/').map(encodeURIComponent).join('/');
72
+ const base = evidenceMediaKind(pathRel) === 'image'
73
+ ? `https://raw.githubusercontent.com/${owner}/${repo}/${sha}/`
74
+ : `https://github.com/${owner}/${repo}/blob/${sha}/`;
75
+ return base + encoded;
76
+ }
77
+
78
+ /**
79
+ * Normaliza e valida os nomes de evidência declarados por um cenário (PURA).
80
+ *
81
+ * Aceita o nome puro (`video.webm`) ou prefixado pela própria subpasta
82
+ * (`cenario-2/video.webm`) — é o erro mais provável de um executor que copiou
83
+ * o caminho inteiro — e rejeita todo o resto: qualquer barra remanescente,
84
+ * `..`, nome fora do padrão da UI ou extensão que a UI não serve.
85
+ *
86
+ * @param {*} value `evidenceFiles` do resultado
87
+ * @param {number} numero número posicional do cenário
88
+ * @param {string} at prefixo das mensagens de erro (ex.: "scenarios[0]")
89
+ * @returns {string[]} nomes de arquivo (sem diretório), sem duplicatas
90
+ */
91
+ export function normalizeEvidenceFiles(value, numero, at = 'evidenceFiles') {
92
+ if (value == null) return [];
93
+ if (!Array.isArray(value)) {
94
+ throw new Error(`${at}.evidenceFiles deveria ser uma lista de nomes de arquivo, veio ${JSON.stringify(value)}.`);
95
+ }
96
+ const prefix = `${evidenceScenarioDir(numero)}/`;
97
+ const out = [];
98
+ value.forEach((item, i) => {
99
+ if (typeof item !== 'string') {
100
+ throw new Error(`${at}.evidenceFiles[${i}] deveria ser string, veio ${JSON.stringify(item)}.`);
101
+ }
102
+ let name = item.trim().replace(/^\.\//, '');
103
+ if (name.startsWith(prefix)) name = name.slice(prefix.length);
104
+ if (name.includes('/') || name.includes('\\') || name.includes('..')) {
105
+ throw new Error(
106
+ `${at}.evidenceFiles[${i}] = ${JSON.stringify(item)}: informe só o NOME do arquivo dentro de ` +
107
+ `${prefix} (sem subpasta, sem \`..\`).`
108
+ );
109
+ }
110
+ if (!QA_EVIDENCE_NAME_RE.test(name)) {
111
+ throw new Error(
112
+ `${at}.evidenceFiles[${i}] = ${JSON.stringify(item)}: nome fora do padrão ` +
113
+ '(letras, dígitos, ponto, hífen e sublinhado; sem espaço, sem começar com ponto).'
114
+ );
115
+ }
116
+ if (!evidenceMediaKind(name)) {
117
+ throw new Error(
118
+ `${at}.evidenceFiles[${i}] = ${JSON.stringify(item)}: extensão fora do contrato ` +
119
+ `(aceitas: ${QA_EVIDENCE_EXTENSIONS.join(', ')}).`
120
+ );
121
+ }
122
+ if (!out.includes(name)) out.push(name);
123
+ });
124
+ return out;
125
+ }
126
+
17
127
  export const QA_REPORT_MARKER_RE =
18
128
  /<!--\s*spec-wave:qa-report\s+v(?<version>\d+)\s+issue=(?<issue>\d+)\s+run=(?<run>\d+)\s+verdict=(?<verdict>pass|fail|blocked)\s+planSha=(?<planSha>[0-9a-f]+)\s+headSha=(?<headSha>[0-9a-f?]+)\s*-->/g;
19
129
 
@@ -84,11 +194,15 @@ export function aggregateVerdict(results = []) {
84
194
  * motivo do relatório de trilha depende dele;
85
195
  * • `fail` exige `evidencia` não vazia — sem evidência não há bug.md
86
196
  * determinístico;
87
- * • `blockedReason: outro` exige `evidencia` não vazia (é o texto livre).
197
+ * • `blockedReason: outro` exige `evidencia` não vazia (é o texto livre);
198
+ * • `evidenceFiles` (opcional) só é validado na FORMA — nomes de arquivo que
199
+ * a UI aceita (normalizeEvidenceFiles). Se existem em disco é o comando que
200
+ * confere, ao publicar: evidência visual é ENRIQUECIMENTO, nunca o canal do
201
+ * veredito, então arquivo ausente vira aviso, não erro.
88
202
  *
89
203
  * @param {*} payload objeto lido do arquivo de resultados
90
204
  * @param {number[]} expected números dos cenários que DEVIAM ter sido executados
91
- * @returns {Array<{numero:number, verdict:'pass'|'fail'|'blocked', evidencia:string, blockedReason:string|null}>}
205
+ * @returns {Array<{numero:number, verdict:'pass'|'fail'|'blocked', evidencia:string, blockedReason:string|null, evidenceFiles:string[]}>}
92
206
  */
93
207
  export function validateQaResults(payload, expected = []) {
94
208
  if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.scenarios)) {
@@ -132,6 +246,7 @@ export function validateQaResults(payload, expected = []) {
132
246
  verdict,
133
247
  evidencia,
134
248
  blockedReason: verdict === 'blocked' ? blockedReason : null,
249
+ evidenceFiles: normalizeEvidenceFiles(item?.evidenceFiles, numero, at),
135
250
  });
136
251
  });
137
252
  const missing = expected.filter(n => !out.has(n));
@@ -178,7 +293,9 @@ export function combineWithPrevious({ executed = [], previous = new Map(), allNu
178
293
  if (prev) {
179
294
  combined.push({
180
295
  numero: n, verdict: prev.verdict, evidencia: prev.evidencia || '(corrida anterior)',
181
- blockedReason: prev.blockedReason || null, carried: true,
296
+ blockedReason: prev.blockedReason || null,
297
+ evidenceFiles: Array.isArray(prev.evidenceFiles) ? prev.evidenceFiles : [],
298
+ carried: true,
182
299
  });
183
300
  } else {
184
301
  pendingNumbers.push(n);
@@ -221,6 +338,11 @@ export function parseLastQaReport(comments = []) {
221
338
  verdict: s.verdict,
222
339
  evidencia: s.evidencia || '',
223
340
  blockedReason: s.blockedReason || null,
341
+ // Caminhos JÁ PUBLICADOS (relativos à raiz do repo) — o cenário
342
+ // herdado num `--only` mantém os links da corrida que o gravou.
343
+ evidenceFiles: Array.isArray(s.evidenceFiles)
344
+ ? s.evidenceFiles.filter(f => typeof f === 'string' && f)
345
+ : [],
224
346
  }]));
225
347
  }
226
348
  // Bugs abertos pela corrida — o `qa-lead` compõe o `bugsOpened` do
@@ -246,12 +368,33 @@ function sanitizeCell(text, max = 200) {
246
368
  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
247
369
  }
248
370
 
371
+ // Links da evidência visual de UM cenário, para o markdown (função PURA).
372
+ // Imagem embutida (miniatura clicável); vídeo só como link — o GitHub não toca
373
+ // vídeo por URL em comentário/markdown, a página blob toca.
374
+ function renderEvidenceLinks(files = [], base = null, { inline = true } = {}) {
375
+ return (files || []).map((rel) => {
376
+ const name = String(rel).split('/').pop();
377
+ if (!base?.owner || !base?.repo || !base?.sha) return `\`${rel}\``;
378
+ const url = evidenceMediaUrl(base.owner, base.repo, base.sha, rel);
379
+ if (evidenceMediaKind(rel) === 'image') {
380
+ return inline
381
+ ? `<a href="${url}"><img src="${url}" alt="${name}" width="160"></a>`
382
+ : `[📷 ${name}](${url})`;
383
+ }
384
+ return `[🎬 ${name}](${url})`;
385
+ });
386
+ }
387
+
249
388
  /**
250
389
  * Monta o comentário de relatório de QA (função PURA).
251
390
  *
252
391
  * Primeira linha = marcador (contrato com a UI). O bloco JSON no fim é o que a
253
392
  * próxima execução com `--only` lê para compor o estado acumulado.
254
393
  *
394
+ * A coluna **Mídia** só existe quando algum cenário tem evidência visual —
395
+ * sem ela a tabela é byte a byte a de antes (a UI parseia o bloco JSON, não a
396
+ * tabela, mas leitores humanos e testes antigos não ganham uma coluna vazia).
397
+ *
255
398
  * @param {object} params
256
399
  * @param {number} params.issue issue onde o relatório será postado
257
400
  * @param {string} params.scope ex.: "Story #412" ou "Feature #360"
@@ -259,14 +402,17 @@ function sanitizeCell(text, max = 200) {
259
402
  * @param {'pass'|'fail'|'blocked'} params.verdict veredito agregado
260
403
  * @param {string} params.planSha sha curto do qa-plan.md executado
261
404
  * @param {string} [params.headSha] sha curto do HEAD do checkout
262
- * @param {Array<{numero, verdict, evidencia, carried?}>} params.results
405
+ * @param {Array<{numero, verdict, evidencia, carried?, evidenceFiles?:string[]}>} params.results
406
+ * `evidenceFiles` = caminhos JÁ PUBLICADOS, relativos à raiz do repositório
407
+ * @param {{owner:string, repo:string, sha:string}|null} [params.evidenceBase]
408
+ * de onde servir a mídia — sem ele os caminhos saem como texto
263
409
  * @param {Array<{number:number, cenario:number, existing?:boolean}>} [params.bugs]
264
410
  * @param {number[]} [params.pendingNumbers] cenários sem veredito em corrida parcial
265
411
  * @param {string} [params.trailer] linha final livre (o que acontece a seguir)
266
412
  * @returns {string} markdown
267
413
  */
268
414
  export function renderQaReport({
269
- issue, scope, run, verdict, planSha, headSha, results = [], bugs = [],
415
+ issue, scope, run, verdict, planSha, headSha, results = [], evidenceBase = null, bugs = [],
270
416
  pendingNumbers = [], trailer = '',
271
417
  } = {}) {
272
418
  const parts = [
@@ -275,11 +421,17 @@ export function renderQaReport({
275
421
  `**Escopo:** ${scope} · **Cenários:** ${results.length} · **Execução:** ${run}ª`,
276
422
  ];
277
423
 
278
- const linhas = ['| Cenário | Veredito | Evidência |', '|---|---|---|'];
424
+ const comMidia = results.some(r => Array.isArray(r.evidenceFiles) && r.evidenceFiles.length > 0);
425
+ const linhas = comMidia
426
+ ? ['| Cenário | Veredito | Evidência | Mídia |', '|---|---|---|---|']
427
+ : ['| Cenário | Veredito | Evidência |', '|---|---|---|'];
279
428
  for (const r of results) {
280
429
  const carried = r.carried ? ' _(corrida anterior)_' : '';
281
430
  const reason = r.verdict === 'blocked' && r.blockedReason ? ` (${r.blockedReason})` : '';
282
- linhas.push(`| ${r.numero} | ${VERDICT_ICON[r.verdict] || r.verdict}${reason} | ${sanitizeCell(r.evidencia)}${carried} |`);
431
+ const midia = comMidia
432
+ ? ` ${renderEvidenceLinks(r.evidenceFiles, evidenceBase).join(' ') || '—'} |`
433
+ : '';
434
+ linhas.push(`| ${r.numero} | ${VERDICT_ICON[r.verdict] || r.verdict}${reason} | ${sanitizeCell(r.evidencia)}${carried} |${midia}`);
283
435
  }
284
436
  parts.push(linhas.join('\n'));
285
437
 
@@ -308,6 +460,10 @@ export function renderQaReport({
308
460
  verdict: r.verdict,
309
461
  evidencia: sanitizeCell(r.evidencia, 400),
310
462
  ...(r.verdict === 'blocked' && r.blockedReason ? { blockedReason: r.blockedReason } : {}),
463
+ // Aditivo ao v1: caminhos publicados da evidência visual (só quando há).
464
+ ...(Array.isArray(r.evidenceFiles) && r.evidenceFiles.length > 0
465
+ ? { evidenceFiles: r.evidenceFiles }
466
+ : {}),
311
467
  })),
312
468
  // Aditivo ao v1: o `qa-lead` lê daqui os Bugs da corrida.
313
469
  bugs: bugs.map(b => ({ number: b.number, cenario: b.cenario, existing: !!b.existing })),
@@ -334,13 +490,18 @@ export function renderQaReport({
334
490
  * @param {string} params.title título do Bug (sem o prefixo [BUG])
335
491
  * @param {{anchor, numero, story, criterio, precondicoes, passos, esperado}} params.scenario
336
492
  * @param {string} params.evidence evidência bruta da reprovação
493
+ * @param {string[]} [params.evidenceFiles] evidência visual JÁ PUBLICADA (caminhos
494
+ * relativos à raiz do repositório)
495
+ * @param {{owner:string, repo:string, sha:string}|null} [params.evidenceBase]
496
+ * de onde servir a mídia — sem ele os caminhos saem como texto
337
497
  * @param {string} params.severity P0–P3
338
498
  * @param {string} [params.headSha] commit do checkout onde a reprova aconteceu
339
499
  * @param {number|null} [params.featureNumber]
340
500
  * @returns {string} markdown
341
501
  */
342
502
  export function renderQaBugDoc({
343
- title, scenario, evidence, severity, headSha = null, featureNumber = null,
503
+ title, scenario, evidence, evidenceFiles = [], evidenceBase = null, severity,
504
+ headSha = null, featureNumber = null,
344
505
  } = {}) {
345
506
  const [
346
507
  reproducao, esperadoObtido, impacto, causaRaiz, escopo, regressao,
@@ -367,6 +528,9 @@ export function renderQaBugDoc({
367
528
  `**Esperado:** ${scenario.esperado || '—'}`,
368
529
  '',
369
530
  `**Obtido:** ${evidence || '(sem evidência registrada)'}`,
531
+ ...(evidenceFiles.length > 0
532
+ ? ['', '**Evidência visual:** ' + renderEvidenceLinks(evidenceFiles, evidenceBase, { inline: false }).join(' · ')]
533
+ : []),
370
534
  '',
371
535
  `## ${impacto}`,
372
536
  '',
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "0.34.1",
4
+ "version": "0.35.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",
@@ -87,7 +87,7 @@ npx @spec-wave/cli@latest story review <n> # Etapa 👀 Code Review, Status Tod
87
87
 
88
88
  Se abre PR e onde faz push depende do **modo de entrega** — o contexto montado já diz qual é (não adivinhe pelo tipo de issue):
89
89
 
90
- - **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`) antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha.
90
+ - **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`), com `Closes #<story>` no corpo, antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha. **Deixe todos em rascunho até o fim:** o rascunho é o sinal de "feature ainda em andamento" (o GitHub bloqueia o merge), e quando a última Story concluir o próprio `implement` marca todos os PRs da Feature como prontos de uma vez. **Não tire nenhum do rascunho à mão.**
91
91
  - **`agent`** (rodando sob o `dev-agent`): **NÃO crie branch, NÃO abra PR** — faça só o commit e o push no branch atual. O daemon mantém um único branch (`agent/issue-<n>`) e é ele quem abre o PR ao final, para a Feature inteira. Abrir um PR por Story aqui cria um branch lateral (`agent/issue-<n>-story-<m>`) cujo trabalho não entra no PR do agente.
92
92
 
93
93
  **A Feature só avança** para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. Enquanto houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. No modo Feature isso acontece dentro da mesma execução.
@@ -23,14 +23,15 @@ O `implement` empilha os PRs de propósito (cada Story revisável sozinha, diff
23
23
 
24
24
  - **Sem `--yes` nada é mergeado** — a saída é o plano: a fila na ordem, qual base será reapontada, o que já está mergeado.
25
25
  - O **plano** calcula a ordem pelas fontes locais (dependency-map.json/decomposition.md/corpo — barato); a **execução com `--yes` reconsulta tudo FRESCO da API**, incluindo o blocked_by nativo: merge de pilha é irreversível e não decide com cache.
26
- - **PR em rascunho bloqueia o plano inteiro.** Marcar pronto é a revisão humana (e o que dispara o CI) — revise e marque cada PR como pronto antes. O comando não faz isso por você, de propósito.
26
+ - **PR em rascunho bloqueia o plano inteiro** — e é assim que se sabe que a feature ainda está em desenvolvimento. Quem tira do rascunho é o `implement`, quando a **última** Story da Feature entra em Code Review: aí todos os PRs da Feature ficam prontos de uma vez. Um PR ainda em rascunho aqui significa que a Feature não terminou (ou que o desrascunho falhou e avisou) — o `merge` não marca por você, de propósito.
27
27
  - **Rodar de novo retoma.** PR mergeado sai do plano sozinho; uma falha no meio (check pendente, conflito) para a fila com as branches dos dependentes intactas.
28
+ - **PRs empilhados são achados pelo corpo** quando preciso: o GitHub só registra o vínculo nativo (`closedByPullRequestsReferences`) quando a base do PR é a default — numa pilha, só o PR de baixo. Para Stories sem vínculo nativo, o comando parseia o `Closes #N` do corpo dos PRs abertos (mesma régua do code-review). Garanta que cada PR da pilha tem `Closes #<story>` no corpo.
28
29
  - Story **sem PR** vira aviso, não bloqueio — mas se um PR da fila depende do código dela, o merge leva esse código junto; confira antes de confirmar.
29
30
  - Cada PR da fila é conferido contra o trailer `Spec-Wave-Story: #<n>` (rastro do `implement`, best-effort — nunca bloqueia): PR sem nenhum commit com o trailer certo vira aviso, vale conferir se é mesmo o trabalho daquela Story antes de mergear.
30
31
 
31
32
  ## Passos
32
33
 
33
- 1. Confirme que os PRs da Feature foram revisados e marcados como prontos (`gh pr ready <n>` se preciso).
34
+ 1. Confirme que os PRs da Feature foram revisados e estão fora do rascunho — o `implement` já os marca ao concluir a última Story. Se algum continua em rascunho, confira se a Feature terminou mesmo antes de marcar à mão (`gh pr ready <n>`).
34
35
  2. Rode sem `--yes` e apresente o plano ao usuário — ordem, retargets, avisos.
35
36
  3. Com o ok, rode com `--yes`.
36
37
  4. Confira o desfecho na saída: N PRs mergeados, board em 🧪 QA (o próprio comando confirma as escritas do board; se algum falhar, ele indica o `run --pr` de reparo).
@@ -30,13 +30,18 @@ Confirme que existe `.spec-wave.json` no repositório (senão → skill **setup*
30
30
  "command": "claude -p \"Execute o QA descrito em {contextFile}\"",
31
31
  "setup": "npm ci && npm run build",
32
32
  "env": { "BASE_URL": "http://localhost:3000" },
33
- "defaultBugPriority": "P2"
33
+ "defaultBugPriority": "P2",
34
+ "platform": "web",
35
+ "web": { "evidence": "playwright" },
36
+ "mobile": { "evidence": "maestro", "appId": "com.exemplo.app", "device": "emulator-5554" }
34
37
  }
35
38
  }
36
39
  ```
37
40
 
38
41
  Placeholders: `{contextFile} {qaPlanFile} {specFile} {issue} {type} {title}`. Sem `qa.command`, o comando monta o contexto, imprime como configurar e **não executa** — não é erro.
39
42
 
43
+ **Evidência visual (opcional):** `qa.platform` (`web` padrão | `mobile`) escolhe quem grava vídeo/foto por cenário — Playwright (`qa.web.evidence`) ou Maestro (`qa.mobile.evidence`, com `appId`/`device`); `"none"` desliga. O executor grava em `.spec-wave/qa-evidence-<n>/cenario-<N>/`, e o `qa` publica em `docs/features/<slug>/qa/cenario-<N>/` (Bug: `docs/bugs/<slug>/qa/`) num commit direto na branch, linkado no relatório e no `bug.md`. Teto de **4 MB por arquivo**; ferramenta ausente só omite a mídia — nunca bloqueia o veredito. O `doctor` confere a plataforma e se a ferramenta está no PATH.
44
+
40
45
  ## 1. Gerar o plano (Feature)
41
46
 
42
47
  ```bash
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-wave-qa-executor
3
- description: "Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md."
3
+ description: "Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta (texto e, quando configurado, vídeo/foto via Maestro ou Playwright) e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md."
4
4
  allowed-tools:
5
5
  - Bash
6
6
  - Read
@@ -67,6 +67,48 @@ caminho exato está no contexto:
67
67
  - A CLI **recusa** o arquivo fora do contrato (schema em
68
68
  `protocol/qa-result.v1.json` do pacote `@spec-wave/cli`) — e arquivo ausente é
69
69
  falha alta: nada é aprovado nem reprovado sem ele.
70
+ - `evidenceFiles` é **opcional** — a evidência visual da seção abaixo. Nunca
71
+ substitui `evidencia` (texto), que segue obrigatória nas mesmas regras.
72
+
73
+ ## Evidência visual (vídeo/foto)
74
+
75
+ O contexto traz uma seção **Evidência visual** com a plataforma
76
+ (`qa.platform`: `web` | `mobile`), a ferramenta (`playwright` | `maestro` |
77
+ nenhuma), o `appId`/`device` do mobile, a `BASE_URL` do `qa.env` e o diretório
78
+ de **staging** (`.spec-wave/qa-evidence-<n>/`). Você não precisa reler o
79
+ `.spec-wave.json`.
80
+
81
+ 1. **Grave por cenário, a partir dos Passos/Critério:**
82
+ - `mobile` → sintetize um **flow Maestro mínimo** para o cenário (abrir o
83
+ `appId`, executar os passos, asserir o esperado) e rode-o **com gravação
84
+ de vídeo**; tire ao menos uma captura do estado final.
85
+ - `web` → sintetize um **script Playwright descartável** (arquivo
86
+ temporário, fora do repositório — **nunca commitado**) contra a
87
+ `BASE_URL`, com vídeo e screenshot habilitados.
88
+ - **Confira as flags/API da versão instalada** (`maestro --help`,
89
+ `maestro record --help`, `npx playwright --version` + docs da versão) —
90
+ as duas ferramentas mudam a gravação entre versões; não assuma.
91
+ 2. **Copie os artefatos para `<staging>/cenario-<N>/`** (N = número POSICIONAL
92
+ do cenário), **arquivos planos, sem subpasta**. Nome: letras, dígitos,
93
+ ponto, hífen e sublinhado — sem espaço, sem barra, sem começar com ponto.
94
+ Extensões aceitas: `mp4 webm mov png jpg jpeg gif webp`.
95
+ 3. **Teto DURO: 4 MB por arquivo.** A UI serve cada arquivo por uma Lambda
96
+ síncrona; acima disso ela mostra "sem prévia" e a CLI nem publica. Grave
97
+ clipes **curtos e em baixa resolução** (webm ou mp4 comprimido; screenshot
98
+ em png/webp). Se o vídeo passou do teto, recomprima ou corte antes de copiar.
99
+ 4. **Referencie em `evidenceFiles`** do cenário, só o **nome** do arquivo:
100
+
101
+ ```json
102
+ { "cenario": 2, "verdict": "fail", "evidencia": "500 — TypeError…",
103
+ "evidenceFiles": ["gravacao.webm", "final.png"] }
104
+ ```
105
+
106
+ A CLI copia para `docs/features/<slug>/qa/cenario-<N>/` (ou
107
+ `docs/bugs/<slug>/qa/`), comita na branch e linka no relatório e no bug.md.
108
+ 5. **Ferramenta ausente ou gravação que falhou NÃO é `blocked`.** Execute o
109
+ cenário do mesmo jeito, registre a `evidencia` em texto e **omita**
110
+ `evidenceFiles`. Evidência visual é enriquecimento; o veredito nunca depende
111
+ dela. Com a gravação desligada no contexto (`none`), não grave nada.
70
112
 
71
113
  ## Setup do ambiente
72
114
 
@@ -293,7 +293,7 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
293
293
  | `--yes` | boolean | Executa os merges. **Sem ela, só mostra o plano** (fila na ordem, retargets, avisos). |
294
294
  | `--keep-branches` | boolean | Não apaga as branches das Stories após o merge. |
295
295
 
296
- > O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** (marcar pronto é a revisão humana — o comando não pula isso). Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
296
+ > O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** — e é assim que se sabe que a Feature ainda está em desenvolvimento: quem tira do rascunho é o `implement`, ao concluir a última Story, para todos os PRs da Feature de uma vez. Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
297
297
 
298
298
  ### `@spec-wave/cli qa <issue>` — executa o plano de QA localmente (e `qa --pr-number <n>` no Action)
299
299
  | Flag/Arg | Tipo | Descrição |
@@ -1096,7 +1096,7 @@ npx @spec-wave/cli@latest story review <n> # Etapa 👀 Code Review, Status Tod
1096
1096
 
1097
1097
  Se abre PR e onde faz push depende do **modo de entrega** — o contexto montado já diz qual é (não adivinhe pelo tipo de issue):
1098
1098
 
1099
- - **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`) antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha.
1099
+ - **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`), com `Closes #<story>` no corpo, antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha. **Deixe todos em rascunho até o fim:** o rascunho é o sinal de "feature ainda em andamento" (o GitHub bloqueia o merge), e quando a última Story concluir o próprio `implement` marca todos os PRs da Feature como prontos de uma vez. **Não tire nenhum do rascunho à mão.**
1100
1100
  - **`agent`** (rodando sob o `dev-agent`): **NÃO crie branch, NÃO abra PR** — faça só o commit e o push no branch atual. O daemon mantém um único branch (`agent/issue-<n>`) e é ele quem abre o PR ao final, para a Feature inteira. Abrir um PR por Story aqui cria um branch lateral (`agent/issue-<n>-story-<m>`) cujo trabalho não entra no PR do agente.
1101
1101
 
1102
1102
  **A Feature só avança** para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. Enquanto houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. No modo Feature isso acontece dentro da mesma execução.
@@ -1139,13 +1139,18 @@ Confirme que existe `.spec-wave.json` no repositório (senão → skill **setup*
1139
1139
  "command": "claude -p \"Execute o QA descrito em {contextFile}\"",
1140
1140
  "setup": "npm ci && npm run build",
1141
1141
  "env": { "BASE_URL": "http://localhost:3000" },
1142
- "defaultBugPriority": "P2"
1142
+ "defaultBugPriority": "P2",
1143
+ "platform": "web",
1144
+ "web": { "evidence": "playwright" },
1145
+ "mobile": { "evidence": "maestro", "appId": "com.exemplo.app", "device": "emulator-5554" }
1143
1146
  }
1144
1147
  }
1145
1148
  ```
1146
1149
 
1147
1150
  Placeholders: `{contextFile} {qaPlanFile} {specFile} {issue} {type} {title}`. Sem `qa.command`, o comando monta o contexto, imprime como configurar e **não executa** — não é erro.
1148
1151
 
1152
+ **Evidência visual (opcional):** `qa.platform` (`web` padrão | `mobile`) escolhe quem grava vídeo/foto por cenário — Playwright (`qa.web.evidence`) ou Maestro (`qa.mobile.evidence`, com `appId`/`device`); `"none"` desliga. O executor grava em `.spec-wave/qa-evidence-<n>/cenario-<N>/`, e o `qa` publica em `docs/features/<slug>/qa/cenario-<N>/` (Bug: `docs/bugs/<slug>/qa/`) num commit direto na branch, linkado no relatório e no `bug.md`. Teto de **4 MB por arquivo**; ferramenta ausente só omite a mídia — nunca bloqueia o veredito. O `doctor` confere a plataforma e se a ferramenta está no PATH.
1153
+
1149
1154
  #### 1. Gerar o plano (Feature)
1150
1155
 
1151
1156
  ```bash
@@ -1535,7 +1540,7 @@ utilitários de board estão flag a flag na *Referência da CLI* acima. Rode
1535
1540
  - **`merge`** — Use para mergear os PRs empilhados das Stories de uma Feature do spec-wave, na ordem das dependências, movendo o board até 🧪 QA. Gatilhos: 'mergeia os PRs da feature 12', 'integra as stories', 'os PRs estão revisados, pode mergear', 'qual a ordem de merge?'. Use DEPOIS da revisão humana (PRs marcados como prontos). NÃO mergeie PRs de pilha à mão com --delete-branch — é o que fecha o PR dependente.
1536
1541
  - **`run`** — Use para conduzir o fluxo do spec-wave LOCALMENTE, sem gastar minutos de GitHub Actions: `spec-wave run <issue>` executa nesta máquina o passo que a label dispararia (spec, plan, crítica, validate, decompose, apply) e `spec-wave mode local|actions` alterna entre os dois mundos. Gatilhos: 'rodar o spec-wave local', 'qual o próximo passo da issue 12', 'sem gastar Actions', 'desligar os workflows', 'trocar para execução local'.
1537
1542
  - **`qa-lead`** — Use para orquestrar o QA de uma TRILHA inteira (milestone) do spec-wave — preparar os planos de todas as Features (`qa-lead plan`), executar o ciclo com containers paralelos (`qa-lead run`) e consultar relatórios de ciclo (`qa-lead report`). Gatilhos: 'rodar o QA do milestone', 'QA da release', 'trilha de QA', 'relatório de QA do ciclo'.
1538
- - **`qa-executor`** — Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md.
1543
+ - **`qa-executor`** — Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta (texto e, quando configurado, vídeo/foto via Maestro ou Playwright) e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md.
1539
1544
  - **`task`** — Use para iniciar ou concluir uma Task do spec-wave no board: task start move para 🚧 Desenvolvimento com Status In Progress, task done move para 🎉 Done. Gatilhos: 'comecei a task 56', 'terminei a task 56', 'marcar task como feita'. Prefira sempre este comando a mexer no board via GraphQL ou gh — ele embute a regra de uma única Task In Progress por Story.
1540
1545
  - **`story`** — Use para mandar uma Story do spec-wave para 👀 Code Review depois de implementar todas as suas Tasks e abrir o PR. Gatilhos: 'terminei a story 34', 'mandar a story para review', 'story pronta para code review'. Prefira este comando a mutações GraphQL manuais no board.
1541
1546
  - **`move`** — Use para mover qualquer item do board spec-wave — Feature, Story, Task, Bug ou RFC — para uma Etapa, quando task start|done e story review não cobrem o movimento (ex.: mover uma Feature para Homologação ou Deploy). Gatilhos: 'mover a feature 12 para homologação', 'passar para deploy', 'avançar o card'. Prefira este comando a gh api graphql manual: a Etapa nunca retrocede, e isso é regra do fluxo, não limitação.
@@ -1617,6 +1622,10 @@ docs/
1617
1622
  escrito pelo decompose --apply e atualizado por
1618
1623
  `order --sync`. É o que deixa order/implement/merge
1619
1624
  consultarem a ordem sem pagar a API por Story
1625
+ qa/
1626
+ cenario-<n>/ ← evidência VISUAL (vídeo/foto) do cenário N, publicada
1627
+ por `spec-wave qa` (Maestro no mobile, Playwright na
1628
+ web); arquivos planos, ≤ 4 MB cada. Bug: docs/bugs/<slug>/qa/
1620
1629
  rfcs/
1621
1630
  <slug-do-rfc>/
1622
1631
  decomposition.md ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
@@ -289,7 +289,7 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
289
289
  | `--yes` | boolean | Executa os merges. **Sem ela, só mostra o plano** (fila na ordem, retargets, avisos). |
290
290
  | `--keep-branches` | boolean | Não apaga as branches das Stories após o merge. |
291
291
 
292
- > O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** (marcar pronto é a revisão humana — o comando não pula isso). Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
292
+ > O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** — e é assim que se sabe que a Feature ainda está em desenvolvimento: quem tira do rascunho é o `implement`, ao concluir a última Story, para todos os PRs da Feature de uma vez. Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
293
293
 
294
294
  ### `@spec-wave/cli qa <issue>` — executa o plano de QA localmente (e `qa --pr-number <n>` no Action)
295
295
  | Flag/Arg | Tipo | Descrição |
@@ -569,6 +569,10 @@ docs/
569
569
  escrito pelo decompose --apply e atualizado por
570
570
  `order --sync`. É o que deixa order/implement/merge
571
571
  consultarem a ordem sem pagar a API por Story
572
+ qa/
573
+ cenario-<n>/ ← evidência VISUAL (vídeo/foto) do cenário N, publicada
574
+ por `spec-wave qa` (Maestro no mobile, Playwright na
575
+ web); arquivos planos, ≤ 4 MB cada. Bug: docs/bugs/<slug>/qa/
572
576
  rfcs/
573
577
  <slug-do-rfc>/
574
578
  decomposition.md ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
@@ -35,8 +35,8 @@ jobs:
35
35
  outputs:
36
36
  feature: ${{ steps.resolve.outputs.feature }}
37
37
  steps:
38
- - uses: actions/checkout@v4
39
- - uses: actions/setup-node@v4
38
+ - uses: actions/checkout@v5
39
+ - uses: actions/setup-node@v5
40
40
  with:
41
41
  node-version: '24'
42
42
 
@@ -69,9 +69,9 @@ jobs:
69
69
  contents: read
70
70
 
71
71
  steps:
72
- - uses: actions/checkout@v4
72
+ - uses: actions/checkout@v5
73
73
 
74
- - uses: actions/setup-node@v4
74
+ - uses: actions/setup-node@v5
75
75
  with:
76
76
  node-version: '24'
77
77
 
@@ -39,11 +39,11 @@ jobs:
39
39
  contents: read
40
40
 
41
41
  steps:
42
- - uses: actions/checkout@v4
42
+ - uses: actions/checkout@v5
43
43
  with:
44
44
  token: ${{ secrets.GITHUB_TOKEN }}
45
45
 
46
- - uses: actions/setup-node@v4
46
+ - uses: actions/setup-node@v5
47
47
  with:
48
48
  node-version: '24'
49
49
 
@@ -70,11 +70,11 @@ jobs:
70
70
  pull-requests: write
71
71
 
72
72
  steps:
73
- - uses: actions/checkout@v4
73
+ - uses: actions/checkout@v5
74
74
  with:
75
75
  token: ${{ secrets.GITHUB_TOKEN }}
76
76
 
77
- - uses: actions/setup-node@v4
77
+ - uses: actions/setup-node@v5
78
78
  with:
79
79
  node-version: '24'
80
80
 
@@ -54,11 +54,11 @@ jobs:
54
54
  pull-requests: write
55
55
 
56
56
  steps:
57
- - uses: actions/checkout@v4
57
+ - uses: actions/checkout@v5
58
58
  with:
59
59
  token: ${{ secrets.GITHUB_TOKEN }}
60
60
 
61
- - uses: actions/setup-node@v4
61
+ - uses: actions/setup-node@v5
62
62
  with:
63
63
  node-version: '24'
64
64
 
@@ -64,11 +64,11 @@ jobs:
64
64
  pull-requests: write
65
65
 
66
66
  steps:
67
- - uses: actions/checkout@v4
67
+ - uses: actions/checkout@v5
68
68
  with:
69
69
  token: ${{ secrets.GITHUB_TOKEN }}
70
70
 
71
- - uses: actions/setup-node@v4
71
+ - uses: actions/setup-node@v5
72
72
  with:
73
73
  node-version: '24'
74
74
 
@@ -41,11 +41,11 @@ jobs:
41
41
  pull-requests: write
42
42
 
43
43
  steps:
44
- - uses: actions/checkout@v4
44
+ - uses: actions/checkout@v5
45
45
  with:
46
46
  token: ${{ secrets.GITHUB_TOKEN }}
47
47
 
48
- - uses: actions/setup-node@v4
48
+ - uses: actions/setup-node@v5
49
49
  with:
50
50
  node-version: '24'
51
51
 
@@ -64,11 +64,11 @@ jobs:
64
64
  pull-requests: write
65
65
 
66
66
  steps:
67
- - uses: actions/checkout@v4
67
+ - uses: actions/checkout@v5
68
68
  with:
69
69
  token: ${{ secrets.GITHUB_TOKEN }}
70
70
 
71
- - uses: actions/setup-node@v4
71
+ - uses: actions/setup-node@v5
72
72
  with:
73
73
  node-version: '24'
74
74
 
@@ -44,9 +44,9 @@ jobs:
44
44
  contents: read
45
45
 
46
46
  steps:
47
- - uses: actions/checkout@v4
47
+ - uses: actions/checkout@v5
48
48
 
49
- - uses: actions/setup-node@v4
49
+ - uses: actions/setup-node@v5
50
50
  with:
51
51
  node-version: '24'
52
52
 
@@ -38,9 +38,9 @@ jobs:
38
38
  contents: read
39
39
 
40
40
  steps:
41
- - uses: actions/checkout@v4
41
+ - uses: actions/checkout@v5
42
42
 
43
- - uses: actions/setup-node@v4
43
+ - uses: actions/setup-node@v5
44
44
  with:
45
45
  node-version: '24'
46
46