@spec-wave/cli 0.12.0 → 0.14.0

package/README.md

@@ -68,7 +68,8 @@ Ferramenta Node.js que configura e opera o fluxo via linha de comando.
 | `generate-spec` | Gera `spec.md` (usado pelo GitHub Action) |
 | `generate-plan` | Gera `plan.md` (usado pelo GitHub Action) |
 | `validate` | Valida spec.md e plan.md (usado pelo GitHub Action) |
-| `decompose` | Decompõe Feature em Stories e Tasks (usado pelo GitHub Action) |
+| `decompose` | Gera o rascunho da decomposição em `decomposition.md`; com `--apply`, cria as Stories/Tasks a partir do rascunho revisado (usado pelo GitHub Action) |
+| `move <n> <etapa>` | Move qualquer item do board (Feature, Story, Task, Bug, RFC) para uma Etapa — a Etapa nunca retrocede |
 | `code-review` | Move Feature para Code Review ao abrir PR (usado pelo GitHub Action) |
 | `qa` | Move Feature para QA ao aprovar PR (usado pelo GitHub Action) |
 | `implement` | Aciona o spec-kit localmente para implementar uma Feature (Stories pendentes em ordem de dependência), Story ou Task |
@@ -81,31 +82,10 @@ Ferramenta Node.js que configura e opera o fluxo via linha de comando.
 | `generate-spec.yml` | label `spec-wave:spec` | Gera `docs/features/<slug>/spec.md` via IA |
 | `generate-plan.yml` | label `spec-wave:plan` | Gera `docs/features/<slug>/plan.md` via IA |
 | `validate.yml` | label `spec-wave:ready` | Valida seções obrigatórias; adiciona `spec-wave:plan-approved` |
-| `decompose.yml` | label `spec-wave:decompose` | Cria Stories e Tasks como sub-issues |
+| `decompose.yml` | labels `spec-wave:decompose` / `spec-wave:decompose-apply` | 1º grava e critica o rascunho `decomposition.md`; 2º cria Stories e Tasks como sub-issues |
 | `code-review.yml` | PR aberto/reaberto | Move Feature para `👀 Code Review` |
 | `qa.yml` | PR aprovado | Move Feature para `🧪 QA` |
 
-**Re-executar uma etapa (`spec-wave:force`).** Adicionada *junto* de uma label de gatilho, a label `spec-wave:force` manda o comando re-executar a etapa ignorando os guards; ela é consumida pelo run (vale uma vez). Sozinha não dispara nada.
-
-```bash
-gh issue edit 12 --add-label "spec-wave:force" --add-label "spec-wave:decompose"
-```
-
-No `decompose` ela **fecha as sub-issues da decomposição anterior** (Stories e suas Tasks) antes de gerar as novas — operação destrutiva, com aviso no comentário da issue quando alguma já saiu de `✅ Ready`. Em `generate-spec`/`generate-plan` ela **versiona** o documento em vez de sobrescrever (veja abaixo). A flag equivalente para execução local é `--force`.
-
-### Documentos versionados
-
-A primeira geração escreve `spec.md`/`plan.md` (v1). Cada regeração **forçada** grava a próxima versão ao lado, preservando as anteriores:
-
-```
-docs/features/<slug>/
-  spec.md       ← v1
-  spec-v2.md    ← regeração forçada  ⬅ spec atual
-  plan.md       ⬅ plano atual (spec e plan versionam independente)
-```
-
-A **maior versão é o documento atual**: é ela que o `generate-plan` usa como contexto, que o `validate` valida, e que o `decompose` e o `implement` leem. Uma regeração **sem** force sobrescreve essa versão atual.
-
 ### Skill (`src/templates/skill/SKILL.md`)
 
 Skill que guia o usuário pelo fluxo via comandos como `/spec-wave spec 42`, `/spec-wave plan 42`, `/spec-wave decompose 42`. A skill lê o `.spec-wave.json` local, detecta o estado atual e executa os comandos corretos sem abrir wizards interativos. Instale-a no seu agente com `install-skill` (ver abaixo).
@@ -306,20 +286,52 @@ O Action `validate.yml` verifica se todas as seções obrigatórias estão prese
 
 ---
 
-### 6. Decompor em Stories e Tasks
+### 6. Decompor em Stories e Tasks (duas etapas)
+
+A decomposição não cria issues de uma vez. Primeiro nasce um **rascunho revisável**;
+as issues só são criadas depois que você aprova.
+
+**6a. Gerar o rascunho:**
 
 ```bash
 gh issue edit 12 --add-label "spec-wave:decompose"
 ```
 
