@spec-wave/cli 0.10.0 → 0.11.0

package/bin/spec-wave.mjs

@@ -222,6 +222,23 @@ program
     await story({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('dev-agent')
+  .description('Instala (--install/--build) ou executa (--run) o spec-wave-agent nesta máquina')
+  .option('--install', 'Baixa o binário da release, gera a config e (com --service) o serviço')
+  .option('--build', 'Clona o repo do agente e compila com cargo (alternativa ao --install)')
+  .option('--run', 'Executa o agente em foreground (Ctrl+C encerra com checkpoint)')
+  .option('--service', 'No --install/--build: também instala e habilita systemd/launchd')
+  .option('--tag <tag>', 'Release (--install) ou branch/tag (--build); padrão: última release / main')
+  .option('--debug', 'No --run: RUST_LOG=debug')
+  .option('--dry-run', 'Mostra o que seria instalado sem gravar')
+  .option('--force', 'Reinstala o binário e regrava a config')
+  .option('--yes', 'Modo não-interativo')
+  .action(async (options) => {
+    const { devAgent } = await import('../src/commands/dev-agent.mjs');
+    await devAgent(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('doctor')
   .description('Diagnostica a configuração do spec-wave no repositório atual')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {
@@ -28,4 +28,4 @@
     "commander": "^13.1.0",
     "js-yaml": "^4.1.0"
   }
-}
+}

package/src/commands/dev-agent.mjs

@@ -0,0 +1,568 @@
+// spec-wave dev-agent --install | --run
+//
+// Instala e executa o spec-wave-agent (daemon Rust) na máquina do dev. O
+// binário vem das releases do repo do agente (baixado com `gh release
+// download`, que usa as credenciais do próprio dev), a config é derivada do
+// .spec-wave.json do repositório e o serviço (systemd/launchd) é opcional.
+//
+// Convenção do repo: a lógica de decisão fica em funções puras exportadas
+// (testadas em test/dev-agent.test.mjs) e o I/O fica na função imperativa.
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import {
+  chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync,
+  readFileSync, rmSync, writeFileSync,
+} from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_FILE } from '../config.mjs';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dir, '..', 'templates', 'agent');
+
+/** Repositório que publica as releases do agente. */
+export const AGENT_REPO = 'astratech-net-br/spec-wave-agent';
+export const BIN_NAME = 'spec-wave-agent';
+/** Instalação sem sudo. */
+export const BIN_DIR = path.join('.local', 'bin');
+export const AGENT_CONFIG = path.join('.config', 'spec-wave-agent', 'config.toml');
+/** Tag instalada — arquivo de estado escrito por nós.
+ *  NÃO detectamos versão executando o binário: versões antigas não têm
+ *  --version e subiriam o DAEMON no lugar de imprimir a versão. */
+export const STATE_FILE = path.join('.local', 'share', 'spec-wave-agent', 'installed-tag');
+/** Clone usado pelo --build (reaproveitado entre builds). */
+export const SRC_DIR = path.join('.local', 'share', 'spec-wave-agent', 'src');
+
+/** Marca de versão para binários compilados do fonte. */
+export function sourceTag(ref, sha) {
+  const short = (sha || '').slice(0, 7);
+  return `fonte:${ref}${short ? `@${short}` : ''}`;
+}
+
+// ---------------------------------------------------------------------------
+// Puro (testável)
+// ---------------------------------------------------------------------------
+
+const TARGETS = {
+  'linux:x64': 'x86_64-unknown-linux-gnu',
+  'darwin:arm64': 'aarch64-apple-darwin',
+  'win32:x64': 'x86_64-pc-windows-msvc',
+};
+
+/** Sufixo do executável na plataforma. */
+export function exeSuffix(platform) {
+  return platform === 'win32' ? '.exe' : '';
+}
+
+/**
+ * Nome do asset da release para a plataforma. Recebe platform/arch por
+ * parâmetro (em vez de ler process.*) para ser testável.
+ * @returns {string|null} null quando a plataforma não tem binário publicado
+ */
+export function assetNameFor(platform, arch) {
+  const target = TARGETS[`${platform}:${arch}`];
+  return target ? `${BIN_NAME}-${target}${exeSuffix(platform)}` : null;
+}
+
+/** Substitui {placeholders} — mesmo idiom do renderCommand do implement. */
+function render(template, vars) {
+  return template.replace(/\{(\w+)\}/g, (m, key) => (key in vars ? vars[key] : m));
+}
+
+/**
+ * config.toml do agente a partir do .spec-wave.json. Nunca escreve token.
+ */
+export function renderAgentConfig({ owner, repo }) {
+  return `# spec-wave-agent — gerado por \`spec-wave dev-agent --install\`
+# Schema completo: https://github.com/${AGENT_REPO}#configuração
+
+repo = "${owner}/${repo}"
+queue_label = "spec-wave:dev-agent"
+
+# Defaults do agente (descomente para ajustar):
+#poll_interval_secs = 60       # consulta à fila quando ocioso
+#heartbeat_secs = 120          # renovação do lease
+#lease_ttl_secs = 600          # >= 4x heartbeat (validado no boot)
+#implement_timeout_secs = 14400  # teto de UMA feature inteira (4h)
+#cooldown_secs = 900           # issue processada sai da fila local por este tempo
+#max_executor_rounds = 8       # teto de rodadas do executor por feature
+
+# Executor (Claude Code). Para fixar o modelo, acrescente --model:
+#feature_command = "claude -p --model opus --output-format stream-json --verbose --permission-mode acceptEdits --allowedTools \\"Bash(npx:*),Bash(git:*),Edit,Write,Read,Glob,Grep,Task\\""
+
+# Origin alternativo (SSH, git self-hosted). Default: https://github.com/{repo}.git
+#remote_url = "git@github.com:${owner}/${repo}.git"
+`;
+}
+
+/**
+ * Unit do serviço a partir dos templates.
+ * @param {'systemd'|'launchd'} kind
+ */
+export function renderServiceUnit(kind, { home, bin, pathEnv }) {
+  const file = kind === 'launchd' ? 'dev.specwave.agent.plist' : 'spec-wave-agent.service';
+  const raw = readFileSync(path.join(TEMPLATES_DIR, file), 'utf-8');
+  return render(raw, { home, bin, path: pathEnv });
+}
+
+/** O diretório já está no PATH? */
+export function isOnPath(dir, pathEnv) {
+  if (!pathEnv) return false;
+  return pathEnv.split(path.delimiter).filter(Boolean).some((e) => path.resolve(e) === path.resolve(dir));
+}
+
+/**
+ * O que o --install vai fazer, para o relatório e o --dry-run.
+ * @param {{binPath, binInstalled, installedTag, targetTag, configPath,
+ *          configExists, service, servicePath, force}} ctx
+ * @returns {Array<{what: string, path: string, action: 'criar'|'atualizar'|'manter'}>}
+ */
+export function planInstall(ctx) {
+  const items = [];
+  const sameVersion = ctx.binInstalled
+    && !!ctx.installedTag
+    && ctx.installedTag === ctx.targetTag;
+  items.push({
+    what: `binário ${ctx.targetTag ?? ''}`.trim(),
+    path: ctx.binPath,
+    action: !ctx.binInstalled ? 'criar' : (sameVersion && !ctx.force ? 'manter' : 'atualizar'),
+  });
+  items.push({
+    what: 'config',
+    path: ctx.configPath,
+    action: !ctx.configExists ? 'criar' : (ctx.force ? 'atualizar' : 'manter'),
+  });
+  if (ctx.service) {
+    items.push({
+      what: `serviço (${ctx.service})`,
+      path: ctx.servicePath,
+      action: ctx.force ? 'atualizar' : 'criar',
+    });
+  }
+  return items;
+}
+
+const ACTION_MARK = { criar: chalk.green('+'), atualizar: chalk.yellow('~'), manter: chalk.dim('=') };
+
+export function renderInstallReport(items) {
+  return items
+    .map((i) => `${ACTION_MARK[i.action] ?? '?'} ${i.what}: ${chalk.dim(i.path)} ${chalk.dim(`(${i.action})`)}`)
+    .join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
+function sh(cmd) {
+  return execSync(cmd, { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+}
+
+function has(cmd) {
+  const probe = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+  try { sh(probe); return true; } catch { return false; }
+}
+
+/** Tag instalada (arquivo de estado), ou null se desconhecida. */
+function readInstalledTag(home) {
+  try { return readFileSync(path.join(home, STATE_FILE), 'utf-8').trim() || null; }
+  catch { return null; }
+}
+
+function writeInstalledTag(home, tag) {
+  const f = path.join(home, STATE_FILE);
+  mkdirSync(path.dirname(f), { recursive: true });
+  writeFileSync(f, `${tag}\n`, 'utf-8');
+}
+
+function readRepoConfig(cwd) {
+  const configPath = path.join(cwd, CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    return { error: `${CONFIG_FILE} não encontrado. Rode \`spec-wave init\` neste repositório primeiro.` };
+  }
+  try {
+    const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+    if (!cfg.owner || !cfg.repo) {
+      return { error: `${CONFIG_FILE} não contém owner/repo. Rode \`spec-wave init\` novamente.` };
+    }
+    return { cfg };
+  } catch (err) {
+    return { error: `${CONFIG_FILE} corrompido: ${err.message}` };
+  }
+}
+
+/** Checagens de pré-requisito no estilo do doctor: nunca lança. */
+function preflight(cfg) {
+  const problems = [];
+  const warnings = [];
+  if (!has('git')) problems.push('git não encontrado no PATH.');
+  if (!has('gh')) {
+    problems.push('gh (GitHub CLI) não encontrado — instale: https://cli.github.com');
+  } else {
+    try { sh('gh auth status'); }
+    catch { problems.push('gh não autenticado — rode `gh auth login`.'); }
+  }
+  if (!has('npx')) problems.push('npx não encontrado — instale Node 18+.');
+  if (!has('claude')) {
+    warnings.push('Claude Code (claude) não encontrado no PATH — o agente precisa dele para implementar.');
+  }
+  if (!cfg?.specKit?.command && !process.env.SPEC_WAVE_IMPLEMENT_CMD) {
+    warnings.push(
+      `${CONFIG_FILE} sem specKit.command — cada story precisa dele para ser implementada. ` +
+      'Configure "specKit": { "command": "claude -p \\"...{tasksFile}...\\" --permission-mode acceptEdits" } ' +
+      'ou exporte SPEC_WAVE_IMPLEMENT_CMD.'
+    );
+  }
+  return { problems, warnings };
+}
+
+function latestTag() {
+  try {
+    return sh(`gh release view --repo ${AGENT_REPO} --json tagName --jq .tagName`);
+  } catch (err) {
+    const msg = String(err.stderr || err.message || '');
+    if (/HTTP 404|Not Found|release not found/i.test(msg)) {
+      throw new Error(
+        `Nenhuma release publicada em ${AGENT_REPO} (ou você não tem acesso ao repositório privado). ` +
+        'Peça acesso à organização ou instale a partir do fonte (veja o README do agente).'
+      );
+    }
+    throw new Error(`Não foi possível consultar as releases de ${AGENT_REPO}: ${msg.trim() || err.message}`);
+  }
+}
+
+/** Baixa o asset + .sha256 num tempdir, confere o hash e devolve o caminho. */
+function downloadAsset(tag, asset) {
+  const dir = mkdtempSync(path.join(tmpdir(), 'spec-wave-agent-'));
+  try {
+    sh(`gh release download ${tag} --repo ${AGENT_REPO} --pattern "${asset}" --pattern "${asset}.sha256" --dir "${dir}" --clobber`);
+  } catch (err) {
+    rmSync(dir, { recursive: true, force: true });
+    const msg = String(err.stderr || err.message || '');
+    if (/no assets match|asset.*not found/i.test(msg)) {
+      throw new Error(`A release ${tag} não tem o binário para esta plataforma (${asset}).`);
+    }
+    throw new Error(`Falha ao baixar ${asset} da release ${tag}: ${msg.trim() || err.message}`);
+  }
+  const binTmp = path.join(dir, asset);
+  const sumFile = path.join(dir, `${asset}.sha256`);
+  if (existsSync(sumFile)) {
+    const expected = readFileSync(sumFile, 'utf-8').trim().split(/\s+/)[0];
+    const actual = createHash('sha256').update(readFileSync(binTmp)).digest('hex');
+    if (expected !== actual) {
+      rmSync(dir, { recursive: true, force: true });
+      throw new Error(`Checksum do binário não confere (esperado ${expected}, obtido ${actual}).`);
+    }
+  }
+  return { dir, binTmp };
+}
+
+function installService({ kind, home, binPath, servicePath }) {
+  const pathEnv = [path.dirname(binPath), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin']
+    .filter((d, i, a) => a.indexOf(d) === i)
+    .join(':');
+  const content = renderServiceUnit(kind, { home, bin: binPath, pathEnv });
+  mkdirSync(path.dirname(servicePath), { recursive: true });
+  writeFileSync(servicePath, content, 'utf-8');
+  if (kind === 'systemd') {
+    execSync('systemctl --user daemon-reload', { stdio: 'inherit' });
+    execSync('systemctl --user enable --now spec-wave-agent', { stdio: 'inherit' });
+  } else {
+    mkdirSync(path.join(home, 'Library', 'Logs'), { recursive: true });
+    try { execSync(`launchctl unload "${servicePath}"`, { stdio: ['pipe', 'pipe', 'pipe'] }); } catch { /* não estava carregado */ }
+    execSync(`launchctl load "${servicePath}"`, { stdio: 'inherit' });
+  }
+}
+
+async function install(options) {
+  const cwd = process.cwd();
+  const home = homedir();
+  const binPath = path.join(home, BIN_DIR, BIN_NAME + exeSuffix(process.platform));
+  const configPath = path.join(home, AGENT_CONFIG);
+
+  // 1. Repositório + pré-requisitos.
+  const { cfg, error } = readRepoConfig(cwd);
+  if (error) { p.log.error(error); process.exitCode = 1; return; }
+
+  const { problems, warnings } = preflight(cfg);
+  for (const w of warnings) p.log.warn(w);
+  if (problems.length > 0) {
+    p.log.error(`Pré-requisitos faltando:\n  - ${problems.join('\n  - ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. Plataforma.
+  const asset = assetNameFor(process.platform, process.arch);
+  if (!asset) {
+    p.log.error(
+      `Sem binário publicado para ${process.platform}/${process.arch}. ` +
+      'Compile a partir do fonte (veja o README do agente).'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // 3. Versão alvo x instalada.
+  const spin = p.spinner();
+  spin.start('Consultando a release do agente...');
+  let targetTag;
+  try { targetTag = options.tag || latestTag(); }
+  catch (err) { spin.stop('Falhou.'); p.log.error(err.message); process.exitCode = 1; return; }
+  spin.stop(`Release alvo: ${chalk.bold(targetTag)}`);
+
+  const binInstalled = existsSync(binPath);
+  const installedTag = binInstalled ? readInstalledTag(home) : null;
+  const items = planInstall({
+    binPath, binInstalled, installedTag, targetTag, configPath,
+    configExists: existsSync(configPath),
+    service: options.service ? (process.platform === 'darwin' ? 'launchd' : 'systemd') : null,
+    servicePath: process.platform === 'darwin'
+      ? path.join(home, 'Library', 'LaunchAgents', 'dev.specwave.agent.plist')
+      : path.join(home, '.config', 'systemd', 'user', 'spec-wave-agent.service'),
+    force: !!options.force,
+  });
+  p.note(renderInstallReport(items), 'Plano de instalação');
+
+  if (options.dryRun) {
+    p.outro('Dry-run: nada foi instalado.');
+    return;
+  }
+
+  // 4. Binário.
+  const binItem = items[0];
+  if (binItem.action === 'manter') {
+    p.log.info(`Binário já está em ${targetTag} — nada a baixar (use --force para reinstalar).`);
+  } else {
+    const s = p.spinner();
+    s.start(`Baixando ${asset} (${targetTag})...`);
+    let tmp;
+    try { tmp = downloadAsset(targetTag, asset); }
+    catch (err) { s.stop('Falhou.'); p.log.error(err.message); process.exitCode = 1; return; }
+    try {
+      mkdirSync(path.dirname(binPath), { recursive: true });
+      copyFileSync(tmp.binTmp, binPath);
+      chmodSync(binPath, 0o755);
+      writeInstalledTag(home, targetTag);
+    } finally {
+      rmSync(tmp.dir, { recursive: true, force: true });
+    }
+    s.stop(`Binário instalado em ${chalk.cyan(binPath)}.`);
+  }
+
+  // 5-7. Config, serviço e avisos (compartilhado com o --build).
+  await finishSetup({ cfg, home, binPath, configPath, options, configAction: items[1].action,
+                      servicePath: options.service ? items[2].path : null });
+}
+
+/** Config + serviço + avisos finais — comum a --install e --build. */
+async function finishSetup({ cfg, home, binPath, configPath, options, configAction, servicePath }) {
+  if (configAction === 'manter') {
+    p.log.info(`Config mantida: ${configPath} já existe (use --force para regerar).`);
+  } else if (existsSync(configPath) && !options.yes) {
+    const ok = await p.confirm({ message: `Sobrescrever ${configPath}?`, initialValue: false });
+    if (p.isCancel(ok) || !ok) {
+      p.log.info('Config mantida.');
+    } else {
+      mkdirSync(path.dirname(configPath), { recursive: true });
+      writeFileSync(configPath, renderAgentConfig(cfg), 'utf-8');
+      p.log.success(`Config regravada em ${configPath}.`);
+    }
+  } else {
+    mkdirSync(path.dirname(configPath), { recursive: true });
+    writeFileSync(configPath, renderAgentConfig(cfg), 'utf-8');
+    p.log.success(`Config criada em ${chalk.cyan(configPath)} (repo ${cfg.owner}/${cfg.repo}).`);
+  }
+
+  if (options.service && process.platform === 'win32') {
+    p.log.warn('--service não é suportado no Windows (sem systemd/launchd). Use `spec-wave dev-agent --run`.');
+  } else if (options.service && servicePath) {
+    const kind = process.platform === 'darwin' ? 'launchd' : 'systemd';
+    try {
+      installService({ kind, home, binPath, servicePath });
+      p.log.success(
+        kind === 'systemd'
+          ? 'Serviço systemd habilitado. Logs: journalctl --user -u spec-wave-agent -f'
+          : `Serviço launchd carregado. Logs: tail -f ${home}/Library/Logs/spec-wave-agent.log`
+      );
+    } catch (err) {
+      p.log.warn(`Falha ao configurar o serviço: ${err.message}`);
+    }
+  }
+
+  const binDir = path.dirname(binPath);
+  if (!isOnPath(binDir, process.env.PATH)) {
+    p.log.warn(`${binDir} não está no PATH. Adicione ao seu shell:\n  export PATH="${binDir}:$PATH"`);
+  }
+  let ghLogin = null;
+  try { ghLogin = sh('gh api user --jq .login'); } catch { /* best-effort */ }
+  if (ghLogin && cfg.owner && ghLogin.toLowerCase() !== cfg.owner.toLowerCase()) {
+    p.log.info(
+      `A conta ativa do gh é ${ghLogin} e o repo é de ${cfg.owner}. Se o agente não enxergar as issues, ` +
+      'exporte o token da conta certa:\n  export GH_TOKEN=$(gh auth token -u <sua-conta>)' +
+      (options.service ? '\n  (no serviço: systemctl --user edit spec-wave-agent → Environment=GH_TOKEN=...)' : '')
+    );
+  }
+
+  p.outro(
+    `${chalk.green('✓')} Agente pronto.\n` +
+    `  Rodar agora:  ${chalk.cyan('spec-wave dev-agent --run')}\n` +
+    '  Enfileirar:   aplique a label spec-wave:dev-agent numa issue [FEATURE] já decomposta.'
+  );
+}
+
+/**
+ * --build: clona (ou atualiza) o repo do agente e compila com cargo.
+ * Alternativa ao --install para plataformas sem binário publicado (Mac Intel,
+ * Linux arm64) ou para rodar o código mais recente da main.
+ */
+async function build(options) {
+  const cwd = process.cwd();
+  const home = homedir();
+  const binPath = path.join(home, BIN_DIR, BIN_NAME + exeSuffix(process.platform));
+  const configPath = path.join(home, AGENT_CONFIG);
+  const srcDir = path.join(home, SRC_DIR);
+
+  const { cfg, error } = readRepoConfig(cwd);
+  if (error) { p.log.error(error); process.exitCode = 1; return; }
+
+  const { problems, warnings } = preflight(cfg);
+  if (!has('cargo')) {
+    problems.push('cargo (Rust) não encontrado — instale com: curl https://sh.rustup.rs -sSf | sh');
+  }
+  for (const w of warnings) p.log.warn(w);
+  if (problems.length > 0) {
+    p.log.error(`Pré-requisitos faltando:\n  - ${problems.join('\n  - ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const ref = options.tag || 'main';
+  const items = planInstall({
+    binPath, binInstalled: existsSync(binPath), installedTag: null,
+    targetTag: `fonte:${ref}`, configPath, configExists: existsSync(configPath),
+    service: options.service ? (process.platform === 'darwin' ? 'launchd' : 'systemd') : null,
+    servicePath: process.platform === 'darwin'
+      ? path.join(home, 'Library', 'LaunchAgents', 'dev.specwave.agent.plist')
+      : path.join(home, '.config', 'systemd', 'user', 'spec-wave-agent.service'),
+    force: !!options.force,
+  });
+  p.note(`${renderInstallReport(items)}\n${chalk.dim(`fonte: ${srcDir} (${ref})`)}`, 'Plano de build');
+
+  if (options.dryRun) { p.outro('Dry-run: nada foi compilado.'); return; }
+
+  // 1. Clone ou atualização do fonte.
+  const s = p.spinner();
+  try {
+    if (!existsSync(path.join(srcDir, '.git'))) {
+      s.start(`Clonando ${AGENT_REPO}...`);
+      mkdirSync(path.dirname(srcDir), { recursive: true });
+      sh(`gh repo clone ${AGENT_REPO} "${srcDir}"`);
+    } else {
+      s.start('Atualizando o fonte...');
+      sh(`git -C "${srcDir}" fetch --all --tags --prune`);
+    }
+    sh(`git -C "${srcDir}" checkout --quiet ${ref}`);
+    // Branch (não tag): traz os commits novos.
+    try { sh(`git -C "${srcDir}" merge --ff-only "origin/${ref}"`); } catch { /* tag/detached: ok */ }
+    s.stop(`Fonte pronto em ${chalk.cyan(srcDir)} (${ref}).`);
+  } catch (err) {
+    s.stop('Falhou.');
+    const msg = String(err.stderr || err.message || '');
+    p.log.error(
+      /not found|Could not resolve|permission/i.test(msg)
+        ? `Não foi possível clonar ${AGENT_REPO} — verifique se a conta ativa do gh tem acesso ao repositório privado.`
+        : `Falha ao preparar o fonte: ${msg.trim() || err.message}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. Build (demora: mostra a saída do cargo ao vivo).
+  p.log.step('Compilando com cargo (pode levar alguns minutos)...');
+  try {
+    execSync('cargo build --release', { cwd: srcDir, stdio: 'inherit' });
+  } catch (err) {
+    p.log.error(`cargo build falhou: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // 3. Instala o binário compilado.
+  const built = path.join(srcDir, 'target', 'release', BIN_NAME + exeSuffix(process.platform));
+  if (!existsSync(built)) {
+    p.log.error(`Binário não encontrado após o build: ${built}`);
+    process.exitCode = 1;
+    return;
+  }
+  mkdirSync(path.dirname(binPath), { recursive: true });
+  copyFileSync(built, binPath);
+  chmodSync(binPath, 0o755);
+  let sha = '';
+  try { sha = sh(`git -C "${srcDir}" rev-parse HEAD`); } catch { /* best-effort */ }
+  writeInstalledTag(home, sourceTag(ref, sha));
+  p.log.success(`Binário instalado em ${chalk.cyan(binPath)} (${sourceTag(ref, sha)}).`);
+
+  await finishSetup({ cfg, home, binPath, configPath, options, configAction: items[1].action,
+                      servicePath: options.service ? items[2].path : null });
+}
+
+function run(options) {
+  const home = homedir();
+  let binPath = path.join(home, BIN_DIR, BIN_NAME + exeSuffix(process.platform));
+  if (!existsSync(binPath)) {
+    try { binPath = sh(process.platform === 'win32' ? `where ${BIN_NAME}` : `command -v ${BIN_NAME}`).split(/\r?\n/)[0]; }
+    catch {
+      p.log.error('spec-wave-agent não encontrado. Rode `spec-wave dev-agent --install` primeiro.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const configPath = path.join(home, AGENT_CONFIG);
+  if (!existsSync(configPath)) {
+    p.log.error(`Config do agente não encontrada em ${configPath}. Rode \`spec-wave dev-agent --install\`.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.log.step(`Executando ${chalk.dim(binPath)} — Ctrl+C encerra com checkpoint.`);
+  p.outro('Logs do agente abaixo.');
+  try {
+    execSync(`"${binPath}"`, {
+      stdio: 'inherit',
+      env: { ...process.env, RUST_LOG: options.debug ? 'debug' : (process.env.RUST_LOG || 'info') },
+    });
+  } catch (err) {
+    // Ctrl+C (SIGINT/SIGTERM) é saída normal: o agente faz checkpoint e sai.
+    if (err.signal === 'SIGINT' || err.signal === 'SIGTERM') return;
+    p.log.error(`Agente encerrou com erro: ${err.message}`);
+    process.exitCode = typeof err.status === 'number' ? err.status : 1;
+  }
+}
+
+export async function devAgent(options = {}) {
+  const modes = ['install', 'build', 'run'].filter((m) => options[m]);
+  if (modes.length > 1) {
+    console.error(`Use apenas um modo por vez (recebido: ${modes.map((m) => `--${m}`).join(', ')}).`);
+    process.exitCode = 1;
+    return;
+  }
+  if (modes.length === 0) {
+    console.error(
+      'Nada a fazer. Use:\n' +
+      '  spec-wave dev-agent --install   instala o agente a partir da release\n' +
+      '  spec-wave dev-agent --build     clona o repo e compila localmente\n' +
+      '  spec-wave dev-agent --run       executa o agente em foreground'
+    );
+    process.exitCode = 1;
+    return;
+  }
+  p.intro(chalk.bold(`spec-wave dev-agent --${modes[0]}`));
+  if (options.install) return install(options);
+  if (options.build) return build(options);
+  run(options);
+}

package/src/commands/doctor.mjs

@@ -11,6 +11,7 @@ import { Octokit } from '@octokit/rest';
 import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import { CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
+import { DEFAULT_MAX_TOKENS } from '../lib/claude.mjs';
 
 // Mesmo padrão de instanciação de github-rest.mjs, mas com o logger mudo:
 // aqui 404/403 são resultados esperados dos checks, não erros a logar.
@@ -297,6 +298,16 @@ async function checkAi(ctx) {
   if (fileAi.models && Object.keys(fileAi.models).length > 0) {
     notes.push(`Modelos por ação (ai.models): ${Object.entries(fileAi.models).map(([a, m]) => `${a}=${m}`).join(', ')}.`);
   }
+  // Teto de saída: quando o documento não cabe, a geração falha com
+  // TruncatedOutputError em vez de gravar um arquivo cortado — mostrar o valor
+  // resolvido evita ter que abrir o log do Action para descobri-lo.
+  const maxTokensNote = fileAi.maxTokens
+    ? `${fileAi.maxTokens} (ai.maxTokens)`
+    : `${DEFAULT_MAX_TOKENS} (default)`;
+  const byAction = fileAi.maxTokensByAction && Object.keys(fileAi.maxTokensByAction).length > 0
+    ? ` · por ação: ${Object.entries(fileAi.maxTokensByAction).map(([a, t]) => `${a}=${t}`).join(', ')}`
+    : '';
+  notes.push(`Teto de saída: ${maxTokensNote}${byAction}.`);
 
   let status = 'ok';
   if (process.env[provider.secret]) {

package/src/commands/generate-plan.mjs

@@ -154,6 +154,20 @@ export async function generatePlan({ issueNumber }) {
     }
 
     console.log(`plan.md criado em: ${filePath}`);
+  } catch (err) {
+    // Mesmo beco sem saída do generate-spec: o gatilho é `issues: [labeled]`,
+    // então com a label ainda aplicada re-adicioná-la não dispara nada. Remove
+    // o gatilho e reporta na issue; o erro segue propagando.
+    // (O catch acima, na crítica adversarial, cobre só aquele trecho.)
+    await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan').catch(() => {});
+    await commentOnIssue(
+      token, owner, repo, parseInt(issueNumber, 10),
+      `❌ **Falha ao gerar o plan.md**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `A label \`spec-wave:plan\` foi removida para destravar o gatilho — ` +
+      `adicione-a de novo para tentar outra vez.`
+    ).catch(() => {});
+    throw err;
   } finally {
     // Best-effort: nunca propaga erro (ver recordUsage).
     await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });

package/src/commands/generate-spec.mjs

@@ -125,6 +125,21 @@ export async function generateSpec({ issueNumber }) {
     );
 
     console.log(`spec.md criado em: ${filePath}`);
+  } catch (err) {
+    // Sem isto a label de gatilho fica aplicada — e como o workflow dispara em
+    // `issues: [labeled]`, re-adicionar uma label já presente não emite evento:
+    // a issue vira um beco sem saída, sem comentário e sem sinal no board.
+    // Espelha o tratamento do tipo não suportado (acima): remove o gatilho e
+    // reporta na issue. O erro segue propagando para o Action falhar visível.
+    await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec').catch(() => {});
+    await commentOnIssue(
+      token, owner, repo, parseInt(issueNumber, 10),
+      `❌ **Falha ao gerar a spec.md**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `A label \`spec-wave:spec\` foi removida para destravar o gatilho — ` +
+      `adicione-a de novo para tentar outra vez.`
+    ).catch(() => {});
+    throw err;
   } finally {
     // Best-effort: nunca propaga erro (ver recordUsage).
     await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });

package/src/commands/validate.mjs

@@ -4,6 +4,7 @@ import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { CONFIG_FILE, LABEL_CRITIQUE_FAILED, REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
+import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
 
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
@@ -49,6 +50,9 @@ export async function validate({ issueNumber }) {
         errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
       }
     }
+    for (const problem of findIncompleteDocSigns(planContent)) {
+      errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
+    }
   }
 
   // Check spec.md
@@ -62,6 +66,11 @@ export async function validate({ issueNumber }) {
         errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
       }
     }
+    // Seções presentes não garantem documento completo: um corte dentro da
+    // última seção passa na checagem acima (foi o caso da EP2-F13).
+    for (const problem of findIncompleteDocSigns(specContent)) {
+      errors.push(`❌ \`spec.md\` parece incompleto: ${problem}`);
+    }
   }
 
   // Remove trigger label

package/src/lib/claude.mjs

@@ -5,19 +5,30 @@ import { CONFIG_FILE, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
 import { lintLanguage } from './output-lint.mjs';
 import { computeCost } from './usage-report.mjs';
 
+// Teto de saída padrão. O valor anterior (8192) truncava specs reais: um
+// documento de ~20 KB em pt-BR já custa ~6k tokens, e modelos com raciocínio
+// (Opus 4.7+, deepseek-r1) gastam o restante "pensando" ANTES de escrever. O
+// teto de saída dos modelos atuais é 128k — 32k deixa folga sem virar cheque em
+// branco. Ajustável por `ai.maxTokens` / `ai.maxTokensByAction`.
+export const DEFAULT_MAX_TOKENS = 32768;
+
 /**
- * Resolve provider/modelo de IA (função PURA — testável sem process.env nem fs).
+ * Resolve provider/modelo/teto de tokens de IA (função PURA — testável sem
+ * process.env nem fs).
  *
  * Precedência do modelo: env.SPEC_WAVE_MODEL → fileAi.models[action] →
  * fileAi.model → default do provider. Provider: env.SPEC_WAVE_PROVIDER →
  * fileAi.provider → default. Assim uma ação específica (ex.: critique) pode
  * usar modelo próprio via bloco `ai.models` do .spec-wave.json.
  *
+ * maxTokens segue a mesma forma: env.SPEC_WAVE_MAX_TOKENS →
+ * fileAi.maxTokensByAction[action] → fileAi.maxTokens → DEFAULT_MAX_TOKENS.
+ *
  * @param {object} params
  * @param {object} [params.env] objeto tipo process.env
  * @param {object} [params.fileAi] bloco `ai` do .spec-wave.json
  * @param {string} [params.action] ação de IA (ver AI_ACTIONS em config.mjs)
- * @returns {{ provider: string, model: string, secret: string, pricing: object|null }}
+ * @returns {{ provider: string, model: string, secret: string, pricing: object|null, maxTokens: number }}
  */
 export function resolveAiConfig({ env = {}, fileAi = {}, action } = {}) {
   const provider = (env.SPEC_WAVE_PROVIDER || fileAi.provider || DEFAULT_PROVIDER).toLowerCase();
@@ -29,7 +40,24 @@ export function resolveAiConfig({ env = {}, fileAi = {}, action } = {}) {
   // pricing: tabela `ai.pricing` do .spec-wave.json ({ [model]: { input,
   // output } } em USD/1M tokens) — usada para estimar custo quando o provider
   // não devolve o valor (Anthropic).
-  return { provider: meta.value, model, secret: meta.secret, pricing: fileAi.pricing || null };
+  const maxTokens = positiveInt(env.SPEC_WAVE_MAX_TOKENS)
+    ?? (action ? positiveInt(fileAi.maxTokensByAction?.[action]) : undefined)
+    ?? positiveInt(fileAi.maxTokens)
+    ?? DEFAULT_MAX_TOKENS;
+  return {
+    provider: meta.value,
+    model,
+    secret: meta.secret,
+    pricing: fileAi.pricing || null,
+    maxTokens,
+  };
+}
+
+// Config vinda de JSON/env pode trazer string, zero ou lixo — só aceita inteiro
+// positivo, senão cai na próxima fonte da precedência.
+function positiveInt(value) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
 }
 
 // Resolve o provider/modelo de IA a partir do .spec-wave.json (gravado pelo init
@@ -49,6 +77,87 @@ function resolveAi(action) {
   return resolveAiConfig({ env: process.env, fileAi, action });
 }
 
+// Retry de falha transitória do provedor. Sem isto, um corpo cortado numa
+// geração de 90s derruba o Action inteiro e a issue fica sem spec — o custo de
+// esperar alguns segundos é irrisório perto de refazer o ciclo à mão.
+export const RETRY_ATTEMPTS = 3;
+const RETRY_BASE_MS = 2000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Transitório = vale a pena repetir a MESMA requisição. Erro de configuração
+// (401, 400, chave ausente) não entra aqui: repetir só atrasa a mensagem útil.
+export function isTransientProviderError(err) {
+  if (!err) return false;
+  if (err.transient) return true; // marcado na origem (corpo inválido/vazio)
+  const status = err.status ?? err.statusCode;
+  if (status === 429 || (status >= 500 && status < 600)) return true;
+  // undici/fetch: falha de rede vem como TypeError com cause
+  return /fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up|network|aborted/i
+    .test(err.message || '');
+}
+
+export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs = RETRY_BASE_MS } = {}) {
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (attempt === attempts || !isTransientProviderError(err)) break;
+      const delayMs = baseMs * 2 ** (attempt - 1); // 2s, 4s, 8s…
+      console.warn(
+        `${label}: falha transitória na tentativa ${attempt}/${attempts} (${err.message}) — ` +
+        `repetindo em ${delayMs / 1000}s.`
+      );
+      await sleep(delayMs);
+    }
+  }
+  throw lastErr;
+}
+
+// Truncamento: os dois provedores dizem explicitamente que cortaram a saída no
+// teto de tokens — OpenRouter (formato OpenAI) em `choices[0].finish_reason`,
+// Anthropic em `message.stop_reason`. Ignorar esse campo é o que produzia um
+// documento cortado no meio de uma frase, commitado como se estivesse completo.
+const TRUNCATION_REASONS = new Set(['length', 'max_tokens']);
+
+/** Motivo de parada indica saída cortada no teto de tokens? (função PURA) */
+export function isTruncationReason(reason) {
+  return TRUNCATION_REASONS.has(reason);
+}
+
+// Repetir a MESMA requisição depois de truncar dá o mesmo corte — só sobe o
+// custo. Por isso NÃO é marcado como transitório: o erro sobe, o Action falha
+// visível, destrava a label e comenta na issue o que ajustar.
+export class TruncatedOutputError extends Error {
+  constructor({ provider, model, maxTokens, reason, chars }) {
+    super(
+      `Saída truncada pelo teto de tokens (${provider} · ${model} · max_tokens=${maxTokens} · ` +
+      `motivo=${reason}). Foram gerados ~${chars} caracteres antes do corte. ` +
+      'Aumente `ai.maxTokens` (ou `ai.maxTokensByAction`) no .spec-wave.json, ou reduza o ' +
+      'tamanho da issue de origem. O documento NÃO foi gravado — um documento cortado ' +
+      'passaria na validação de seções e valeria menos que nenhum.'
+    );
+    this.name = 'TruncatedOutputError';
+    this.truncated = true;
+  }
+}
+
+// Os parâmetros de sampling foram REMOVIDOS a partir do Claude Opus 4.7 (vale
+// para 4.8 e 5, Sonnet 5, Fable 5 e Mythos 5): enviar temperature/top_p/top_k
+// devolve 400. A OpenRouter hoje normaliza e não quebra, mas o caminho direto
+// da Anthropic quebraria em toda requisição — daí a checagem no modelo, não no
+// provider. Aceita tanto o id primário (`claude-opus-4-8`) quanto o slug da
+// OpenRouter (`anthropic/claude-opus-4.8`).
+const MODELS_WITHOUT_SAMPLING_PARAMS =
+  /claude-(?:opus-(?:4[.-]7|4[.-]8|5)|sonnet-5|fable-5|mythos-5)/i;
+
+/** O modelo ainda aceita `temperature`? (função PURA) */
+export function supportsTemperature(model) {
+  return !MODELS_WITHOUT_SAMPLING_PARAMS.test(model || '');
+}
+
 // temperature padrão 0.2 (RFC-002 §5): "Determinism over Creativity". Pode ser
 // sobrescrita por chamada via opts, mas o default cobre spec/plan/decompose.
 //
@@ -66,10 +175,16 @@ function resolveAi(action) {
 export async function generateDocument(systemPrompt, userContent, opts = {}) {
   const ai = resolveAi(opts.action);
   const temperature = opts.temperature ?? 0.2;
-  // Modelos de reasoning (ex.: deepseek-r1) consomem tokens "pensando" antes da
-  // resposta, então o teto precisa ser maior para o plano não vir truncado.
-  const maxTokens = opts.maxTokens ?? 8192;
-  console.log(`Provider de IA: ${ai.provider} · modelo: ${ai.model} · temperature: ${temperature} · max_tokens: ${maxTokens}`);
+  // Modelos de reasoning (ex.: deepseek-r1, Opus 4.7+) consomem tokens
+  // "pensando" antes da resposta, então o teto precisa cobrir raciocínio +
+  // documento — ver DEFAULT_MAX_TOKENS.
+  const maxTokens = opts.maxTokens ?? ai.maxTokens;
+  const sendTemperature = supportsTemperature(ai.model);
+  console.log(
+    `Provider de IA: ${ai.provider} · modelo: ${ai.model} · ` +
+    `temperature: ${sendTemperature ? temperature : 'n/a (removida neste modelo)'} · ` +
+    `max_tokens: ${maxTokens}`
+  );
 
   // Acumuladores de uso desta invocação (1 ou 2 chamadas, com o retry de lint).
   let inputTokens = 0;
@@ -77,9 +192,14 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
   let cost = null; // soma dos custos conhecidos; se todos null → null
 
   const generate = async (system) => {
-    const { text, usage } = ai.provider === 'openrouter'
-      ? await generateWithOpenRouter(system, userContent, ai, temperature, maxTokens)
-      : await generateWithAnthropic(system, userContent, ai, temperature, maxTokens);
+    const callOpts = {
+      temperature: sendTemperature ? temperature : undefined,
+      maxTokens,
+    };
+    const { text, usage } = await withRetry(`Geração via ${ai.provider}`, () =>
+      ai.provider === 'openrouter'
+        ? generateWithOpenRouter(system, userContent, ai, callOpts)
+        : generateWithAnthropic(system, userContent, ai, callOpts));
     inputTokens += usage.inputTokens;
     outputTokens += usage.outputTokens;
     if (typeof usage.cost === 'number') cost = (cost ?? 0) + usage.cost;
@@ -179,7 +299,7 @@ export function extractOpenRouterUsage(usage) {
   };
 }
 
-async function generateWithAnthropic(systemPrompt, userContent, ai, temperature, maxTokens) {
+async function generateWithAnthropic(systemPrompt, userContent, ai, { temperature, maxTokens }) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -192,15 +312,56 @@ async function generateWithAnthropic(systemPrompt, userContent, ai, temperature,
   const message = await client.messages.create({
     model: ai.model,
     max_tokens: maxTokens,
-    temperature,
+    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5):
+    // enviá-la devolve 400.
+    ...(temperature === undefined ? {} : { temperature }),
     messages: [{ role: 'user', content: userContent }],
     system: systemPrompt,
   });
 
-  return { text: message.content[0].text, usage: extractAnthropicUsage(message.usage) };
+  // A resposta nem sempre começa com um bloco de texto (recusa, resposta vazia):
+  // `content[0].text` cru virava TypeError com mensagem inútil.
+  const text = (message.content || [])
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+
+  if (message.stop_reason === 'refusal') {
+    throw new Error(
+      `A Anthropic recusou a requisição (stop_reason=refusal` +
+      `${message.stop_details?.category ? `, categoria=${message.stop_details.category}` : ''}). ` +
+      'Revise o conteúdo da issue de origem.'
+    );
+  }
+  if (message.stop_reason === 'model_context_window_exceeded') {
+    // Estouro na ENTRADA — subir max_tokens não resolve; o que precisa encolher
+    // é a issue/contexto enviado.
+    throw new Error(
+      `Contexto de entrada excedido (${ai.model}). Reduza o tamanho da issue de origem ` +
+      'ou do tech_context antes de repetir.'
+    );
+  }
+  if (isTruncationReason(message.stop_reason)) {
+    throw new TruncatedOutputError({
+      provider: 'anthropic',
+      model: ai.model,
+      maxTokens,
+      reason: message.stop_reason,
+      chars: text.length,
+    });
+  }
+  if (!text) {
+    const err = new Error(
+      `A Anthropic retornou resposta sem texto (stop_reason=${message.stop_reason}).`
+    );
+    err.transient = true;
+    throw err;
+  }
+
+  return { text, usage: extractAnthropicUsage(message.usage) };
 }
 
-async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature, maxTokens) {
+async function generateWithOpenRouter(systemPrompt, userContent, ai, { temperature, maxTokens }) {
   const apiKey = process.env.OPENROUTER_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -220,7 +381,8 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature
     body: JSON.stringify({
       model: ai.model,
       max_tokens: maxTokens,
-      temperature,
+      // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5).
+      ...(temperature === undefined ? {} : { temperature }),
       messages: [
         { role: 'system', content: systemPrompt },
         { role: 'user', content: userContent },
@@ -232,13 +394,48 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature
 
   if (!res.ok) {
     const body = await res.text();
-    throw new Error(`OpenRouter API ${res.status}: ${body}`);
+    const err = new Error(`OpenRouter API ${res.status}: ${body}`);
+    err.status = res.status;
+    throw err;
   }
 
-  const data = await res.json();
-  const content = stripReasoning(data?.choices?.[0]?.message?.content || '');
+  // Um 200 com corpo vazio ou cortado acontece em gerações longas. `res.json()`
+  // cru lançaria "Unexpected end of JSON input" — mensagem que não diz nada a
+  // quem está olhando o board. Lê como texto, reporta o que veio e marca como
+  // transitória para o retry pegar.
+  const raw = await res.text();
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    const err = new Error(
+      `OpenRouter devolveu ${res.status} com corpo inválido (${raw.length} bytes): ` +
+      `${raw.slice(0, 200) || '(vazio)'}`
+    );
+    err.transient = true;
+    throw err;
+  }
+
+  const choice = data?.choices?.[0];
+  const content = stripReasoning(choice?.message?.content || '');
+
+  // finish_reason='length' = cortado no teto. Checado ANTES do conteúdo vazio:
+  // um corte durante o raciocínio devolve texto vazio, e "resposta vazia" (que
+  // é tratada como transitória) esconderia a causa real por trás de 3 retries.
+  if (isTruncationReason(choice?.finish_reason)) {
+    throw new TruncatedOutputError({
+      provider: 'openrouter',
+      model: ai.model,
+      maxTokens,
+      // native_finish_reason preserva o motivo cru do provedor upstream.
+      reason: `${choice.finish_reason}${choice.native_finish_reason ? `/${choice.native_finish_reason}` : ''}`,
+      chars: content.length,
+    });
+  }
   if (!content) {
-    throw new Error(`OpenRouter retornou resposta vazia: ${JSON.stringify(data)}`);
+    const err = new Error(`OpenRouter retornou resposta vazia: ${JSON.stringify(data)}`);
+    err.transient = true;
+    throw err;
   }
   return { text: content, usage: extractOpenRouterUsage(data.usage) };
 }

package/src/lib/critique.mjs

@@ -151,7 +151,11 @@ export async function runCritique({ kind, spec, plan, techContextYaml, stories,
   const raw = await generateDocument(buildSystemPrompt(kind), userContent, {
     action: 'critique',
     temperature: 0,
-    maxTokens: 4096,
+    // Teto próprio: a crítica devolve uma lista JSON de findings, bem menor que
+    // um spec/plan. 4096 ficava justo quando os dois documentos são longos e o
+    // JSON vinha cortado — o parse falhava sem dizer por quê. Com a detecção de
+    // truncamento o corte agora é explícito, e a folga evita chegar nele.
+    maxTokens: 8192,
     usage,
   });
 

package/src/lib/doc-completeness.mjs

@@ -0,0 +1,54 @@
+// Rede de segurança contra documento cortado.
+//
+// A defesa principal contra truncamento é a detecção no provedor
+// (claude.mjs → TruncatedOutputError): um documento cortado nunca chega a ser
+// gravado. Esta checagem cobre o que escapa disso — documento editado à mão,
+// commit parcial, ou geração feita por uma versão antiga da CLI.
+//
+// O critério é DELIBERADAMENTE estreito. Só entram sinais que não têm leitura
+// inocente em Markdown: um falso positivo aqui bloqueia o ready de uma Feature
+// legítima, o que é pior que deixar passar um documento suspeito. "Termina sem
+// ponto final" e afins ficaram de fora de propósito — títulos, tabelas e itens
+// de lista terminam assim o tempo todo.
+
+/**
+ * Procura sinais objetivos de documento incompleto (função PURA).
+ *
+ * @param {string} content conteúdo do markdown
+ * @returns {string[]} descrições dos problemas encontrados (vazio = sem sinais)
+ */
+export function findIncompleteDocSigns(content) {
+  const problems = [];
+  const text = content || '';
+
+  if (!text.trim()) {
+    return ['o arquivo está vazio'];
+  }
+
+  // 1. Cerca de código aberta. Um ``` sem par significa que o corte aconteceu
+  //    dentro de um bloco (gherkin, mermaid, yaml) — não há leitura válida.
+  const fences = text.split('\n').filter((line) => /^\s*```/.test(line)).length;
+  if (fences % 2 !== 0) {
+    problems.push(`bloco de código não fechado (${fences} marcações \`\`\`)`);
+  }
+
+  // 2. Parênteses/colchetes abertos na última linha com conteúdo. É o formato
+  //    exato de um corte no meio da frase — ex.: "...(versionCode/S" — e prosa
+  //    completa não termina assim.
+  const lines = text.split('\n').filter((line) => line.trim());
+  const lastLine = lines[lines.length - 1] || '';
+  for (const [open, close, nome] of [['(', ')', 'parêntese'], ['[', ']', 'colchete']]) {
+    const opened = lastLine.split(open).length - 1;
+    const closed = lastLine.split(close).length - 1;
+    if (opened > closed) {
+      problems.push(`${nome} aberto e não fechado na última linha: "${truncate(lastLine)}"`);
+    }
+  }
+
+  return problems;
+}
+
+function truncate(line, max = 60) {
+  const t = line.trim();
+  return t.length > max ? `${t.slice(0, max)}…` : t;
+}

package/src/templates/agent/dev.specwave.agent.plist

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+ "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>dev.specwave.agent</string>
+  <key>ProgramArguments</key>
+    <array><string>{bin}</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>RUST_LOG</key><string>info</string>
+    <key>PATH</key><string>{path}</string>
+  </dict>
+  <key>StandardOutPath</key><string>{home}/Library/Logs/spec-wave-agent.log</string>
+  <key>StandardErrorPath</key><string>{home}/Library/Logs/spec-wave-agent.log</string>
+</dict></plist>

package/src/templates/agent/spec-wave-agent.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=spec-wave dev agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart={bin}
+Restart=on-failure
+RestartSec=10
+Environment=RUST_LOG=info
+Environment=PATH={path}
+# SIGTERM no desligamento => checkpoint + release do lease (takeover imediato)
+KillSignal=SIGTERM
+# Deve ser maior que o tempo do checkpoint (commit + push do WIP)
+TimeoutStopSec=30
+
+[Install]
+WantedBy=default.target

package/src/templates/skill/SKILL.md

@@ -67,6 +67,10 @@ Exemplo de `.spec-wave.json`:
 
 Exceção: se o usuário pedir explicitamente para revisar ou melhorar um documento já gerado, use o Write tool para editar o arquivo local.
 
+**Nunca crie Story ou Task avulsa com `/spec-wave issue`.** Story e Task nascem do `decompose`, já na Etapa **✅ Ready** e vinculadas ao pai. Criadas à mão elas caem em **📥 Backlog**, que é a coluna de descoberta de *produto* — e ali **não aparecem em tela nenhuma** da UI do spec-wave: o inbox do PM lista só Features, a tela do Dev lê a etapa 🚧 Desenvolvimento e a fila do TL lê ✅ Ready. Se o usuário insistir numa Story/Task avulsa, crie-a **com `--parent <n>`** e, logo em seguida, avance-a para ✅ Ready — explicando por que esse passo extra é necessário.
+
+**Nunca use `gh issue create` para criar work items.** Ele não adiciona a issue ao Project, então ela fica **sem Etapa** — e some de todas as telas da UI. Use sempre `npx @spec-wave/cli issue` (ou os atalhos `initiative` / `feature`).
+
 ---
 
 ## Fluxo Kanban
@@ -77,6 +81,20 @@ Exceção: se o usuário pedir explicitamente para revisar ou melhorar um docume
 → 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done
 ```
 
+Essa é a sequência completa, mas **cada tipo de artefato percorre só um trecho dela** — e, principalmente, **nasce numa Etapa diferente**. Consulte esta tabela antes de criar ou mover qualquer item.
+
+| Artefato | Nasce em | Percorre | Observações |
+|----------|----------|----------|-------------|
+| **Initiative / Epic** | 📥 Backlog | — | Agrupadores. Não têm fluxo próprio; acompanham os filhos. |
+| **Feature** | 📥 Backlog | 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready → 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done | Fica parada em **✅ Ready** esperando um dev assumir — é ali que ela aparece na fila do TL. Só avança para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. |
+| **Story** | **✅ Ready** (criada pelo `decompose`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | **Nunca nasce em 📥 Backlog.** |
+| **Task** | **✅ Ready** (criada pelo `decompose`) | 🚧 Desenvolvimento → 🎉 Done | **Não** passa por Code Review, QA nem Homologação — só `task start` e `task done`. |
+| **RFC** | 📥 Backlog | decompõe direto em **Tasks** (que nascem em ✅ Ready) | Não usa spec/plan. |
+| **Bug** | 📥 Backlog | 🚧 Desenvolvimento → 🎉 Done | Ao aprovar, vai direto para Done (não passa por Homologação). |
+| **Spike** | 📥 Backlog | **movido só à mão pelo usuário** | Nunca avance a Etapa de um Spike por conta própria. |
+
+**Regra da Etapa:** a Etapa **só avança, nunca retrocede**. O campo **Status** (Todo / In Progress / Done) mede o progresso *dentro* da Etapa e reinicia a cada avanço. Prefira sempre os comandos da CLI (`task start|done`, `story review`) a mutações manuais no board — eles embutem essas regras.
+
 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)
@@ -115,7 +133,9 @@ Esta skill é um **wrapper** da CLI `@spec-wave/cli`, sempre invocada como `npx
 | `--priority <p>` | string | **Opcional.** `P0`, `P1`, `P2` ou `P3`. Omita se o usuário não pediu — a prioridade fica `null` (sem prioridade). Nunca atribua por conta própria. |
 | `--area <area>` | string | `Frontend`, `Backend`, `Mobile`, `Infra`, `DevOps` ou `Data`. |
 
-> Faz tudo: cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula ao parent como sub-issue, adiciona ao Project e define os campos **Etapa = 📥 Backlog**, **Work Item Type**, **Area** e, **só se informada, Priority**. Grava `Parent: #N` no corpo. Lê o Project do `.spec-wave.json`. **Não use `gh issue create` direto** — ele não adiciona ao board nem vincula o parent.
+> Faz tudo: cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula ao parent como sub-issue, adiciona ao Project e define os campos **Etapa**, **Work Item Type**, **Area** e, **só se informada, Priority**. Grava `Parent: #N` no corpo. Lê o Project do `.spec-wave.json`. **Não use `gh issue create` direto** — ele não adiciona ao board nem vincula o parent.
+>
+> ⚠️ **A Etapa inicial é sempre 📥 Backlog, para qualquer `--type`.** Isso é o correto para **Initiative, Epic, Feature, RFC, Bug e Spike**. Para **Story e Task está errado** — elas pertencem a ✅ Ready (veja a *Regra fundamental*): prefira criá-las via `decompose`; se criar à mão, avance a Etapa logo depois.
 
 ### `@spec-wave/cli initiative` — atalho de `issue --type initiative`
 Cria o nó raiz da hierarquia (agrupa Epics). Mesmas flags do `issue` exceto `--type` (fixo em `initiative`) e `--parent` (Initiative é raiz, não tem pai).
@@ -180,7 +200,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 > Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Feature** → lista as Stories (sub-issues), **ordena topologicamente pelas dependências** (`Depende de:` + *blocked by*), **pula** as já em 👀 Code Review+ (listadas no contexto como "não tocar") e monta **um único** contexto com todas as pendentes (cada uma com suas Tasks), acionando o spec-kit **uma vez** com `{issue}/{type}/{title}` da Feature — **ciclo de dependências entre Stories pendentes aborta o comando (exit 1)**; **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui os **comentários da issue**, um **digest do código recente** e um **aviso de dependências pendentes** quando a issue depende (linha `Depende de: #N` ou relação nativa *blocked by*) de outra que ainda não foi concluída — nesse caso, confirme com o usuário antes de seguir. Inclui também instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** para Code Review quando **TODAS as suas Stories** já estiverem em Code Review — enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento. Etapa só avança (nunca volta); Status mede o progresso dentro da etapa.
 
 ### `@spec-wave/cli doctor` — preflight de auth e configuração (comando LOCAL)
-Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models` + secrets do Actions), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e presença dos workflows.
+Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models`/teto de saída + secrets do Actions), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e presença dos workflows.
 
 > Saída: `✓` ok, `✗` problema confirmado, `!` não verificável (best-effort — falha de rede nunca derruba o doctor). **Exit 1** se houver algum `✗`. **Quando rodar:** no início de uma sessão de trabalho, ou sempre que aparecer um erro estranho (ex.: **404 ao criar issues** — causa típica: token sem acesso ao repo/org, que o doctor aponta). É o primeiro passo de troubleshooting — prefira-o a depurar `gh api` na mão.
 
@@ -253,6 +273,25 @@ Cada ação de IA (`spec`, `plan`, `decompose`, `critique`) pode usar um modelo
 
 Edite o bloco `ai` no `.spec-wave.json` (e commite) — o `doctor` mostra o provider, o modelo e os overrides de `ai.models` resolvidos.
 
+### Teto de saída (`ai.maxTokens`) e truncamento
+
+O teto de tokens de saída é **32.768** por padrão, ajustável globalmente por `ai.maxTokens` e por ação em `ai.maxTokensByAction` (mesma forma de `model`/`models`; `SPEC_WAVE_MAX_TOKENS` na env tem precedência):
+
+```json
+{
+  "ai": {
+    "maxTokens": 32768,
+    "maxTokensByAction": { "spec": 49152 }
+  }
+}
+```
+
+**Quando a saída não cabe no teto, a geração FALHA — nada é gravado.** Os dois provedores sinalizam o corte (`finish_reason: "length"` no OpenRouter, `stop_reason: "max_tokens"` na Anthropic) e a CLI transforma isso em erro: um documento cortado no meio de uma frase passaria na validação de seções e valeria menos que documento nenhum. O erro é comentado na issue e a label de gatilho é removida, então basta corrigir e re-aplicar a label.
+
+Se acontecer, as saídas são: **aumentar o teto** (`ai.maxTokens`) ou **reduzir o tamanho da issue de origem** — corpo muito grande gera documento muito grande. Modelos com raciocínio (Opus 4.7+, deepseek-r1) gastam parte do teto "pensando" antes de escrever, então o teto precisa cobrir raciocínio + documento.
+
+O `validate` também recusa documento com sinal objetivo de corte (bloco de código não fechado, parêntese aberto na última linha) — rede de segurança para documento editado à mão ou gerado por versão antiga da CLI.
+
 ---
 
 ## Sub-comandos
@@ -314,7 +353,7 @@ Configura o spec-wave no repositório. Você dirige o `init` com flags — **nun
 
 ### `/spec-wave issue <tipo> <descrição>` · `/spec-wave initiative <descrição>` · `/spec-wave feature <descrição>`
 
-Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado ao board em **📥 Backlog**, opcionalmente como sub-issue de um parent.
+Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado ao board, opcionalmente como sub-issue de um parent. A Etapa inicial é **📥 Backlog** — correta para Initiative, Epic, Feature, RFC, Bug e Spike. **Story e Task não devem ser criadas por aqui** (nascem do `decompose`, em ✅ Ready — veja a *Regra fundamental*).
 
 **Hierarquia típica:** Initiative → Epic → Feature → Story → Task. A **Initiative** é o nó raiz e agrupa Epics. Use `--parent <n>` para criar como sub-issue do nível acima (ex.: um Epic filho de uma Initiative, ou uma Story filha de uma Feature). O GitHub mostra o parent na issue filha e vice-versa; a CLI ainda grava `Parent: #N` no corpo.
 
@@ -334,6 +373,7 @@ Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado
    ```
    Para Features, pode usar o atalho `npx @spec-wave/cli@latest feature --title ...` (equivale a `--type feature`).
    A CLI cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula como sub-issue do parent, adiciona ao Project e define Etapa = 📥 Backlog + Work Item Type + Area (+ Priority só se informada). **Não use `gh issue create`** (não adiciona ao board nem vincula o parent).
+   **Se o tipo for `story` ou `task`**, avise o usuário que o caminho normal é o `decompose` e, se ele confirmar mesmo assim, avance a Etapa para ✅ Ready depois de criar — senão o item fica invisível na UI.
 3. Informe o número criado e o vínculo com o pai (se houver).
 4. Para Features: "Quando quiser iniciar, mova para **📋 Spec** e use `/spec-wave spec <número>` para gerar a especificação funcional (o plano técnico vem depois)".