@spec-wave/cli 0.17.0 → 0.18.0

package/bin/spec-wave.mjs

@@ -170,6 +170,15 @@ program
     await generatePlan(options).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('critique')
+  .description('Re-critica o plan.md COMO ESTÁ, sem regerar — para depois de corrigi-lo à mão')
+  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .action(async (options) => {
+    const { critique } = await import('../src/commands/generate-plan.mjs');
+    await critique(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('generate-spec')
   .description('Gera spec.md para uma Feature — roda no GitHub Action ou localmente')

package/package.json

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

package/src/commands/generate-plan.mjs

@@ -244,3 +244,56 @@ export async function generatePlan({ issueNumber }) {
     await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });
   }
 }
+
+/**
+ * Roda a crítica adversarial sobre o `plan.md` COMO ESTÁ, sem regerar.
+ *
+ * Existe porque o único gatilho do plano regenerava o documento. O SKILL manda
+ * "corrija o plan.md e reaplique o gatilho" — e o gatilho descartava a correção
+ * feita à mão, gerando outro plano do zero. Pior: com o plano regenerado, as
+ * decisões que o Tech Leader tomou sobre os findings anteriores deixam de casar
+ * (os achados são outros), e o portão volta à estaca zero.
+ *
+ * Mesma semântica que o `decompose` já tinha para o rascunho: documento
+ * presente é criticado como está. Para gerar outro plano do zero, o caminho
+ * continua sendo `spec-wave:plan`.
+ */
+export async function critique({ issueNumber }) {
+  const token = await resolveToken();
+  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'critique' });
+  console.log(`Modo de execução: ${mode}`);
+
+  const n = parseInt(issueNumber, 10);
+  const issue = await getIssue(token, owner, repo, n);
+  const type = detectIssueType(issue);
+  if (!allowsSpecPlan(type)) {
+    console.log(`Issue #${n} é ${type}: não usa plan.md, nada a criticar.`);
+    await removeLabel(token, owner, repo, n, LABEL_CRITIQUE).catch(() => {});
+    return;
+  }
+
+  const featureDir = resolveFromRoot(root, `docs/features/${slugify(issue.title)}`);
+  const planPath = path.join(featureDir, 'plan.md');
+  if (!existsSync(planPath)) {
+    console.log('plan.md ainda não existe — gere o plano antes de criticá-lo.');
+    await removeLabel(token, owner, repo, n, LABEL_CRITIQUE).catch(() => {});
+    await commentOnIssue(token, owner, repo, n,
+      'ℹ️ **Nada a criticar:** o `plan.md` ainda não foi gerado. ' +
+      'Aplique `spec-wave:plan` para gerá-lo.').catch(() => {});
+    return;
+  }
+  const specPath = path.join(featureDir, 'spec.md');
+
+  const issueLabels = labelNames(issue.labels || []);
+  await critiquePlan({
+    token, owner, repo, issueNumber: n,
+    spec: existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null,
+    plan: readFileSync(planPath, 'utf-8'),
+    techContextYaml: buildTechContext({ issueBody: issue.body || '' }).yaml,
+    labels: issueLabels, config, usage: [],
+  });
+
+  // O gatilho sai SEMPRE: `issues: [labeled]` não redispara com a label ainda
+  // aplicada, então mantê-la deixaria a issue sem como pedir outra crítica.
+  await removeLabel(token, owner, repo, n, LABEL_CRITIQUE).catch(() => {});
+}

package/src/config.mjs

@@ -338,10 +338,15 @@ export const LABEL_NEEDS_HUMAN = 'spec-wave:needs-human';
 // depois que a crítica passa: sem ela, o risco aceito some da vista assim que a
 // rodada seguinte roda limpa, e ninguém mais sabe que houve uma decisão.
 export const LABEL_RISK_ACCEPTED = 'spec-wave:risk-accepted';
