@spec-wave/cli 0.30.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.30.0",
+  "version": "0.33.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {
@@ -11,10 +11,12 @@
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "protocol"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "skill:gen": "node scripts/generate-skill.mjs"
   },
   "engines": {
     "node": ">=20"

package/protocol/qa-result.v1.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/astratech-net-br/spec-wave-cli/blob/main/packages/spec-wave/protocol/qa-result.v1.json",
+  "title": "spec-wave qa result v1",
+  "description": "Contrato do arquivo `.spec-wave/qa-result-<n>.json`, escrito pelo agente executor e lido por `spec-wave qa <n>`. Formato ADOTADO da implementação existente do comando `qa` (Tarefa Zero da rfc/spec-qa-lead.md): os campos são `cenario`/`evidencia` — não `n`/`evidence` como a §4.2 da spec propunha — estendidos com `blockedReason` (D-QAL6). `version`, `issue`, `planSha` e `headSha` são aceitos e ignorados pela CLI (a integridade do plano é conferida pela própria CLI, que re-lê o qa-plan.md após a execução).",
+  "type": "object",
+  "required": ["scenarios"],
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "issue": { "type": "integer", "minimum": 1 },
+    "planSha": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+    "headSha": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+    "scenarios": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["cenario", "verdict"],
+        "properties": {
+          "cenario": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Número POSICIONAL do cenário no escopo da execução."
+          },
+          "verdict": {
+            "enum": ["pass", "fail", "blocked"]
+          },
+          "evidencia": {
+            "type": "string",
+            "description": "Evidência bruta (comando, saída, código de status). OBRIGATÓRIA e não vazia em `fail` (vira o bug.md determinístico) e em `blocked` com `blockedReason: outro`."
+          },
+          "blockedReason": {
+            "enum": [
+              "ambiente",
+              "setup-falhou",
+              "massa-de-dados",
+              "dependencia-nao-entregue",
+              "bloqueado-por-bug",
+              "credencial",
+              "outro"
+            ],
+            "description": "OBRIGATÓRIO quando `verdict` é `blocked` (D-QAL6). Proibido nos demais vereditos."
+          }
+        },
+        "allOf": [
+          {
+            "if": { "properties": { "verdict": { "const": "blocked" } } },
+            "then": { "required": ["blockedReason"] }
+          },
+          {
+            "if": { "properties": { "verdict": { "const": "fail" } } },
+            "then": { "required": ["evidencia"], "properties": { "evidencia": { "minLength": 1 } } }
+          },
+          {
+            "if": { "properties": { "blockedReason": { "const": "outro" } } },
+            "then": { "required": ["evidencia"], "properties": { "evidencia": { "minLength": 1 } } }
+          }
+        ]
+      }
+    }
+  }
+}

