@spec-wave/cli 0.12.0 → 0.14.0

package/src/commands/implement.mjs

@@ -14,9 +14,9 @@ import { detectIssueType } from '../lib/issue-type.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
 import { loadProjectConfig, resolveField } from '../lib/board.mjs';
-import { resolveDoc } from '../lib/feature-docs.mjs';
 import { planBoardMoves, applyBoardMoves } from '../lib/implement-board.mjs';
 import { extractPathsFromPlan, buildCodeDigest } from '../lib/code-digest.mjs';
+import { findConfigPath, resolveFromRoot } from '../lib/project-root.mjs';
 
 // Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
 const WORK_DIR = '.spec-wave';
@@ -42,16 +42,15 @@ async function resolveFeature(token, startNodeId) {
   return null;
 }
 
-// Lê os documentos ATUAIS (maior versão) de um docs/features/<slug>: com
-// regerações forçadas o vigente é spec-v2.md/plan-v3.md…, não o original.
+// Lê spec.md/plan.md de um docs/features/<slug> se existirem.
 function readSpecPlan(featureDir) {
-  const spec = resolveDoc(featureDir, 'spec');
-  const plan = resolveDoc(featureDir, 'plan');
+  const specPath = path.join(featureDir, 'spec.md');
+  const planPath = path.join(featureDir, 'plan.md');
   return {
-    specPath: spec?.path || path.join(featureDir, 'spec.md'),
-    planPath: plan?.path || path.join(featureDir, 'plan.md'),
-    spec: spec ? readFileSync(spec.path, 'utf-8') : null,
-    plan: plan ? readFileSync(plan.path, 'utf-8') : null,
+    specPath,
+    planPath,
+    spec: existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null,
+    plan: existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null,
   };
 }
 
