@spec-wave/cli 0.2.2 → 0.4.0

package/bin/spec-wave.mjs

@@ -49,9 +49,9 @@ program
 
 program
   .command('issue')
-  .description('Cria um work item (epic/feature/story/task...), opcionalmente como sub-issue, e adiciona ao board')
+  .description('Cria um work item (initiative/epic/feature/story/task...), opcionalmente como sub-issue, e adiciona ao board')
   .requiredOption('--title <title>', 'Título (sem o prefixo de tipo, ex.: [FEATURE])')
-  .option('--type <type>', 'Tipo: epic, feature, story, task, bug, spike ou rfc', 'feature')
+  .option('--type <type>', 'Tipo: initiative, epic, feature, story, task, bug, spike ou rfc', 'feature')
   .option('--parent <n>', 'Número da issue pai (cria como sub-issue dela)')
   .option('--body <text>', 'Descrição')
   .option('--priority <p>', 'Prioridade: P0, P1, P2 ou P3')
@@ -61,6 +61,18 @@ program
     await issue(options).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('initiative')
+  .description('Atalho de `issue --type initiative` (nó raiz que agrupa Epics)')
+  .requiredOption('--title <title>', 'Título da initiative (sem o prefixo [INITIATIVE])')
+  .option('--body <text>', 'Descrição da initiative')
+  .option('--priority <p>', 'Prioridade: P0, P1, P2 ou P3 (adiciona label)')
+  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
+  .action(async (options) => {
+    const { initiative } = await import('../src/commands/initiative.mjs');
+    await initiative(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('feature')
   .description('Atalho de `issue --type feature`')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "@octokit/graphql": "^9.0.1",
     "@octokit/rest": "^22.0.0",
     "chalk": "^5.4.1",
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "js-yaml": "^4.1.0"
   }
 }

package/src/commands/generate-plan.mjs

@@ -1,24 +1,29 @@
 import { execSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { buildTechContext } from '../lib/tech-context.mjs';
 
-const SYSTEM_PROMPT = `Você é um Tech Lead experiente. Gere um plano técnico (plan.md) completo e detalhado para a Feature descrita pelo usuário.
+const SYSTEM_PROMPT = `Você é um Tech Lead experiente. Gere um plano técnico (plan.md) completo e detalhado, baseado ESTRITAMENTE no spec.md fornecido.
 
-O plano deve conter exatamente estas seções em português:
-# Frontend
-# Backend
-# Banco de dados
-# Infraestrutura
-# Segurança
-# Testes
-# Estimativa (Story Points)
+O plano deve conter EXATAMENTE estas seções em português, nesta ordem:
+# Estratégia Técnica
+  - Abordagem Arquitetural, Decisões-Chave e uma Matriz de Rastreabilidade (tabela) ligando cada Critério de Aceite do spec a um componente técnico.
+# Detalhamento da Implementação
+  - Subseções: ## Backend, ## Banco de Dados, ## Frontend, ## Infraestrutura.
+# Segurança e Conformidade
+# Estratégia de Testes
+  - Unitários, Integração e E2E.
+# Rollback e Monitoramento
+  - Plano de Rollback, Métricas Observadas e Alertas.
 
-Para cada seção, forneça detalhes técnicos concretos e acionáveis baseados na descrição da Feature.
-A estimativa de Story Points deve usar a sequência de Fibonacci: 1, 2, 3, 5, 8, 13, 21.
-Responda APENAS com o conteúdo do plan.md, sem texto adicional.`;
+Regras OBRIGATÓRIAS:
+- TODA mudança de banco, endpoint de API ou componente de UI DEVE referenciar um Critério de Aceite específico do spec.md (rastreabilidade).
+- Use APENAS as tecnologias e serviços listados no tech_context fornecido. Não invente APIs ou serviços inexistentes.
+- Forneça detalhes acionáveis: caminhos exatos de endpoints, nomes de DTOs, constraints de banco.
+- Responda APENAS com o conteúdo do plan.md, sem texto adicional.`;
 
 export async function generatePlan({ issueNumber }) {
   const token = await resolveToken();
@@ -38,11 +43,28 @@ export async function generatePlan({ issueNumber }) {
   const featureDir = `docs/features/${slug}`;
   const filePath = `${featureDir}/plan.md`;
 
+  // Read existing spec.md if available (spec é gerada antes do plano)
+  const specPath = `${featureDir}/spec.md`;
+  const specContent = existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null;
+
+  // Tech context (RFC-002 §4): estático + dinâmico + override do corpo da issue.
+  const tech = buildTechContext({ issueBody: issue.body || '' });
+
+  // Payload estruturado (RFC-002 §5.2): spec_content + tech_context.
+  const payload = {
+    spec_content: specContent || '(spec.md ainda não gerado — baseie-se na descrição da Feature)',
+    feature_title: issue.title,
+    feature_description: issue.body || '(sem descrição)',
+    tech_context: {
+      static: tech.merged,
+      dynamic: tech.dynamic,
+      overrides: tech.overrides,
+    },
+  };
+  const userContent = `Gere o plan.md a partir deste payload JSON:\n\n${JSON.stringify(payload, null, 2)}`;
+
   console.log(`Gerando plan.md para: ${issue.title}`);
-  const content = await generateDocument(
-    SYSTEM_PROMPT,
-    `Feature: ${issue.title}\n\nDescrição:\n${issue.body || '(sem descrição)'}`
-  );
+  const content = await generateDocument(SYSTEM_PROMPT, userContent);
 
   mkdirSync(featureDir, { recursive: true });
   writeFileSync(filePath, content, 'utf-8');
@@ -63,8 +85,8 @@ export async function generatePlan({ issueNumber }) {
     token, owner, repo, parseInt(issueNumber, 10),
     `📋 **plan.md gerado automaticamente!**\n\n` +
     `📄 Arquivo: [\`${filePath}\`](${filePath})\n\n` +
-    `Revise o plano e, quando estiver pronto, mova o card para a coluna **📋 Spec** ou use:\n` +
-    `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:spec"\n\`\`\``
+    `Revise o plano e, quando estiver pronto, valide a Feature: mova o card para **✅ Ready** ou use:\n` +
+    `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:ready"\n\`\`\``
   );
 
   console.log(`plan.md criado em: ${filePath}`);

package/src/commands/generate-spec.mjs

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
@@ -7,17 +7,23 @@ import { slugify } from '../lib/slugify.mjs';
 
 const SYSTEM_PROMPT = `Você é um Product Manager experiente. Gere uma especificação funcional (spec.md) completa para a Feature descrita pelo usuário.
 
-O spec deve conter exatamente estas seções em português:
-# Objetivo
+O spec deve conter EXATAMENTE estas seções em português, nesta ordem:
+# Visão Geral
+  - Objetivo, Personas e Critérios de Sucesso como bullets.
 # Regras de Negócio
 # Fluxos
+  - Subseções: ## Fluxo Principal (Happy Path), ## Fluxos Alternativos, ## Cenários de Erro.
 # Critérios de Aceite
-# Casos de Erro
+  - OBRIGATORIAMENTE no formato Gherkin, dentro de um bloco \`\`\`gherkin com Given/When/Then. Um cenário por critério.
 # Dependências
+  - Subdivida em Internas e Externas.
+# Requisitos Não-Funcionais
+  - Performance, Segurança e Usabilidade.
 
-Para cada seção, seja específico e detalhado. Os Critérios de Aceite devem estar no formato de checklist markdown (- [ ] item).
-Se um plano técnico (plan.md) for fornecido, use-o para enriquecer os detalhes técnicos relevantes.
-Responda APENAS com o conteúdo do spec.md, sem texto adicional.`;
+Regras:
+- NÃO invente regras de negócio. Se faltar informação, marque explicitamente com "[TODO: requer esclarecimento do PO]".
+- Seja específico e detalhado em cada seção.
+- Responda APENAS com o conteúdo do spec.md, sem texto adicional.`;
 
 export async function generateSpec({ issueNumber }) {
   const token = await resolveToken();
@@ -37,15 +43,18 @@ export async function generateSpec({ issueNumber }) {
   const featureDir = `docs/features/${slug}`;
   const filePath = `${featureDir}/spec.md`;
 
-  // Read existing plan.md if available
-  const planPath = `${featureDir}/plan.md`;
-  const planContent = existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null;
-
-  const userContent = [
-    `Feature: ${issue.title}`,
-    `\nDescrição:\n${issue.body || '(sem descrição)'}`,
-    planContent ? `\nPlano Técnico (plan.md):\n${planContent}` : '',
-  ].join('');
+  // Payload estruturado (RFC-002 §5.1): metadata + entrada de negócio.
+  const payload = {
+    metadata: {
+      feature_title: issue.title,
+      feature_description: issue.body || '(sem descrição)',
+      labels: (issue.labels || []).map((l) => (typeof l === 'string' ? l : l.name)),
+    },
+    business_input: {
+      raw: issue.body || '(sem descrição)',
+    },
+  };
+  const userContent = `Gere o spec.md a partir deste payload JSON:\n\n${JSON.stringify(payload, null, 2)}`;
 
   console.log(`Gerando spec.md para: ${issue.title}`);
   const content = await generateDocument(SYSTEM_PROMPT, userContent);
@@ -69,8 +78,8 @@ export async function generateSpec({ issueNumber }) {
     token, owner, repo, parseInt(issueNumber, 10),
     `📋 **spec.md gerado automaticamente!**\n\n` +
     `📄 Arquivo: [\`${filePath}\`](${filePath})\n\n` +
-    `Revise a especificação e, quando estiver pronto, mova o card para **✅ Ready** ou use:\n` +
-    `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:ready"\n\`\`\``
+    `Revise a especificação e, quando estiver pronto, gere o plano técnico: mova o card para **📋 Plan** ou use:\n` +
+    `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:plan"\n\`\`\``
   );
 
   console.log(`spec.md criado em: ${filePath}`);

package/src/commands/init.mjs

@@ -122,7 +122,7 @@ export async function init(options) {
     labelSpinner.start('Criando labels...');
     try {
       await setupLabels(token, owner, repo, labelSpinner);
-      labelSpinner.stop('Labels criadas (15 labels)');
+      labelSpinner.stop('Labels criadas (16 labels)');
     } catch (err) {
       labelSpinner.stop('');
       p.log.error(`Erro ao criar labels: ${err.message}`);

package/src/commands/initiative.mjs

@@ -0,0 +1,8 @@
+import { issue } from './issue.mjs';
+
+// `initiative` é um atalho de `issue --type initiative`. A Initiative é o nó raiz
+// da hierarquia (Initiative → Epic → Feature → Story → Task) e agrupa Epics.
+// Toda a lógica vive em issue.mjs.
+export async function initiative(options) {
+  return issue({ ...options, type: 'initiative' });
+}

package/src/commands/issue.mjs

@@ -179,8 +179,13 @@ export async function issue(options) {
   }
 
   const parentLine = parent ? ` (sub-issue de #${parent.number})` : '';
+  const hints = {
+    Feature: `Próximo: \`/spec-wave plan ${created.number}\` para o planejamento técnico.`,
+    Initiative: `Próximo: crie Epics sob esta Initiative com \`spec-wave issue --type epic --parent ${created.number} --title "..."\`.`,
+    Epic: `Próximo: crie Features sob este Epic com \`spec-wave feature --parent ${created.number} --title "..."\`.`,
+  };
   p.outro(
     `${chalk.green('✓')} ${type} #${created.number} criado em "${INITIAL_STAGE}"${parentLine}.\n` +
-    `  ${type === 'Feature' ? `Próximo: \`/spec-wave plan ${created.number}\` para o planejamento técnico.` : ''}`
+    `  ${hints[type] || ''}`
   );
 }

package/src/commands/validate.mjs

@@ -67,8 +67,8 @@ export async function validate({ issueNumber }) {
   await commentOnIssue(
     token, owner, repo, parseInt(issueNumber, 10),
     `✅ **Validação concluída com sucesso!**\n\n` +
-    `- [\`${planPath}\`](${planPath}) ✓\n` +
-    `- [\`${specPath}\`](${specPath}) ✓\n\n` +
+    `- [\`${specPath}\`](${specPath}) ✓\n` +
+    `- [\`${planPath}\`](${planPath}) ✓\n\n` +
     `A Feature está pronta para decomposição. Mova o card para **📋 Backlog Técnico** ou use:\n` +
     `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:decompose"\n\`\`\``
   );

package/src/config.mjs

@@ -36,8 +36,8 @@ export function getProvider(value) {
 export const STATUS_OPTIONS = [
   { name: '📥 Backlog',          color: 'GRAY'   },
   { name: '🎯 Priorizado',       color: 'BLUE'   },
-  { name: '📋 Plan',             color: 'YELLOW' },
   { name: '📋 Spec',             color: 'YELLOW' },
+  { name: '📋 Plan',             color: 'YELLOW' },
   { name: '✅ Ready',            color: 'GREEN'  },
   { name: '📋 Backlog Técnico',  color: 'BLUE'   },
   { name: '🚧 Desenvolvimento',  color: 'ORANGE' },
@@ -53,6 +53,7 @@ export const CUSTOM_FIELDS = [
     name: 'Work Item Type',
     dataType: 'SINGLE_SELECT',
     options: [
+      { name: 'Initiative', color: 'PINK', description: 'Agrupamento estratégico de Epics' },
       { name: 'Epic',    color: 'PURPLE', description: 'Objetivo estratégico' },
       { name: 'Feature', color: 'BLUE',   description: 'Capacidade funcional' },
       { name: 'Story',   color: 'GREEN',  description: 'Necessidade do usuário' },
@@ -110,6 +111,7 @@ export const WORK_ITEM_TYPES = CUSTOM_FIELDS
   .options.map(o => o.name);
 
 export const TYPE_LABELS = [
+  { name: '[INITIATIVE]', color: 'C5DEF5', description: 'Agrupamento estratégico de Epics' },
   { name: '[EPIC]',    color: '7B61FF', description: 'Objetivo estratégico'  },
   { name: '[FEATURE]', color: '0075CA', description: 'Capacidade funcional'  },
   { name: '[STORY]',   color: '0E8A16', description: 'Necessidade do usuário' },
@@ -127,8 +129,8 @@ export const PRIORITY_LABELS = [
 ];
 
 export const TRIGGER_LABELS = [
-  { name: 'spec-wave:plan',      color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'     },
   { name: 'spec-wave:spec',      color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'     },
+  { name: 'spec-wave:plan',      color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'     },
   { name: 'spec-wave:ready',     color: '0E8A16', description: 'Validar spec+plan e mover para Ready' },
   { name: 'spec-wave:decompose', color: 'BFD4F2', description: 'Decompor em Stories e Tasks'         },
 ];
@@ -147,14 +149,24 @@ export const ISSUE_TEMPLATE_FILES = [
   'spec-template.md',
 ];
 
+export const REQUIRED_SPEC_SECTIONS = [
+  'Visão Geral',
+  'Critérios de Aceite',
+  'Requisitos Não-Funcionais',
+];
+
 export const REQUIRED_PLAN_SECTIONS = [
-  'Frontend',
-  'Backend',
-  'Banco de dados',
-  'Testes',
+  'Estratégia Técnica',
+  'Detalhamento da Implementação',
+  'Segurança e Conformidade',
+  'Estratégia de Testes',
+  'Rollback e Monitoramento',
 ];
 
-export const REQUIRED_SPEC_SECTIONS = [
-  'Objetivo',
-  'Critérios de Aceite',
+// Arquivos de configuração versionados gerados pelo `init` em .github/config/.
+// O tech_context.yml (RFC-002 §4) é a fonte de verdade estática que o
+// generate-plan lê para embasar o plano técnico. O scaffold em setup/files.mjs
+// só cria o arquivo se ainda não existir, para não sobrescrever ajustes manuais.
+export const CONFIG_FILES = [
+  'tech_context.yml',
 ];

package/src/lib/claude.mjs

@@ -23,17 +23,40 @@ function resolveAi() {
   return { provider: meta.value, model, secret: meta.secret };
 }
 
-export async function generateDocument(systemPrompt, userContent) {
+// 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.
+export async function generateDocument(systemPrompt, userContent, opts = {}) {
   const ai = resolveAi();
-  console.log(`Provider de IA: ${ai.provider} · modelo: ${ai.model}`);
+  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}`);
 
-  if (ai.provider === 'openrouter') {
-    return generateWithOpenRouter(systemPrompt, userContent, ai);
-  }
-  return generateWithAnthropic(systemPrompt, userContent, ai);
+  const raw = ai.provider === 'openrouter'
+    ? await generateWithOpenRouter(systemPrompt, userContent, ai, temperature, maxTokens)
+    : await generateWithAnthropic(systemPrompt, userContent, ai, temperature, maxTokens);
+
+  return stripOuterFence(raw);
+}
+
+// Remove blocos de raciocínio que alguns modelos (ex.: deepseek-r1) embutem no
+// content. A OpenRouter normalmente separa em `reasoning`, mas isto é uma rede
+// de segurança caso o <think> venha junto do conteúdo final.
+function stripReasoning(text) {
+  return text.replace(/<think>[\s\S]*?<\/think>/gi, '').trim();
+}
+
+// Alguns modelos (ex.: deepseek-r1) envolvem o documento inteiro numa fence
+// ```markdown ... ```. Removemos só o wrapper externo (a primeira e a última
+// linha de cerca), preservando fences internas (gherkin, typescript, etc.).
+function stripOuterFence(text) {
+  const t = (text || '').trim();
+  const m = t.match(/^```[a-zA-Z]*\n([\s\S]*)\n```$/);
+  return m ? m[1].trim() : t;
 }
 
-async function generateWithAnthropic(systemPrompt, userContent, ai) {
+async function generateWithAnthropic(systemPrompt, userContent, ai, temperature, maxTokens) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -45,7 +68,8 @@ async function generateWithAnthropic(systemPrompt, userContent, ai) {
   const client = new Anthropic({ apiKey });
   const message = await client.messages.create({
     model: ai.model,
-    max_tokens: 4096,
+    max_tokens: maxTokens,
+    temperature,
     messages: [{ role: 'user', content: userContent }],
     system: systemPrompt,
   });
@@ -53,7 +77,7 @@ async function generateWithAnthropic(systemPrompt, userContent, ai) {
   return message.content[0].text;
 }
 
-async function generateWithOpenRouter(systemPrompt, userContent, ai) {
+async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature, maxTokens) {
   const apiKey = process.env.OPENROUTER_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -72,7 +96,8 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai) {
     },
     body: JSON.stringify({
       model: ai.model,
-      max_tokens: 4096,
+      max_tokens: maxTokens,
+      temperature,
       messages: [
         { role: 'system', content: systemPrompt },
         { role: 'user', content: userContent },
@@ -86,7 +111,7 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai) {
   }
 
   const data = await res.json();
-  const content = data?.choices?.[0]?.message?.content;
+  const content = stripReasoning(data?.choices?.[0]?.message?.content || '');
   if (!content) {
     throw new Error(`OpenRouter retornou resposta vazia: ${JSON.stringify(data)}`);
   }

package/src/lib/tech-context.mjs

@@ -0,0 +1,142 @@
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+// Subsistema de Tech Context (RFC-002 §4).
+//
+// Monta o contexto técnico que o `generate-plan` injeta na chamada de IA, no
+// formato do payload RFC §5.2: { static, dynamic, overrides }. Roda no checkout
+// do GitHub Action, então lê tudo do filesystem local (cwd = raiz do repo-alvo).
+
+const TECH_CONTEXT_PATH = '.github/config/tech_context.yml';
+
+// Diretórios onde migrations costumam viver (várias stacks).
+const MIGRATION_DIRS = [
+  'migrations',
+  'db/migrations',
+  'src/migrations',
+  'prisma/migrations',
+  'database/migrations',
+];
+
+const MAX_MIGRATIONS = 10;
+
+// §4.1 — Fonte de verdade estática. Ausência não é erro: segue com {} e avisa.
+function readStaticContext(cwd) {
+  const filePath = path.join(cwd, TECH_CONTEXT_PATH);
+  if (!existsSync(filePath)) {
+    console.warn(
+      `⚠️ ${TECH_CONTEXT_PATH} não encontrado. ` +
+      `O plano será gerado sem contexto técnico estático. ` +
+      `Rode \`spec-wave init\` para gerar o scaffold.`
+    );
+    return {};
+  }
+  try {
+    return yaml.load(readFileSync(filePath, 'utf-8')) || {};
+  } catch (err) {
+    console.warn(`⚠️ Falha ao parsear ${TECH_CONTEXT_PATH}: ${err.message}. Ignorando.`);
+    return {};
+  }
+}
+
+// §4.2 — Augmentação dinâmica: migrations recentes + versões exatas de pacotes.
+function readDynamicContext(cwd) {
+  return {
+    recent_migrations: listRecentMigrations(cwd),
+    current_packages: readPackageVersions(cwd),
+  };
+}
+
+function listRecentMigrations(cwd) {
+  for (const dir of MIGRATION_DIRS) {
+    const abs = path.join(cwd, dir);
+    if (!existsSync(abs)) continue;
+    try {
+      const entries = readdirSync(abs)
+        .map((name) => {
+          const full = path.join(abs, name);
+          return { name, mtime: statSync(full).mtimeMs };
+        })
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, MAX_MIGRATIONS)
+        .map((e) => `${dir}/${e.name}`);
+      if (entries.length) return entries;
+    } catch {
+      // diretório ilegível → tenta o próximo
+    }
+  }
+  return [];
+}
+
+function readPackageVersions(cwd) {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return {};
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  } catch {
+    return {};
+  }
+}
+
+// §4.3 — Override do corpo da issue. Extrai a seção markdown exatamente titulada
+// `## Tech Override` e parseia o bloco como YAML. Retorna {} se ausente.
+export function parseTechOverride(issueBody) {
+  if (!issueBody) return {};
+  const lines = issueBody.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === '## Tech Override');
+  if (start === -1) return {};
+
+  // Captura até o próximo heading de mesmo nível (ou superior) ou fim do corpo.
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#{1,2}\s/.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+
+  // Tolera o YAML vir dentro de uma fence ```yaml ... ```.
+  let raw = body.join('\n').trim();
+  const fence = raw.match(/```(?:ya?ml)?\s*\n([\s\S]*?)```/);
+  if (fence) raw = fence[1];
+  if (!raw.trim()) return {};
+
+  try {
+    return yaml.load(raw) || {};
+  } catch (err) {
+    console.warn(`⚠️ Falha ao parsear a seção '## Tech Override': ${err.message}. Ignorando.`);
+    return {};
+  }
+}
+
+// Deep-merge: override vence; objetos são mesclados recursivamente, escalares e
+// arrays são substituídos.
+function deepMerge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) return override;
+  const out = { ...base };
+  for (const key of Object.keys(override)) {
+    out[key] = key in base ? deepMerge(base[key], override[key]) : override[key];
+  }
+  return out;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// Monta o tech context completo. `cwd` default = process.cwd() (checkout do Action).
+export function buildTechContext({ issueBody = '', cwd = process.cwd() } = {}) {
+  const staticContext = readStaticContext(cwd);
+  const dynamic = readDynamicContext(cwd);
+  const overrides = parseTechOverride(issueBody);
+  const merged = deepMerge(staticContext, overrides);
+
+  return {
+    static: staticContext,
+    dynamic,
+    overrides,
+    merged,
+    // String pronta para injetar no prompt: contexto efetivo + efêmeros.
+    yaml: yaml.dump({ ...merged, _dynamic: dynamic }, { lineWidth: 120 }),
+  };
+}

package/src/setup/files.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
-import { upsertFile, isRepoInitialized } from '../api/github-rest.mjs';
+import { upsertFile, getFileContent, isRepoInitialized } from '../api/github-rest.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dir, '..', 'templates');
@@ -60,4 +60,24 @@ export async function setupFiles(token, owner, repo, spinner) {
     spinner.message(`Criando arquivo ${i + 1}/${filesToCreate.length}: ${file.path}`);
     await upsertFile(token, owner, repo, file.path, file.content, file.message);
   }
+
+  // Arquivos de config criados apenas se ainda não existirem, para não
+  // sobrescrever ajustes manuais (tech_context.yml é editado pelo time).
+  const configFiles = [
+    {
+      path: '.github/config/tech_context.yml',
+      content: readTemplate('config', 'tech_context.yml'),
+      message: 'chore: scaffold tech_context.yml [spec-wave]',
+    },
+  ];
+
+  for (const file of configFiles) {
+    const existing = await getFileContent(token, owner, repo, file.path);
+    if (existing !== null) {
+      spinner.message(`Mantendo ${file.path} existente (não sobrescrito)`);
+      continue;
+    }
+    spinner.message(`Criando arquivo de config: ${file.path}`);
+    await upsertFile(token, owner, repo, file.path, file.content, file.message);
+  }
 }

package/src/templates/config/tech_context.yml

@@ -0,0 +1,42 @@
+# tech_context.yml — Fonte de verdade estática do sistema (RFC-002 §4)
+#
+# O comando `generate-plan` lê este arquivo para embasar o plano técnico, usando
+# APENAS as tecnologias e serviços aqui declarados. Mantenha-o atualizado.
+#
+# Augmentação dinâmica (automática, não precisa editar): o agente também lê as
+# migrations recentes e as versões exatas de pacotes (package.json) em tempo de
+# execução. Para desvios pontuais, adicione uma seção `## Tech Override` no corpo
+# da issue da Feature — ela é mesclada (deep-merge) sobre esta config.
+
+system_info:
+  name: "Order Management System"
+  stack:
+    backend: "Node.js (NestJS v10)"
+    frontend: "React 18 with Vite"
+    database: "PostgreSQL 15"
+    cache: "Redis 7"
+    messaging: "RabbitMQ"
+    infra: "Kubernetes (EKS) + Helm"
+  architecture: "Microservices via API Gateway"
+
+security:
+  auth_protocol: "JWT (Access/Refresh)"
+  rbac_roles: ["ADMIN", "MANAGER", "GARCOM", "COZINHA"]
+
+database_schemas:
+  - table: "users"
+    columns: "id, name, email, role, password_hash"
+  - table: "tables"
+    columns: "id, number, status, capacity"
+  - table: "products"
+    columns: "id, name, category, price, stock"
+
+existing_services:
+  - name: "Inventory API"
+    endpoint: "/api/inventory/{productId}/availability"
+    auth: "mTLS"
+    docs: "https://docs.internal/inventory"
+
+internal_libraries:
+  - "shared-logger"
+  - "db-client (TypeORM)"

package/src/templates/issue/plan-template.md

@@ -6,30 +6,46 @@ labels: "[FEATURE]"
 assignees: ""
 ---
 
-# Frontend
+# Estratégia Técnica
 
-<!-- Componentes, rotas, estados, integrações de UI -->
+- **Abordagem Arquitetural:** <!-- ex.: CQRS, Event Sourcing, REST -->
+- **Decisões-Chave:** <!-- Justificativa das tecnologias/padrões escolhidos -->
+- **Matriz de Rastreabilidade:** <!-- Cada Critério de Aceite do spec mapeado para um componente técnico -->
 
-# Backend
+| Critério de Aceite | Componente Técnico |
+|--------------------|--------------------|
+|                    |                    |
 
-<!-- Endpoints, serviços, regras de negócio -->
+# Detalhamento da Implementação
 
-# Banco de dados
+## Backend
 
-<!-- Migrations, tabelas, índices, queries relevantes -->
+<!-- Endpoints, DTOs, controllers, serviços, casos de uso, jobs/filas -->
 
-# Infraestrutura
+## Banco de Dados
 
-<!-- Configurações de ambiente, variáveis, serviços externos -->
+<!-- Novas tabelas, migrations, índices -->
 
-# Segurança
+## Frontend
 
-<!-- Autenticação, autorização, validações críticas -->
+<!-- Componentes/telas, gerenciamento de estado, rotas e guards -->
 
-# Testes
+## Infraestrutura
 
-<!-- Estratégia de testes: unitários, integração, E2E -->
+<!-- ConfigMaps/Secrets, pipeline CI/CD, feature flags e estratégia de rollout -->
 
-# Estimativa (Story Points)
+# Segurança e Conformidade
 
-<!-- 1 / 2 / 3 / 5 / 8 / 13 / 21 -->
+<!-- Autenticação/autorização (quais papéis acessam?), criptografia (em repouso/trânsito), logging e auditoria -->
+
+# Estratégia de Testes
+
+- **Unitários:** <!-- Escopo e frameworks -->
+- **Integração:** <!-- Escopo e mocks -->
+- **E2E:** <!-- Caminhos críticos -->
+
+# Rollback e Monitoramento
+
+- **Plano de Rollback:** <!-- Rollback de banco, revert de código -->
+- **Métricas Observadas:** <!-- Dashboards (New Relic/Datadog) -->
+- **Alertas:** <!-- Thresholds e caminhos de escalonamento -->

package/src/templates/issue/spec-template.md

@@ -6,9 +6,11 @@ labels: "[FEATURE]"
 assignees: ""
 ---
 
-# Objetivo
+# Visão Geral
 
-<!-- O que esta Feature entrega e qual problema resolve? -->
+- **Objetivo:** <!-- O que esta Feature entrega e qual problema resolve? -->
+- **Personas:** <!-- Quais usuários são afetados? (ex.: Garçom, Cozinha) -->
+- **Critérios de Sucesso:** <!-- Resultados mensuráveis -->
 
 # Regras de Negócio
 
@@ -16,17 +18,37 @@ assignees: ""
 
 # Fluxos
 
-<!-- Descreva o fluxo principal e os fluxos alternativos -->
+## Fluxo Principal (Happy Path)
 
-# Critérios de Aceite
+<!-- Passo a passo do caminho feliz -->
+
+## Fluxos Alternativos
 
-- [ ] 
-- [ ] 
+<!-- Variações do fluxo principal -->
 
-# Casos de Erro
+## Cenários de Erro
 
 <!-- O que acontece quando algo dá errado? Como o sistema se comporta? -->
 
+# Critérios de Aceite
+
+<!-- Use o formato Gherkin (Given/When/Then). Um cenário por critério. -->
+
+```gherkin
+Feature: [Nome da Feature]
+  Scenario: [Título do cenário]
+    Given [pré-condição]
+    When [ação]
+    Then [resultado esperado]
+```
+
 # Dependências
 
-<!-- Outras Features, integrações, APIs externas ou pré-requisitos -->
+- **Internas:** <!-- Serviços/APIs dentro do sistema -->
+- **Externas:** <!-- Sistemas de terceiros -->
+
+# Requisitos Não-Funcionais
+
+- **Performance:** <!-- ex.: tempo de resposta < 200ms -->
+- **Segurança:** <!-- ex.: RBAC obrigatório -->
+- **Usabilidade:** <!-- ex.: responsivo em mobile -->