package/protocol/qa-trail-report.v1.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/astratech-net-br/spec-wave-cli/blob/main/packages/spec-wave/protocol/qa-trail-report.v1.json",
+  "title": "spec-wave qa trail report v1",
+  "description": "Contrato do `docs/qa/<slug-milestone>/cycle-<n>/report.json`, escrito por `spec-wave qa-lead run` (rfc/spec-qa-lead.md §4.3). É o que a UI do SpecWave e o `qa-lead report` consomem.",
+  "type": "object",
+  "required": ["version", "milestone", "cycle", "features", "totals", "verdict"],
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "milestone": {
+      "type": "object",
+      "required": ["number", "title"],
+      "properties": {
+        "number": { "type": "integer", "minimum": 1 },
+        "title": { "type": "string" }
+      }
+    },
+    "cycle": { "type": "integer", "minimum": 1 },
+    "startedAt": { "type": ["string", "null"], "format": "date-time" },
+    "finishedAt": { "type": ["string", "null"], "format": "date-time" },
+    "preflight": {
+      "type": "object",
+      "required": ["ok", "checks"],
+      "properties": {
+        "ok": { "type": "boolean" },
+        "checks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "ok"],
+            "properties": {
+              "name": { "type": "string" },
+              "ok": { "type": "boolean" },
+              "detail": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["issue", "title", "verdict", "scenarios"],
+        "properties": {
+          "issue": { "type": "integer", "minimum": 1 },
+          "title": { "type": "string" },
+          "verdict": {
+            "enum": ["verde", "vermelho", "inconclusivo", "execucao-abortada", "fora-do-ciclo", "ja-aprovada"]
+          },
+          "scenarios": {
+            "type": "object",
+            "required": ["pass", "fail", "blocked", "total"],
+            "properties": {
+              "pass": { "type": "integer", "minimum": 0 },
+              "fail": { "type": "integer", "minimum": 0 },
+              "blocked": { "type": "integer", "minimum": 0 },
+              "total": { "type": "integer", "minimum": 0 }
+            }
+          },
+          "bugsOpened": { "type": "array", "items": { "type": "integer" } },
+          "durationSec": { "type": ["integer", "null"], "minimum": 0 }
+        }
+      }
+    },
+    "totals": {
+      "type": "object",
+      "required": ["pass", "fail", "blocked", "naoExecutado", "total"],
+      "properties": {
+        "pass": { "type": "integer", "minimum": 0 },
+        "fail": { "type": "integer", "minimum": 0 },
+        "blocked": { "type": "integer", "minimum": 0 },
+        "naoExecutado": { "type": "integer", "minimum": 0 },
+        "total": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "blockedByReason": {
+      "type": "object",
+      "propertyNames": {
+        "enum": [
+          "ambiente",
+          "setup-falhou",
+          "massa-de-dados",
+          "dependencia-nao-entregue",
+          "bloqueado-por-bug",
+          "credencial",
+          "outro"
+        ]
+      },
+      "additionalProperties": { "type": "integer", "minimum": 0 }
+    },
+    "bugs": {
+      "type": "object",
+      "required": ["opened", "closedSincePreviousCycle", "openBlocking"],
+      "properties": {
+        "opened": { "type": "integer", "minimum": 0 },
+        "closedSincePreviousCycle": { "type": "integer", "minimum": 0 },
+        "openBlocking": { "type": "array", "items": { "type": "integer" } }
+      }
+    },
+    "delta": {
+      "type": ["object", "null"],
+      "properties": {
+        "pass": { "type": "integer" },
+        "blocked": { "type": "integer" }
+      }
+    },
+    "verdict": { "enum": ["liberada", "nao-liberada", "ciclo-abortado"] },
+    "terminationReason": {
+      "enum": ["todas-verdes", "sem-mudanca-de-estado", "teto-de-ciclos", "preflight-falhou", null]
+    }
+  }
+}

package/src/api/github-graphql.mjs

@@ -282,7 +282,7 @@ export async function listProjectItems(token, projectId) {
                     }
                   }
                 }
-                content { ... on Issue { number title state id } }
+                content { ... on Issue { number title state id milestone { number title } } }
               }
             }
           }
@@ -304,6 +304,11 @@ export async function listProjectItems(token, projectId) {
         state: issue.state,
         nodeId: issue.id,
         itemId: node.id,
+        // Habilita filtrar o snapshot por milestone sem nenhuma chamada extra
+        // (`order --milestone`, e o cache do board fica mais rico de graça).
+        milestone: issue.milestone
+          ? { number: issue.milestone.number, title: issue.milestone.title }
+          : null,
         fields,
       });
     }

package/src/api/github-rest.mjs

@@ -307,6 +307,27 @@ export async function listMilestones(token, owner, repo) {
   });
 }
 
