@spec-wave/cli 0.33.0 → 0.34.0

package/src/commands/implement.mjs

@@ -7,6 +7,7 @@ import { resolveToken } from '../api/auth.mjs';
 import {
   CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE, STAGE_ORDER,
   PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE, labelNames,
+  TRAILER_STORY, TRAILER_TASKS, TRAILER_AGENT,
 } from '../config.mjs';
 import { getIssue, listIssueComments, listBlockedBy, getFileContent } from '../api/github-rest.mjs';
 import { listSubIssues, getIssueParent } from '../api/github-graphql.mjs';
@@ -23,6 +24,9 @@ import { extractPathsFromPlan, buildCodeDigest } from '../lib/code-digest.mjs';
 import { findConfigPath, resolveFromRoot, loadConfig } from '../lib/project-root.mjs';
 import { loadFeatureStories, loadBoardSnapshot, cachedSubIssues } from '../lib/story-graph.mjs';
 import { resolveCacheTtl } from '../lib/net-cache.mjs';
+import { deliveryMode } from '../lib/delivery-mode.mjs';
+import { renderTrailers, missingTrailers, readLocalCommitMessages } from '../lib/commit-trailers.mjs';
+import { currentGitBranch } from '../lib/repo-links.mjs';
 
 // Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
 const WORK_DIR = '.spec-wave';
