@guilhermefsousa/open-spec-kit 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guilhermefsousa/open-spec-kit",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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/agents/spec-hub.agent.md

@@ -84,13 +84,16 @@ specs/NNN-nome/
   links.md                   ← PRs + link da feature page
   audit-report.md            ← resultado do self-review do /spec
   conformance-report.json    ← validação pós-implementação do /dev
+  conformance-history.log    ← histórico de validações (append por run)
+  openapi.yaml               ← stub OpenAPI 3.0 (opcional, se REST endpoints)
 ```
 
 ## Validation checklist
 
 - [ ] Brief máx 1 página
 - [ ] Todo cenário tem Given/When/Then
-- [ ] Cenários de falha cobertos
+- [ ] Cenários de falha cobertos (401, 403, input validation 400)
+- [ ] Cenários de NFR cobertos (se PRD tem Requisitos Não-Funcionais)
 - [ ] Tasks agrupadas por repo (per projects.yml)
 - [ ] Dependências explícitas
 - [ ] Cada task = 1 PR

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

@@ -24,7 +24,8 @@ applyTo: '**/*.md'
 
 1. Created: spec directory with brief + scenarios + contracts + tasks
 2. In progress: tasks are checked off, links.md tracks PRs
-3. Done: all tasks checked, spec directory stays (it IS the history)
+3. Post-merge sync: if implementation diverged intentionally from spec, /dev updates contracts.md and scenarios.md to match reality (Phase D.1.5)
+4. Done: all tasks checked, spec directory stays (it IS the history)
 
 Specs are NOT archived or moved. The spec directory with checked tasks IS the record.
 
@@ -39,6 +40,8 @@ Specs are NOT archived or moved. The spec directory with checked tasks IS the re
 | PR tracking | `specs/<spec>/links.md` |
 | Spec quality audit | `specs/<spec>/audit-report.md` |
 | Implementation conformance | `specs/<spec>/conformance-report.json` |
+| Conformance history | `specs/<spec>/conformance-history.log` |
+| OpenAPI stub (optional) | `specs/<spec>/openapi.yaml` |
 | Architecture overview | `docs/architecture.md` |
 | Architecture decisions | `docs/decisions/ADR-NNN.md` |
 | Lessons learned | `docs/lessons/NNN-title.md` |

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

@@ -6,7 +6,7 @@ applyTo: '**/*.md'
 
 # Rule: Artifact Ownership (RACI)
 
-Every artifact in this project has exactly **one Owner** (creates it) and at most **one Updater** (can modify it after creation). Other skills may **Read** or **Validate**, but never **Write**.
+Every artifact in this project has exactly **one Owner** (creates it) and one or more designated **Updaters** (can modify it after creation under specific conditions). Other skills may **Read** or **Validate**, but never **Write**.
 
 This rule exists to prevent the "duplicate responsibility" anti-pattern where multiple skills update the same artifact with no clear authority, causing drift and conflicts.
 
@@ -16,8 +16,8 @@ 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) |
-| DD (Design Document) | /spec (via `design-doc` agent, fallback: MCP direct) | /dev (via `design-doc` agent, fallback: MCP direct) | — | — |
+| Glossário | /setup | /discovery (exit gate), /dev (post-merge only) | /spec | /spec (read-only validate) |
+| DD (Design Document) | /spec (via `design-doc` agent) | /dev (post-merge, via `design-doc` agent) | — | — |
 | Domínio/Regras | /setup | /dev (post-merge only) | /discovery, /spec | — |
 | Domínio/Fluxos | /setup | /dev (post-merge only) | /discovery | — |
 | Domínio/Tabelas | /setup | — | /discovery | — |
@@ -27,25 +27,35 @@ This rule exists to prevent the "duplicate responsibility" anti-pattern where mu
 | Feature labels | each skill at its transition | — | all | — |
 | Arquivados/ | /setup | — | — | — |
 
+**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}".
+
+**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.
+
 ## Local Artifacts
 
 | 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 resolved decisions post-merge) | /spec, /dev | /spec (validates no blockers) |
 | `docs/lessons/` | /dev | /dev | all | — |
 | `docs/decisions/` | manual / spec-agent | — | all | — |
+| `docs/pending-confluence-updates.md` | any skill (on MCP failure) | any skill (on retry) | all | — |
 | `specs/NNN/brief.md` | /spec | — | /dev | — |
-| `specs/NNN/scenarios.md` | /spec | — | /dev | — |
-| `specs/NNN/contracts.md` | /spec | — | /dev | — |
+| `specs/NNN/scenarios.md` | /spec | /dev (post-merge sync D.1.5 — only if conformance report shows intentional divergence) | /dev | — |
+| `specs/NNN/contracts.md` | /spec | /dev (post-merge sync D.1.5 — only if conformance report shows intentional divergence) | /dev | — |
 | `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/openapi.yaml` | /spec (optional, if REST endpoints) | /dev (may extend) | — | — |
+| `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) | — | — |
+| `CHANGELOG.md` (impl repo) | /dev (Phase D.4.5) | /dev | all | — |
+
+**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
 
