@spec-wave/cli 0.34.2 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/package.json +2 -2
  2. package/protocol/qa-result.v1.json +9 -0
  3. package/src/agent/anthropic-agent.mjs +35 -2
  4. package/src/api/github-graphql.mjs +60 -2
  5. package/src/api/github-rest.mjs +23 -0
  6. package/src/cli.mjs +23 -0
  7. package/src/commands/code-review.mjs +71 -60
  8. package/src/commands/decompose.mjs +75 -4
  9. package/src/commands/doctor.mjs +105 -4
  10. package/src/commands/implement.mjs +82 -10
  11. package/src/commands/init.mjs +147 -29
  12. package/src/commands/merge.mjs +56 -4
  13. package/src/commands/move.mjs +4 -7
  14. package/src/commands/order.mjs +2 -2
  15. package/src/commands/qa-run.mjs +140 -19
  16. package/src/commands/qa.mjs +22 -21
  17. package/src/commands/repair-stage.mjs +2 -5
  18. package/src/commands/story.mjs +2 -2
  19. package/src/commands/task.mjs +2 -2
  20. package/src/commands/triage.mjs +2 -5
  21. package/src/commands/update.mjs +31 -8
  22. package/src/commands/validate.mjs +2 -5
  23. package/src/commands/workspace.mjs +112 -0
  24. package/src/config.mjs +19 -0
  25. package/src/lib/artifact-pr.mjs +1 -1
  26. package/src/lib/bug-doc.mjs +6 -1
  27. package/src/lib/claude.mjs +4 -0
  28. package/src/lib/decomposition-doc.mjs +56 -3
  29. package/src/lib/dependency-map.mjs +3 -0
  30. package/src/lib/doc-paths.mjs +6 -1
  31. package/src/lib/flow-run.mjs +14 -3
  32. package/src/lib/pr-link.mjs +109 -0
  33. package/src/lib/pr-ready.mjs +146 -0
  34. package/src/lib/project-root.mjs +51 -0
  35. package/src/lib/qa-exec.mjs +73 -0
  36. package/src/lib/qa-report.mjs +172 -8
  37. package/src/lib/repo-role.mjs +102 -0
  38. package/src/lib/workspace.mjs +151 -0
  39. package/src/plugin/.claude-plugin/plugin.json +1 -1
  40. package/src/plugin/skills/decompose/SKILL.md +1 -0
  41. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  42. package/src/plugin/skills/implement/SKILL.md +2 -2
  43. package/src/plugin/skills/merge/SKILL.md +3 -2
  44. package/src/plugin/skills/qa/SKILL.md +6 -1
  45. package/src/plugin/skills/qa-executor/SKILL.md +43 -1
  46. package/src/plugin/skills/setup/SKILL.md +12 -0
  47. package/src/setup/files.mjs +35 -13
  48. package/src/templates/skill/SKILL.md +27 -5
  49. package/src/templates/skill/core.md +5 -1
  50. package/src/templates/workflows/code/code-review.yml +60 -0
  51. package/src/templates/workflows/code/qa.yml +59 -0
  52. package/src/templates/workflows/pr-events.yml +116 -0
