@spec-wave/cli 0.27.0 → 0.29.0

package/src/lib/critique.mjs

@@ -44,12 +44,16 @@ export const CRITIQUE_TOOL_NAME = 'registrar_findings';
 // Rótulo do artefato auditado, por contexto — usado no cabeçalho do comentário.
 const KIND_LABEL = {
   plan: 'plan.md', stories: 'decomposition.md', bug: 'bug.md', spec: 'spec.md',
+  conjunto: 'specs da milestone (conjunto)',
 };
 
 // Prompt por tipo de auditoria. 'plan' audita o plan.md contra a spec;
-// 'stories' audita a decomposição proposta contra spec + plan.
+// 'stories' audita a decomposição proposta contra spec + plan; 'conjunto'
+// audita TODAS as specs de uma milestone entre si — é a única cujo objeto é a
+// relação entre documentos, não um documento.
 const KIND_PROMPT = {
   plan: 'plan/critique', stories: 'decompose/critique', bug: 'bug/critique', spec: 'spec/critique',
+  conjunto: 'audit/critique',
 };
 
 // A decomposição virou arquivo revisável (decomposition.md): um finding só é
@@ -62,6 +66,13 @@ const ANCHOR_RULE = `Cada finding DEVE citar, no campo "anchor", o trecho audita
 - "geral" quando o problema for da decomposição como um todo (ex.: requisito da spec que nenhuma Story cobre).
 Use EXATAMENTE os números que aparecem nos títulos "## Story N — ..." e "### Task N.M — ..." do documento.`;
 