-1. **One Writer per artifact** — if two skills both write to the same artifact, one of them is wrong. The matrix above is the source of truth.
+1. **One Owner per artifact** — each artifact has exactly one Owner that creates it. Updaters are explicitly designated in the matrix above with conditions (e.g., "post-merge only"). If a skill writes to an artifact where it is not listed as Owner or Updater, it is wrong.
 
 2. **Validate ≠ Update** — /spec validates the Glossário (checks all terms are present) but does NOT add terms. If terms are missing, it stops and asks the dev to re-run /discovery.
 
@@ -111,7 +121,7 @@ The `docs/architecture.md` "Decisões em Aberto" table uses this schema:
 
 Status values: `aberta`, `resolvida — [decisão tomada]`
 
-Only /discovery updates this column (exit gate). /spec validates that no `aberta` decision blocks /dev.
+/discovery updates this column during its exit gate. /dev may also add resolved decisions post-merge (Phase D.4) when new decisions are discovered during implementation. /spec validates that no `aberta` decision blocks /dev.
 
 ## links.md PR Table Format
 

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

@@ -58,7 +58,7 @@ Read from `projects.yml` → `agents` section:
 
 | Role | Config key | If null or missing |
 |------|-----------|-------------------|
-| Security scan | `agents.security` | Skip scan, add note to MR: "Security scan manual necessario" |
+| Security scan | `agents.security` | Skip scan, add note to MR: "Security scan manual necessário" |
 | Code review | `agents.code_review` | Skip pre-review, notify dev |
 | Design document | `agents.design_doc` | Update DD directly no Confluence (read → append → update) |
 
@@ -75,12 +75,12 @@ Read from `projects.yml` → `agents` section:
    - Dependencies between groups
    - Parallelizable groups (marked `[P]`)
    - Execution order
-3. **Check if repos exist** — for each repo referenced in tasks.md:
+4. **Check if repos exist** — for each repo referenced in tasks.md:
    - Look up the repo in `projects.yml`
    - If `status: active` and `url` is filled → repo exists, skip
    - If `status: planned` and `url` is null → **create the repo** (see Phase A.1 below)
    - If the repo is NOT declared in projects.yml → stop and ask the dev
-4. Create GitLab/GitHub Issues (1 per task) via API or terminal:
+5. Create GitLab/GitHub Issues (1 per task) via API or terminal:
    - Title: `[NNN] task description`
    - Labels: `spec`, `NNN-feature-name`
    - Assign to the repo's issue board
@@ -256,6 +256,12 @@ The orchestrator extracts response type field names from contracts.md and asks t
 
 This artifact enables CI Guard (see below) and provides audit trail for compliance.
 