@@ -0,0 +1,102 @@
1
+ // Papel do repositório no Project (RFC-005): um Project tem UM repositório
2
+ // hub — onde nascem as issues, os documentos e os workflows — e N repositórios
3
+ // de código, onde só acontecem branch e PR. Mono-repo é o caso degenerado:
4
+ // um hub sem repos de código, que é exatamente o estado de toda instalação
5
+ // anterior à RFC. Por isso a AUSÊNCIA de `role` no .spec-wave.json significa
6
+ // hub, e nenhum config antigo precisa ser regravado.
7
+ //
8
+ // hub: { role: 'hub', repositories: [{ slug, owner, repo }] } (repositories opcional)
9
+ // code: { role: 'code', hub: { owner, repo } }
10
+ //
11
+ // Funções PURAS — testáveis sem rede nem disco.
12
+
13
+ export const REPO_ROLES = ['hub', 'code'];
14
+ export const DEFAULT_REPO_ROLE = 'hub';
15
+
16
+ // Mesma regra do slug da UI (shared/src/projectRepos.ts): minúsculas,
17
+ // [a-z0-9-], até 39 caracteres — o limite de um login do GitHub. O slug vai
18
+ // na label `repo:<slug>` e é IMUTÁVEL depois do primeiro vínculo, porque está
19
+ // gravado em issues.
20
+ const REPO_SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38})$/;
21
+
22
+ export function isValidRepoSlug(slug) {
23
+ return typeof slug === 'string' && REPO_SLUG_RE.test(slug);
24
+ }
25
+
26
+ /** @returns {'hub'|'code'} */
27
+ export function configuredRole(config) {
28
+ const role = String(config?.role || '').toLowerCase();
29
+ return REPO_ROLES.includes(role) ? role : DEFAULT_REPO_ROLE;
30
+ }
31
+
32
+ export function isCodeRepo(config) {
33
+ return configuredRole(config) === 'code';
34
+ }
35
+
36
+ /**
37
+ * O hub declarado por um repo de código, ou null quando o config não é de
38
+ * repo de código ou está incompleto.
39
+ * @returns {{ owner: string, repo: string }|null}
40
+ */
41
+ export function declaredHub(config) {
42
+ if (!isCodeRepo(config)) return null;
43
+ const hub = config?.hub;
44
+ if (!hub?.owner || !hub?.repo) return null;
45
+ return { owner: String(hub.owner), repo: String(hub.repo) };
46
+ }
47
+
48
+ /**
49
+ * Repositórios de código vinculados ao hub, já validados. Entradas
50
+ * malformadas são descartadas em vez de derrubar o comando — o hub continua
51
+ * funcionando como mono-repo enquanto o vínculo não estiver completo.
52
+ * @returns {{ slug: string, owner: string, repo: string }[]}
53
+ */
54
+ export function codeRepositories(config) {
55
+ if (isCodeRepo(config)) return [];
56
+ const list = Array.isArray(config?.repositories) ? config.repositories : [];
57
+ const out = [];
58
+ const seen = new Set();
59
+ for (const entry of list) {
60
+ if (!isValidRepoSlug(entry?.slug) || !entry?.owner || !entry?.repo) continue;
61
+ if (seen.has(entry.slug)) continue;
62
+ seen.add(entry.slug);
63
+ out.push({ slug: entry.slug, owner: String(entry.owner), repo: String(entry.repo) });
64
+ }
65
+ return out;
66
+ }
67
+
68
+ export function repositoryBySlug(config, slug) {
69
+ return codeRepositories(config).find(r => r.slug === slug) || null;
70
+ }
71
+
72
+ /**
73
+ * `owner/repo` → { owner, repo }; null para qualquer outra forma. É a
74
+ * gramática de `--repo`, `--hub` e `--pr-repo`.
75
+ */
76
+ export function parseRepoRef(value) {
77
+ const m = /^([\w.-]+)\/([\w.-]+)$/.exec(String(value ?? '').trim());
78
+ return m ? { owner: m[1], repo: m[2] } : null;
79
+ }
80
+
81
+ /** A label que uma Story usa para declarar que toca este repositório. */
82
+ export const REPO_LABEL_PREFIX = 'repo:';
83
+
84
+ export function repoLabel(slug) {
85
+ return `${REPO_LABEL_PREFIX}${slug}`;
86
+ }
87
+
88
+ /**
89
+ * Slugs declarados pelas labels de uma issue, na ordem em que aparecem.
90
+ * A label é a fonte de verdade (§3.3) — o campo do board é só espelho.
91
+ * @param {Array<string|{name?: string}>} labels
92
+ */
93
+ export function repoSlugsFromLabels(labels) {
94
+ const out = [];
95
+ for (const l of labels || []) {
96
+ const name = typeof l === 'string' ? l : l?.name;
97
+ if (!name || !name.startsWith(REPO_LABEL_PREFIX)) continue;
98
+ const slug = name.slice(REPO_LABEL_PREFIX.length);
99
+ if (isValidRepoSlug(slug) && !out.includes(slug)) out.push(slug);
100
+ }
101
+ return out;
102
+ }
@@ -0,0 +1,151 @@
1
+ // Workspace multi-repo (RFC-005 §3.5/§7.2): um subdiretório por slug, ao lado
2
+ // do hub. É a peça que unifica o conceito de workspace nos três executores —
3
+ // no dev local resolve a convenção de irmãos, no Action clona, e o
4
+ // `implement` deriva daqui os placeholders {workspaceDir}/{repoDirs}.
5
+ //
6
+ // <workspace>/
7
+ // hub/ ← .spec-wave.json (role: hub), docs/features/<slug>/
8
+ // api/
9
+ // web/
10
+ //
11
+ // Caminho de máquina NUNCA entra no .spec-wave.json commitado. O override local
12
+ // vive em .spec-wave/workspace.json (gitignored) e a CLONAGEM gerenciada em
13
+ // .spec-wave/repos/<slug>/ — dentro do diretório de scratch que já não é
14
+ // versionado. Irmãos e overrides são do dev: nunca são clonados, puxados ou
15
+ // tocados; só mapeados.
16
+
17
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
18
+ import path from 'node:path';
19
+ import { execFileSync } from 'node:child_process';
20
+ import { codeRepositories, repoSlugsFromLabels } from './repo-role.mjs';
21
+
22
+ export const WORKSPACE_OVERRIDE_FILE = path.join('.spec-wave', 'workspace.json');
23
+ export const WORKSPACE_CLONES_DIR = path.join('.spec-wave', 'repos');
24
+
25
+ /**
26
+ * Slugs que um item toca (função PURA): os das próprias labels; uma Feature,
27
+ * que não declara repo, AGREGA os dos filhos (§5.2 `repoSlugsOfFeature`).
28
+ *
29
+ * @param {object} params
30
+ * @param {Array<string|{name?:string}>} [params.labels]
31
+ * @param {Array<{labels?: Array}>} [params.children]
32
+ * @returns {string[]} ordenados, sem repetição
33
+ */
34
+ export function slugsForItem({ labels = [], children = [] } = {}) {
35
+ const own = repoSlugsFromLabels(labels);
36
+ if (own.length > 0) return [...own].sort();
37
+ const agg = new Set();
38
+ for (const child of children) {
39
+ for (const slug of repoSlugsFromLabels(child?.labels)) agg.add(slug);
40
+ }
41
+ return [...agg].sort();
42
+ }
43
+
44
+ /**
45
+ * Onde cada repositório fica (função PURA — `exists` é injetável).
46
+ *
47
+ * Por slug, nesta ordem: override em .spec-wave/workspace.json → irmão
48
+ * (`<pai do hub>/<slug>`) → clone gerenciado (`<hub>/.spec-wave/repos/<slug>`).
49
+ * Slug fora de `repositories[]` volta em `unknown`, nunca vira diretório.
50
+ *
51
+ * @param {object} params
52
+ * @param {string} params.root raiz do hub (diretório do .spec-wave.json)
53
+ * @param {object} params.config .spec-wave.json do hub
54
+ * @param {string[]} params.slugs
55
+ * @param {{dirs?: Record<string,string>}|null} [params.override]
56
+ * @param {(p: string) => boolean} [params.exists]
57
+ * @returns {{ hubDir: string, workspaceDir: string, unknown: string[],
58
+ * repos: Array<{slug:string, owner:string, repo:string, dir:string,
59
+ * source:'override'|'sibling'|'clone', present:boolean}> }}
60
+ */
61
+ export function resolveWorkspaceLayout({ root, config, slugs = [], override = null, exists = existsSync }) {
62
+ const hubDir = path.resolve(root);
63
+ const workspaceDir = path.dirname(hubDir);
64
+ const known = new Map(codeRepositories(config).map(r => [r.slug, r]));
65
+ const repos = [];
66
+ const unknown = [];
67
+ for (const slug of slugs) {
68
+ const meta = known.get(slug);
69
+ if (!meta) { unknown.push(slug); continue; }
70
+ const overridden = override?.dirs?.[slug];
71
+ if (typeof overridden === 'string' && overridden.trim()) {
72
+ const dir = path.resolve(hubDir, overridden.trim());
73
+ repos.push({ ...meta, dir, source: 'override', present: exists(dir) });
74
+ continue;
75
+ }
76
+ const sibling = path.join(workspaceDir, slug);
77
+ if (exists(sibling)) {
78
+ repos.push({ ...meta, dir: sibling, source: 'sibling', present: true });
79
+ continue;
80
+ }
81
+ const managed = path.join(hubDir, WORKSPACE_CLONES_DIR, slug);
82
+ repos.push({ ...meta, dir: managed, source: 'clone', present: exists(managed) });
83
+ }
84
+ return { hubDir, workspaceDir, repos, unknown };
85
+ }
86
+
87
+ /** Override local (`{ "dirs": { "<slug>": "<caminho>" } }`), ou null. */
88
+ export function readWorkspaceOverride(root) {
89
+ try {
90
+ const parsed = JSON.parse(readFileSync(path.join(root, WORKSPACE_OVERRIDE_FILE), 'utf-8'));
91
+ return parsed && typeof parsed === 'object' ? parsed : null;
92
+ } catch {
93
+ return null;
94
+ }
95
+ }
96
+
97
+ /**
98
+ * Valor do placeholder `{repoDirs}` do implement: `slug=/dir slug=/dir`,
99
+ * separado por espaço — legível num shell e trivial de partir num script.
100
+ */
101
+ export function renderRepoDirs(repos = []) {
102
+ return repos.map(r => `${r.slug}=${r.dir}`).join(' ');
103
+ }
104
+
105
+ function cloneUrl({ owner, repo }, token) {
106
+ // Token na URL só no Action, onde o clone é descartável; localmente o git
107
+ // usa o credential helper do dev (o do gh, normalmente).
108
+ return token
109
+ ? `https://x-access-token:${token}@github.com/${owner}/${repo}.git`
110
+ : `https://github.com/${owner}/${repo}.git`;
111
+ }
112
+
113
+ function defaultGit(args) {
114
+ return execFileSync('git', args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
115
+ }
116
+
117
+ /**
118
+ * Materializa o workspace: clona o que falta e é de fonte `clone`. Irmão ou
119
+ * override ausente é AVISO — o diretório é do dev, não desta CLI.
120
+ *
121
+ * @param {object} params
122
+ * @param {ReturnType<typeof resolveWorkspaceLayout>} params.layout
123
+ * @param {string|null} [params.token] só no Action (vai para a URL do clone)
124
+ * @param {boolean} [params.shallow] `--depth 1` — leitura pelos prompts
125
+ * @param {(args: string[]) => string} [params.git] injetável nos testes
126
+ * @param {{warn: Function, info: Function}} [params.log]
127
+ * @returns {Promise<{ cloned: string[], missing: string[] }>}
128
+ */
129
+ export async function prepareWorkspace({ layout, token = null, shallow = false, git = defaultGit, log = console }) {
130
+ const cloned = [];
131
+ const missing = [];
132
+ for (const r of layout.repos) {
133
+ if (r.present) continue;
134
+ if (r.source !== 'clone') {
135
+ missing.push(r.slug);
136
+ log.warn(`${r.slug}: ${r.dir} não existe (${r.source === 'override' ? 'override em ' + WORKSPACE_OVERRIDE_FILE : 'irmão do hub'}) — clone você mesmo ou remova o override.`);
137
+ continue;
138
+ }
139
+ mkdirSync(path.dirname(r.dir), { recursive: true });
140
+ // Diretório auto-ignorado: um clone inteiro dentro do hub não pode virar
141
+ // "untracked" à espera de um `git add .` — e o hub não tem template de
142
+ // .gitignore para depender dele.
143
+ const ignore = path.join(path.dirname(r.dir), '.gitignore');
144
+ if (!existsSync(ignore)) writeFileSync(ignore, '*\n');
145
+ log.info(`Clonando ${r.owner}/${r.repo} em ${r.dir}...`);
146
+ git(['clone', '--quiet', ...(shallow ? ['--depth', '1'] : []), cloneUrl(r, token), r.dir]);
147
+ r.present = true;
148
+ cloned.push(r.slug);
149
+ }
150
+ return { cloned, missing };
151
+ }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "0.34.2",
4
+ "version": "1.0.1",
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",
@@ -94,6 +94,7 @@ Corpo técnico.
94
94
 
95
95
  - a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
96
96
  - `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma
97
+ - `**Repos:** api, web` (opcional, **só no multi-repo** — RFC-005): os slugs de `repositories[]` do `.spec-wave.json` do hub que a Story toca. No apply viram labels `repo:<slug>` na Story **e nas Tasks**; slug que o hub não conhece reprova o rascunho **antes** de criar qualquer issue. Sem a linha, nenhum repo é declarado (mono-repo)
97
98
  - o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
98
99
  - **para gerar outro rascunho do zero:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já foi mergeado) e reaplique `spec-wave:decompose`
99
100
 
@@ -5,7 +5,7 @@ description: Decompõe uma Feature em Stories ordenadas, cada uma com suas Tasks
5
5
  tools: [Read, Glob, Grep]
6
6
  maxTurns: 30
7
7
  json:
8
- shape: '{"stories": [{"title": "...", "userStory": "...", "body": "...", "dependsOn": [0], "tasks": [{"title": "...", "body": "..."}]}]}'
8
+ shape: '{"stories": [{"title": "...", "userStory": "...", "body": "...", "dependsOn": [0], "repos": ["api"], "tasks": [{"title": "...", "body": "..."}]}]}'
9
9
  retries: 1
10
10
  ---
11
11
 
@@ -39,6 +39,7 @@ Responda APENAS com JSON válido neste formato:
39
39
  "userStory": "Como <perfil>, quero <objetivo>, para <benefício>",
40
40
  "body": "Descrição complementar da story com contexto e critérios de aceite relevantes",
41
41
  "dependsOn": [0],
42
+ "repos": ["api"],
42
43
  "tasks": [
43
44
  {
44
45
  "title": "Título técnico curto da task (sem prefixo)",
@@ -60,10 +61,11 @@ Responda APENAS com JSON válido neste formato:
60
61
  - Gere entre 3 e 7 Stories por Feature
61
62
  - Ordene as stories na sequência de implementação — a ORDEM da lista importa
62
63
  - `dependsOn` (opcional): índices 0-based das stories ANTERIORES na lista das quais esta story depende. Referencie apenas índices menores que o da própria story. Use `[]` quando a story puder ser feita em paralelo (sem dependências); se omitido, assume-se dependência da story anterior (sequencial)
64
+ - `repos` (opcional): **só** quando a entrada trouxer a seção "Repositórios de código". São os slugs dos repositórios que a story toca, copiados EXATAMENTE da lista (uma story pode tocar mais de um). Sem essa seção, **omita o campo** — o projeto é mono-repo
63
65
  - Escreva títulos e corpos em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
64
66
 
65
67
  ## O que acontece com a sua saída
66
68
 
67
- Cada story vira uma issue `[STORY]` e cada task uma issue `[TASK]` vinculada como sub-issue, posicionadas na etapa **✅ Ready** do board. As dependências viram a relação nativa `blocked_by` do GitHub e uma linha "Depende de: #N" no corpo. Ou seja: a ordem e o `dependsOn` que você devolver determinam a ordem real de execução do time.
69
+ Cada story vira uma issue `[STORY]` e cada task uma issue `[TASK]` vinculada como sub-issue, posicionadas na etapa **✅ Ready** do board. As dependências viram a relação nativa `blocked_by` do GitHub e uma linha "Depende de: #N" no corpo; `repos` vira a label `repo:<slug>` na Story e nas suas Tasks — é por ela que o time sabe em que repositório abrir o PR. Ou seja: a ordem, o `dependsOn` e o `repos` que você devolver determinam a execução real do time.
68
70
 
69
71
  Antes disso, uma crítica adversarial audita as stories contra a spec e o plan (ver a skill `critique-stories`). Achados graves cancelam a criação — nenhuma issue é aberta.
@@ -59,7 +59,7 @@ Outros tipos (Spike, Epic) → o comando **recusa**.
59
59
  ```bash
60
60
  npx @spec-wave/cli@latest implement <número>
61
61
  ```
62
- Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`.
62
+ Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title} {workspaceDir} {repoDirs}`. Os dois últimos são do multi-repo (RFC-005): `{workspaceDir}` é o diretório pai do hub e `{repoDirs}` lista `slug=/caminho` por repositório que a issue declara (label `repo:<slug>`) — vazio no mono-repo. Se algum repo estiver ausente, o comando avisa: rode `npx @spec-wave/cli@latest workspace prepare --issue <número>` antes.
63
63
 
64
64
  Use `--feature-dir docs/features/<slug>` se a resolução automática falhar e você quiser anexar `spec.md`/`plan.md`.
65
65
 
@@ -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
 
@@ -25,6 +25,18 @@ Você dirige o `init` **com flags**. Nunca rode `npx @spec-wave/cli@latest init`
25
25
  | `--skip-labels` | flag | Pula as labels. |
26
26
  | `--skip-files` | flag | Pula workflows + issue templates. |
27
27
  | `--dry-run` | flag | Simula sem alterar nada. |
28
+ | `--role <hub\|code>` | string | Papel do repo no Project (RFC-005). Default `hub`. |
29
+ | `--hub <owner/repo>` | string | Só com `--role code`: o hub a que este repo de código pertence. |
30
+
31
+ ### Repositório de código (multi-repo, RFC-005)
32
+
33
+ Um Project tem **um** hub (issues, docs, labels, Project, workflows do fluxo) e N repos de código, onde só acontecem branch e PR. Para vincular um repo de código:
34
+
35
+ ```bash
36
+ npx @spec-wave/cli@latest init --role code --repo <owner/api> --hub <owner/hub>
37
+ ```
38
+
39
+ Isso grava **só** dois despachantes (`code-review.yml`, `qa.yml`, que avisam o hub por `repository_dispatch`) e um `.spec-wave.json` com `role: "code"` e `hub`. Nada de labels, Project, issue templates ou secret de IA. Depois: o secret `SPEC_WAVE_HUB_TOKEN` no repo de código (token com escrita em Contents no hub), `spec-wave update` no hub (instala o `pr-events.yml`), e o registro em `repositories[]` do `.spec-wave.json` do hub — `{ slug, owner, repo }`, slug em `[a-z0-9-]`, imutável. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
28
40
 
29
41
  ## Passos
30
42
 
@@ -1,24 +1,28 @@
1
1
  import { upsertFile, getFileContent, isRepoInitialized } from '../api/github-rest.mjs';
2
- import { WORKFLOW_FILES } from '../config.mjs';
2
+ import { WORKFLOW_FILES, CODE_WORKFLOW_FILES } from '../config.mjs';
3
3
  // readTemplate resolve {{CLI_VERSION}} — é o que fixa a versão da CLI nos
4
4
  // workflows gravados no repo-alvo (ver src/lib/templates.mjs).
5
5
  import { readTemplate } from '../lib/templates.mjs';
6
6
 
7
- export async function setupFiles(token, owner, repo, spinner) {
8
- spinner.message('Verificando repositório...');
9
- const initialized = await isRepoInitialized(token, owner, repo);
10
- if (!initialized) {
11
- throw new Error(
12
- `O repositório ${owner}/${repo} está vazio (sem commits).\n` +
13
- `Inicialize-o com um commit antes de continuar:\n` +
14
- ` gh repo clone ${owner}/${repo} && cd ${repo}\n` +
15
- ` git commit --allow-empty -m "chore: initial commit" && git push`
16
- );
7
+ /**
8
+ * Arquivos que um repositório recebe, por papel (RFC-005 §7.5). O repo de
9
+ * código recebe SÓ os despachantes — sem issue templates, sem tech_context,
10
+ * sem os outros sete workflows. Função PURA (só lê templates do pacote).
11
+ *
12
+ * @param {'hub'|'code'} role
13
+ * @returns {Array<{path: string, content: string, message: string}>}
14
+ */
15
+ export function repoFilesFor(role) {
16
+ if (role === 'code') {
17
+ return CODE_WORKFLOW_FILES.map((file) => ({
18
+ path: `.github/workflows/${file}`,
19
+ content: readTemplate('workflows', 'code', file),
20
+ message: `chore: add ${file.replace(/\.yml$/, '')} dispatcher [spec-wave]`,
21
+ }));
17
22
  }
18
-
19
23
  // Workflows vêm de WORKFLOW_FILES (config.mjs, fonte única) — adicionar um
20
24
  // workflow novo lá basta para o init (e o update) instalarem.
21
- const filesToCreate = [
25
+ return [
22
26
  {
23
27
  path: '.github/ISSUE_TEMPLATE/plan-template.md',
24
28
  content: readTemplate('issue', 'plan-template.md'),
@@ -35,6 +39,21 @@ export async function setupFiles(token, owner, repo, spinner) {
35
39
  message: `chore: add ${file.replace(/\.yml$/, '')} workflow [spec-wave]`,
36
40
  })),
37
41
  ];
42
+ }
43
+
44
+ export async function setupFiles(token, owner, repo, spinner, { role = 'hub' } = {}) {
45
+ spinner.message('Verificando repositório...');
46
+ const initialized = await isRepoInitialized(token, owner, repo);
47
+ if (!initialized) {
48
+ throw new Error(
49
+ `O repositório ${owner}/${repo} está vazio (sem commits).\n` +
50
+ `Inicialize-o com um commit antes de continuar:\n` +
51
+ ` gh repo clone ${owner}/${repo} && cd ${repo}\n` +
52
+ ` git commit --allow-empty -m "chore: initial commit" && git push`
53
+ );
54
+ }
55
+
56
+ const filesToCreate = repoFilesFor(role);
38
57
 
39
58
  for (let i = 0; i < filesToCreate.length; i++) {
40
59
  const file = filesToCreate[i];
@@ -42,6 +61,9 @@ export async function setupFiles(token, owner, repo, spinner) {
42
61
  await upsertFile(token, owner, repo, file.path, file.content, file.message);
43
62
  }
44
63
 
64
+ // O tech_context é do hub: é lá que os prompts o leem.
65
+ if (role === 'code') return;
66
+
45
67
  // Arquivos de config criados apenas se ainda não existirem, para não
46
68
  // sobrescrever ajustes manuais (tech_context.yml é editado pelo time).
47
69
  const configFiles = [
@@ -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 |
@@ -549,6 +549,18 @@ Você dirige o `init` **com flags**. Nunca rode `npx @spec-wave/cli@latest init`
549
549
  | `--skip-labels` | flag | Pula as labels. |
550
550
  | `--skip-files` | flag | Pula workflows + issue templates. |
551
551
  | `--dry-run` | flag | Simula sem alterar nada. |
552
+ | `--role <hub\|code>` | string | Papel do repo no Project (RFC-005). Default `hub`. |
553
+ | `--hub <owner/repo>` | string | Só com `--role code`: o hub a que este repo de código pertence. |
554
+
555
+ ##### Repositório de código (multi-repo, RFC-005)
556
+
557
+ Um Project tem **um** hub (issues, docs, labels, Project, workflows do fluxo) e N repos de código, onde só acontecem branch e PR. Para vincular um repo de código:
558
+
559
+ ```bash
560
+ npx @spec-wave/cli@latest init --role code --repo <owner/api> --hub <owner/hub>
561
+ ```
562
+
563
+ Isso grava **só** dois despachantes (`code-review.yml`, `qa.yml`, que avisam o hub por `repository_dispatch`) e um `.spec-wave.json` com `role: "code"` e `hub`. Nada de labels, Project, issue templates ou secret de IA. Depois: o secret `SPEC_WAVE_HUB_TOKEN` no repo de código (token com escrita em Contents no hub), `spec-wave update` no hub (instala o `pr-events.yml`), e o registro em `repositories[]` do `.spec-wave.json` do hub — `{ slug, owner, repo }`, slug em `[a-z0-9-]`, imutável. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
552
564
 
553
565
  #### Passos
554
566
 
@@ -999,6 +1011,7 @@ Corpo técnico.
999
1011
 
1000
1012
  - a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
1001
1013
  - `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma
1014
+ - `**Repos:** api, web` (opcional, **só no multi-repo** — RFC-005): os slugs de `repositories[]` do `.spec-wave.json` do hub que a Story toca. No apply viram labels `repo:<slug>` na Story **e nas Tasks**; slug que o hub não conhece reprova o rascunho **antes** de criar qualquer issue. Sem a linha, nenhum repo é declarado (mono-repo)
1002
1015
  - o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
1003
1016
  - **para gerar outro rascunho do zero:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já foi mergeado) e reaplique `spec-wave:decompose`
1004
1017
 
@@ -1068,7 +1081,7 @@ Outros tipos (Spike, Epic) → o comando **recusa**.
1068
1081
  ```bash
1069
1082
  npx @spec-wave/cli@latest implement <número>
1070
1083
  ```
1071
- Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`.
1084
+ Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title} {workspaceDir} {repoDirs}`. Os dois últimos são do multi-repo (RFC-005): `{workspaceDir}` é o diretório pai do hub e `{repoDirs}` lista `slug=/caminho` por repositório que a issue declara (label `repo:<slug>`) — vazio no mono-repo. Se algum repo estiver ausente, o comando avisa: rode `npx @spec-wave/cli@latest workspace prepare --issue <número>` antes.
1072
1085
 
1073
1086
  Use `--feature-dir docs/features/<slug>` se a resolução automática falhar e você quiser anexar `spec.md`/`plan.md`.
