@spec-wave/cli 0.16.1 → 0.16.3

package/package.json

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

package/src/commands/doctor.mjs

@@ -282,6 +282,34 @@ async function checkConfig(ctx) {
  * @param {string[]} [params.repoLabels] nomes das labels do repo
  * @returns {{ unknownStages: string[], missingStages: string[], orphanLabels: string[], missingLabels: string[] }}
  */
+/**
+ * Os ids de opção do .spec-wave.json batem com os do Project? (função PURA)
+ *
+ * Compara ID, não nome. `inspectBoardHygiene` compara nomes — e é justamente
+ * essa cegueira que deixou passar dois defeitos: o `refresh --stages` que
+ * recriava as opções, e o config commitado defasado.
+ *
+ * Por que importa: o que liga um item do board à coluna é o id. Um
+ * `.spec-wave.json` com ids velhos faz TODA escrita de Etapa falhar com "The
+ * single select option Id does not belong to the field" — e a falha é
+ * best-effort em quase todo caminho (implement, code-review, qa), então o card
+ * simplesmente não se move e ninguém percebe.
+ *
+ * Acontece sempre que alguém roda `refresh --config` e não commita: quem clona
+ * o repo — o dev-agent, o runner do Action — lê a versão velha.
+ *
+ * @param {object} params
+ * @param {Record<string,string>|null} [params.configOptions] nome → id do config
+ * @param {Record<string,string>|null} [params.boardOptions] nome → id do Project
+ * @returns {{ staleIds: string[], checked: boolean }}
+ */
+export function inspectStageIds({ configOptions = null, boardOptions = null } = {}) {
+  if (!configOptions || !boardOptions) return { staleIds: [], checked: false };
+  const staleIds = Object.keys(configOptions)
+    .filter(name => boardOptions[name] && boardOptions[name] !== configOptions[name]);
+  return { staleIds, checked: true };
+}
+
 export function inspectBoardHygiene({ boardStages = null, repoLabels = null } = {}) {
   const canonical = STATUS_OPTIONS.map(s => s.name);
   const known = new Set(canonical);
@@ -396,6 +424,24 @@ async function checkBoardHygiene(ctx) {
       'do campo "Etapa" e rode `refresh --config`.'
     );
   }
+  // Divergência de ID entre o config e o Project: invisível para quem só
+  // compara nomes, e fatal para toda escrita de Etapa.
+  const { staleIds, checked } = inspectStageIds({
+    configOptions: cfg.project.fields?.['Etapa']?.options ?? null,
+    boardOptions: snapshot?.fields?.['Etapa']?.options ?? null,
+  });
+  if (checked && staleIds.length > 0) {
+    status = 'warn';
+    notes.push(
+      `${CONFIG_FILE} com ids de opção DEFASADOS (${staleIds.length} de ` +
+      `${Object.keys(cfg.project.fields['Etapa'].options).length}): ${staleIds.join(', ')}. ` +
+      'Toda escrita de Etapa falha com "The single select option Id does not belong to the ' +
+      'field" — e a falha é best-effort, então o card não se move e nada é reportado. ' +
+      `Rode \`refresh --config\` e **commite** o ${CONFIG_FILE}: quem clona o repo ` +
+      '(dev-agent, runner do Action) lê a versão commitada.'
+    );
+  }
+
   const { missingTrackStages } = inspectBugTrack({ boardStages, openBugCount });
   if (missingTrackStages.length > 0) {
     status = 'warn';

package/src/commands/implement.mjs

@@ -8,10 +8,11 @@ import {
   CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE, STAGE_ORDER,
   PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE, labelNames,
 } from '../config.mjs';
-import { getIssue, listIssueComments, listBlockedBy } from '../api/github-rest.mjs';
+import { getIssue, listIssueComments, listBlockedBy, getFileContent } from '../api/github-rest.mjs';
 import { listSubIssues, getIssueParent, addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { bugDocPaths } from '../lib/bug-doc.mjs';
+import { missingDocMessage, existsOnRemote } from '../lib/doc-availability.mjs';
 import { buildBugContext } from '../lib/bug-context.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
@@ -393,7 +394,14 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
     bugDoc = readFileSync(fileAbs, 'utf-8');
     p.log.info(`bug.md encontrado em ${chalk.cyan(fileRel)}.`);
   } else {
-    p.log.warn(`Sem bug.md em ${fileRel} — o contexto assume a investigação inteira.`);
+    const onRemote = await existsOnRemote({
+      getFileContent, token, owner, repo, pathRel: fileRel,
+    });
+    p.log.warn(missingDocMessage({
+      pathRel: fileRel,
+      onRemote,
+      fallback: 'o contexto assume a investigação inteira.',
+    }));
   }
 
   // Board: Bug → Desenvolvimento (In Progress). Não move a Feature-pai.
@@ -564,7 +572,15 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   if (existsSync(featureDir)) {
     specPlan = readSpecPlan(featureDir);
   } else {
-    p.log.warn(`Diretório da feature não encontrado (${featureDir}); seguindo só com as Stories.`);
+    const specRel = `docs/features/${slugify(feature.title)}/spec.md`;
+    const onRemote = await existsOnRemote({
+      getFileContent, token, owner, repo, pathRel: specRel,
+    });
+    p.log.warn(missingDocMessage({
+      pathRel: specRel,
+      onRemote,
+      fallback: 'seguindo só com as Stories.',
+    }));
   }
 
   // F7. Dependências EXTERNAS ainda abertas (da Feature e das Stories pendentes)
@@ -754,7 +770,17 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   if (featureDir && existsSync(featureDir)) {
     specPlan = readSpecPlan(featureDir);
   } else if (featureDir) {
-    p.log.warn(`Diretório da feature não encontrado (${featureDir}); seguindo só com as tasks.`);
+    const specRel = feature?.title
+      ? `docs/features/${slugify(feature.title)}/spec.md`
+      : featureDir;
+    const onRemote = feature?.title
+      ? await existsOnRemote({ getFileContent, token, owner, repo, pathRel: specRel })
+      : null;
+    p.log.warn(missingDocMessage({
+      pathRel: specRel,
+      onRemote,
+      fallback: 'seguindo só com as tasks.',
+    }));
   } else {
     p.log.warn('Não foi possível resolver a Feature; seguindo só com as tasks (use --feature-dir).');
   }

package/src/commands/refresh.mjs

@@ -279,5 +279,13 @@ export async function refresh(options = {}) {
     `${chalk.dim('Versão CLI:')} ${pkg.version}`,
     'Configuração atualizada'
   );
-  p.outro(`${CONFIG_FILE} atualizado. Faça commit do arquivo para versioná-lo.`);
+  // O commit não é opcional: quem CLONA o repo — o dev-agent e o runner do
+  // Action — lê a versão commitada, não a local. Um config não commitado após
+  // mudança de board faz toda escrita de Etapa falhar em silêncio para eles.
+  p.log.warn(
+    `Commite o ${CONFIG_FILE} agora: ele guarda os IDS das opções do board, e quem ` +
+    'clona o repositório (dev-agent, GitHub Actions) lê a versão commitada. Sem o ' +
+    'commit, os cards deixam de se mover para eles — sem erro visível.'
+  );
+  p.outro(`${CONFIG_FILE} atualizado.  git add ${CONFIG_FILE} && git commit -m "chore: sincroniza o board"`);
 }

package/src/commands/update.mjs

@@ -596,7 +596,7 @@ export async function update(options = {}) {
     (skillJobs.length ? ' Recarregue o agente para pegar a skill nova.' : '') +
     (prUrl ? ` Revise e faça o merge do Pull Request: ${prUrl}` : '') +
     (!prMode && repoFiles.length ? ' Arquivos do repo foram commitados no remoto.' : '') +
-    (configPending ? ` Faça commit do ${CONFIG_FILE}.` : '') +
+    (configPending ? ` COMMITE o ${CONFIG_FILE} — quem clona o repo (dev-agent, Actions) lê a versão commitada.` : '') +
     (finalConfigDecision.included
       ? ` O ${CONFIG_FILE} local ficou igual ao do PR — depois do merge, descarte a cópia ` +
         `local com \`git checkout -- ${CONFIG_FILE}\`.`

package/src/lib/doc-availability.mjs

@@ -0,0 +1,52 @@
+// Documento ausente LOCALMENTE não é a mesma coisa que documento inexistente.
+//
+// spec.md, plan.md e bug.md são gerados por GitHub Action e commitados no
+// REMOTO. Quem roda `implement` logo depois — que é o caso comum, porque a
+// geração é o passo anterior — tem o arquivo no repositório e não no clone.
+//
+// A mensagem antiga dizia "sem bug.md — o contexto assume a investigação
+// inteira", mandando o executor investigar do zero quando bastava um
+// `git pull`. Encontrado no smoke test do RFC-004.
+//
+// Decisão em função pura, I/O na função imperativa: a mensagem é testável sem
+// rede, e a consulta ao remoto é best-effort (nunca lança, nunca bloqueia).
+
+/**
+ * Mensagem para um documento ausente no clone local (função PURA).
+ *
+ * @param {object} params
+ * @param {string} params.pathRel caminho do documento, relativo à raiz do repo
+ * @param {boolean|null} params.onRemote true = existe no remoto; false = não
+ *   existe; null = não foi possível consultar (sem token/rede)
+ * @param {string} params.fallback o que o comando fará sem o documento
+ * @returns {string}
+ */
+export function missingDocMessage({ pathRel, onRemote, fallback }) {
+  if (onRemote === true) {
+    return (
+      `${pathRel} existe no repositório mas NÃO no seu clone — rode \`git pull\` e ` +
+      'repita o comando. Seguir agora ignoraria o documento já gerado.'
+    );
+  }
+  if (onRemote === false) {
+    return `Sem ${pathRel} no repositório — ${fallback}`;
+  }
+  return (
+    `Sem ${pathRel} no clone local (não foi possível consultar o remoto) — ${fallback} ` +
+    'Se o documento já foi gerado, rode `git pull` antes.'
+  );
+}
+
+/**
+ * O documento existe no remoto? Best-effort — NUNCA lança.
+ *
+ * @returns {Promise<boolean|null>} null quando não deu para consultar
+ */
+export async function existsOnRemote({ getFileContent, token, owner, repo, pathRel }) {
+  if (!token || !owner || !repo) return null;
+  try {
+    return (await getFileContent(token, owner, repo, pathRel)) != null;
+  } catch {
+    return null;
+  }
+}

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

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "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",