+Also append a summary line to `specs/NNN-name/conformance-history.log` (create if it doesn't exist):
+```
+{timestamp} | {result} | {matching}/{total} endpoints | {matching}/{total} fields
+```
+This preserves history across multiple /dev runs.
+
 C.4. **Run extension hooks** (if any)
 
 If the spec repo has a `hooks/pre-merge/` directory with executable scripts, run each one in alphabetical order. Each script receives two arguments: `<spec-dir>` and `<repo-dir>`.
@@ -315,6 +321,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 +353,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` with 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.
+
+Lessons template:
     ```
     ## O que aconteceu
     [description]
@@ -345,6 +368,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 \
@@ -387,6 +430,7 @@ E.3. Validate the API (orchestrator does via curl):
    - Health check (`GET /health` → 200)
    - Minimum flow: register → login → 1 authenticated CRUD operation
    - Verify CORS (front origin must be accepted)
+   - If the spec has NFR scenarios (performance targets): run a basic load smoke test against the critical endpoint (e.g., `hey -n 100 -c 10 {url}` or equivalent) and verify the p95 response time meets the target. If load testing tooling is not available, log: "NFR validation manual necessária — tooling de load test não disponível."
 
 E.4. Validate the frontend (orchestrator checks):
    - Build passes (stack agent executes the build)
@@ -534,6 +578,9 @@ BUNDLE_SIZE=$(du -sk "$2/dist/assets/" | cut -f1)
 
 ## Validation checklist
 
+- [ ] Audit-report.md read and evaluated (no ❌ items)
+- [ ] Repos auto-created if `status: planned` (Phase A.1)
+- [ ] Feature label changed to `em-dev` on Confluence
 - [ ] Correct coding agent selected per stack
 - [ ] VCS Issues created (1 per task)
 - [ ] Tests generated before implementation (TDD)
@@ -541,7 +588,7 @@ BUNDLE_SIZE=$(du -sk "$2/dist/assets/" | cut -f1)
 - [ ] All tests pass
 - [ ] **Commit GREEN** (`feat(NNN): all tests pass [GREEN]`) done after all tests pass
 - [ ] Conformance check passed (endpoints + response fields match contracts.md)
-- [ ] Conformance report saved (`specs/NNN/conformance-report.json`)
+- [ ] Conformance report saved (`specs/NNN/conformance-report.json`) + history appended to `conformance-history.log`
 - [ ] Extension hooks passed (if any in `hooks/pre-merge/`)
 - [ ] Security scan passed
 - [ ] MR created with spec references
@@ -549,6 +596,9 @@ BUNDLE_SIZE=$(du -sk "$2/dist/assets/" | cut -f1)
 - [ ] MR rejected loop handled (if applicable — fix, re-test, re-check conformance)
 - [ ] links.md updated with MR links
 - [ ] Living docs updated on Confluence (DD, Dominio, Glossario)
+- [ ] Spec synced with implementation if intentional divergences (Phase D.1.5)
+- [ ] Architecture.md updated with new decisions if discovered during implementation (Phase D.4)
+- [ ] CHANGELOG.md updated in main repo (Phase D.4.5)
 - [ ] Feature label → `done` on Confluence
 - [ ] Lessons saved if applicable
 - [ ] GChat notifications sent at each transition

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

@@ -47,9 +47,13 @@ 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?"
-7. Proceed with the chosen feature.
+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?"
+8. Proceed with the chosen feature.
 
 If argument WAS passed (e.g., `/discovery TFB-001`):
 - Locate the corresponding feature page and proceed normally.
@@ -69,7 +73,7 @@ Read these files FIRST:
 ### 1. Compile all information
 
 From Confluence (via MCP), read:
-- The feature page in `Features/` (demand extracted by /setup)
+- The feature page in `Features/` (demand extracted by /setup). Read the metadata table — especially the "Seções do PO" field, which tells you exactly which PO document sections are relevant for this feature. Use this to focus your gap analysis.
 - `Dominio/` — business rules, flows, reference tables, integrations
 - `Visao do Produto` — product scope and success metrics
 - Previous Q&A rounds on the feature page (if any)
@@ -178,9 +182,12 @@ 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".
 
+**Special rule — TECHNOLOGY**: this category can NEVER be marked as "Covered" without verifying: (1) all repos in projects.yml have a stack declared, (2) the declared stack supports all feature requirements (WebSocket, background jobs, full-text search, etc.), (3) the auth mechanism is defined. Absence of technology constraints does not mean the stack is fine — it means the constraint is implicit.
+
 For each category marked Partial or Missing, generate a candidate question.
 
 **Prioritize:** Impact (High/Medium/Low) x Blocks spec? (Yes/No).
@@ -272,7 +279,7 @@ After documenting technical decisions, **return to step 6** and re-evaluate: if
 
 **IF no gaps remain (or all answered):**
 
-Generate the PRD on the feature page in Confluence:
+Generate the PRD on the feature page in Confluence. **IMPORTANT: APPEND the PRD section BELOW the existing metadata table and Escopo section created by /setup — do NOT replace or remove them.**
 
 ```
 ## PRD
@@ -297,6 +304,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 dependências críticas**: 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 crítico 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."
@@ -356,7 +381,7 @@ In the local spec repo:
 | # | Decisao | Impacto | Bloqueia | Status |
 |---|---------|---------|----------|--------|
 | 1 | Worker separado ou parte da API? | Alto — define repos e CI | /spec | aberta |
-| 2 | Valores do enum de Status | Medio — afeta model e validacao | /dev | aberta |
+| 2 | Valores do enum de Status | Médio — afeta model e validação | /dev | aberta |
 ```
 
 Status values: `aberta`, `resolvida — [decisão tomada]`. The /discovery updates this column when resolving decisions (exit gate).
@@ -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, OAuth, roles, permissões, autorização, autenticação, LGPD, rate limit) → verify a feature covers auth implementation. If they mention automation keywords (automático, SLA, prazo, timeout, scheduled, job, cron, fechamento automático) → verify a feature covers it. If missing → create the dedicated feature. Use the same trigger keywords from Phase B.
 
 ### 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,15 +479,21 @@ 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
 - [ ] projects.yml filled with all detected repos (status: planned, not commented)
 - [ ] docs/architecture.md draft with Mermaid diagrams (flowchart, erDiagram) and open decisions table
