@spec-wave/cli 0.26.0 → 0.28.0

package/src/commands/update.mjs

@@ -12,7 +12,7 @@ import {
 } from '../api/github-rest.mjs';
 import {
   resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
-  decideConfigInPr, explainGitWriteError,
+  decideConfigInPr, decideSkillInPr, composeConfigCleanupHint, explainGitWriteError,
 } from '../lib/pr-branch.mjs';
 // MESMO readTemplate do init: resolve {{CLI_VERSION}} antes da comparação byte a
 // byte com o remoto. Se só o init resolvesse, todo update veria os workflows
@@ -20,10 +20,11 @@ import {
 import { readTemplate } from '../lib/templates.mjs';
 import {
   TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
-  mergeAgentsFile, resolveDest, isDetected, skillCopyReason, versionBanner,
+  mergeAgentsFile, mergeAgentsContent, resolveDest, isDetected, skillCopyReason, versionBanner,
 } from './install-skill.mjs';
 import { planPluginSkillFiles } from '../lib/plugin-skills.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
+import { currentGitBranch } from '../lib/repo-links.mjs';
 
 // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
 const REPO_FILES = [
@@ -68,6 +69,41 @@ function applySkill(job) {
   writeFileSync(job.dest.path, content, 'utf-8');
 }
 
+/**
+ * Arquivos que uma atualização de skill grava, em caminhos RELATIVOS à raiz do
+ * repositório — a chave para perguntar à base se aquela cópia é versionada.
+ *
+ * Devolve [] quando o destino cai FORA da raiz, e é o que dispensa um caso
+ * especial para `--global`: `~/.claude/skills/...` e o `~/.gemini/AGENTS.md` do
+ * Antigravity jamais são conteúdo de repositório, e `path.relative` já diz isso.
+ *
+ * O formato `agents` (AGENTS.md) devolve `block` em vez de `content`: o conteúdo
+ * final depende do que existe na BASE — mesclar no arquivo local arrastaria para
+ * dentro do PR as edições não commitadas do desenvolvedor.
+ *
+ * @param {{dest: {path: string, format: string}, desired?: string}} job
+ * @param {string} repoRoot
+ * @returns {Array<{ relPath: string, content?: string, block?: string }>}
+ */
+export function skillRepoTargets(job, repoRoot) {
+  const items = job.dest.format === 'skills-dir'
+    ? planPluginSkillFiles(job.dest.path, CLI_VERSION, versionBanner)
+        .map(f => ({ absPath: f.path, content: f.content }))
+    : [{
+        absPath: job.dest.path,
+        ...(job.dest.format === 'agents' ? { block: job.desired } : { content: job.desired }),
+      }];
+
+  const out = [];
+  for (const { absPath, ...rest } of items) {
+    const rel = path.relative(repoRoot, absPath);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+    // A API do GitHub fala POSIX; path.relative devolve no separador do SO.
+    out.push({ ...rest, relPath: rel.split(path.sep).join('/') });
+  }
+  return out;
+}
+
 /**
  * Compara ALL_LABELS com as labels do repo (função PURA — testável).
  *
@@ -325,6 +361,70 @@ export async function update(options = {}) {
     }
   }
 
+  // 2d) Skill: a BASE versiona alguma destas cópias?
+  //
+  // Até aqui o update gravava a skill em disco e o corpo do PR AFIRMAVA ao
+  // revisor que ela "não faz parte do repositório" — premissa fixa. Em repos que
+  // versionam `.claude/skills/spec-wave/SKILL.md` (ou `.agents/skills/`, ou o
+  // AGENTS.md) isso era falso duas vezes: sobrava um commit manual a cada bump, e
+  // até ele o repositório seguia distribuindo a skill da versão anterior para
+  // quem clonasse. A checagem é a MESMA do .spec-wave.json — perguntar à base —,
+  // e a política também: só entra no PR o que o projeto já versiona.
+  let skillPrFiles = [];        // [{ relPath, content, reason, agent }]
+  // agente → motivo da PRIMEIRA cópia incluída. É o motivo que o resumo mostra:
+  // dizer "versionada no repo" para uma cópia que entrou por `--skill-in-pr`
+  // seria repetir, em miniatura, a premissa que este código veio corrigir.
+  const skillPrAgents = new Map();
+  // `skillRepoTargets` já devolve vazio para o que mora fora da raiz, o que cobre
+  // o `--global` inteiro sem um caso especial: nada a perguntar, nada a gastar.
+  const skillCandidates = prMode
+    ? skillJobs
+        .map(job => ({ job, targets: skillRepoTargets(job, path.dirname(configPath)) }))
+        .filter(c => c.targets.length)
+    : [];
+  if (skillCandidates.length) {
+    const tk = await getToken();
+    const s = p.spinner();
+    s.start('Verificando se o repositório versiona a skill...');
+    try {
+      for (const { job, targets } of skillCandidates) {
+        // Em paralelo: o destino do Codex são 20+ arquivos, e um GET por vez
+        // transformaria a checagem na parte mais lenta do comando.
+        const remotes = await Promise.all(
+          targets.map(t => getFileContent(tk, owner, repo, t.relPath, base))
+        );
+        targets.forEach((t, i) => {
+          const remote = remotes[i];
+          const desired = t.block !== undefined
+            ? mergeAgentsContent(remote ?? '', t.block)
+            : t.content;
+          const d = decideSkillInPr({ remote, desired, force: options.skillInPr });
+          if (!d.included) return;
+          skillPrFiles.push({
+            relPath: t.relPath,
+            content: desired,
+            reason: remote == null ? 'ausente' : 'desatualizado',
+            agent: job.target.name,
+          });
+          if (!skillPrAgents.has(job.target.name)) skillPrAgents.set(job.target.name, d.reason);
+        });
+      }
+      s.stop(skillPrFiles.length
+        ? `Skill versionada no repositório: ${skillPrFiles.length} arquivo(s) vão no Pull Request.`
+        : 'A skill não é versionada neste repositório — segue apenas local.');
+    } catch (err) {
+      // Falhar aqui não pode custar o update inteiro: sem a resposta da base, a
+      // skill volta a ser só local — o comportamento anterior, agora explícito.
+      s.stop('');
+      p.log.warn(`Não foi possível checar a skill na base: ${err.message} — ela seguirá apenas local.`);
+      skillPrFiles = [];
+      skillPrAgents.clear();
+    }
+  }
+  const skillLocalAgents = skillJobs
+    .map(j => j.target.name)
+    .filter(n => !skillPrAgents.has(n));
+
   // Decisão preliminar sobre o config. O conteúdo regenerado ainda não existe;
   // `willRegenerate` cobre isso, porque o regenerado SEMPRE difere do remoto
   // (refreshedAt muda a cada execução). Na aplicação a decisão é recalculada com
@@ -355,21 +455,39 @@ export async function update(options = {}) {
   const lines = [];
   if (skillJobs.length) {
     lines.push(chalk.bold('Skill:'));
-    for (const j of skillJobs) lines.push(`  ${chalk.yellow('↻')} ${j.target.name} (${j.reason})\n     ${chalk.dim(j.dest.path)}`);
+    for (const j of skillJobs) {
+      const destino = skillPrAgents.has(j.target.name)
+        ? chalk.dim(` → vai no PR: ${skillPrAgents.get(j.target.name)}`)
+        : '';
+      lines.push(`  ${chalk.yellow('↻')} ${j.target.name} (${j.reason})${destino}\n     ${chalk.dim(j.dest.path)}`);
+    }
   }
   if (configStale) {
     lines.push(chalk.bold('Config local:'));
     lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} — ${configStale.reason}` +
       (configStale.canApply ? '' : chalk.dim(' (sem project.id — rode `init` sem --skip-project)')));
   }
+  // Cabeçalho ÚNICO no modo PR: workflows, skill e config viajam no mesmo commit,
+  // e três títulos para um commit só sugeriam três destinos diferentes.
+  let prHeaderShown = false;
+  const prHeader = () => {
+    if (prHeaderShown) return;
+    prHeaderShown = true;
+    lines.push(chalk.bold(`Pull Request (${branch} → ${base}):`));
+  };
   if (repoFiles.length) {
-    lines.push(prMode
-      ? chalk.bold(`Arquivos do repo → Pull Request (${branch} → ${base}):`)
-      : chalk.bold('Arquivos do repo:'));
+    if (prMode) prHeader();
+    else lines.push(chalk.bold('Arquivos do repo:'));
     for (const f of repoFiles) lines.push(`  ${chalk.yellow('↻')} ${f.repoPath} (${f.reason})`);
   }
+  if (skillPrFiles.length) {
+    prHeader();
+    for (const f of skillPrFiles) {
+      lines.push(`  ${chalk.yellow('↻')} ${f.relPath} (${f.reason} — skill ${f.agent})`);
+    }
+  }
   if (prMode && configDecision.included) {
-    if (!repoFiles.length) lines.push(chalk.bold(`Pull Request (${branch} → ${base}):`));
+    prHeader();
     lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} (${configDecision.reason})`);
   }
   if (prMode && doConfig && !configDecision.included && configDecision.reason) {
@@ -388,7 +506,8 @@ export async function update(options = {}) {
   p.note(lines.join('\n'), `${total} item(ns) desatualizado(s)`);
 
   // --branch sem efeito: melhor dizer POR QUE do que criar uma branch inútil.
-  const prHasPayload = prMode && (repoFiles.length > 0 || configDecision.included);
+  const prHasPayload = prMode
+    && (repoFiles.length > 0 || skillPrFiles.length > 0 || configDecision.included);
   if (prRequested && options.skipRepo) {
     p.log.warn(
       '--branch ignorado junto com --skip-repo: o Pull Request existe justamente para ' +
@@ -408,7 +527,7 @@ export async function update(options = {}) {
 
   if (options.dryRun) {
     if (prHasPayload) {
-      const n = repoFiles.length + (configDecision.included ? 1 : 0);
+      const n = repoFiles.length + skillPrFiles.length + (configDecision.included ? 1 : 0);
       p.note(
         `Branch:    ${branch}${branchExists ? ' (já existe — o commit seria empilhado nela)' : ' (seria criada)'}\n` +
         `Base:      ${base}\n` +
@@ -516,6 +635,11 @@ export async function update(options = {}) {
     const tk = await getToken();
     const treeFiles = [
       ...repoFiles.map(f => ({ path: f.repoPath, reason: f.reason, content: f.local })),
+      ...skillPrFiles.map(f => ({
+        path: f.relPath,
+        reason: `${f.reason} — skill ${f.agent}`,
+        content: f.content,
+      })),
       ...(finalConfigDecision.included
         ? [{
             path: CONFIG_FILE,
@@ -562,7 +686,7 @@ export async function update(options = {}) {
               files: treeFiles,
               config: doConfig ? finalConfigDecision : null,
               labels: labelResult,
-              skill: skillJobs.map(j => j.target.name),
+              skill: { inPr: [...skillPrAgents.keys()], local: skillLocalAgents },
             }),
           });
           if (!pr) {
@@ -605,9 +729,16 @@ export async function update(options = {}) {
     (prUrl ? ` Revise e faça o merge do Pull Request: ${prUrl}` : '') +
     (!prMode && repoFiles.length ? ' Arquivos do repo foram commitados no remoto.' : '') +
     (configPending ? ` COMMITE o ${CONFIG_FILE} — quem clona o repo (dev-agent, Actions) lê a versão commitada.` : '') +
+    // A dica de descarte depende da branch do CHECKOUT, não de premissa:
+    // `git checkout -- <arquivo>` restaura o que está no índice, e rodado de uma
+    // branch de trabalho reverte o arquivo para a versão ANTIGA dela — o oposto
+    // do que a mensagem promete.
     (finalConfigDecision.included
-      ? ` O ${CONFIG_FILE} local ficou igual ao do PR — depois do merge, descarte a cópia ` +
-        `local com \`git checkout -- ${CONFIG_FILE}\`.`
+      ? ` ${composeConfigCleanupHint({
+          file: CONFIG_FILE,
+          base,
+          current: currentGitBranch(path.dirname(configPath)),
+        })}`
       : '')
   );
 }

package/src/commands/validate.mjs

@@ -1,5 +1,3 @@
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
@@ -14,6 +12,48 @@ import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 import { executionMode } from '../lib/flow-run.mjs';
 import { docBlobUrl } from '../lib/repo-links.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
+import { isAwaitingMerge } from '../lib/doc-source.mjs';
+import { getRepoDefaultBranch } from '../api/github-rest.mjs';
+
+/**
+ * Aborto por documento ainda em Pull Request.
+ *
+ * Este é o portão mais importante do `validate`, e existe por um motivo
+ * assimétrico: a reprova NÃO é inócua. Ela remove `spec-wave:ready` (o gatilho,
+ * que `issues: [labeled]` não redispara sozinho) e comenta a falha na issue —
+ * ou seja, danifica estado COMPARTILHADO. Fazer isso porque o documento está num
+ * PR não mergeado seria reprovar por uma condição que não é do documento.
+ *
+ * É exatamente o incidente que o comentário do `readsByType` em
+ * lib/next-step.mjs já registra ter acontecido antes, com clone desatualizado.
+ *
+ * Aborta ANTES do removeLabel: a label fica, e reaplicá-la depois do merge
+ * simplesmente funciona.
+ */
+async function abortIfPendingPr({ token, owner, repo, n, docs }) {
+  const pendentes = docs.filter(d => isAwaitingMerge(d.state));
+  if (pendentes.length === 0) return null;
+
+  // Cada documento carrega o SEU desbloqueio: um está esperando merge, outro
+  // esperando alguém abrir o PR. Um texto único ("faça o merge do PR") mandaria
+  // metade dos casos procurar uma tela que não existe.
+  const blocos = pendentes.map(d => awaitingMergeBlock({
+    pathRel: d.pathRel, state: d.state, pr: d.pr, branch: d.ref,
+  }));
+  const linhas = blocos.map(b => `- ${b.message}\n  ${b.unblock}`);
+
+  await commentOnIssue(token, owner, repo, n,
+    '⏸️ **Validação adiada — documento ainda não está na branch base.**\n\n' +
+    `${linhas.join('\n')}\n\n` +
+    'Resolvido isso, reaplique `spec-wave:ready` — a label foi **mantida** na issue, ' +
+    'e nada foi reprovado.'
+  ).catch(() => {});
+
+  console.error(`Validação adiada: ${pendentes.map(d => d.pathRel).join(', ')} fora da base.`);
+  return { ok: false, errors: linhas, awaitingMerge: true };
+}
 
 /**
  * Validação do bug.md (RFC-004 §5).
@@ -23,11 +63,19 @@ import { docBlobUrl } from '../lib/repo-links.mjs';
  * um único arquivo, e a falha NÃO devolve o item para a etapa de spec (Bug não
  * tem etapa de spec). Reaplicar `spec-wave:bug` é o caminho de retomada.
  */
-async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
+async function validateBug({ token, owner, repo, issue, issueNumber, root, base }) {
   const n = parseInt(issueNumber, 10);
-  const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
+  const { fileRel } = bugDocPaths(issue.title, root);
   const errors = [];
 
+  const bug = await loadArtifact({
+    token, owner, repo, root, pathRel: fileRel, doc: 'bug', issueNumber: n, base,
+  });
+  const adiado = await abortIfPendingPr({
+    token, owner, repo, n, docs: [{ ...bug, pathRel: fileRel }],
+  });
+  if (adiado) return adiado;
+
   const names = labelNames(issue);
   const critiqueFailed = names.includes(LABEL_CRITIQUE_FAILED);
   const needsHuman = names.includes(LABEL_NEEDS_HUMAN);
@@ -44,12 +92,12 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
     );
   }
 
-  if (!existsSync(fileAbs)) {
+  if (bug.content == null) {
     errors.push(
       `❌ \`bug.md\` não encontrado em \`${fileRel}\` — aplique \`${LABEL_BUG}\` para gerá-lo.`
     );
   } else {
-    const content = readFileSync(fileAbs, 'utf-8');
+    const content = bug.content;
     for (const faltante of describeMissingSections(content, REQUIRED_BUG_SECTIONS)) {
       errors.push(renderMissingSection('bug.md', faltante));
     }
@@ -124,19 +172,23 @@ export async function validate({ issueNumber }) {
     );
   }
 
-  const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+  const n = parseInt(issueNumber, 10);
+  const issue = await getIssue(token, owner, repo, n);
+
+  // Branch base para a leitura em camadas. Best-effort: sem ela o resolvedor cai
+  // no default da API, que é a mesma branch.
+  const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);
 
   // Bug tem artefato próprio (bug.md) e caminho próprio de validação — não passa
   // pelo par spec.md + plan.md, que é exclusivo de Feature.
   if (detectIssueType(issue) === 'Bug') {
-    return await validateBug({ token, owner, repo, issue, issueNumber, root });
+    return await validateBug({ token, owner, repo, issue, issueNumber, root, base });
   }
 
   const slug = slugify(issue.title);
   // Ancorado na RAIZ do repo, não no cwd: rodar de um subdiretório encontra o
   // config subindo na árvore e precisa encontrar os documentos no mesmo lugar.
   const featureRel = `docs/features/${slug}`;
-  const featureDir = path.resolve(root || process.cwd(), featureRel);
 
   const errors = [];
 
@@ -158,12 +210,28 @@ export async function validate({ issueNumber }) {
     );
   }
 