1074
1087
 
@@ -1096,7 +1109,7 @@ npx @spec-wave/cli@latest story review <n> # Etapa 👀 Code Review, Status Tod
1096
1109
 
1097
1110
  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
1111
 
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.
1112
+ - **`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
1113
  - **`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
1114
 
1102
1115
  **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 +1152,18 @@ Confirme que existe `.spec-wave.json` no repositório (senão → skill **setup*
1139
1152
  "command": "claude -p \"Execute o QA descrito em {contextFile}\"",
1140
1153
  "setup": "npm ci && npm run build",
1141
1154
  "env": { "BASE_URL": "http://localhost:3000" },
1142
- "defaultBugPriority": "P2"
1155
+ "defaultBugPriority": "P2",
1156
+ "platform": "web",
1157
+ "web": { "evidence": "playwright" },
1158
+ "mobile": { "evidence": "maestro", "appId": "com.exemplo.app", "device": "emulator-5554" }
1143
1159
  }
1144
1160
  }
1145
1161
  ```
1146
1162
 
1147
1163
  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
1164
 
1165
+ **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.
1166
+
1149
1167
  #### 1. Gerar o plano (Feature)
1150
1168
 
1151
1169
  ```bash
@@ -1535,7 +1553,7 @@ utilitários de board estão flag a flag na *Referência da CLI* acima. Rode
1535
1553
  - **`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
1554
  - **`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
1555
  - **`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.
1556
+ - **`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
1557
  - **`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
1558
  - **`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
1559
  - **`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 +1635,10 @@ docs/
1617
1635
  escrito pelo decompose --apply e atualizado por
1618
1636
  `order --sync`. É o que deixa order/implement/merge
1619
1637
  consultarem a ordem sem pagar a API por Story
1638
+ qa/
1639
+ cenario-<n>/ ← evidência VISUAL (vídeo/foto) do cenário N, publicada
1640
+ por `spec-wave qa` (Maestro no mobile, Playwright na
1641
+ web); arquivos planos, ≤ 4 MB cada. Bug: docs/bugs/<slug>/qa/
1620
1642
  rfcs/
1621
1643
  <slug-do-rfc>/
1622
1644
  decomposition.md ← mesmo papel, com "## Task N" (RFC não usa spec/plan)