+- [ ] `docs/lessons/` and `docs/decisions/` directories created
 
 ### Quality gates
 - [ ] Self-review performed (re-read PRD vs. output)
+- [ ] Figma context read and incorporated (if configured)
 - [ ] No business context was invented
 - [ ] All ambiguities marked "A CONFIRMAR" with explanation
 - [ ] Unreadable attachments listed as "NAO PROCESSADO"
 - [ ] Demand label changed to `processado` (verified)
+- [ ] GChat notification sent (if webhook configured)

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
@@ -63,7 +70,7 @@ Read these files FIRST:
 ### 1. Read PRD from Confluence
 
 From Confluence (via MCP), read the approved PRD on the feature page.
-Extract: requirements, decisions, scope, out of scope, assumptions.
+Extract: requirements, decisions, scope, out of scope, assumptions, and NFRs (if the PRD has a "Requisitos Não-Funcionais" section).
 
 ### 2. Identify features in the PRD
 
@@ -123,11 +130,16 @@ 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)
   - Invalid page values (page ≤ 0, pageSize > max) — expected: 400 or clamped to defaults
+- **NFR scenarios (if PRD has "Requisitos Não-Funcionais")**: for each measurable NFR target (e.g., "GET /bills < 200ms p95"), create at least one CT-NNN-XX scenario with a concrete Given/When/Then. Example: `Given 50 concurrent users, When GET /api/v1/bills with filters, Then p95 response time < 200ms`. If the NFR is not measurable in a test (e.g., "99.9% uptime"), include it in brief.md under "Restrições" instead. Add NFR-related tasks to tasks.md (e.g., "add response time middleware", "configure rate limiting").
 - **No unresolved markers (MANDATORY)**: specs MUST NOT contain any of these markers anywhere — including inside code blocks and code examples:
   `MOCKADO`, `TODO`, `A CONFIRMAR`, `TBD`, `FIXME`, `PLACEHOLDER`, `TKTK`
   If any assumption is not validated, go back to /discovery to resolve it.
@@ -154,9 +166,9 @@ Numbering is sequential: find the highest existing number in `specs/` and increm
    | UpdatedAt | DateTime | Sim | Data de última atualização |
    ```
 5. **Error codes**: every error code specific to this feature, as constants/enum
-5. **Validation rules** (as a top-level `##` section, NOT nested inside a per-stack section): every field validation (required, format, max length, valid values)
-6. **Response examples**: at least one success example and one error example per endpoint, with HTTP status code
-7. **Shared types**: if this feature DEFINES types that other features will reuse (ex: ErrorResponse, PaginatedResponse), mark them in a `## Tipos compartilhados` section. If this feature USES types from another feature, REFERENCE them ("Ver contracts.md da feature NNN") — do NOT copy the full definition. If extending a type, define only the extension.
+6. **Validation rules** (as a top-level `##` section, NOT nested inside a per-stack section): every field validation (required, format, max length, valid values)
+7. **Response examples**: at least one success example and one error example per endpoint, with HTTP status code
+8. **Shared types**: if this feature DEFINES types that other features will reuse (ex: ErrorResponse, PaginatedResponse), mark them in a `## Tipos compartilhados` section. If this feature USES types from another feature, REFERENCE them ("Ver contracts.md da feature NNN") — do NOT copy the full definition. If extending a type, define only the extension.
 
 Additional structural rule: **editável entities MUST have both `CriadoEm` and `AtualizadoEm` fields**. If an entity can be modified via PUT/PATCH, it needs `AtualizadoEm` for auditability.
 
