@guilhermefsousa/open-spec-kit 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guilhermefsousa/open-spec-kit",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "CLI para spec-driven development com suporte a Claude Code e GitHub Copilot",
   "type": "module",
   "bin": {

package/src/commands/doctor.js

@@ -67,7 +67,10 @@ export async function doctorCommand() {
   if (agents.includes('claude')) {
     try {
       claudeMcpContent = await readFile(join(cwd, '.mcp.json'), 'utf-8');
-      if (claudeMcpContent.includes('SEU-TOKEN') || claudeMcpContent.includes('SEU-DOMINIO')) {
+      if (claudeMcpContent.includes('SEU-TOKEN') || claudeMcpContent.includes('SEU-DOMINIO')
+          || claudeMcpContent.includes('seu-token-aqui') || claudeMcpContent.includes('seu-dominio')
+          || claudeMcpContent.includes('seu-email') || claudeMcpContent.includes('${CONFLUENCE_URL}')
+          || claudeMcpContent.includes('${CONFLUENCE_API_TOKEN}')) {
         console.log(chalk.yellow('  ⚠ .mcp.json (Claude) existe mas tem placeholders'));
         fail++;
       } else {
@@ -93,8 +96,16 @@ export async function doctorCommand() {
   if (agents.includes('copilot')) {
     try {
       copilotMcpContent = await readFile(join(cwd, '.vscode/mcp.json'), 'utf-8');
-      console.log(chalk.green('  ✓ .vscode/mcp.json (Copilot) encontrado'));
-      pass++;
+      if (copilotMcpContent.includes('SEU-TOKEN') || copilotMcpContent.includes('SEU-DOMINIO')
+          || copilotMcpContent.includes('seu-token-aqui') || copilotMcpContent.includes('seu-dominio')
+          || copilotMcpContent.includes('seu-email') || copilotMcpContent.includes('${CONFLUENCE_URL}')
+          || copilotMcpContent.includes('${CONFLUENCE_API_TOKEN}')) {
+        console.log(chalk.yellow('  ⚠ .vscode/mcp.json (Copilot) existe mas tem placeholders'));
+        fail++;
+      } else {
+        console.log(chalk.green('  ✓ .vscode/mcp.json (Copilot) configurado'));
+        pass++;
+      }
     } catch {
       console.log(chalk.red('  ✗ .vscode/mcp.json (Copilot) ausente'));
       fail++;

package/src/commands/init.js

@@ -103,7 +103,7 @@ function deriveSigla(projectName) {
     .filter(w => !skip.has(w.toLowerCase()))
     .map(w => w[0].toUpperCase())
     .join('');
-  return letters.slice(0, 4) || projectName.slice(0, 3).toUpperCase();
+  return (letters.slice(0, 4) || projectName.trim().slice(0, 3).toUpperCase()).trim();
 }
 
 // ──────────────────────────────────────────────────────
@@ -342,15 +342,7 @@ Thumbs.db
 *.swp
 `;
 
-  if (config.agents.includes('copilot')) {
-    content += `
-# VS Code (exceto MCP config compartilhada)
-.vscode/*
-!.vscode/mcp.json
-`;
-  } else {
-    content += '\n.vscode/\n';
-  }
+  content += '\n.vscode/\n';
 
   return content;
 }
@@ -391,53 +383,38 @@ FIGMA_API_KEY=seu-figma-api-key
   return content;
 }
 
-function generateClaudeMcp(config) {
+function buildMcpServers(config, { stdio = false } = {}) {
   const runner = detectMcpRunner();
-  const confluenceArgs = [
-    ...runner.prefix,
-    '--confluence-url', '${CONFLUENCE_URL}',
-    '--confluence-username', '${CONFLUENCE_USERNAME}',
-    '--confluence-token', '${CONFLUENCE_API_TOKEN}'
-  ];
+  const base = stdio ? { type: 'stdio' } : {};
   const servers = {
     confluence: {
+      ...base,
       command: runner.command,
-      args: confluenceArgs,
+      args: [
+        ...runner.prefix,
+        '--confluence-url', config.confluenceUrl,
+        '--confluence-username', config.confluenceUser,
+        '--confluence-token', config.confluenceToken
+      ],
     }
   };
   if (config.hasFigma && config.figmaFileUrl) {
     const npx = detectNpxRunner();
     servers.figma = {
+      ...base,
       command: npx.command,
-      args: [...npx.prefix, FIGMA_MCP_PACKAGE, '--figma-api-key', '${FIGMA_API_KEY}']
+      args: [...npx.prefix, FIGMA_MCP_PACKAGE, '--figma-api-key', config.figmaToken]
     };
   }
-  return JSON.stringify({ mcpServers: servers }, null, 2) + '\n';
+  return servers;
+}
+
+function generateClaudeMcp(config) {
+  return JSON.stringify({ mcpServers: buildMcpServers(config) }, null, 2) + '\n';
 }
 
 function generateCopilotMcp(config) {
-  const runner = detectMcpRunner();
-  const confluenceArgs = [
-    ...runner.prefix,
-    '--env-file', '.env',
-    '--no-confluence-ssl-verify'
-  ];
-  const servers = {
-    confluence: {
-      type: 'stdio',
-      command: runner.command,
-      args: confluenceArgs,
-    }
-  };
-  if (config.hasFigma && config.figmaFileUrl) {
-    const npx = detectNpxRunner();
-    servers.figma = {
-      type: 'stdio',
-      command: npx.command,
-      args: [...npx.prefix, FIGMA_MCP_PACKAGE, '--figma-api-key', '${input:figma-api-key}']
-    };
-  }
-  return JSON.stringify({ servers }, null, 2) + '\n';
+  return JSON.stringify({ servers: buildMcpServers(config, { stdio: true }) }, null, 2) + '\n';
 }
 
 function generateArchitectureSkeleton(config) {
@@ -982,3 +959,16 @@ export async function initCommand() {
     process.exit(1);
   }
 }
+
+// Exported for testing — pure functions with no side effects
+export {
+  stripHtml,
+  detectTechInText,
+  detectRepoNames,
+  deriveSigla,
+  generateProjectsYml,
+  generateEnvFile,
+  generateEnvExample,
+  generateGitignore,
+  generateArchitectureSkeleton,
+};

package/src/commands/validate.js

@@ -24,7 +24,7 @@ import * as rules from '../schemas/spec.schema.js';
 function parseBrief(content) {
   const sections = parseSections(content);
   return {
-    lineCount: content.split('\n').length,
+    lineCount: content.split(/\r?\n/).length,
     hasProblema: !!findSection(sections, /problema|contexto|visão\s*geral|overview|background|objetivo\s+do\s+produto|situação\s*atual|descri[çc][aã]o|identifica[çc][aã]o/i),
     hasForaDeEscopo: !!findSection(sections, /fora\s+de\s+escopo/i),
     reqIds: content.match(/REQ-\w+/g) || [],

package/src/utils/http.js

@@ -63,7 +63,7 @@ const SSL_ERROR_CODES = new Set([
 ]);
 
 export function isSslError(err) {
-  return err.status === 0 && (
+  return err.status === 0 && !!(
     SSL_ERROR_CODES.has(err.code) ||
     SSL_ERROR_CODES.has(err.message) ||
     (err.message && SSL_ERROR_CODES.has(err.message.split(':').pop()?.trim()))

package/templates/agents/rules/ownership.instructions.md

@@ -17,7 +17,11 @@ This rule exists to prevent the "duplicate responsibility" anti-pattern where mu
 | Demandas/ labels | /setup | — | /discovery | — |
 | Visão do Produto | /setup | — | all | — |
 | **Glossário** | /setup | **/discovery** (adds domain terms found in PRD analysis, exit gate), **/dev** (post-merge only — adds terms that emerged during implementation and weren't in the PRD) | /spec | /spec (read-only validate — if terms are missing, stop and ask dev to re-run /discovery) |
+
+> **Glossário conflict rule**: if /dev (post-merge) needs to update a term that /discovery defined, /dev's update wins — it reflects implemented reality. /dev adds a note: "Atualizado pós-merge: {reason}". If /dev adds a term that already exists with a different definition, update the definition to match implementation.
 | DD (Design Document) | /spec (via `design-doc` agent, fallback: MCP direct) | /dev (via `design-doc` agent, fallback: MCP direct) | — | — |
+
+> **DD update coordination**: /spec updates the DD FIRST (during spec phase), /dev updates AFTER MERGE (during Phase D). If /dev needs to change something /spec wrote, /dev overwrites with implemented reality (code is source of truth post-merge). No locking needed — the sequential workflow prevents simultaneous updates.
 | Domínio/Regras | /setup | /dev (post-merge only) | /discovery, /spec | — |
 | Domínio/Fluxos | /setup | /dev (post-merge only) | /discovery | — |
 | Domínio/Tabelas | /setup | — | /discovery | — |
@@ -32,7 +36,7 @@ This rule exists to prevent the "duplicate responsibility" anti-pattern where mu
 | Artifact | Owner (creates) | Updater | Readers | Validators |
 |----------|----------------|---------|---------|------------|
 | `projects.yml` | /setup | /spec (adds planned repos), /dev (repo URLs + status) | all | — |
-| `docs/architecture.md` | /setup | /discovery (resolves decisions) | /spec, /dev | /spec (validates no blockers) |
+| `docs/architecture.md` | /setup | /discovery (resolves decisions), /dev (adds decisions discovered during implementation — post-merge only) | /spec, /dev | /spec (validates no blockers) |
 | `docs/lessons/` | /dev | /dev | all | — |
 | `docs/decisions/` | manual / spec-agent | — | all | — |
 | `specs/NNN/brief.md` | /spec | — | /dev | — |
@@ -41,7 +45,10 @@ This rule exists to prevent the "duplicate responsibility" anti-pattern where mu
 | `specs/NNN/tasks.md` | /spec | — | /dev | — |
 | `specs/NNN/links.md` | /spec (template) | /dev (MR links) | — | — |
 | `specs/NNN/audit-report.md` | /spec (self-review) | — | /dev (reads before Phase B, blocks if ❌) | — |
-| `specs/NNN/conformance-report.json` | /dev (Phase C.3) | — | CI Guard | — |
+| `specs/NNN/conformance-report.json` | /dev (Phase C.3) | /dev (overwrites per run) | CI Guard | — |
+| `specs/NNN/conformance-history.log` | /dev (Phase C.3) | /dev (appends per run) | — | — |
+
+> **Conformance versioning**: `conformance-report.json` is overwritten on each /dev run. To preserve history, /dev appends a summary line to `specs/NNN/conformance-history.log`: `{timestamp} | {result} | {matching}/{total} endpoints | {matching}/{total} fields`
 
 ## Key Rules
 

package/templates/agents/skills/dev-orchestrator/SKILL.md

@@ -315,6 +315,17 @@ If the code reviewer (human or agent) rejects the MR:
 After the dev merges the MR:
 
 D.1. Update `specs/NNN-name/links.md` with merged MR link
+
+D.1.5. **Sync spec with implementation reality**
+If the conformance report (Phase C.3) detected INTENTIONAL divergences (spec was wrong, implementation corrected it), update the LOCAL spec files to match what was actually implemented:
+- `contracts.md`: fix endpoint paths, response fields, or types that diverged
+- `scenarios.md`: update Given/When/Then if behavior changed
+- Commit: `fix(NNN): sync spec with implementation — {summary of changes}`
+
+This ensures specs remain the source of truth for FUTURE features that reference them. Without this update, /discovery and /spec for next features read stale contracts.
+
+If conformance report shows NO divergences → skip (specs already match).
+
 D.2. Move VCS Issue → `done`
 D.3. **Update living docs on Confluence** (via MCP):
 
@@ -336,7 +347,13 @@ D.3. **Update living docs on Confluence** (via MCP):
 - Notify the dev with message: "Confluence indisponível — atualizações salvas em docs/pending-confluence-updates.md. Execute manualmente quando o Confluence voltar."
 - On the next /dev execution, check if `docs/pending-confluence-updates.md` exists and attempt to apply pending updates
 
-D.4. If something surprised during implementation → generate `docs/lessons/NNN-title.md` with template:
+D.4. **Post-implementation discoveries:**
+
+If implementation revealed:
+- a) A SURPRISE (unexpected behavior, edge case) → save to `docs/lessons/NNN-title.md` (template below)
+- b) A NEW ARCHITECTURE DECISION (chose a pattern, discovered a constraint) → add to `docs/architecture.md` "Decisões em Aberto" table with Status: `resolvida — [decisão tomada durante implementação de {SIGLA}-NNN]`. This ensures architecture.md reflects decisions made during /dev, not just during /discovery.
+
+If something surprised during implementation → generate `docs/lessons/NNN-title.md` with template:
     ```
     ## O que aconteceu
     [description]
@@ -345,6 +362,26 @@ D.4. If something surprised during implementation → generate `docs/lessons/NNN
     ## Como evitar
     [what to do differently next time]
     ```
+D.4.5. **Update CHANGELOG.md**
+
+In the MAIN repo (first repo in projects.yml), create or update `CHANGELOG.md` with an entry for this feature:
+
+```markdown
+## [{SIGLA}-NNN] Feature Name — YYYY-MM-DD
+
+### Adicionado
+- {list new endpoints from conformance report}
+- {list new entities from contracts.md}
+
+### Alterado
+- {list modified entities/endpoints, if evolution feature}
+
+### Observações
+- {any "A CONFIRMAR" items still pending}
+```
+
+If `CHANGELOG.md` doesn't exist, create it with header: `# Changelog` and a reference to [Keep a Changelog](https://keepachangelog.com/).
+
 D.5. Notify Google Chat (rich card format):
     ```bash
     ./scripts/notify-gchat.sh --card \

package/templates/agents/skills/discovery/SKILL.md

@@ -47,8 +47,12 @@ If NO argument was passed (user ran `/discovery` without a feature name):
 
    Bloqueadas:
    - 🚀 TFB-002 - Conferência (depende de TFB-001)
+
+   Caminho crítico recomendado: TFB-000 → TFB-001 → TFB-003 → TFB-002
+   (002 depende de 001; 003 pode ser paralela com 001)
    ```
-6. Ask: "Qual feature deseja trabalhar?"
+6. **Suggest execution order**: analyze the dependency graph from all features' "Depende de" fields and suggest the order that minimizes blocked time. This is a SUGGESTION — the dev chooses the final order.
+7. Ask: "Qual feature deseja trabalhar?"
 7. Proceed with the chosen feature.
 
 If argument WAS passed (e.g., `/discovery TFB-001`):
@@ -178,6 +182,7 @@ Covered / Partial / Missing.
 | SECURITY | Sensitive data? Auth requirements? Redaction needed? |
 | PERFORMANCE | SLAs? Expected load? Rate limits? |
 | UX | Error messages? Empty states? (if frontend) |
+| TECHNOLOGY | Stack in projects.yml compatible with requirements? WebSocket needed but no support? Background jobs needed but no worker declared? Auth mechanism defined? DB supports required queries (full-text search, JSONB, geo)? |
 
 **Special rule — PERFORMANCE**: this category can NEVER be marked as "Covered" without at least one question about: data limits (how many records per entity?), response SLA (max acceptable response time per endpoint), or expected throughput (requests/second, concurrent users). If the PO demand does not mention performance, ASK — absence of a performance requirement does not mean "no requirement", it means "undocumented implicit requirement".
 
@@ -297,6 +302,14 @@ Generate the PRD on the feature page in Confluence:
 ### Decisões tomadas
 - Duvida N.1: [decision] — Justificativa: [why]
 - ...
+
+### Requisitos Não-Funcionais (se aplicável)
+- **Performance**: [target, e.g., "GET /bills < 200ms p95, 100 req/s"]
+- **Disponibilidade**: [target, e.g., "99.9% uptime"]
+- **Escalabilidade**: [constraints, e.g., "suportar 10k faturas/mês"]
+
+_Include this section only if the gap analysis identified PERFORMANCE or TECHNOLOGY
+gaps with concrete targets. If no NFRs were identified, omit entirely._
 ```
 
 Then:

package/templates/agents/skills/setup-project/SKILL.md

@@ -165,6 +165,7 @@ Must contain these sections:
 - **Premissas**: assumptions stated in the PO docs (copy them, don't summarize)
 - **Escopo da v1**: what's in
 - **Fora de escopo**: what's explicitly out
+- **Riscos e dependencias criticas**: external systems without defined contracts, teams/knowledge dependencies, technical unknowns. If PO docs mention integration with an external system but no contract or API is defined, register as risk. If PO mentions a technology the team has no experience with, register as risk. If no risks identified, write "Nenhum risco critico identificado nos documentos do PO."
 - **Metricas de sucesso**: if the PO defined metrics, use them. If not, write "Metricas de negocio — A CONFIRMAR. Nao definidas pelo PO." Do NOT invent metrics. Do NOT use functional test criteria as metrics.
 - **Restricoes**: mandatory tech, environment, compliance constraints
 
@@ -296,10 +297,31 @@ All subsequent features ({SIGLA}-001 onwards) have an implicit dependency on {SI
 
 **Reminder: feature pages are children of `{SIGLA} — Features` (which is a child of `ROOT_ID`). Do NOT create features inside `Demandas/`.**
 
-Analyze the PO documents in `Demandas/` and identify distinct features/capabilities described. For EACH feature identified:
+**Follow this feature identification algorithm — both phases are mandatory:**
+
+**Phase A — Map PO sections to feature candidates:**
+1. Read each PO document in `Demandas/`
+2. Identify every NUMBERED SECTION or HEADING that describes a distinct user capability (look for: "Objetivo:", "Como [persona]...", numbered items "0.", "1.", "2.", or distinct headings with acceptance criteria)
+3. One section with a distinct objective = one feature candidate
+4. Record for each candidate: source reference (e.g., "Regra de Negocio §2"), title, number of acceptance criteria
+5. If a document has NO numbered sections (free-form text), identify capabilities by change of theme, persona, or objective — each distinct capability = one candidate
+
+**Phase B — Cross-cutting concern sweep:**
+After listing business features from Phase A, scan ALL PO documents AND architecture docs for these triggers. If found AND no Phase A candidate already covers the concern explicitly, CREATE a dedicated feature:
+
+| Trigger keywords in input docs | Feature to create |
+|-------------------------------|-------------------|
+| SSO, JWT, OAuth, roles, permissões, autorização, autenticação, LGPD, rate limit | {SIGLA}-NNN - Autenticação e Autorização |
+| automático, SLA, prazo, timeout, scheduled, job, cron, fechamento automático | {SIGLA}-NNN - Processos Automáticos e SLA |
+
+General principle: any capability mentioned in the PO that is NOT tied to a specific user screen or flow but affects multiple features should be evaluated as a potential cross-cutting feature.
+
+If the concern IS already an explicit PO section (identified in Phase A as its own candidate), do NOT create a duplicate.
+
+**After identifying all features, create a page for EACH.** For each feature:
 
 1. Create a child page under `{SIGLA} — Features` with title: `🚀 {SIGLA}-NNN - Feature name` (numbering sequential: 001, 002, ...). E.g., `🚀 FT-001 - Cadastro e Autenticação`, `🚀 TD-003 - Gerenciamento de Tarefas`
-2. Content MUST start with a metadata table:
+2. Content MUST follow this template (in pt-BR):
    ```
    | Campo | Valor |
    |-------|-------|
@@ -307,8 +329,11 @@ Analyze the PO documents in `Demandas/` and identify distinct features/capabilit
    | Depende de | {SIGLA}-000 (e outras se houver, separadas por vírgula) |
    | Complexidade | baixa / média / alta |
    | Repos envolvidos | {quais repos participam} |
+   | Seções do PO | {source sections, e.g., "Regra de Negocio §2, §7; DefinicoesTecnicas §2.2"} |
+
+   ## Escopo
+   {bullet list of what this feature includes — extracted from PO docs, not invented}
    ```
-   After the table: 1-2 paragraphs extracted from PO documents describing what the feature does.
 3. Add label `em-discovery` (ready for /discovery to process)
 
 If the PO documents describe a SINGLE monolithic system without clear feature boundaries, create ONE feature page covering the full scope and note: "Feature única — considerar quebra em sub-features durante /discovery."
@@ -384,6 +409,8 @@ Before closing the loop, the agent MUST do a self-review:
    - Did I invent anything that isn't in the PO documents?
 3. **Fix any gaps found** by updating the pages
 4. **Report** what was added/fixed in the self-review
+5. **Feature coverage**: for EACH numbered section or distinct capability in the PO documents, verify it is covered by at least one feature page. If uncovered → create a feature or add the scope to an existing one. Report: "Cobertura de features: {N}/{total} seções do PO cobertas."
+6. **Cross-cutting check**: if PO/architecture docs mention auth keywords (SSO, JWT, roles, LGPD) → verify a feature covers auth implementation. If they mention automation keywords (SLA, automático, scheduled) → verify a feature covers it. If missing → create the dedicated feature.
 
 ### 6. Close the loop
 
@@ -434,6 +461,7 @@ The output is considered good when:
 - **Architecture.md**: has an "open decisions" table ranked by impact
 - **projects.yml**: has all detected repos declared (not commented), with stack and status
 - **Self-review**: was performed, gaps were found and fixed (or confirmed none exist)
+- **Features**: every numbered section/capability in the PO documents is covered by at least one feature. Cross-cutting concerns (auth, automated processes) have dedicated features when triggered by keywords in the input. Feature pages include Escopo and Seções do PO fields.
 
 ## Validation checklist
 
@@ -443,7 +471,7 @@ The output is considered good when:
 - [ ] Demand label transition: (none/novo) → processando → processado
 
 ### Content generated
-- [ ] Visao do Produto: all required sections present (O que é, Para quem, Por que existe, Premissas, Escopo da v1, Fora de escopo, Métricas de sucesso, Restrições)
+- [ ] Visao do Produto: all required sections present (O que é, Para quem, Por que existe, Premissas, Escopo da v1, Fora de escopo, Riscos e dependências críticas, Métricas de sucesso, Restrições)
 - [ ] Glossario: covers all domain terms from PRD (verified by re-read)
 - [ ] Regras: all rules have ID + Fonte (PRD section) + Verificavel
 - [ ] Fluxos: all flows have happy path + exceptions + Mermaid flowchart TD
@@ -451,6 +479,9 @@ The output is considered good when:
 - [ ] Integracoes: all events have producer + consumer + expected payload
 - [ ] {SIGLA} — Features parent page created
 - [ ] Initial feature pages created under {SIGLA} — Features (with label `em-discovery`)
+- [ ] Every PO section covered by at least one feature (verified in self-review)
+- [ ] Cross-cutting features created when PO mentions auth/SSO/JWT or SLA/automático keywords
+- [ ] Feature pages have: Seções do PO field + Escopo section
 - [ ] {SIGLA} — Arquivados parent page created
 
 ### Spec repo updated

package/templates/agents/skills/specifying-features/SKILL.md

@@ -43,6 +43,13 @@ Read these files FIRST:
 - **Reuse** shared types (ErrorResponse, PaginatedResponse) by reference
 - If the new feature MODIFIES behavior of an existing endpoint, document the change explicitly in brief.md: "Modifica GET /api/contas para incluir campo `saldoAtual` no response"
 
+**Figma freshness check (if Figma configured):**
+If `projects.yml` has `figma.file_url` and Figma MCP is available:
+1. Read `get_metadata()` for the feature's frames
+2. Compare key elements (screen count, form fields) against what /discovery captured in the PRD
+3. If significant changes detected (new screens, removed fields) → WARN: "Design no Figma mudou desde o /discovery. Diferenças: {list}. Continuar com o design atual ou re-executar /discovery?"
+4. If no changes or Figma unavailable → proceed silently
+
 ## Inputs
 
 - Approved PRD on Confluence (label `prd-aprovado`) — read via MCP
@@ -123,7 +130,11 @@ Numbering is sequential: find the highest existing number in `specs/` and increm
   - Every REQ-NNN from the PRD MUST have at least one scenario covering it
   - If a REQ has no scenario, either the REQ is unverifiable (fix the PRD) or a scenario is missing (add it)
 - **Cross-check with business rules**: read `Domínio/Regras` on Confluence and verify that every RN referenced in the scenarios exists. If a scenario contradicts an RN, flag it as error.
-- **Mandatory auth scenario**: if the feature has ANY authenticated endpoint, include a scenario testing access WITHOUT a token (expected: 401 NAO_AUTORIZADO). One per feature is sufficient — it validates the auth middleware applies.
+- **Mandatory security scenarios**: if the feature has ANY authenticated endpoint, include:
+  - At least 1 scenario: request WITHOUT token → expected 401 NAO_AUTORIZADO
+  - At least 1 scenario: request with WRONG role → expected 403 ACESSO_NEGADO
+  - At least 1 scenario per endpoint accepting user input: malformed/malicious input → expected 400 with validation error (NOT 500)
+  If feature has NO authenticated endpoints, skip auth scenarios.
 - **Mandatory pagination scenarios**: if ANY endpoint uses explicit pagination (PaginatedResponse, page/pageSize params, or similar envelope), include scenarios for:
   - Default pagination (no params → uses defaults)
   - Last page (partial results)
@@ -175,6 +186,11 @@ Additional rules:
 - **Dependency between blocks**: if a repo block REQUIRES another block to be COMPLETED first, declare explicitly with `> Dependency: todo-api block must be completed before starting`
 - Each task = 1 PR
 - Reference REQ-NNN from scenarios
+- **Size estimate**: each task line should include a size indicator (P/M/G):
+  - P (pequeno): < 2h, single file change, well-understood pattern
+  - M (médio): 2-8h, multiple files, may need investigation
+  - G (grande): > 8h, complex logic, new patterns, integration work
+  - Format: `- [ ] [P] T-NNN-REPO-XX: description (REQ-NNN)`
 - **Feature grande**: if the PRD has more than 15 behaviors/requirements or spans 4+ repos, /discovery should have flagged it already. If it arrived here approved, proceed without questioning. Just note in brief.md: "Feature com {N} requisitos — escopo aprovado pelo PO."
 
 #### links.md
@@ -202,6 +218,17 @@ Confirm you generated all **5 files** for this feature:
 
 If any file is missing, **create it now** before continuing.
 
+#### Optional: OpenAPI stub (if API endpoints exist)
+
+If contracts.md defines REST endpoints, generate a minimal OpenAPI 3.0 stub file at `specs/NNN-name/openapi.yaml` containing:
+- paths (from endpoint table: method + route)
+- request/response schemas (from contract types)
+- auth scheme (if authenticated endpoints: bearerAuth)
+
+This is a STUB — /dev may extend it during implementation. Mark as draft: `info.description: "Auto-generated from contracts.md — draft"`
+
+If the feature has no REST endpoints (e.g., worker-only feature), skip this step.
+
 
 
 Before generating the DD or closing the loop, run ALL checks below. Fix any failures, then generate the audit report.