@@ -170,9 +174,9 @@ function pushDigestSpecPlan(lines, { codeDigest, spec, plan, specPath, planPath
 }
 
 // Monta o markdown de contexto que será entregue ao spec-kit implement.
-function buildContext({
+export function buildContext({
   type, issue, tasks, feature, siblingStories = [], spec, plan, specPath, planPath,
-  comments = [], codeDigest = null, blockedByWarnings = [],
+  comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack',
 }) {
   const lines = [];
   lines.push(`# Contexto de implementação — ${type} #${issue.number}`);
@@ -216,13 +220,35 @@ function buildContext({
     lines.push('   4. Só então avance para a próxima Task.');
     lines.push('');
     lines.push(`3. **Ao concluir TODA a Story** (todas as Tasks na Etapa ${STAGE_DONE}):`);
-    lines.push('   1. Faça o **commit** de todas as mudanças da implementação.');
-    // Draft de propósito: numa pilha de Stories (um PR baseado no anterior),
-    // cada rebase em cascata dispararia o CI inteiro em PRs que ninguém vai
-    // mergear naquele estado. Rascunho não mergeia (o GitHub bloqueia) e o
-    // required check continua valendo: quem revisa marca o PR como pronto, o
-    // `ready_for_review` dispara o CI, e só então o merge destrava.
-    lines.push(`   2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`) — o CI não roda em rascunho; quem revisa marca o PR como pronto e é aí que os checks disparam.`);
+    lines.push(
+      `   1. Faça o **commit** de todas as mudanças da implementação. O assunto é livre — ` +
+      'inclua estes `git trailer`(s) no **rodapé** (após uma linha em branco), literalmente ' +
+      'assim, sem alterar as chaves:'
+    );
+    lines.push('      ```');
+    lines.push(renderTrailers({
+      story: issue.number, tasks: tasks.map(t => t.number),
+      agent: mode === 'agent' ? 'spec-wave-agent' : undefined,
+    }).split('\n').map(l => `      ${l}`).join('\n'));
+    lines.push('      ```');
+    if (mode === 'agent') {
+      // Sob o dev-agent, o daemon mantém UM branch e UM PR por Feature
+      // (agent/issue-<n>) e é ele quem abre o PR ao final — nunca o modelo.
+      // Instruir "abra o PR da Story" aqui é o que produzia um branch lateral
+      // (agent/issue-<n>-story-<m>) cujo trabalho nunca entra nesse PR.
+      lines.push(
+        '   2. Faça **push no branch atual** — **NÃO crie um branch novo** e ' +
+        '**NÃO abra Pull Request**: o agente já mantém um único branch e um único ' +
+        'Pull Request para a Feature inteira, aberto por ele mesmo ao final.'
+      );
+    } else {
+      // Draft de propósito: numa pilha de Stories (um PR baseado no anterior),
+      // cada rebase em cascata dispararia o CI inteiro em PRs que ninguém vai
+      // mergear naquele estado. Rascunho não mergeia (o GitHub bloqueia) e o
+      // required check continua valendo: quem revisa marca o PR como pronto, o
+      // `ready_for_review` dispara o CI, e só então o merge destrava.
+      lines.push(`   2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`) — o CI não roda em rascunho; quem revisa marca o PR como pronto e é aí que os checks disparam.`);
+    }
     lines.push(
       `   3. **Avance a Etapa da Story #${issue.number} para ${STAGE_CODE_REVIEW}** ` +
       `(reinicie o Status para ${PROGRESS_TODO}). As Tasks já estão em ${STAGE_DONE}.`
@@ -374,7 +400,7 @@ export function planFeatureImplementation(stories, {
 export function buildFeatureContext({
   feature, stories, skipped = [],
   spec, plan, specPath, planPath,
-  comments = [], codeDigest = null, blockedByWarnings = [],
+  comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack',
 }) {
   const lines = [];
   lines.push(`# Contexto de implementação — Feature #${feature.number}`);
@@ -402,7 +428,32 @@ export function buildFeatureContext({
   lines.push(`   1. **Ao começar:** Status da Task → **${PROGRESS_IN_PROGRESS}** (a Etapa continua ${STAGE_DEVELOPMENT}).`);
   lines.push('   2. **Implemente** a Task por completo.');
   lines.push(`   3. **Ao concluir:** **avance a Task para a Etapa ${STAGE_DONE}** com Status **${PROGRESS_DONE}**.`);
-  lines.push(`3. **Ao concluir TODAS as Tasks da Story:** faça o **commit**, abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\` — o CI não roda em rascunho; quem revisa marca o PR como pronto e os checks disparam) e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`);
+  // O rodapé do commit é o rastro verificável: assunto livre, mas os
+  // trailers abaixo são o contrato (item 6 do rfc/plano-hardening-agentes-
+  // 2026-08.md — sobrevivem a squash/rebase, ao contrário de qualquer
+  // convenção de assunto).
+  const trailerHint = mode === 'agent'
+    ? `${TRAILER_STORY}: #<número da Story>\n${TRAILER_TASKS}: #<números das Tasks, separados por vírgula>\n${TRAILER_AGENT}: spec-wave-agent`
+    : `${TRAILER_STORY}: #<número da Story>\n${TRAILER_TASKS}: #<números das Tasks, separados por vírgula>`;
+  if (mode === 'agent') {
+    // Mesma razão do buildContext: o daemon mantém UM branch e UM PR para a
+    // Feature inteira e abre o PR ele mesmo ao final — o modelo não cria
+    // branch nem abre PR por Story aqui.
+    lines.push(
+      `3. **Ao concluir TODAS as Tasks da Story:** faça o **commit** (assunto livre; rodapé com os trailers abaixo), ` +
+      `faça **push no branch atual** (**NÃO crie branch novo, NÃO abra Pull Request**) ` +
+      `e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`
+    );
+  } else {
+    lines.push(
+      `3. **Ao concluir TODAS as Tasks da Story:** faça o **commit** (assunto livre; rodapé com os trailers abaixo), ` +
+      `abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\` — o CI não roda em rascunho; ` +
+      `quem revisa marca o PR como pronto e os checks disparam) e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`
+    );
+  }
+  lines.push('   ```');
+  lines.push(trailerHint.split('\n').map(l => `   ${l}`).join('\n'));
+  lines.push('   ```');
   lines.push('4. Só então inicie a próxima Story.');
   lines.push('');
   lines.push(
@@ -411,17 +462,24 @@ export function buildFeatureContext({
     `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.`
   );
   lines.push('');
-  // O trecho pós-implementação era o único do fluxo inteiramente manual — e o
-  // merge de PRs empilhados é ordem-dependente (apagar a branch do primeiro já
-  // fechou o segundo). O contexto termina apontando o comando que encapsula a
-  // sequência segura, em vez de deixar a mecânica por conta de quem mergeia.
-  lines.push(
-    '**Ao terminar, informe no relatório final:** os PRs ficam **empilhados** (cada um baseado no anterior) — ' +
-    'o merge é **ordem-dependente**. Depois da revisão humana (marcar cada PR como pronto), o merge é ' +
-    `\`npx @spec-wave/cli@latest merge ${feature.number}\`: ele mergeia na ordem das dependências, ` +
-    'reaponta as bases, move o board até 🧪 QA e só apaga as branches no fim. ' +
-    '**NUNCA** mergeie um PR da pilha com `--delete-branch` à mão — apagar a branch antes de reapontar o dependente fecha o PR seguinte.'
-  );
+  if (mode === 'agent') {
+    lines.push(
+      '**Ao terminar, informe no relatório final:** o agente mantém um único branch e um único ' +
+      'Pull Request para a Feature inteira, aberto por ele mesmo ao final — não há pilha de PRs a mergear aqui.'
+    );
+  } else {
+    // O trecho pós-implementação era o único do fluxo inteiramente manual — e o
+    // merge de PRs empilhados é ordem-dependente (apagar a branch do primeiro já
+    // fechou o segundo). O contexto termina apontando o comando que encapsula a
+    // sequência segura, em vez de deixar a mecânica por conta de quem mergeia.
+    lines.push(
+      '**Ao terminar, informe no relatório final:** os PRs ficam **empilhados** (cada um baseado no anterior) — ' +
+      'o merge é **ordem-dependente**. Depois da revisão humana (marcar cada PR como pronto), o merge é ' +
+      `\`npx @spec-wave/cli@latest merge ${feature.number}\`: ele mergeia na ordem das dependências, ` +
+      'reaponta as bases, move o board até 🧪 QA e só apaga as branches no fim. ' +
+      '**NUNCA** mergeie um PR da pilha com `--delete-branch` à mão — apagar a branch antes de reapontar o dependente fecha o PR seguinte.'
+    );
+  }
   lines.push('');
   lines.push(boardRuleBlockquote());
 
@@ -550,9 +608,14 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
     // dependências não legíveis — segue
   }
 
+  const currentBranch = currentGitBranch(repoRoot);
+  const mode = deliveryMode({ branch: currentBranch });
+  if (mode === 'agent') {
+    p.log.info(`Modo dev-agent detectado (branch ${chalk.cyan(currentBranch)}) — o PR é aberto pelo agente ao final.`);
+  }
   const context = buildBugContext({
     bug: { number: issueNumber, title: bug.title, body: bug.body || '' },
-    bugDoc, parent, comments, codeDigest, blockedByWarnings, severity,
+    bugDoc, parent, comments, codeDigest, blockedByWarnings, severity, mode,
   });
 
   await writeContextAndRunSpecKit({
@@ -563,7 +626,12 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
     specPlan: { spec: null, plan: null, specPath: null, planPath: null },
     context,
     dryRun,
-    outroSuccess: `Bug #${issueNumber} corrigido — abra o PR com \`Fixes #${issueNumber}\`.`,
+    mode,
+    repoRoot,
+    expectedBranch: currentBranch,
+    outroSuccess: mode === 'agent'
+      ? `Bug #${issueNumber} corrigido — o PR é aberto pelo próprio agente ao final.`
+      : `Bug #${issueNumber} corrigido — abra o PR com \`Fixes #${issueNumber}\`.`,
     onSuccess: async () => {
       await applyBoardMoves({
         token,
@@ -577,6 +645,11 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
 
 async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun, repoRoot, refresh = false }) {
   const ttlSec = resolveCacheTtl(config);
+  const currentBranch = currentGitBranch(repoRoot);
+  const mode = deliveryMode({ branch: currentBranch });
+  if (mode === 'agent') {
+    p.log.info(`Modo dev-agent detectado (branch ${chalk.cyan(currentBranch)}) — sem branch/PR por Story.`);
+  }
 
   // F1-F2. Stories da Feature com as arestas já resolvidas (lib/story-graph):
   // dependency-map.json/decomposition.md ∪ linhas "Depende de:" do body — zero
@@ -748,6 +821,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
     comments,
     codeDigest,
     blockedByWarnings,
+    mode,
   });
   await writeContextAndRunSpecKit({
     config,
@@ -757,10 +831,16 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
     specPlan,
     context,
     dryRun,
-    outroSuccess:
-      `${chalk.green('✓')} Implementação acionada para a Feature #${feature.number} ` +
-      `(${pending.length} story(ies) pendente(s)).\n` +
-      `  Próximo: acompanhe os PRs de cada Story; a Feature avança para ${STAGE_CODE_REVIEW} após a última.`,
+    mode,
+    repoRoot,
+    expectedBranch: currentBranch,
+    outroSuccess: mode === 'agent'
+      ? `${chalk.green('✓')} Implementação acionada para a Feature #${feature.number} ` +
+        `(${pending.length} story(ies) pendente(s)).\n` +
+        `  Próximo: acompanhe o PR único da Feature; ele é aberto pelo próprio agente ao final.`
+      : `${chalk.green('✓')} Implementação acionada para a Feature #${feature.number} ` +
+        `(${pending.length} story(ies) pendente(s)).\n` +
+        `  Próximo: acompanhe os PRs de cada Story; a Feature avança para ${STAGE_CODE_REVIEW} após a última.`,
     onSuccess: async () => {
       // Execução única para todas as pendentes: no sucesso, Tasks → Done e
       // Stories → Code Review.
@@ -787,7 +867,9 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
   });
 }
 
-export async function implement({ issue: issueArg, featureDir: featureDirOpt, dryRun, refresh = false }) {
+export async function implement({
+  issue: issueArg, featureDir: featureDirOpt, dryRun, refresh = false, verifyCommits = false,
+}) {
   const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
   if (!Number.isInteger(issueNumber)) {
     p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 12 ou #12.`);
@@ -979,15 +1061,28 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   } catch { /* aviso é best-effort — segue sem ele */ }
 
   // 5-6. Monta o contexto e aciona o spec-kit (comando configurável).
+  const currentBranch = currentGitBranch(repoRoot);
+  const mode = deliveryMode({ branch: currentBranch });
+  if (mode === 'agent') {
+    p.log.info(`Modo dev-agent detectado (branch ${chalk.cyan(currentBranch)}) — sem branch/PR novo para esta ${type}.`);
+  }
   const context = buildContext({
     type, issue, tasks, feature, siblingStories, ...specPlan,
-    comments, codeDigest, blockedByWarnings,
+    comments, codeDigest, blockedByWarnings, mode,
   });
   await writeContextAndRunSpecKit({
     config, issueNumber, type, title: issue.title, specPlan, context, dryRun,
-    outroSuccess:
-      `${chalk.green('✓')} Implementação acionada para ${type} #${issueNumber}.\n` +
-      '  Próximo: revise as mudanças e abra o PR — o board já foi atualizado.',
+    mode, repoRoot, expectedBranch: currentBranch,
+    verifyCommits,
+    expectedTrailers: {
+      stories: type === 'Story' ? [issue.number] : [],
+      tasks: tasks.map(t => t.number),
+    },
+    outroSuccess: mode === 'agent'
+      ? `${chalk.green('✓')} Implementação acionada para ${type} #${issueNumber}.\n` +
+        '  Próximo: o board já foi atualizado; o PR é aberto pelo próprio agente ao final.'
+      : `${chalk.green('✓')} Implementação acionada para ${type} #${issueNumber}.\n` +
+        '  Próximo: revise as mudanças e abra o PR — o board já foi atualizado.',
     onSuccess: async () => {
       await applyBoardMoves({ token, moves: planBoardMoves('success', {
         story: type === 'Story' ? { nodeId: issue.node_id, number: issue.number } : null,
@@ -1020,7 +1115,11 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
 
 // Grava o arquivo de contexto e aciona o spec-kit (comando configurável) —
 // fecho comum dos modos Feature e Story/Task.
-async function writeContextAndRunSpecKit({ config, issueNumber, type, title, specPlan, context, dryRun, outroSuccess, onSuccess }) {
+async function writeContextAndRunSpecKit({
+  config, issueNumber, type, title, specPlan, context, dryRun, outroSuccess, onSuccess,
+  mode = 'pr-stack', repoRoot = null, expectedBranch = null,
+  verifyCommits = false, expectedTrailers = null,
+}) {
   mkdirSync(WORK_DIR, { recursive: true });
   const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
   writeFileSync(tasksFile, context);
@@ -1075,6 +1174,40 @@ async function writeContextAndRunSpecKit({ config, issueNumber, type, title, spe
     return;
   }
 
+  // Guarda barata contra o sintoma do item 1 do rfc/plano-hardening-agentes-
+  // 2026-08.md: sob o dev-agent, se o executor saiu do branch único do agente
+  // (por exemplo criando um branch lateral por Story), o commit foi parar
+  // fora do PR que o daemon abre ao final. O aviso aparece na própria saída
+  // em vez de custar um ciclo de "onde foi parar meu trabalho".
+  if (mode === 'agent' && expectedBranch) {
+    const branchAfter = currentGitBranch(repoRoot);
+    if (branchAfter && branchAfter !== expectedBranch) {
+      p.log.warn(
+        `⚠️ o executor saiu de ${chalk.cyan(expectedBranch)} para ${chalk.cyan(branchAfter)} — ` +
+        'se algo foi commitado nesse branch, mova o trabalho de volta antes do daemon abrir o PR.'
+      );
+    }
+  }
+
+  // --verify-commits (item 6 do rfc/plano-hardening-agentes-2026-08.md): lê
+  // os commits recentes do checkout e confere se o rastro (trailer) do que
+  // acabou de ser implementado está lá — best-effort, nunca bloqueia.
+  if (verifyCommits && expectedTrailers) {
+    const messages = readLocalCommitMessages(repoRoot || process.cwd());
+    const { missingStories, missingTasks } = missingTrailers(messages, expectedTrailers);
+    if (missingStories.length === 0 && missingTasks.length === 0) {
+      p.log.success('Trailers de rastro (Spec-Wave-Story/Tasks) confirmados nos commits recentes.');
+    } else {
+      const partes = [];
+      if (missingStories.length) partes.push(`Story ${missingStories.map(n => `#${n}`).join(', ')}`);
+      if (missingTasks.length) partes.push(`Task(s) ${missingTasks.map(n => `#${n}`).join(', ')}`);
+      p.log.warn(
+        `⚠️ Sem trailer de rastro para: ${partes.join('; ')} — nenhum commit recente traz ` +
+        '`Spec-Wave-Story`/`Spec-Wave-Tasks`. Confira se o commit saiu como instruído no contexto.'
+      );
+    }
+  }
+
   if (onSuccess) await onSuccess();
   p.outro(outroSuccess);
 }

package/src/commands/merge.mjs

@@ -22,8 +22,10 @@ import chalk from 'chalk';
 import { resolveToken } from '../api/auth.mjs';
 import {
   getIssue, getPR, getRepoDefaultBranch, updatePRBase, mergePR, deleteBranch,
+  listPullRequestCommitMessages,
 } from '../api/github-rest.mjs';
 import { listIssuePullRequests } from '../api/github-graphql.mjs';
+import { missingTrailers } from '../lib/commit-trailers.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { orderStories } from '../lib/dependencies.mjs';
 import { resolveRepoContext, loadConfig } from '../lib/project-root.mjs';
@@ -242,6 +244,22 @@ export async function merge({
   for (const a of plano.avisos) p.log.warn(a);
   for (const b of plano.bloqueios) p.log.error(b);
 
+  // Conferência de trailers (item 6 do rfc/plano-hardening-agentes-2026-08.md):
+  // best-effort, nunca bloqueia o merge — nasce como relatório, não como
+  // guarda. Só as PRs que de fato vão ser mergeadas (plano.fila) valem a
+  // chamada extra por PR; falha de rede não afirma nada, só é pulada.
+  for (const { story, pr } of plano.fila) {
+    const messages = await listPullRequestCommitMessages(token, owner, repo, pr.number).catch(() => null);
+    if (messages === null) continue;
+    const { missingStories } = missingTrailers(messages, { stories: [story] });
+    if (missingStories.length > 0) {
+      p.log.warn(
+        `PR #${pr.number} (Story #${story}): nenhum commit traz o trailer \`Spec-Wave-Story: #${story}\` ` +
+        '— confira se é mesmo o trabalho certo antes de mergear.'
+      );
+    }
+  }
+
   if (plano.bloqueios.length > 0) {
     p.outro('Bloqueado — merge parcial de pilha é o pior estado; resolva e rode de novo.');
     process.exitCode = 1;

package/src/commands/update.mjs

@@ -9,6 +9,7 @@ import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import {
   getFileContent, upsertFile, listLabels, createLabel, updateLabel, deleteLabel,
   getRepoDefaultBranch, compareBranches, commitFilesToBranch, ensurePullRequest,
+  countOpenIssuesWithLabel,
 } from '../api/github-rest.mjs';
 import {
   resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
@@ -116,18 +117,21 @@ export function skillRepoTargets(job, repoRoot) {
  * 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.
  *
- * As labels de modelo (`spec-wave:model:<apelido>`) entram pelo `fileAi`: são
- * derivadas de `ai.modelAliases`, e tratá-las como desconhecidas fazia o update
- * APAGAR justamente o override de modelo por issue — o mecanismo que destrava
- * uma Feature que não gera plano no modelo default. Passar o bloco `ai` também
- * é o que faz o update CRIÁ-LAS, em vez de exigir `gh label create` à mão.
+ * As labels de modelo (`spec-wave:model:<apelido>`) entram pelo `fileAi`, e as
+ * de trilha do dev-agent (`spec-wave:dev-agent-b`, …) pelo `devAgent`: as duas
+ * são derivadas do `.spec-wave.json`, e tratá-las como desconhecidas fazia o
+ * update APAGAR o override de modelo por issue ou a fila de uma trilha
+ * paralela — mecanismos que destravam trabalho, não lixo a limpar. Passar os
+ * dois blocos também é o que faz o update CRIÁ-LAS, em vez de exigir
+ * `gh label create` à mão.
  *
  * @param {Array<{name,color,description}>} existing labels do repo
  * @param {object} [fileAi] bloco `ai` do .spec-wave.json
+ * @param {object} [devAgent] bloco `devAgent` do .spec-wave.json
  * @returns {{ missing: object[], changed: object[], orphan: object[] }}
  */
-export function diffLabels(existing, fileAi) {
-  const wanted = allLabelsFor(fileAi);
+export function diffLabels(existing, fileAi, devAgent) {
+  const wanted = allLabelsFor(fileAi, devAgent);
   const byName = new Map((existing || []).map(l => [l.name, l]));
   const missing = [];
   const changed = [];
@@ -147,6 +151,30 @@ export function diffLabels(existing, fileAi) {
   return { missing, changed, orphan };
 }
 
+/**
+ * Decide se uma label órfã pode ser deletada (função PURA — testável sem rede).
+ *
+ * Deletar uma label no GitHub a remove de TODA issue aberta que a tem — é
+ * irreversível, e a label nem fica disponível para reaplicar. Por isso o
+ * default é conservador nos dois sentidos: `inUse` desconhecido (rede falhou
+ * ao contar) trava a remoção do mesmo jeito que `inUse > 0`, porque "não sei"
+ * não é "zero". `forceLabels` pula a checagem por completo — para quem sabe
+ * que a label é lixo de verdade.
+ *
+ * @param {{ inUse: number|null, forceLabels?: boolean }} params
+ * @returns {{ ok: boolean, motivo: string|null }}
+ */
+export function shouldDeleteOrphanLabel({ inUse, forceLabels = false }) {
+  if (forceLabels) return { ok: true, motivo: null };
+  if (inUse === null) {
+    return { ok: false, motivo: 'não foi possível confirmar o uso — mantida por precaução' };
+  }
+  if (inUse > 0) {
+    return { ok: false, motivo: `está em ${inUse} issue(s) aberta(s) — NÃO removida` };
+  }
+  return { ok: true, motivo: null };
+}
+
 /**
  * Regenera o conteúdo do .spec-wave.json a partir do Project remoto SEM GRAVAR.
  *
@@ -186,11 +214,20 @@ async function buildConfigContent(token, config) {
  * Label NUNCA entra num PR: é metadado do repositório, não arquivo versionado —
  * não existe forma de propor a mudança para revisão.
  *
+ * Órfã em uso não é removida por default (item 7 do
+ * rfc/plano-hardening-agentes-2026-08.md): apagar uma label no GitHub a
+ * remove de TODA issue aberta que a tem, e isso é irreversível — a label nem
+ * fica disponível para reaplicar. A guarda vale mesmo com `devAgent.queues`
+ * configurado certo: um erro de digitação no config não pode custar uma fila
+ * inteira. `forceLabels` pula a checagem, para quem sabe que a label é lixo
+ * de verdade e quer removê-la mesmo com issues abertas.
+ *
+ * @param {boolean} [forceLabels]
  * @returns {Promise<{created: string[], updated: string[], removed: string[]}>}
  *          só o que REALMENTE passou — é o que o corpo do PR vai afirmar a quem
  *          revisa, e ele não pode prometer o que falhou.
  */
-async function applyLabels(token, owner, repo, labelDiff) {
+async function applyLabels(token, owner, repo, labelDiff, forceLabels = false) {
   const done = { created: [], updated: [], removed: [] };
   for (const label of labelDiff.missing) {
     try {
@@ -212,6 +249,14 @@ async function applyLabels(token, owner, repo, labelDiff) {
   }
   for (const label of labelDiff.orphan) {
     try {
+      const inUse = forceLabels
+        ? 0
+        : await countOpenIssuesWithLabel(token, owner, repo, label.name).catch(() => null);
+      const decision = shouldDeleteOrphanLabel({ inUse, forceLabels });
+      if (!decision.ok) {
+        p.log.warn(`Label ${label.name}: ${decision.motivo}. Use --force-labels para remover mesmo assim.`);
+        continue;
+      }
       await deleteLabel(token, owner, repo, label.name);
       done.removed.push(label.name);
       p.log.success(`Label descontinuada removida: ${label.name}`);
@@ -310,7 +355,7 @@ export async function update(options = {}) {
           if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
           else if (remote !== local) repoFiles.push({ ...f, reason: 'desatualizado', local });
         }
-        labelDiff = diffLabels(await listLabels(tk, owner, repo), config?.ai);
+        labelDiff = diffLabels(await listLabels(tk, owner, repo), config?.ai, config?.devAgent);
         repoChecked = true;
         s.stop('Repositório comparado.');
       } catch (err) {
@@ -626,7 +671,7 @@ export async function update(options = {}) {
   // Labels — sempre direto na base (metadado do repo, não versionável).
   let labelResult = { created: [], updated: [], removed: [] };
   if (labelTotal) {
-    labelResult = await applyLabels(await getToken(), owner, repo, labelDiff);
+    labelResult = await applyLabels(await getToken(), owner, repo, labelDiff, !!options.forceLabels);
   }
 
   // Arquivos do repo

package/src/commands/validate.mjs

@@ -16,6 +16,7 @@ import { loadArtifact } from '../lib/doc-source.mjs';
 import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
 import { isAwaitingMerge } from '../lib/doc-source.mjs';
 import { getRepoDefaultBranch } from '../api/github-rest.mjs';
+import { dependencySection } from '../lib/spec-audit.mjs';
 
 /**
  * Aborto por documento ainda em Pull Request.
@@ -241,6 +242,7 @@ export async function validate({ issueNumber }) {
   }
 
   // Check spec.md
+  const warnings = [];
   if (spec.content == null) {
     errors.push('❌ `spec.md` não encontrado em `' + specRel + '`');
   } else {
@@ -253,6 +255,17 @@ export async function validate({ issueNumber }) {
     for (const problem of findIncompleteDocSigns(specContent)) {
       errors.push(`❌ \`spec.md\` parece incompleto: ${problem}`);
     }
+    // Aviso, NUNCA erro (item 3e do rfc/plano-hardening-agentes-2026-08.md):
+    // "Dependências" não está em REQUIRED_SPEC_SECTIONS de propósito — exigi-la
+    // quebraria specs antigas num comando que é gatilho de Action. O parser
+    // aqui é o mesmo (tolerante) que o `audit` usa, então "não achei" já
+    // significa "o audit também não vai achar" — vale avisar sem bloquear.
+    if (dependencySection(specContent) == null) {
+      warnings.push(
+        '⚠️ Não encontrei a seção de Dependências (heading `#`/`##`/`###` começando com ' +
+        '"Dependências") — o `audit` não vai enxergar as dependências desta Feature.'
+      );
+    }
   }
 
   // Remove trigger label
@@ -292,6 +305,7 @@ export async function validate({ issueNumber }) {
     `✅ **Validação concluída com sucesso!**\n\n` +
     `- [\`${featureRel}/spec.md\`](${featureRel}/spec.md) ✓\n` +
     `- [\`${featureRel}/plan.md\`](${featureRel}/plan.md) ✓\n\n` +
+    (warnings.length > 0 ? `${warnings.join('\n')}\n\n` : '') +
     `A Feature está pronta para a decomposição. O próximo passo gera o **rascunho** ` +
     `em \`${featureRel}/decomposition.md\` para revisão (nada é criado ainda):\n` +
     `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:decompose"\n\`\`\``

package/src/config.mjs

@@ -341,6 +341,13 @@ export const LABEL_DECOMPOSE_APPLY = 'spec-wave:decompose-apply';
 // rotina apagava a label da fila e desligava o agente sem aviso.
 export const LABEL_DEV_AGENT = 'spec-wave:dev-agent';
 
+// Prefixo das labels de trilha EXTRA do dev-agent (multi-trilha: rodar mais de
+// um daemon em paralelo, um por fila — `spec-wave:dev-agent-b`, `-c`, …). A
+// fila default (`dev-agent`) já é `LABEL_DEV_AGENT`, coberta acima; este
+// prefixo só identifica as trilhas adicionais, declaradas em `devAgent.queues`
+// do .spec-wave.json (ver `queueLabels`).
+export const DEV_AGENT_QUEUE_PREFIX = `${LABEL_DEV_AGENT}-`;
+
 // Gatilho e estado do bug.md (RFC-004 §5). O bug.md é o artefato do Bug — leve
 // por decisão: um defeito não gera spec.md + plan.md.
 export const LABEL_BUG = 'spec-wave:bug';
@@ -447,6 +454,17 @@ export const LABEL_RISK_ACCEPTED = 'spec-wave:risk-accepted';
 // a correção — e troca os findings, fazendo as decisões do TL deixarem de casar.
 export const LABEL_CRITIQUE = 'spec-wave:critique';
 
+// Rastro verificável do commit de implementação (item 6 do rfc/plano-
+// hardening-agentes-2026-08.md). O ASSUNTO do commit continua livre — quem
+// implementa escreve o que quiser ("feat: story #1533 [spec-wave-agent]" ou
+// "feat(ep3-f3): wizard de aprovação"); os `git trailer` no rodapé é que são o
+// contrato, porque sobrevivem a squash, rebase e reescrita de assunto (e
+// `git log --format='%(trailers:key=...)'` lê sem depender de convenção de
+// prosa). Ver `lib/commit-trailers.mjs`.
+export const TRAILER_STORY = 'Spec-Wave-Story';
+export const TRAILER_TASKS = 'Spec-Wave-Tasks';
+export const TRAILER_AGENT = 'Spec-Wave-Agent';
+
 export const TRIGGER_LABELS = [
   { name: LABEL_SPEC,                color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
   { name: LABEL_PLAN,                color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
@@ -511,15 +529,50 @@ export function modelLabels(modelAliases) {
 }
 
 /**
- * Labels do fluxo + as de modelo deste repo (função PURA).
+ * Labels das trilhas EXTRA do dev-agent, derivadas de `devAgent.queues`
+ * (função PURA) — item 7 do rfc/plano-hardening-agentes-2026-08.md.
+ *
+ * Mesma armadilha de `modelLabels`, mesmo remédio: sem isto, uma fila custom
+ * (`spec-wave:dev-agent-b`, para rodar um segundo daemon em paralelo) é a
+ * ÚNICA label que não cabe em `ALL_LABELS` — e o `update` REMOVE toda
+ * `spec-wave:*` que não esteja na lista conhecida. Apagar a label a remove de
+ * todas as issues: a fila inteira esvazia e o paralelismo morre em silêncio.
+ *
+ * A fila default (`dev-agent`) fica de fora do retorno — já está coberta por
+ * `LABEL_DEV_AGENT`/`ALL_LABELS`, e repeti-la aqui arriscaria duas descrições
+ * divergindo da mesma label entre execuções.
+ *
+ * @param {object} [devAgent] bloco `devAgent` do .spec-wave.json
+ * @returns {Array<{name: string, color: string, description: string}>}
+ */
+export function queueLabels(devAgent) {
+  const queues = Array.isArray(devAgent?.queues) ? devAgent.queues : [];
+  const extra = new Set(
+    queues
+      .filter(q => typeof q === 'string' && q.trim())
+      .map(q => q.trim())
+      .filter(q => q !== 'dev-agent')
+  );
+  return [...extra].map(q => ({
+    name: `spec-wave:${q}`,
+    color: '5319E7',
+    description: `Enfileira a issue para a trilha "${q}" do dev-agent`,
+  }));
+}
+
+/**
+ * Labels do fluxo + as de modelo + as de trilha do dev-agent deste repo
+ * (função PURA).
  *
  * É este o conjunto que `update`, `doctor` e `init` devem usar — ALL_LABELS
- * sozinha é incompleta em qualquer repo que configure `ai.modelAliases`.
+ * sozinha é incompleta em qualquer repo que configure `ai.modelAliases` ou
+ * `devAgent.queues`.
  *
  * @param {object} [fileAi] bloco `ai` do .spec-wave.json
+ * @param {object} [devAgent] bloco `devAgent` do .spec-wave.json
  */
-export function allLabelsFor(fileAi) {
-  return [...ALL_LABELS, ...modelLabels(fileAi?.modelAliases)];
+export function allLabelsFor(fileAi, devAgent) {
+  return [...ALL_LABELS, ...modelLabels(fileAi?.modelAliases), ...queueLabels(devAgent)];
 }
 
 /**

package/src/lib/bug-context.mjs

@@ -23,11 +23,12 @@ import { STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, PROGRESS_IN_PROGRESS } from '../c
  * @param {string|null} [params.codeDigest]
  * @param {string[]} [params.blockedByWarnings]
  * @param {string|null} [params.severity] P0–P3
+ * @param {'agent'|'pr-stack'} [params.mode] quem abre o PR — ver lib/delivery-mode.mjs
  * @returns {string}
  */
 export function buildBugContext({
   bug, bugDoc = null, parent = null, comments = [], codeDigest = null,
-  blockedByWarnings = [], severity = null,
+  blockedByWarnings = [], severity = null, mode = 'pr-stack',
 }) {
   const lines = [];
   lines.push(`# Contexto de correção — Bug #${bug.number}`);
@@ -102,11 +103,21 @@ export function buildBugContext({
     `1. Commit com a **causa raiz** na mensagem: \`fix: <o que estava errado> (#${bug.number})\`, ` +
     'e o corpo explicando a origem — não o sintoma.'
   );
-  lines.push(`2. Abra o Pull Request com \`Fixes #${bug.number}\` no corpo.`);
-  lines.push(
-    `3. O board move sozinho: o Bug sai de **${STAGE_DEVELOPMENT}** (${PROGRESS_IN_PROGRESS}) ` +
-    `para **${STAGE_CODE_REVIEW}** quando o PR abre. Não mova à mão.`
-  );
+  if (mode === 'agent') {
+    // O daemon mantém UM branch e UM PR por issue e abre o PR ele mesmo ao
+    // final (inclusive para Bug) — o modelo só faz push no branch atual.
+    lines.push('2. Faça **push no branch atual** — **NÃO abra Pull Request**: o agente abre o PR ele mesmo ao final.');
+    lines.push(
+      `3. O board move sozinho: o Bug sai de **${STAGE_DEVELOPMENT}** (${PROGRESS_IN_PROGRESS}) ` +
+      `para **${STAGE_CODE_REVIEW}** quando o PR abre. Não mova à mão.`
+    );
+  } else {
+    lines.push(`2. Abra o Pull Request com \`Fixes #${bug.number}\` no corpo.`);
+    lines.push(
+      `3. O board move sozinho: o Bug sai de **${STAGE_DEVELOPMENT}** (${PROGRESS_IN_PROGRESS}) ` +
+      `para **${STAGE_CODE_REVIEW}** quando o PR abre. Não mova à mão.`
+    );
+  }
 
   if (bugDoc && bugDoc.trim()) {
     lines.push('');