+// Milestone pelo número — o `qa-lead` lê a DESCRIÇÃO atual antes de atualizar
+// o bloco de trilha (substituir o bloco exige conhecer o resto do texto).
+export async function getMilestone(token, owner, repo, milestoneNumber) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.issues.getMilestone({
+    owner, repo, milestone_number: milestoneNumber,
+  });
+  return res.data;
+}
+
+// Atualiza SÓ a descrição do milestone. O chamador é responsável por preservar
+// o que já estava lá (Release Notes etc.) — ver upsertMilestoneBlock: o
+// contrato é substituir um bloco delimitado, nunca a descrição inteira.
+export async function updateMilestoneDescription(token, owner, repo, milestoneNumber, description) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.issues.updateMilestone({
+    owner, repo, milestone_number: milestoneNumber, description,
+  });
+  return res.data;
+}
+
 // Issues de uma milestone (pelo NÚMERO dela), abertas e fechadas.
 //
 // `state: 'all'` de propósito: uma Feature fechada continua contando para o

package/src/cli.mjs

@@ -345,7 +345,59 @@ export function buildProgram() {
       const { qaRun } = await import('./commands/qa-run.mjs');
       await qaRun({ issue: issueArg, ...options })
         .catch(err => { console.error(err.message); process.exit(1); });
-    });
+    })
+    .addHelpText('after', `
+A fase de QA em duas metades (a ordem é obrigatória):
+  1. plano   label spec-wave:qa na FEATURE → Action gera docs/features/<slug>/qa-plan.md
+             (valida + critica; limpo → label spec-wave:qa-ready)
+  2. executar  qa <issue> — SEMPRE local, contra o checkout. Exige qa-ready na Feature:
+             o verde avança a Etapa sozinho, então o portão humano é a revisão do plano.
+
+Alvos: qa <feature> (Stories ainda sem qa-approved) · qa <story> · qa <bug> (Teste de Regressão do bug.md).
+
+Desfechos:
+  verde      +qa-approved · Story → 📋 Homologação · Bug → 🚀 Deploy · Feature quando todas liberarem
+             (Bug filho aberto segura a Story mesmo verde)
+  vermelho   1 Bug por cenário reprovado (filho da Story, ✅ Ready, bug.md commitado) · exit 1
+  blocked    sem fail = inconclusivo: nada move, nenhum Bug · exit 1
+
+Executor: "qa": { "command": "..." } no .spec-wave.json (ou SPEC_WAVE_QA_CMD).
+Placeholders: {contextFile} {qaPlanFile} {specFile} {issue} {type} {title}.
+Re-teste após o fix: qa <story> --only <cenário> (não duplica Bug — comenta no existente).
+
+Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
+
+  program
+    .command('qa-lead')
+    .description('Orquestra o QA de uma trilha (milestone): prepara os planos (plan), executa o ciclo em containers paralelos (run) e reimprime relatórios (report)')
+    .argument('<acao>', 'plan | run | report')
+    .argument('[milestone]', 'Milestone da trilha, por número ou título, ex.: 12 ou "v1.4"')
+    .option('--watch', 'No plan: aguarda os planos disparados resolverem (qa-ready/critique-failed), com teto qa.lead.planWaitTimeoutMin')
+    .option('--only <features>', 'No run: sub-trilha explícita, ex.: --only 318,320 (decisão humana declarada, não relaxamento do portão)')
+    .option('--max-cycles <n>', 'No run: teto de ciclos desta trilha (default: qa.lead.maxCycles, 3)')
+    .option('--cycle <n>', 'No report: qual ciclo imprimir (default: o último)')
+    .option('--dry-run', 'Classifica/planeja e imprime — nenhuma label, zero container, zero escrita')
+    .action(async (acao, milestone, options) => {
+      const { qaLead } = await import('./commands/qa-lead.mjs');
+      await qaLead({ action: acao, milestone, ...options })
+        .catch(err => { console.error(err.message); process.exit(1); });
+    })
+    .addHelpText('after', `
+Trilha = milestone (D-QAL1), na ordem do \`spec-wave order\` sem argumento. Duas fases (D-QAL2):
+  plan   classifica cada Feature (pronta / portão humano / em voo / sem spec-plan) e aplica
+         \`spec-wave:qa\` nas que precisam de plano. PARA no portão humano: revise os qa-plan.md.
+  run    exige a trilha inteira com \`spec-wave:qa-ready\`. Preflight global → até
+         qa.lead.maxParallel containers (um por Feature, backend docker) → coleta os comentários
+         de veredito → grava docs/qa/<slug>/cycle-<n>/{report.md,report.json} e o bloco
+         delimitado na descrição do milestone. Ciclo N+1 só se um Bug fechou ou um bloqueio
+         caiu (D-QAL7); teto de 3 ciclos.
+  report reimprime um ciclo já gravado, sem executar nada.
+
+O Lead NUNCA aplica label de estado, não move card e não abre issue — isso é do \`qa\` dentro
+dos containers. Configuração: bloco "qa": { "lead": { ... } } no .spec-wave.json (§4.5 da spec);
+\`container.image\` é obrigatória para a fase run.
+
+Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
 
   program
     .command('generate-qa-plan')
@@ -354,7 +406,15 @@ export function buildProgram() {
     .action(async (options) => {
       const { generateQaPlan } = await import('./commands/generate-qa-plan.mjs');
       await generateQaPlan(options).catch(err => { console.error(err.message); process.exit(1); });
-    });
+    })
+    .addHelpText('after', `
+Só em FEATURE (o plano é um arquivo por Feature, com seções "## Cenário N — Story #X").
+Arquivo ausente → gera via IA e publica em PR; presente → valida + critica COMO ESTÁ
+(edições manuais preservadas — para regerar do zero, apague o arquivo e reaplique a label).
+Requer spec.md e plan.md na base. Limpo → spec-wave:qa-ready (revise o plano ANTES de
+rodar \`spec-wave qa <issue>\` — o veredito verde avança a Etapa sozinho).
+
+Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
 
   program
     .command('implement')
@@ -362,6 +422,7 @@ export function buildProgram() {
     .argument('<issue>', 'Número da issue (Feature, Story ou Task), ex.: 12 ou #12')
     .option('--feature-dir <path>', 'Caminho do docs/features/<slug> (sobrescreve a resolução automática)')
     .option('--dry-run', 'Monta o contexto e imprime o comando sem executar o spec-kit')
+    .option('--refresh', 'Ignora o cache local (sub-issues/dependências) e reconsulta a API')
     .action(async (issue, options) => {
       const { implement } = await import('./commands/implement.mjs');
       await implement({ issue, ...options }).catch(err => { console.error(err.message); process.exit(1); });
@@ -371,10 +432,21 @@ export function buildProgram() {
     .command('order')
     .description('Ordena as Stories pelas dependências (topológica). Sem argumento, o mapa de todas as Features com trabalho')
     .argument('[feature]', 'Número da issue da Feature, ex.: 12 ou #12. Omitido: todas as Features abertas fora de 🎉 Done')
-    .action(async (feature) => {
+    .option('--milestone <ref>', 'Só as Features desta milestone (número ou título) — no mapa sem argumento')
+    .option('--json', 'Saída em JSON estável (para agentes/scripts), sem ANSI')
+    .option('--remote', 'Une também o blocked_by da API (1 chamada por Story) — pega arestas criadas só pela UI')
+    .option('--refresh', 'Ignora o cache local e reconsulta a API')
+    .option('--sync', 'Grava as dependências VIVAS (body + blocked_by) de volta no decomposition.md e regenera o dependency-map.json')
+    .action(async (feature, options) => {
       const { order } = await import('./commands/order.mjs');
-      await order({ feature }).catch(err => { console.error(err.message); process.exit(1); });
-    });
+      await order({ feature, ...options }).catch(err => { console.error(err.message); process.exit(1); });
+    })
+    .addHelpText('after', `
+As ARESTAS vêm de fontes locais (dependency-map.json do decompose --apply, decomposition.md,
+linhas "Depende de:" do corpo) — zero chamada por Story. A Etapa vem de UM snapshot do board,
+cacheado por ${'`cache.ttlSec`'} (default 600s; SPEC_WAVE_CACHE_TTL na env; 0 desliga) com
+staleness sempre visível. blocked_by criado SÓ pela UI não está nas fontes locais: use --remote
+para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefatos.`);
 
   program
     .command('merge')
@@ -383,6 +455,8 @@ export function buildProgram() {
     .option('--yes', 'Executa os merges (sem isso, só mostra o plano)')
     .option('--dry-run', 'Mostra o plano e sai')
     .option('--keep-branches', 'Não apaga as branches das Stories depois do merge')
+    .option('--remote', 'No plano: une também o blocked_by da API (a execução com --yes sempre o faz, fresco)')
+    .option('--refresh', 'Ignora o cache local e reconsulta a API')
     .action(async (feature, options) => {
       const { merge } = await import('./commands/merge.mjs');
       await merge({ feature, ...options }).catch(err => { console.error(err.message); process.exit(1); });
@@ -471,6 +545,7 @@ Fluxo típico (cada tema, na ordem):
   implementar    implement <issue> · task start/done · story review
   entregar       merge <feature> (PRs empilhados, na ordem) · run --pr <n> (board até QA)
   validar (QA)   label spec-wave:qa (gera qa-plan.md) → qa <issue> [--only n] (executa e dá o veredito)
+                 trilha inteira (milestone): qa-lead plan → [revisão humana] → qa-lead run · qa-lead report
   acompanhar     info · order · move · repair-stage
 
 Docs: https://astratech-net-br.github.io/spec-wave-cli/  ·  spec-wave <comando> --help`);

package/src/commands/decompose.mjs

@@ -38,6 +38,8 @@ import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 import { resolveFlowContext } from '../lib/flow-run.mjs';
 import { publishArtifact } from '../lib/artifact-publish.mjs';
+import { buildDependencyMap, storiesFromAppliedDoc, DEPENDENCY_MAP_FILE } from '../lib/dependency-map.mjs';
+import { invalidateCache } from '../lib/net-cache.mjs';
 import { loadArtifact } from '../lib/doc-source.mjs';
 import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
 import { isAwaitingMerge } from '../lib/doc-source.mjs';
@@ -258,14 +260,14 @@ function formatItemsLintWarning(texts) {
  * dezenas de itens). Sem o `await`, a promise rejeitada não é capturada por esse
  * catch: o aviso some e vira unhandled rejection.
  */
-async function publishFile(ctx, { doc, pathRel, content, nextLabel = null }) {
+async function publishFile(ctx, { doc, pathRel, content, nextLabel = null, extraFiles = [] }) {
   const { token, owner, repo, issue, issueNumber, base } = ctx;
   const published = await publishArtifact({
     token, owner, repo, doc,
     issueNumber: parseInt(issueNumber, 10),
     issueTitle: issue?.title || '',
     issueUrl: issue?.html_url || '',
-    pathRel, content, base, nextLabel,
+    pathRel, content, base, nextLabel, extraFiles,
   });
   if (published.warning) console.warn(`⚠️  ${published.warning}`);
   return published;
@@ -626,10 +628,30 @@ async function applyDecomposition(ctx) {
   // da branch do rascunho: aquela já foi mergeada (é pré-condição do apply), e
   // reabri-la produziria um PR reintroduzindo estado antigo.
   try {
+    const appliedAt = new Date().toISOString();
+    // O dependency-map.json viaja no MESMO commit da anotação: o apply é o
+    // momento em que o grafo nasce pronto em memória — é ele que torna a ordem
+    // consultável por qualquer clone SEM pagar a API (lib/dependency-map.mjs).
+    const extraFiles = [];
+    if (doc.kind === 'stories') {
+      const converted = storiesFromAppliedDoc({ ...doc, appliedAt });
+      if (converted.ok) {
+        const mapRel = docRel.replace(/decomposition\.md$/, DEPENDENCY_MAP_FILE);
+        extraFiles.push({
+          path: mapRel,
+          content: `${JSON.stringify(buildDependencyMap({
+            featureNumber: number, stories: converted.stories, source: 'apply', generatedAt: appliedAt,
+          }), null, 2)}\n`,
+        });
+      } else {
+        console.warn(`⚠️  dependency-map.json não gerado: ${converted.reason}.`);
+      }
+    }
     const anotado = await publishFile(ctx, {
       doc: 'decomposition-apply',
       pathRel: docRel,
-      content: renderDecompositionDoc({ ...doc, appliedAt: new Date().toISOString() }),
+      content: renderDecompositionDoc({ ...doc, appliedAt }),
+      extraFiles,
     });
     console.log(anotado.pr?.number
       ? `${docRel} anotado com as issues criadas — PR #${anotado.pr.number}.`
@@ -641,6 +663,10 @@ async function applyDecomposition(ctx) {
     );
   }
 
+  // As sub-issues da Feature mudaram — o cache local de quem consultar agora
+  // mentiria por até um TTL inteiro.
+  invalidateCache(ctx.root, `subissues-${number}`, 'board-items');
+
   await addLabel(token, owner, repo, number, LABEL_DECOMPOSED)
     .catch(err => console.warn(`Falha ao aplicar a label ${LABEL_DECOMPOSED}: ${err.message}`));
   // Best-effort como as duas vizinhas: as issues já existem, e derrubar o run

package/src/commands/doctor.mjs

@@ -5,6 +5,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { Octokit } from '@octokit/rest';
@@ -18,7 +19,7 @@ import { getRepoVariable } from '../api/github-rest.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
   AI_PROVIDERS, STATUS_OPTIONS,
-  RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
+  RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, LABEL_QA_READY, MODEL_LABEL_PREFIX,
   DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS, recommendedModelAliases,
   modelLabels, STAGE_QA,
 } from '../config.mjs';
@@ -976,11 +977,59 @@ export function featuresInQaWithoutPlan({ items = [], exists = () => false } = {
     .filter(f => !exists(f.rel));
 }
 
-// QA (rfc/spec-qa-skill.md): executor configurado + Features em 🧪 QA com plano.
+/**
+ * Checks do bloco `qa.lead` (função PURA — rfc/spec-qa-lead.md §6.6).
+ *
+ * `container.image` ausente é "!" e não "✗" de propósito: sem ela a fase A
+ * (`qa-lead plan`) funciona inteira — só a fase B recusa, orientando.
+ *
+ * @param {object} params
+ * @param {object|null} [params.lead] bloco `qa.lead` do .spec-wave.json
+ * @param {boolean|null} [params.dockerOk] docker acessível (null = não sondado)
+ * @param {boolean} [params.schemasOk] protocol/*.json presentes e legíveis
+ * @returns {{ warn: boolean, notes: string[] }}
+ */
+export function inspectQaLead({ lead = null, dockerOk = null, schemasOk = true } = {}) {
+  const notes = [];
+  let warn = false;
+  const backend = lead?.backend === 'sandbox' ? 'sandbox' : 'docker';
+  const image = lead?.container?.image;
+
+  if (!image) {
+    warn = true;
+    notes.push(
+      'qa-lead: `qa.lead.container.image` ausente — a fase B (`qa-lead run`) vai recusar. ' +
+      'A fase A (`qa-lead plan`) funciona sem ela.'
+    );
+  } else {
+    notes.push(`qa-lead: backend ${backend} · imagem ${image}.`);
+  }
+  if (backend === 'sandbox') {
+    warn = true;
+    notes.push(
+      'qa-lead: backend `sandbox` ainda não tem implementação (a API de sessão do ' +
+      'spec-wave-sandbox não existe) — use `docker`.'
+    );
+  } else if (dockerOk === false) {
+    warn = true;
+    notes.push('qa-lead: docker não acessível nesta máquina — a fase B não vai conseguir despachar containers.');
+  }
+  if (!schemasOk) {
+    warn = true;
+    notes.push(
+      'qa-lead: schemas do protocol/ (qa-result.v1.json / qa-trail-report.v1.json) ausentes ou ' +
+      'ilegíveis na instalação da CLI — reinstale o pacote.'
+    );
+  }
+  return { warn, notes };
+}
+
+// QA (rfc/spec-qa-skill.md + rfc/spec-qa-lead.md): executor configurado,
+// Features em 🧪 QA com plano, e a configuração do orquestrador de trilha.
 // As labels novas e o workflow generate-qa-plan.yml são cobertos pelos checks
 // existentes (higiene de labels e workflows), que leem as listas do config.mjs.
 async function checkQa(ctx) {
-  const name = 'QA (qa.command e planos das Features em 🧪 QA)';
+  const name = 'QA (qa.command, planos das Features em 🧪 QA e qa-lead)';
   const notes = [];
   let status = 'ok';
 
@@ -1022,6 +1071,32 @@ async function checkQa(ctx) {
       } else {
         notes.push(`Nenhuma Feature em ${STAGE_QA} sem plano de QA.`);
       }
+
+      // Trilha travada no portão da fase B (spec-qa-lead §6.6): Feature em
+      // 🧪 QA sem `qa-ready` faz o `qa-lead run` do milestone dela recusar.
+      const emQa = items.filter(i => i?.number
+        && String(i.state || '').toUpperCase() !== 'CLOSED'
+        && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
+        && i.fields?.Etapa === STAGE_QA);
+      const semReady = [];
+      for (const item of emQa) {
+        const issue = await makeOctokit(ctx.token).rest.issues
+          .get({ owner: ctx.cfg.owner, repo: ctx.cfg.repo, issue_number: item.number })
+          .catch(() => null);
+        if (!issue) continue;
+        const labels = (issue.data.labels || []).map(l => (typeof l === 'string' ? l : l.name));
+        if (!labels.includes(LABEL_QA_READY)) {
+          semReady.push({ number: item.number, milestone: issue.data.milestone?.title || '(sem milestone)' });
+        }
+      }
+      if (semReady.length > 0) {
+        status = 'warn';
+        notes.push(
+          `Feature(s) em ${STAGE_QA} sem \`${LABEL_QA_READY}\`: ` +
+          semReady.map(f => `#${f.number} [${f.milestone}]`).join(', ') +
+          ' — o `qa-lead run` desses milestones vai recusar; rode `qa-lead plan` e revise os planos.'
+        );
+      }
     } catch (err) {
       notes.push(`Features em ${STAGE_QA} não verificáveis agora: ${err.message}`);
     }
@@ -1029,6 +1104,30 @@ async function checkQa(ctx) {
     notes.push('Features em 🧪 QA não verificadas (sem token, project ou raiz do repo).');
   }
 
+  // Orquestrador de trilha (spec-qa-lead §6.6).
+  const lead = ctx.cfg?.qa?.lead || null;
+  let dockerOk = null;
+  if (lead?.container?.image && lead?.backend !== 'sandbox') {
+    try {
+      execSync('docker info', { stdio: ['ignore', 'pipe', 'pipe'] });
+      dockerOk = true;
+    } catch {
+      dockerOk = false;
+    }
+  }
+  const protocolDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'protocol');
+  const schemasOk = ['qa-result.v1.json', 'qa-trail-report.v1.json'].every((file) => {
+    try {
+      JSON.parse(readFileSync(path.join(protocolDir, file), 'utf-8'));
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  const leadCheck = inspectQaLead({ lead, dockerOk, schemasOk });
+  if (leadCheck.warn) status = status === 'fail' ? 'fail' : 'warn';
+  notes.push(...leadCheck.notes);
+
   return { name, status, detail: notes.join('\n') };
 }