+  // Os dois documentos vêm do resolvedor em camadas (disco → base → PR aberto):
+  // ler só o disco reprovaria uma Feature cujo plan.md está publicado, o que
+  // custa a label de gatilho e um comentário de falha na issue.
+  const planRel = `${featureRel}/plan.md`;
+  const specRel = `${featureRel}/spec.md`;
+  const ler = (doc, pathRel) => loadArtifact({
+    token, owner, repo, root, pathRel, doc, issueNumber: n, base,
+  });
+  const plan = await ler('plan', planRel);
+  const spec = await ler('spec', specRel);
+
+  const adiado = await abortIfPendingPr({
+    token, owner, repo, n,
+    docs: [{ ...plan, pathRel: planRel }, { ...spec, pathRel: specRel }],
+  });
+  if (adiado) return adiado;
+
   // Check plan.md
-  const planPath = path.join(featureDir, 'plan.md');
-  if (!existsSync(planPath)) {
-    errors.push('❌ `plan.md` não encontrado em `' + `${featureRel}/plan.md` + '`');
+  if (plan.content == null) {
+    errors.push('❌ `plan.md` não encontrado em `' + planRel + '`');
   } else {
-    const planContent = readFileSync(planPath, 'utf-8');
+    const planContent = plan.content;
     for (const faltante of describeMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
       errors.push(renderMissingSection('plan.md', faltante));
     }
@@ -173,11 +241,10 @@ export async function validate({ issueNumber }) {
   }
 
   // Check spec.md
-  const specPath = path.join(featureDir, 'spec.md');
-  if (!existsSync(specPath)) {
-    errors.push('❌ `spec.md` não encontrado em `' + `${featureRel}/spec.md` + '`');
+  if (spec.content == null) {
+    errors.push('❌ `spec.md` não encontrado em `' + specRel + '`');
   } else {
-    const specContent = readFileSync(specPath, 'utf-8');
+    const specContent = spec.content;
     for (const faltante of describeMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
       errors.push(renderMissingSection('spec.md', faltante));
     }

package/src/config.mjs

@@ -519,6 +519,24 @@ export const WORKFLOW_FILES = [
   'qa.yml',
 ];
 
+/**
+ * Workflows que PUBLICAM um documento gerado (branch própria + Pull Request).
+ *
+ * Lista explícita de propósito. O teste que verifica permissões selecionava os
+ * workflows por `content.includes('contents: write')` — um predicado que passa
+ * VACUAMENTE se o marcador sumir do YAML: nenhum arquivo é selecionado, o laço
+ * não roda, e o teste fica verde justamente no cenário que ele deveria pegar.
+ *
+ * Estes quatro precisam de `contents: write` (o commit vai por Git Data API) E
+ * de `pull-requests: write` (sem ela o commit existe e o PR não).
+ */
+export const ARTIFACT_WORKFLOW_FILES = [
+  'generate-spec.yml',
+  'generate-plan.yml',
+  'generate-bug.yml',
+  'decompose.yml',
+];
+
 export const ISSUE_TEMPLATE_FILES = [
   'plan-template.md',
   'spec-template.md',