@@ -361,7 +360,7 @@ function renderCommand(template, vars) {
 // Modo Feature: avalia as Stories da Feature (dependências + Etapa no board),
 // pula as já implementadas (Code Review+) e monta UM contexto único com todas
 // as pendentes em ordem topológica — spec-kit acionado uma vez.
-async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun }) {
+async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun, repoRoot }) {
   // F1. Stories (sub-issues) da Feature.
   const subs = await listSubIssues(token, feature.node_id).catch(() => []);
   const stories = subs.filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
@@ -376,7 +375,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   p.log.info(`Feature com ${stories.length} story(ies): ${stories.map(s => `#${s.number}`).join(', ')}`);
 
   // F1-board. Feature → Desenvolvimento (In Progress) já no início.
-  await applyBoardMoves({ token, moves: planBoardMoves('start', {
+  await applyBoardMoves({ token, dryRun, moves: planBoardMoves('start', {
     feature: { nodeId: feature.node_id, number: feature.number },
   }) });
 
@@ -393,7 +392,15 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   // F3. Etapa de cada Story no board (best-effort — sem board, nada é pulado).
   const { project, error: projectError } = loadProjectConfig();
   const stageOf = new Map();
-  if (projectError) {
+  if (dryRun) {
+    // A leitura da Etapa passa por addProjectItem, que é MUTAÇÃO (adiciona a
+    // Story ao Project se ainda não estiver lá). Num dry-run isso é proibido, então
+    // a consulta é pulada inteira — o planejamento segue com stage null.
+    p.log.warn(
+      'Dry-run: Etapas do board não consultadas (a consulta adicionaria itens ao Project); ' +
+      'nenhuma Story será considerada implementada.'
+    );
+  } else if (projectError) {
     p.log.warn(`${projectError} — Etapas do board não consultadas; nenhuma Story será considerada implementada.`);
   } else {
     const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
@@ -453,7 +460,8 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   }
 
   // F6. spec.md/plan.md — a issue-alvo JÁ é a Feature (sem resolveFeature).
-  const featureDir = featureDirOpt || path.join('docs', 'features', slugify(feature.title));
+  const featureDir = featureDirOpt
+    || resolveFromRoot(repoRoot, 'docs', 'features', slugify(feature.title));
   let specPlan = { spec: null, plan: null, specPath: null, planPath: null };
   if (existsSync(featureDir)) {
     specPlan = readSpecPlan(featureDir);
@@ -558,12 +566,15 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   }
 
   // 1. Config local (.spec-wave.json) — owner/repo e bloco opcional specKit.
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
-  if (!existsSync(configPath)) {
+  // Procurado subindo na árvore, como o git faz com o .git: rodar de dentro de
+  // apps/web precisa achar o config da raiz. `repoRoot` ancora docs/features.
+  const configPath = findConfigPath();
+  if (!configPath) {
     p.log.error(`Repositório não inicializado (sem ${CONFIG_FILE}). Rode \`spec-wave init\` primeiro.`);
     process.exitCode = 1;
     return;
   }
+  const repoRoot = path.dirname(configPath);
   let config;
   try {
     config = JSON.parse(readFileSync(configPath, 'utf-8'));
@@ -617,7 +628,7 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     p.log.info(`Task única #${issueNumber}.`);
   } else if (type === 'Feature') {
     // Modo Feature: Stories pendentes em ordem de dependência, contexto único.
-    await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun });
+    await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun, repoRoot });
     return;
   } else {
     p.log.error(
@@ -632,7 +643,9 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   const feature = await resolveFeature(token, issue.node_id);
   let featureDir = featureDirOpt;
   if (!featureDir && feature?.title) {
-    featureDir = path.join('docs', 'features', slugify(feature.title));
+    // Ancorado na RAIZ do repo: o config é encontrado subindo na árvore, e os
+    // documentos precisam ser procurados no mesmo lugar.
+    featureDir = resolveFromRoot(repoRoot, 'docs', 'features', slugify(feature.title));
   }
   let specPlan = { spec: null, plan: null, specPath: null, planPath: null };
   if (featureDir && existsSync(featureDir)) {
@@ -646,7 +659,7 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   // 4a-board. Board determinístico: Feature/Story → Desenvolvimento (In
   // Progress) já no início — a UI mostra o desenvolvimento em andamento sem
   // depender de o LLM mover cards. Best-effort: falha vira warn.
-  await applyBoardMoves({ token, moves: planBoardMoves('start', {
+  await applyBoardMoves({ token, dryRun, moves: planBoardMoves('start', {
     feature: feature ? { nodeId: feature.nodeId, number: feature.number } : null,
     story: type === 'Story' ? { nodeId: issue.node_id, number: issue.number } : null,
     tasks: tasks.map(t => ({ nodeId: t.nodeId, number: t.number })),
@@ -755,6 +768,21 @@ async function writeContextAndRunSpecKit({ config, issueNumber, type, title, spe
     title,
   };
 
+  // O dry-run é decidido ANTES do early return de "spec-kit não configurado":
+  // sem isso, com o comando ausente os dois caminhos ficavam indistinguíveis e a
+  // saída não dizia que estava em dry-run.
+  if (dryRun) {
+    if (template) {
+      p.note(renderCommand(template, vars), 'Comando que seria executado (--dry-run)');
+    } else {
+      p.log.warn(`Comando do spec-kit não configurado em ${CONFIG_FILE} — nada a imprimir.`);
+    }
+    p.outro(
+      `Dry-run: nada executado e nada escrito no GitHub. Contexto montado em ${tasksFile}.`
+    );
+    return;
+  }
+
   if (!template) {
     p.log.warn('Comando do spec-kit não configurado.');
     p.note(
@@ -770,12 +798,6 @@ async function writeContextAndRunSpecKit({ config, issueNumber, type, title, spe
 
   const command = renderCommand(template, vars);
 
-  if (dryRun) {
-    p.note(command, 'Comando que seria executado (--dry-run)');
-    p.outro(`Dry-run: nada executado. Contexto em ${tasksFile}.`);
-    return;
-  }
-
   p.log.step(`Executando: ${chalk.dim(command)}`);
   try {
     execSync(command, { stdio: 'inherit' });

package/src/commands/info.mjs

@@ -1,8 +1,9 @@
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { CONFIG_FILE, PORTAL_URL } from '../config.mjs';
+import { findConfigPath } from '../lib/project-root.mjs';
 import { skillStatus } from './install-skill.mjs';
 
 // Resume o estado da skill para a saída JSON. `null` = não foi possível checar.
@@ -43,10 +44,10 @@ function reportSkill(status) {
 // as informações ou oferecer rodar o `init`. Também valida se a skill instalada
 // nos agentes detectados está em dia com a versão empacotada na CLI.
 export async function info(options = {}) {
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  const configPath = findConfigPath();
   const skill = skillStatus();
 
-  if (!existsSync(configPath)) {
+  if (!configPath) {
     if (options.json) {
       console.log(JSON.stringify({ initialized: false, skill: skillJson(skill) }));
       return;

package/src/commands/issue.mjs

@@ -1,9 +1,9 @@
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import { readFileSync, existsSync } from 'node:fs';
-import path from 'node:path';
+import { readFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { CONFIG_FILE, STATUS_OPTIONS, PRIORITY_LABELS, WORK_ITEM_TYPES } from '../config.mjs';
+import { findConfigPath } from '../lib/project-root.mjs';
 import { createIssue, getIssue } from '../api/github-rest.mjs';
 import { addProjectItem, setItemSingleSelect, getSingleSelectField, addSubIssue } from '../api/github-graphql.mjs';
 
@@ -70,8 +70,8 @@ export async function issue(options) {
     return;
   }
 
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
-  if (!existsSync(configPath)) {
+  const configPath = findConfigPath();
+  if (!configPath) {
     p.log.error(`Repositório não inicializado (sem ${CONFIG_FILE}). Rode \`spec-wave init\` primeiro.`);
     process.exitCode = 1;
     return;

package/src/commands/move.mjs

@@ -0,0 +1,162 @@
+// Move QUALQUER item do board para uma Etapa (Feature, Story, Task, Bug, RFC…).
+//
+// Existia um buraco no fluxo: `story` só aceita `review` e `task` só
+// `start`/`done`, então mover uma Feature pela CLI era impossível — o único
+// caminho era mutação GraphQL manual, justamente o que a skill instrui a evitar
+// ("prefira sempre os comandos da CLI a mutações manuais no board").
+//
+// O comando se chama `move` e não `feature <ação>` porque `feature` já está
+// registrado no bin CRIANDO issues; reaproveitar o nome colidiria.
+//
+// As guardas do board são as mesmas dos outros comandos — reusa advanceToStage,
+// logo a Etapa NUNCA retrocede e não há escape hatch.
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { resolveToken } from '../api/auth.mjs';
+import { getIssue } from '../api/github-rest.mjs';
+import { addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadProjectConfig, resolveField, advanceToStage, resolveStageName } from '../lib/board.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import {
+  CONFIG_FILE, PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
+  isManualStageType, MANUAL_STAGE_TYPES,
+} from '../config.mjs';
+
+const PROGRESS_VALUES = [PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE];
+
+/**
+ * Resolve o valor do campo Status a partir da entrada do usuário (função PURA).
+ * Sem `--status`, o destino é "Todo": ao avançar de Etapa o progresso reinicia
+ * (ver a distinção Etapa × Status em config.mjs).
+ *
+ * @param {string} [input]
+ * @returns {{ status: string|null, error: string|null }}
+ */
+export function resolveProgressName(input) {
+  if (input === undefined || input === null || String(input).trim() === '') {
+    return { status: PROGRESS_TODO, error: null };
+  }
+  const key = String(input).trim().toLowerCase();
+  const match = PROGRESS_VALUES.find(v => v.toLowerCase() === key)
+    || PROGRESS_VALUES.find(v => v.toLowerCase().replace(/\s+/g, '') === key.replace(/[\s_-]+/g, ''));
+  return match
+    ? { status: match, error: null }
+    : {
+        status: null,
+        error:
+          `Status "${input}" não existe. Use um destes: ${PROGRESS_VALUES.map(v => `"${v}"`).join(', ')}.`,
+      };
+}
+
+export async function move({ issue: issueArg, stage: stageArg, status: statusArg }) {
+  const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 12 ou #12.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { stage, error: stageError } = resolveStageName(stageArg);
+  if (stageError) {
+    p.log.error(stageError);
+    process.exitCode = 1;
+    return;
+  }
+  const { status, error: statusError } = resolveProgressName(statusArg);
+  if (statusError) {
+    p.log.error(statusError);
+    process.exitCode = 1;
+    return;
+  }
+
+  // owner/repo: env GITHUB_REPOSITORY (padrão dos comandos de Action) com
+  // fallback no .spec-wave.json, procurado subindo na árvore.
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { config, root } = loadConfig();
+  const owner = envOwner || config?.owner;
+  const repo = envRepo || config?.repo;
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`) ou defina GITHUB_REPOSITORY=owner/repo.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold(`spec-wave move #${issueNumber} → ${stage}`));
+
+  let issue;
+  try {
+    issue = await getIssue(token, owner, repo, issueNumber);
+  } catch (err) {
+    p.log.error(`Não foi possível ler a issue #${issueNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Spike tem avanço decidido pelo usuário no board, não por comando.
+  const type = detectIssueType(issue);
+  if (isManualStageType(type)) {
+    p.log.error(
+      `Issue #${issueNumber} é do tipo ${type}, cuja Etapa é movida à mão no board ` +
+      `(tipos manuais: ${MANUAL_STAGE_TYPES.join(', ')}).`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const { project, error: projectError } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (projectError) {
+    p.log.error(`${projectError} — board não atualizado. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);
+    process.exitCode = 1;
+    return;
+  }
+  const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+  const statusField = await resolveField(token, project, 'Status').catch(() => null);
+
+  let moved;
+  try {
+    moved = await advanceToStage(
+      token, project, etapaField, statusField, issue.node_id, stage, status);
+  } catch (err) {
+    p.log.error(`Falha ao atualizar o board: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (moved) {
+    p.log.success(
+      `${type || 'Issue'} #${issueNumber} → Etapa ${chalk.bold(stage)} / Status ${chalk.bold(status)}.`
+    );
+    p.outro(`${chalk.green('✓')} ${issue.title}`);
+    return;
+  }
+
+  // false = já está nessa Etapa ou adiante (ou numa coluna fora da ordem
+  // canônica). A Etapa NUNCA retrocede — lê a atual só para informar.
+  let current = null;
+  if (etapaField?.id) {
+    try {
+      const itemId = await addProjectItem(token, project.id, issue.node_id);
+      current = await getItemSingleSelectValue(token, itemId, etapaField.id);
+    } catch {
+      // sem leitura da Etapa — segue com o aviso genérico
+    }
+  }
+  p.log.info(
+    `#${issueNumber} não foi movida: a Etapa nunca retrocede, e ela já está em ` +
+    `${chalk.bold(current || `"${stage}" ou etapa posterior`)}.`
+  );
+  p.outro('Nada a fazer.');
+}

package/src/commands/order.mjs

@@ -7,26 +7,15 @@
 // GITHUB_REPOSITORY quando existir, senão do .spec-wave.json (gravado pelo init).
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, listBlockedBy } from '../api/github-rest.mjs';
 import { addProjectItem, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
 import { loadProjectConfig, resolveField } from '../lib/board.mjs';
+import { resolveRepoContext } from '../lib/project-root.mjs';
 import { CONFIG_FILE, STAGE_ORDER, STAGE_DEVELOPMENT, STAGE_DONE } from '../config.mjs';
 
-// Resolve owner/repo: env GITHUB_REPOSITORY (padrão dos comandos de Action) com
-// fallback no .spec-wave.json — comandos locais rodam sem essa env.
-function resolveRepoContext() {
-  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  let cfg = {};
-  const cfgPath = path.join(process.cwd(), CONFIG_FILE);
-  try { if (existsSync(cfgPath)) cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch {}
-  return { owner: envOwner || cfg.owner, repo: envRepo || cfg.repo };
-}
-
 export async function order({ feature: featureArg }) {
   const featureNumber = parseInt(String(featureArg).replace('#', ''), 10);
   if (!Number.isInteger(featureNumber) || featureNumber <= 0) {

package/src/commands/qa.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 { getIssueParent } 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, PROGRESS_TODO } from '../config.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { STATUS_OPTIONS, PROGRESS_TODO } from '../config.mjs';
 
 const QA_STAGE = STATUS_OPTIONS.find(s => s.name.includes('QA'))?.name;
 const TODO_STATUS = PROGRESS_TODO;
@@ -47,11 +46,9 @@ export async function qa({ 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(

package/src/commands/refresh.mjs

@@ -1,10 +1,11 @@
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { CONFIG_FILE } from '../config.mjs';
+import { findConfigPath } from '../lib/project-root.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
@@ -21,8 +22,8 @@ export async function refresh(options = {}) {
     return;
   }
 
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
-  if (!existsSync(configPath)) {
+  const configPath = findConfigPath();
+  if (!configPath) {
     p.log.error(`Repositório não inicializado (sem ${CONFIG_FILE}). Rode \`spec-wave init\` primeiro.`);
     process.exitCode = 1;
     return;

package/src/commands/story.mjs

@@ -7,25 +7,14 @@
 // estiver em Code Review ou adiante, o comando apenas informa a Etapa atual.
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue } from '../api/github-rest.mjs';
 import { addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { resolveRepoContext } from '../lib/project-root.mjs';
 import { CONFIG_FILE, STAGE_CODE_REVIEW, PROGRESS_TODO } from '../config.mjs';
 
-// Resolve owner/repo: env GITHUB_REPOSITORY (padrão dos comandos de Action) com
-// fallback no .spec-wave.json — comandos locais rodam sem essa env.
-function resolveRepoContext() {
-  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  let cfg = {};
-  const cfgPath = path.join(process.cwd(), CONFIG_FILE);
-  try { if (existsSync(cfgPath)) cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch {}
-  return { owner: envOwner || cfg.owner, repo: envRepo || cfg.repo };
-}
-
 export async function story({ action, issue: issueArg }) {
   if (action !== 'review') {
     p.log.error(

package/src/commands/task.mjs

@@ -10,13 +10,12 @@
 //    (regra pura canStartTask, testada em test/board-rules.test.mjs).
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue } 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, setItemStatus } from '../lib/board.mjs';
+import { resolveRepoContext } from '../lib/project-root.mjs';
 import {
   CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_DONE,
   PROGRESS_IN_PROGRESS, PROGRESS_DONE,
@@ -36,15 +35,6 @@ export function canStartTask({ siblings } = {}) {
   return busy ? { ok: false, blocker: busy.number } : { ok: true, blocker: null };
 }
 
-// Resolve owner/repo: env GITHUB_REPOSITORY (padrão dos comandos de Action) com
-// fallback no .spec-wave.json — comandos locais rodam sem essa env.
-function resolveRepoContext() {
-  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  let cfg = {};
-  const cfgPath = path.join(process.cwd(), CONFIG_FILE);
-  try { if (existsSync(cfgPath)) cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch {}
-  return { owner: envOwner || cfg.owner, repo: envRepo || cfg.repo };
-}
 
 export async function task({ action, issue: issueArg }) {
   if (action !== 'start' && action !== 'done') {

package/src/commands/update.mjs

@@ -1,25 +1,23 @@
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { CONFIG_FILE, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS } from '../config.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import {
-  getFileContent, upsertFile, listLabels, createLabel, updateLabel,
+  getFileContent, upsertFile, listLabels, createLabel, updateLabel, deleteLabel,
 } from '../api/github-rest.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
+// como desatualizados para sempre.
+import { readTemplate } from '../lib/templates.mjs';
 import {
   TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
   mergeAgentsFile, resolveDest, isDetected, skillCopyReason,
 } from './install-skill.mjs';
-
-const __dir = path.dirname(fileURLToPath(import.meta.url));
-const TEMPLATES_DIR = path.join(__dir, '..', 'templates');
-function readTemplate(...parts) {
-  return readFileSync(path.join(TEMPLATES_DIR, ...parts), 'utf-8');
-}
+import { findConfigPath } from '../lib/project-root.mjs';
 
 // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
 const REPO_FILES = [
@@ -52,10 +50,23 @@ function applySkill(job) {
   writeFileSync(job.dest.path, content, 'utf-8');
 }
 
-// Compara ALL_LABELS com as labels do repo. color no config é hex maiúsculo; a
-// API retorna minúsculo — daí o toLowerCase() na comparação.
-function diffLabels(existing) {
-  const byName = new Map(existing.map(l => [l.name, l]));
+/**
+ * Compara ALL_LABELS com as labels do repo (função PURA — testável).
+ *
+ * `color` no config é hex maiúsculo e a API retorna minúsculo — daí o
+ * toLowerCase() na comparação.
+ *
+ * `orphan` são labels `spec-wave:*` que existem no repo mas saíram do config: o
+ * update só sabia criar e atualizar, nunca remover, então uma label descontinuada
+ * ficava para sempre — foi o caso da `spec-wave:force`, removida do código na
+ * 0.13.0 mas ainda presente em todo repo inicializado com a 0.12.0. Só o
+ * namespace `spec-wave:` é considerado: labels do time não são da nossa conta.
+ *
+ * @param {Array<{name,color,description}>} existing labels do repo
+ * @returns {{ missing: object[], changed: object[], orphan: object[] }}
+ */
+export function diffLabels(existing) {
+  const byName = new Map((existing || []).map(l => [l.name, l]));
   const missing = [];
   const changed = [];
   for (const label of ALL_LABELS) {
@@ -63,13 +74,15 @@ function diffLabels(existing) {
     if (!cur) {
       missing.push(label);
     } else if (
-      cur.color.toLowerCase() !== label.color.toLowerCase() ||
+      (cur.color || '').toLowerCase() !== label.color.toLowerCase() ||
       (cur.description || '') !== (label.description || '')
     ) {
       changed.push(label);
     }
   }
-  return { missing, changed };
+  const known = new Set(ALL_LABELS.map(l => l.name));
+  const orphan = (existing || []).filter(l => l.name?.startsWith('spec-wave:') && !known.has(l.name));
+  return { missing, changed, orphan };
 }
 
 export async function update(options = {}) {
@@ -84,9 +97,9 @@ export async function update(options = {}) {
   const skillJobs = options.skipSkill ? [] : detectSkill(parsed, baseDir, isGlobal);
 
   // 2) Config + repo dependem do .spec-wave.json local do repo atual.
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  const configPath = findConfigPath();
   let config = null;
-  if (existsSync(configPath)) {
+  if (configPath) {
     try {
       config = JSON.parse(readFileSync(configPath, 'utf-8'));
     } catch (err) {
@@ -124,7 +137,7 @@ export async function update(options = {}) {
 
   // 2b) Arquivos do repo e labels divergentes (exige token + rede).
   let repoFiles = [];
-  let labelDiff = { missing: [], changed: [] };
+  let labelDiff = { missing: [], changed: [], orphan: [] };
   let repoChecked = false;
   if (doRepo) {
     const s = p.spinner();
@@ -153,7 +166,7 @@ export async function update(options = {}) {
   }
 
   // ---------- Resumo ----------
-  const labelTotal = labelDiff.missing.length + labelDiff.changed.length;
+  const labelTotal = labelDiff.missing.length + labelDiff.changed.length + labelDiff.orphan.length;
   const total = skillJobs.length + (configStale ? 1 : 0) + repoFiles.length + labelTotal;
 
   if (total === 0) {
@@ -180,6 +193,9 @@ export async function update(options = {}) {
     lines.push(chalk.bold('Labels:'));
     if (labelDiff.missing.length) lines.push(`  ${chalk.yellow('+')} criar: ${labelDiff.missing.map(l => l.name).join(', ')}`);
     if (labelDiff.changed.length) lines.push(`  ${chalk.yellow('↻')} atualizar: ${labelDiff.changed.map(l => l.name).join(', ')}`);
+    if (labelDiff.orphan.length) {
+      lines.push(`  ${chalk.red('−')} remover (descontinuadas): ${labelDiff.orphan.map(l => l.name).join(', ')}`);
+    }
   }
   p.note(lines.join('\n'), `${total} item(ns) desatualizado(s)`);
 
@@ -279,6 +295,14 @@ export async function update(options = {}) {
         p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
       }
     }
+    for (const label of labelDiff.orphan) {
+      try {
+        await deleteLabel(tk, owner, repo, label.name);
+        p.log.success(`Label descontinuada removida: ${label.name}`);
+      } catch (err) {
+        p.log.error(`Falha ao remover label ${label.name}: ${err.message}`);
+      }
+    }
   }
 
   const committedRepo = repoFiles.length > 0;