+// No conjunto o achado vive ENTRE documentos: sem dizer quais, o leitor relê a
+// milestone inteira procurando o par. O campo é validado como array de números
+// de issue — é o equivalente da âncora "Story N" para este contexto.
+const FEATURES_RULE = `Cada finding DEVE listar, no campo "features", os números das issues das Features envolvidas
+(ex.: [412, 415] para uma contradição entre as duas; [412] quando o problema é de uma spec só,
+visto à luz das outras). Use EXATAMENTE os números que aparecem nos títulos "## spec.md — #N ..." fornecidos.`;
+
 /**
  * Monta o system prompt da crítica: corpo editável + contrato de máquina.
  *
@@ -79,7 +90,8 @@ Use EXATAMENTE os números que aparecem nos títulos "## Story N — ..." e "###
  */
 function buildSystemPrompt(kind, cwd) {
   const prompt = loadPrompt(KIND_PROMPT[kind] || KIND_PROMPT.plan, ...(cwd ? [{ cwd }] : []));
-  const anchor = kind === 'stories' ? `\n\n${ANCHOR_RULE}` : '';
+  const anchor = kind === 'stories' ? `\n\n${ANCHOR_RULE}`
+    : kind === 'conjunto' ? `\n\n${FEATURES_RULE}` : '';
 
   const contract = `## Contrato de saída
 
@@ -134,6 +146,17 @@ function critiqueJsonSchema(kind) {
     };
     required.push('anchor');
   }
+  if (kind === 'conjunto') {
+    properties.features = {
+      type: 'array',
+      items: { type: 'integer' },
+      minItems: 1,
+      description:
+        'Números das issues das Features envolvidas no finding — os "#N" dos títulos ' +
+        '"## spec.md — #N ..." fornecidos.',
+    };
+    required.push('features');
+  }
   return {
     type: 'object',
     properties: {
@@ -245,10 +268,23 @@ export function validateCritiquePayload(payload) {
       );
     }
     const extra = itemKeys.filter(
-      k => k !== 'severity' && k !== 'text' && k !== 'anchor' && k !== 'quote');
+      k => k !== 'severity' && k !== 'text' && k !== 'anchor' && k !== 'quote' && k !== 'features');
     if (extra.length > 0) {
       throw new CritiqueSchemaError(`${at} tem campo(s) não reconhecido(s): ${extra.join(', ')}.`);
     }
+    // `features` (kind 'conjunto'): quais issues o finding atravessa. Fora do
+    // formato é erro de schema — a localização é a metade do valor do achado.
+    let features = null;
+    if ('features' in item) {
+      if (!Array.isArray(item.features)
+        || item.features.length === 0
+        || !item.features.every(n => Number.isInteger(n) && n > 0)) {
+        throw new CritiqueSchemaError(
+          `${at}.features deveria ser um array não-vazio de números de issue, veio ${describe(item.features)}.`
+        );
+      }
+      features = [...new Set(item.features)];
+    }
     // Normaliza só caixa e espaço — isso não é ambiguidade semântica. "GRAVE"
     // passa; "gravíssimo", "critical" e "high" NÃO.
     const severity = typeof item.severity === 'string' ? item.severity.trim().toLowerCase() : null;
@@ -268,6 +304,7 @@ export function validateCritiquePayload(payload) {
     return {
       severity,
       ...(anchor ? { anchor } : {}),
+      ...(features ? { features } : {}),
       ...(quote ? { quote } : {}),
       text: item.text.trim(),
     };
@@ -721,6 +758,12 @@ const KIND_TRAILER = {
       'até ser removida. Um bug com causa raiz errada produz correção errada — corrija o ' +
       '`bug.md` e reaplique `spec-wave:bug`.'
     : '_Findings menores não bloqueiam a triagem._'),
+  // O conjunto roda fora do ciclo de tentativas e não aplica label: o achado é
+  // decisão de PO entre duas specs, e o destino dele é a issue das duas pontas.
+  conjunto: (graves) => (graves
+    ? '⛔ Há findings **graves** entre specs: comente nas issues DOS DOIS lados, apontando ' +
+      'uma para a outra, e resolva antes de gerar os planos — cada spec sozinha parece certa.'
+    : '_Nenhuma contradição entre as specs que exija decisão antes dos planos._'),
 };
 
 /**
@@ -782,8 +825,12 @@ export function renderCritiqueMarkdown({
     return parts.join('\n\n');
   }
 
+  // Localização do finding: a âncora ("Story N") ou, no conjunto, as Features
+  // que ele atravessa ("#412 × #415").
+  const onde = f => f.anchor
+    || (f.features?.length ? f.features.map(n => `#${n}`).join(' × ') : '');
   const bullets = list => list
-    .map(f => `- ${f.anchor ? `**${f.anchor}** — ` : ''}${sanitizeFindingText(f.text)}`)
+    .map(f => `- ${onde(f) ? `**${onde(f)}** — ` : ''}${sanitizeFindingText(f.text)}`)
     .join('\n');
   if (graves.length > 0) parts.push(`### ❌ Graves\n\n${bullets(graves)}`);
   if (menores.length > 0) parts.push(`### ⚠️ Menores\n\n${bullets(menores)}`);
@@ -791,7 +838,7 @@ export function renderCritiqueMarkdown({
     parts.push(
       '### ↘️ Rebaixados (vieram como graves, não bloqueiam)\n\n' +
       rebaixados
-        .map(f => `- ${f.anchor ? `**${f.anchor}** — ` : ''}${sanitizeFindingText(f.text)}\n` +
+        .map(f => `- ${onde(f) ? `**${onde(f)}** — ` : ''}${sanitizeFindingText(f.text)}\n` +
           `  - _Rebaixado: ${sanitizeFindingText(f.downgradeReason || 'não se sustenta como bloqueio')}._`)
         .join('\n') +
       '\n\n_Continuam valendo como observação. Se algum for mesmo grave, corrija o documento ' +
@@ -811,6 +858,7 @@ export function renderCritiqueMarkdown({
         fingerprint: findingFingerprint({ kind, anchor: f.anchor, text: f.text }),
         severity: f.severity,
         anchor: f.anchor || null,
+        ...(f.features?.length ? { features: f.features } : {}),
         text: sanitizeFindingText(f.text),
         ...(f.downgraded ? { downgradedFrom: f.downgraded, downgradeReason: f.downgradeReason } : {}),
       })),
@@ -832,8 +880,10 @@ export function renderCritiqueMarkdown({
  * chamador decidir entre seguir com aviso e abortar.
  *
  * @param {object} params
- * @param {'plan'|'stories'|'bug'} params.kind o que está sendo auditado
+ * @param {'plan'|'stories'|'bug'|'spec'|'conjunto'} params.kind o que está sendo auditado
  * @param {string} [params.spec] conteúdo do spec.md
+ * @param {Array<{number:number, title:string, content:string}>} [params.specs]
+ *        kind 'conjunto': TODAS as specs da milestone, uma seção por Feature
  * @param {string} [params.plan] conteúdo do plan.md
  * @param {string} [params.techContextYaml] tech_context serializado em YAML
  * @param {string} [params.decomposition] conteúdo do decomposition.md
@@ -847,12 +897,17 @@ export function renderCritiqueMarkdown({
  * @returns {Promise<{grave, findings, markdown, attempt, model}>}
  */
 export async function runCritique({
-  kind, spec, plan, techContextYaml, decomposition, bugDoc, bugReport,
+  kind, spec, specs, plan, techContextYaml, decomposition, bugDoc, bugReport,
   attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
   model, labels = [], usage, cwd, decisions = null, standalone = false,
 } = {}) {
   const sections = [];
   if (spec) sections.push(`## spec.md\n\n${spec}`);
+  // Conjunto: o título de cada seção carrega o "#N" que o campo `features` dos
+  // findings cita de volta — é o contrato de localização deste kind.
+  for (const s of specs || []) {
+    sections.push(`## spec.md — #${s.number} ${s.title}\n\n${s.content}`);
+  }
   if (plan) sections.push(`## plan.md\n\n${plan}`);
   if (techContextYaml) sections.push(`## tech_context\n\n\`\`\`yaml\n${techContextYaml}\n\`\`\``);
   // Cerca de QUATRO crases: o decomposition.md contém cercas de três, e uma
@@ -898,7 +953,8 @@ export async function runCritique({
   // sustenta não deve entrar no contador de tentativas nem bloquear o Action.
   const findings = downgradeUnsupportedFindings(
     report.value.findings,
-    [spec, plan, decomposition, bugDoc, techContextYaml].filter(Boolean),
+    [spec, ...(specs || []).map(s => s.content), plan, decomposition, bugDoc, techContextYaml]
+      .filter(Boolean),
   );
   const grave = findings.some(f => f.severity === 'grave');
   const rebaixados = findings.filter(f => f.downgraded).length;

package/src/lib/pr-branch.mjs

@@ -130,7 +130,11 @@ export function buildCommitMessage({ version = CLI_VERSION, files = [] } = {}) {
  * @param {{created: string[], updated: string[], removed: string[]}|null} [a.labels]
  *        labels EFETIVAMENTE aplicadas (não o diff detectado — o corpo não pode
  *        prometer o que falhou)
- * @param {string[]} [a.skill] nomes dos agentes cuja skill foi atualizada localmente
+ * @param {string[]|{inPr?: string[], local?: string[]}} [a.skill] agentes cuja
+ *        skill foi atualizada: `inPr` os que entraram no commit (a cópia da skill
+ *        É versionada na base) e `local` os que ficaram só na máquina. Um array
+ *        simples é lido como `local` — a forma antiga, de quando a skill nunca
+ *        entrava no PR.
  * @returns {string} markdown
  */
 export function composePrBody({
@@ -173,14 +177,31 @@ export function composePrBody({
     if (labels.removed.length) l.push(`- removidas (descontinuadas): ${labels.removed.map(n => `\`${n}\``).join(', ')}`);
   }
 
-  if (skill.length) {
+  // A skill não é mais declarada "fora do repositório" por premissa: quem chama
+  // consultou a base arquivo a arquivo (decideSkillInPr) e diz aqui o que
+  // realmente aconteceu. Afirmar "não faz parte do repositório" para um repo que
+  // versiona `.claude/skills/spec-wave/SKILL.md` mandava o revisor aprovar um PR
+  // incompleto — e deixava o repositório distribuindo a skill da versão anterior.
+  const skillInPr = Array.isArray(skill) ? [] : (skill?.inPr ?? []);
+  const skillLocal = Array.isArray(skill) ? skill : (skill?.local ?? []);
+  if (skillInPr.length || skillLocal.length) {
     l.push('');
-    l.push('## Skill dos agentes — fora deste PR');
+    l.push('## Skill dos agentes');
     l.push('');
-    l.push(
-      `Atualizada localmente em: ${skill.map(n => `\`${n}\``).join(', ')}. ` +
-      'Não faz parte do repositório.'
-    );
+    if (skillInPr.length) {
+      l.push(
+        `Incluída neste PR, nos arquivos listados acima: ${skillInPr.map(n => `\`${n}\``).join(', ')}. ` +
+        `Esta cópia da skill é conteúdo do repositório — o merge em \`${base}\` é o que a ` +
+        'entrega a quem clonar.'
+      );
+    }
+    if (skillLocal.length) {
+      if (skillInPr.length) l.push('');
+      l.push(
+        `Atualizada só na máquina local: ${skillLocal.map(n => `\`${n}\``).join(', ')}. ` +
+        'Esta cópia não é versionada no repositório e não faz parte deste PR.'
+      );
+    }
   }
 
   l.push('');
@@ -235,6 +256,74 @@ export function decideConfigInPr({ remote, desired, willRegenerate = false, forc
   return { included: true, reason: 'versionado na base e divergente do local' };
 }
 
+/**
+ * Uma cópia da skill entra no PR? (função PURA)
+ *
+ * MESMA regra do .spec-wave.json, pelo mesmo motivo: onde o arquivo mora é
+ * decisão do projeto, e o update não pode mudá-la sozinho — nem passando a
+ * versionar o que ninguém commitou, nem deixando de atualizar o que o repositório
+ * já distribui. A diferença é que aqui não existe `willRegenerate`: o conteúdo
+ * desejado da skill é renderizado do pacote e já está pronto na hora de decidir.
+ *
+ * Vale por ARQUIVO, não por agente: o destino do Codex (`.agents/skills/`) são 20+
+ * arquivos, e nada garante que o repositório versione todos.
+ *
+ * @param {object} [a]
+ * @param {string|null|undefined} [a.remote] conteúdo do arquivo na base (null/undefined = não versionado)
+ * @param {string|null} [a.desired] conteúdo que a instalação local grava
+ * @param {boolean|undefined} [a.force] undefined | true (--skill-in-pr) | false (--no-skill-in-pr)
+ * @returns {{ included: boolean, reason: string }}
+ */
+export function decideSkillInPr({ remote, desired, force } = {}) {
+  const versioned = remote !== null && remote !== undefined;
+  if (force === false) return { included: false, reason: '--no-skill-in-pr' };
+  if (!desired) return { included: false, reason: 'sem conteúdo local para enviar' };
+  if (force === true) {
+    return versioned
+      ? { included: true, reason: '--skill-in-pr' }
+      : { included: true, reason: '--skill-in-pr (passa a versionar a skill)' };
+  }
+  if (!versioned) {
+    return {
+      included: false,
+      reason: 'não está versionada na base, segue apenas local ' +
+        '(use --skill-in-pr para versioná-la)',
+    };
+  }
+  if (remote === desired) return { included: false, reason: 'já idêntica na base' };
+  return { included: true, reason: 'versionada na base e divergente do local' };
+}
+
+/**
+ * Dica para descartar a cópia local de um arquivo que também foi no PR (PURA).
+ *
+ * `git checkout -- <arquivo>` restaura a versão do ÍNDICE, isto é, a do HEAD da
+ * branch que está no checkout. Ele só descarta uma cópia redundante quando o
+ * clone está na base; rodado de uma branch de trabalho, faz o oposto do que a
+ * mensagem promete — reverte o arquivo para a versão antiga daquela branch. A
+ * dica, portanto, depende da branch corrente, que a CLI já sabe consultar.
+ *
+ * @param {object} [a]
+ * @param {string} [a.file] caminho do arquivo, relativo à raiz
+ * @param {string} [a.base] branch base do Pull Request
+ * @param {string|null} [a.current] branch do clone local (null = detached/fora de git)
+ * @returns {string} frase única, para o `outro` do comando
+ */
+export function composeConfigCleanupHint({ file = CONFIG_FILE, base = 'main', current = null } = {}) {
+  const cabeca = `O ${file} local ficou igual ao do PR`;
+  if (current === base) {
+    return `${cabeca} — depois do merge, descarte a cópia local com ` +
+      `\`git checkout -- ${file}\` antes do \`git pull\`.`;
+  }
+  const onde = current
+    ? `o checkout está em "${current}", e \`git checkout -- ${file}\` ali restauraria a ` +
+      'versão antiga dessa branch'
+    : `o checkout não está numa branch, e \`git checkout -- ${file}\` ali restauraria a ` +
+      'versão antiga do HEAD atual';
+  return `${cabeca} — ${onde}. Depois do merge, descarte a cópia local na base: ` +
+    `\`git switch ${base} && git checkout -- ${file}\`.`;
+}
+
 /**
  * Traduz o erro cru da Git Data API para uma dica acionável (função PURA).
  *

package/src/lib/pr-step.mjs

@@ -82,21 +82,26 @@ export function nextPrStep({
     return { steps: [], warnings, reason: 'PR fechado sem merge.', blocked: null };
   }
 
-  if (merged) warnings.push('PR já mergeado — o board é atualizado como se o review tivesse acabado agora.');
-  if (merged && !approved) warnings.push('Mergeado sem review aprovada: o `qa` não roda (o qa.yml também não rodaria).');
-  if (changesRequestedAfterApproval) {
+  // Merge move até 🧪 QA mesmo sem aprovação formal: o autor não consegue
+  // aprovar o próprio PR (fluxo solo nunca teria QA por construção), e QA de
+  // verdade começa com o código integrado. O qa.yml tem o mesmo gatilho de
+  // merge — os dois modos continuam idênticos.
+  if (merged) warnings.push('PR já mergeado — merge move até 🧪 QA, com ou sem aprovação formal.');
+  if (changesRequestedAfterApproval && !merged) {
     warnings.push('Há aprovação E pedido de mudanças: o Actions moveria assim mesmo — confirme com `--yes`.');
   }
 
-  let steps = approved ? ['code-review', 'qa'] : ['code-review'];
+  let steps = (approved || merged) ? ['code-review', 'qa'] : ['code-review'];
   if (only) steps = steps.filter(s => s === only);
 
   return {
     steps,
     warnings,
-    reason: approved
-      ? 'PR com review aprovada: board até 🧪 QA.'
-      : 'PR sem review aprovada: board até 👀 Code Review.',
+    reason: merged
+      ? 'PR mergeado: board até 🧪 QA.'
+      : approved
+        ? 'PR com review aprovada: board até 🧪 QA.'
+        : 'PR sem review aprovada: board até 👀 Code Review.',
     blocked: null,
   };
 }