@@ -175,6 +187,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,7 +219,18 @@ 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.
+
+### 4. Self-review and audit
 
 Before generating the DD or closing the loop, run ALL checks below. Fix any failures, then generate the audit report.
 
@@ -215,9 +243,11 @@ Before generating the DD or closing the loop, run ALL checks below. Fix any fail
    - Response type defined
    - At least one success example and one error example
    - Error codes cover all failure scenarios
-4. **Auth consistency**: if feature has authenticated endpoints, confirm a CT for "sem token → 401" exists
-5. **Pagination consistency**: if any endpoint returns lists, confirm pagination scenarios exist
-6. **Cross-feature types**: if contracts.md defines a type that already exists in another feature's contracts.md, replace with a reference
+4. **Auth consistency**: if feature has authenticated endpoints, confirm CTs exist for: "sem token → 401", "role errado → 403"
+5. **Input validation**: for each endpoint accepting user input, confirm at least one CT for "input malformado → 400" exists
+6. **Pagination consistency**: if any endpoint returns lists, confirm pagination scenarios exist
+7. **Cross-feature types**: if contracts.md defines a type that already exists in another feature's contracts.md, replace with a reference
+8. **NFR coverage**: if the PRD has a "Requisitos Não-Funcionais" section, confirm each measurable NFR has at least one CT scenario. Non-measurable NFRs should appear in brief.md "Restrições"
 
 If ANY check fails, fix the spec files BEFORE proceeding. Report what was fixed.
 
@@ -231,9 +261,11 @@ If ANY check fails, fix the spec files BEFORE proceeding. Report what was fixed.
 | 1 | REQ → Scenarios | ✅ 12/12 | All REQs have ≥1 scenario |
 | 2 | RN → Scenarios | ✅ 8/8 | All RNs have ≥1 scenario |
 | 3 | Endpoints → Contracts | ✅ 6/6 | All endpoints have request/response/errors |
-| 4 | Auth (401 scenario) | ✅ 1/1 | CT-NNN-XX covers |
-| 5 | Pagination scenarios | ✅ 2/2 | CT-NNN-XX, CT-NNN-YY |
-| 6 | Cross-feature types | ✅ OK | References only, no redefinitions |
+| 4 | Auth (401 + 403 scenarios) | ✅ 2/2 | CT-NNN-XX (401), CT-NNN-YY (403) |
+| 5 | Input validation (400 scenarios) | ✅ 3/3 | One per input endpoint |
+| 6 | Pagination scenarios | ✅ 2/2 | CT-NNN-XX, CT-NNN-YY |
+| 7 | Cross-feature types | ✅ OK | References only, no redefinitions |
+| 8 | NFR coverage | ✅ 2/2 | Each measurable NFR has CT scenario |
 
 **Generated**: YYYY-MM-DD
 **Fixed during review**: (list what was added/corrected, or "none")
@@ -345,8 +377,10 @@ If a Confluence operation fails mid-flow (updating DD, changing labels, reading
 - [ ] Every scenario has Given/When/Then
 - [ ] Happy path covered for every endpoint/behavior
 - [ ] Failure scenarios covered (validation errors, not found, ownership)
-- [ ] Auth scenario (401 without token) present if feature has authenticated endpoints
+- [ ] Auth scenarios (401 without token + 403 wrong role) present if feature has authenticated endpoints
+- [ ] Input validation scenarios (malformed input → 400) present for each endpoint accepting user input
 - [ ] Pagination scenarios present if any endpoint returns paginated lists
+- [ ] NFR scenarios present if PRD has "Requisitos Não-Funcionais" section (each measurable target has a CT)
 - [ ] Edge cases covered (boundary values, empty results, duplicates)
 
 ### Contracts quality
@@ -362,9 +396,17 @@ If a Confluence operation fails mid-flow (updating DD, changing labels, reading
 - [ ] Each task = 1 PR
 - [ ] links.md has correct Confluence page link
 
+### Artifacts
+- [ ] `audit-report.md` generated with all checks passing
+- [ ] `openapi.yaml` generated (if feature has REST endpoints)
+- [ ] Figma freshness check performed (if configured)
+
 ### Integration
 - [ ] DD updated on Confluence
+- [ ] Glossary validated on Confluence (all PRD terms present)
+- [ ] All open decisions in architecture.md resolved (no blockers for /dev)
 - [ ] Feature label updated on Confluence → `em-spec`
+- [ ] All spec files committed and pushed
 - [ ] GChat notification sent
 - [ ] Lessons from docs/lessons/ applied