-O Action `decompose.yml` usa IA para criar sub-issues da Feature #12:
+O Action grava `docs/features/<slug>/decomposition.md` no repositório e submete o
+arquivo à crítica adversarial. **Nenhuma issue é criada.**
+
+```markdown
+# Decomposição — [FEATURE] Pagamento com PIX
+<!-- spec-wave:decomposition v1 issue=12 kind=stories -->
+
+## Story 1 — selecionar PIX como forma de pagamento
+
+**User story:** Como cliente, quero selecionar PIX, para pagar mais rápido
+**Depende de:** —
+
+### Task 1.1 — criar endpoint POST /orders/:id/payment/pix
+### Task 1.2 — integrar API do banco via webhook
+```
+
+Se a crítica encontrar contradições **graves**, ela comenta na issue citando
+`Story N` / `Task N.M`, aplica `spec-wave:critique-failed` e o Action **falha**.
+Você corrige o `decomposition.md` — o artefato que os achados referenciam — e
+reaplica `spec-wave:decompose`: o arquivo é criticado como está, sem ser regerado.
+
+**6b. Aplicar o rascunho aprovado:**
+
+```bash
+gh issue edit 12 --add-label "spec-wave:decompose-apply"
+```
+
+Agora as sub-issues da Feature #12 são criadas a partir do arquivo:
 
 ```
-#13 [STORY] Como cliente, quero selecionar PIX como forma de pagamento
+#13 [STORY] selecionar PIX como forma de pagamento
   #14 [TASK] Criar endpoint POST /orders/:id/payment/pix
   #15 [TASK] Integrar API do banco via webhook
   #16 [TASK] Exibir QR Code na tela de checkout
-#17 [STORY] Como cliente, quero receber confirmação do pagamento
+#17 [STORY] receber confirmação do pagamento
   #18 [TASK] Webhook de confirmação do banco
   #19 [TASK] Notificação por e-mail ao confirmar
 ```

package/bin/spec-wave.mjs

@@ -132,7 +132,6 @@ program
   .command('generate-plan')
   .description('Gera plan.md para uma Feature (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
-  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
   .action(async (options) => {
     const { generatePlan } = await import('../src/commands/generate-plan.mjs');
     await generatePlan(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -142,7 +141,6 @@ program
   .command('generate-spec')
   .description('Gera spec.md para uma Feature (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
-  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
   .action(async (options) => {
     const { generateSpec } = await import('../src/commands/generate-spec.mjs');
     await generateSpec(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -159,9 +157,9 @@ program
 
 program
   .command('decompose')
-  .description('Decompõe uma Feature em Stories e Tasks (usado pelo GitHub Action)')
+  .description('Gera o rascunho da decomposição em decomposition.md; com --apply, cria as Stories/Tasks a partir do rascunho revisado (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
-  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
+  .option('--apply', 'Aplica o decomposition.md já revisado: cria as issues (sem esta flag, apenas gera/critica o rascunho)')
   .action(async (options) => {
     const { decompose } = await import('../src/commands/decompose.mjs');
     await decompose(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -215,6 +213,18 @@ program
     await task({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('move')
+  .description('Move qualquer item do board (Feature, Story, Task, Bug, RFC) para uma Etapa — a Etapa nunca retrocede')
+  .argument('<n>', 'Número da issue, ex.: 8 ou #8')
+  .argument('<etapa>', 'Etapa de destino, com ou sem emoji, ex.: "code review", "Homologação", "🎉 Done"')
+  .option('--status <valor>', 'Valor do campo Status no destino: Todo, In Progress ou Done (default: Todo)')
+  .action(async (n, etapa, options) => {
+    const { move } = await import('../src/commands/move.mjs');
+    await move({ issue: n, stage: etapa, ...options })
+      .catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('story')
   .description('Gerencia uma Story no board: review (move para Code Review)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-graphql.mjs

@@ -198,7 +198,6 @@ export async function listSubIssues(token, issueNodeId) {
               number
               title
               body
-              state
               labels(first: 20) { nodes { name } }
             }
           }
@@ -212,9 +211,6 @@ export async function listSubIssues(token, issueNodeId) {
     title: n.title,
     body: n.body || '',
     nodeId: n.id,
-    // 'OPEN' | 'CLOSED' (GraphQL) normalizado para o vocabulário do REST, que
-    // é o que o resto do código compara (issue.state === 'closed').
-    state: n.state === 'CLOSED' ? 'closed' : 'open',
     labels: (n.labels?.nodes || []).map(l => l.name),
   }));
 }

package/src/api/github-rest.mjs

@@ -101,19 +101,6 @@ export async function getIssue(token, owner, repo, issueNumber) {
   return res.data;
 }
 
-// Fecha uma issue. Usado pelo re-decompose forçado para limpar as sub-issues
-// da decomposição anterior antes de gerar as novas.
-export async function closeIssue(token, owner, repo, issueNumber, reason = 'not_planned') {
-  const octokit = makeOctokit(token);
-  await octokit.rest.issues.update({
-    owner,
-    repo,
-    issue_number: issueNumber,
-    state: 'closed',
-    state_reason: reason,
-  });
-}
-
 export async function deleteLabel(token, owner, repo, name) {
   const octokit = makeOctokit(token);
   try {

package/src/commands/code-review.mjs

@@ -1,11 +1,10 @@
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, getPR, commentOnIssue } from '../api/github-rest.mjs';
 import { addProjectItem, getIssueParent, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
-import { CONFIG_FILE, STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType } from '../config.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType } from '../config.mjs';
 
 // Ao abrir o PR: Stories/Feature → Etapa "👀 Code Review" (Status "Todo");
 // Tasks → Etapa "🎉 Done" (Status "Done"), pois a implementação da task terminou.
@@ -118,11 +117,9 @@ export async function codeReview({ prNumber }) {
   const token = await resolveToken();
   const projectToken = process.env.PROJECT_TOKEN || token;
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const cfgPath = path.join(process.cwd(), CONFIG_FILE);
-  let cfg = {};
-  try { if (existsSync(cfgPath)) cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch {}
-  const owner = envOwner || cfg.owner;
-  const repo = envRepo || cfg.repo;
+  const { config: cfg } = loadConfig();
+  const owner = envOwner || cfg?.owner;
+  const repo = envRepo || cfg?.repo;
 
   if (!owner || !repo) {
     throw new Error(