+// Gatilho de re-crítica do plano. Separado de `spec-wave:plan` porque aquele
+// REGERA o documento: reaplicá-lo depois de corrigir o plan.md à mão descarta
+// a correção — e troca os findings, fazendo as decisões do TL deixarem de casar.
+export const LABEL_CRITIQUE = 'spec-wave:critique';
 
 export const TRIGGER_LABELS = [
   { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
   { name: 'spec-wave:plan',          color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
+  { name: LABEL_CRITIQUE,            color: 'BFD4F2', description: 'Re-criticar o plan.md COMO ESTÁ, sem regerar' },
   { name: 'spec-wave:ready',         color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
   { name: 'spec-wave:plan-approved', color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
   { name: LABEL_DECOMPOSE,           color: 'BFD4F2', description: 'Gerar/re-criticar o rascunho da decomposição (decomposition.md)' },
@@ -385,6 +390,7 @@ export function labelNames(issueOrLabels) {
 export const WORKFLOW_FILES = [
   'generate-bug.yml',
   'generate-plan.yml',
+  'critique.yml',
   'generate-spec.yml',
   'validate.yml',
   'decompose.yml',

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "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.",
   "author": {
     "name": "Astratech",

package/src/templates/skill/SKILL.md

@@ -98,6 +98,7 @@ Essa é a sequência completa, mas **cada tipo de artefato percorre só um trech
 Labels de gatilho:
 - `spec-wave:spec` → dispara `generate-spec.yml` → gera `spec.md` (especificação funcional, primeiro)
 - `spec-wave:plan` → dispara `generate-plan.yml` → gera `plan.md` (plano técnico, a partir da spec)
+- `spec-wave:critique` → dispara `critique.yml` → **re-critica o `plan.md` COMO ESTÁ**, sem regerar. É o gatilho de retomada depois de corrigir o plano à mão — `spec-wave:plan` geraria outro do zero, descartando a correção.
 - `spec-wave:ready` → dispara `validate.yml` → valida ambos os arquivos
 - `spec-wave:decompose` → dispara `decompose.yml` → gera (ou **re-critica**) o **rascunho** em `decomposition.md`. **Não cria issue nenhuma.**
 - `spec-wave:decompose-apply` → dispara o mesmo workflow em modo aplicação → cria as Stories e Tasks **a partir do rascunho revisado**
@@ -269,7 +270,7 @@ A saída da crítica é **estruturada e validada por schema**: `severity` só ac
 
 | Reprovou depois de | O que corrigir | Como retomar |
 |--------------------|----------------|--------------|
-| `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija/regere → remova `spec-wave:critique-failed` → reaplique `spec-wave:ready` |
+| `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija → remova `spec-wave:critique-failed` → reaplique **`spec-wave:critique`** (re-critica o arquivo como está). `spec-wave:ready` apenas valida, **não** re-critica; e `spec-wave:plan` **regera** o plano, descartando a correção. |
 | `decompose` (rascunho) | **`decomposition.md`** — os achados citam **`Story N`** e **`Task N.M`**, que são os títulos desse arquivo | edite o arquivo e commite → remova `spec-wave:critique-failed` → reaplique `spec-wave:decompose` (ele **critica o arquivo como está**, sem regerar) |
 
 > ⚠️ No contexto do `decompose`, os achados são sobre as **Stories propostas**, não sobre o `plan.md`. Corrigir o plan não influencia o rascunho já gravado — edite o `decomposition.md` diretamente. Foi exatamente essa confusão que fazia o ciclo não convergir.

package/src/templates/workflows/critique.yml

@@ -0,0 +1,38 @@
+name: Critique Plan
+
+on:
+  issues:
+    types: [labeled]
+
+concurrency:
+  group: spec-wave-critique-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  critique:
+    if: >
+      github.event.label.name == 'spec-wave:critique' &&
+      contains(github.event.issue.title, '[FEATURE]')
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      # read: a crítica LÊ o plan.md do checkout e não escreve arquivo nenhum —
+      # ao contrário do generate-plan, que commita o documento gerado.
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Critique plan.md as-is
+        run: npx @spec-wave/cli@{{CLI_VERSION}} critique --issue-number ${{ github.event.issue.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          GITHUB_REPOSITORY: ${{ github.repository }}