@guilhermefsousa/open-spec-kit 0.0.10 → 0.0.11

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

@@ -1,9 +1,421 @@
 ---
-name: specifying-features
-description: "Criar especificacoes de features com brief, cenarios (Given/When/Then), contratos e tasks divididas por repo."
+name: osk-spec
+description: "Breaks an approved PRD into N feature specifications with brief, scenarios (Given/When/Then), contracts, and repo-partitioned tasks. Generates/updates Design Document on Confluence."
+metadata:
+  works_on: [copilot, antigravity, claude]
+argument-hint: "[feature description or Confluence PRD link]"
 ---
 
-# Specifying Features (Copilot)
+# Specifying Features
 
-> Source of truth: `.agents/skills/specifying-features/SKILL.md`
-> Leia o SKILL.md completo em `.agents/skills/specifying-features/` e siga todas as instrucoes de la.
+## Objective
+
+Take an approved PRD and produce minimal, unambiguous feature specifications that enable parallel implementation across multiple repos. Also generate or update the Design Document on Confluence.
+
+## Before you start
+
+### Validate prerequisites
+
+1. Read `projects.yml` — if empty, **stop** with message: "/osk-init não foi executado."
+2. Read `docs/architecture.md` — if file does not exist: **stop** — "/osk-init não gerou architecture.md. Execute /osk-init primeiro."
+3. In Confluence (via MCP — same as /osk-init), find the feature page and check its labels:
+   - If label `prd-aprovado` is NOT present: **stop** — "PRD não aprovado. A feature precisa ter label 'prd-aprovado' antes de rodar /osk-spec. Execute /osk-discover primeiro."
+   - If label `prd-rejeitado` is present AND its addition date is MORE RECENT than `prd-aprovado` (check via MCP — page metadata or label timestamps): **stop** — "PRD foi rejeitado após aprovação. Execute /osk-discover para resolver antes de prosseguir."
+   - If `prd-aprovado` IS present and no subsequent `prd-rejeitado`: proceed
+4. Read the feature page content — verify it has a "## PRD" section with "### Requisitos aceitos". If not: **stop** — "PRD não encontrado na página da feature."
+5. **Idempotency check**: if `specs/` already contains a directory for this feature (matching name or Confluence page ID in links.md):
+   - If all 5 files exist and are complete: **stop** — "Spec já existe em specs/NNN-name/. Para re-gerar, delete o diretório primeiro ou passe --force."
+   - If some files are missing or incomplete: **warn** and continue — will overwrite/complete the existing spec.
+
+### Read context
+
+Read these files FIRST:
+
+1. `projects.yml` — repos, stack, dependencies
+2. `docs/architecture.md` — system structure
+3. ALL files in `docs/lessons/` — past mistakes to avoid
+4. ALL files in `docs/decisions/` — technical choices
+5. ALL existing `specs/` — read `contracts.md` of every previous spec to know which entities, endpoints, types, and error formats already exist. This is the **baseline** for the new spec.
+
+**Evolution rule**: when the project already has specs, the new spec MUST:
+- **Reference** existing types with "Ver contracts.md da feature NNN" — never redefine
+- **Extend** existing entities by documenting only the NEW fields (e.g., "Adiciona campo `saldo` à entidade `Conta` definida em 002")
+- **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 /osk-discover captured in the PRD
+3. If significant changes detected (new screens, removed fields) → WARN: "Design no Figma mudou desde o /osk-discover. Diferenças: {list}. Continuar com o design atual ou re-executar /osk-discover?"
+4. If no changes or Figma unavailable → proceed silently
+
+## Inputs
+
+- Approved PRD on Confluence (label `prd-aprovado`) — read via MCP
+- Feature context from Discovery phase (questions answered, decisions taken)
+
+## Artifacts produced
+
+| File | Purpose | Max size |
+|------|---------|----------|
+| `brief.md` | Problem, solution, out of scope | 1 page |
+| `scenarios.md` | Given/When/Then for every behavior | As many as needed |
+| `contracts.md` | Event schemas, entities, enums, business rules | As many as needed |
+| `tasks.md` | Checklist grouped by repo | As many as needed |
+| `links.md` | PRs, boards, Confluence feature page link | Updated during implementation |
+
+## Flow
+
+### 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, and NFRs (if the PRD has a "Requisitos Não-Funcionais" section).
+
+### 2. Identify features in the PRD
+
+A single PRD may contain N features. Each feature becomes a spec directory.
+Numbering is sequential: find the highest existing number in `specs/` and increment.
+
+### 3. Write specs (per feature)
+
+> **⚠️ MANDATORY: generate ALL 5 files per feature — `brief.md`, `scenarios.md`, `contracts.md`, `tasks.md`, `links.md`.**
+> `/osk-build` rejects specs with missing files (checks in Phase A). `open-spec-kit validate` fails on Rule-01 if any of the 5 are absent.
+> `links.md` is frequently forgotten because it's the smallest — it is **mandatory** and `/osk-build` depends on it to track post-merge PRs.
+
+**MANDATORY LANGUAGE for ALL generated files**: Brazilian Portuguese (pt-BR) with correct accents. This includes code comments, Gherkin descriptions, and free text. Examples: "não" NOT "nao", "autenticação" NOT "autenticacao", "código" NOT "codigo", "é" NOT "e", "já" NOT "ja", "número" NOT "numero", "válido" NOT "valido", "obrigatório" NOT "obrigatorio", "mínimo" NOT "minimo". Technical terms stay in English (endpoint, token, hash, bcrypt, JWT).
+
+#### brief.md
+- Start with the PROBLEM, not the solution
+- One page maximum
+- Include "Out of Scope" section
+- Reference contracts.md for event/API details
+- Include "Appetite" section — timebox (S/M/L or days/weeks) with justification for the investment level
+
+#### scenarios.md
+- Every behavior gets a Given/When/Then scenario
+- Include happy path AND failure paths
+- Include edge cases (duplicates, missing fields, timeouts, boundary values)
+- Each scenario maps to at least one test
+- Use REQ-NNN identifiers (from PRD requirements). **Format: 3-digit zero-padded** — REQ-001, REQ-011, NOT REQ-1 or REQ-11. The `open-spec-kit validate` command enforces this format.
+- **CT ID format (MANDATORY)**: every scenario heading MUST use the format:
+  `### CT-NNN-XX: description (REQ-NNN)`
+  Where NNN = feature spec number, XX = sequential within that REQ.
+
+  Example for spec 001:
+  ```
+  ## REQ-001: Idempotent shipment ingestion
+
+  ### CT-001-01: New shipment arrives (REQ-001)
+  - **Given:** no record exists with sourceId="SHP-001"
+  - **When:** ShipmentPaymentCalculated event arrives
+  - **Then:** a new record is created with status=Pending
+
+  ### CT-001-02: Duplicate of unbilled shipment (REQ-001)
+  - **Given:** record exists with sourceId="SHP-001" and status=Pending
+  - **When:** event arrives with different totalAmount
+  - **Then:** record is updated with new totalAmount
+
+  ## REQ-002: Payload validation
+
+  ### CT-002-01: Required field missing (REQ-002)
+  - **Given:** event arrives without tripId
+  - **When:** consumer processes
+  - **Then:** event sent to dead-letter queue
+  ```
+
+  The `open-spec-kit validate` command enforces this format. Specs without CT IDs will fail validation.
+- **Bidirectional traceability (MANDATORY)**:
+  - Every scenario MUST reference at least one REQ-NNN
+  - 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 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 /osk-discover to resolve it.
+  The `open-spec-kit validate` command will ERROR on any unresolved marker.
+- **Cross-spec dependencies are NOT REQs**: if a feature uses an entity or type defined in another spec, do NOT create a REQ for it. Instead, use a `> Dependency:` block in the brief:
+  `> Dependency: Uses entity Tutor defined in specs/002 (see contracts.md of feature 002)`
+  REQs are testable requirements — a reference to another spec is not testable.
+- Descriptions in Gherkin MUST have accents (ex: "não revela", "usuário autenticado", "credenciais inválidas")
+
+#### contracts.md
+
+**Mandatory sections** (every contracts.md MUST have ALL of these):
+
+1. **Endpoint table**: Method | Route | Description | Authenticated
+2. **Contracts per stack**: if `projects.yml` lists repos with different stacks (ex: dotnet + nodejs), contracts MUST include BOTH. Typically: C# (backend) AND TypeScript (frontend). One language is NOT sufficient. Use separate sections with headings: `## Contratos C# (.NET API)` and `## Contratos TypeScript (React Frontend)` (or equivalent for the project's stack).
+3. **Full endpoint paths in ALL contract examples**: every code example (backend AND frontend, any stack) MUST use the COMPLETE route path exactly as defined in the endpoint table (e.g., `/api/auth/login`, NOT `/auth/login`). This eliminates ambiguity about path prefixes and ensures consistency between backend route definitions and frontend API calls. The endpoint table is the single source of truth for paths — every code example must match it literally.
+4. **Entities/models**: every new entity introduced by this feature MUST have its own heading in the format `## Entidade: EntityName` followed by a table with columns `Campo | Tipo | Obrigatório | Descrição` (or English equivalents `Field | Type | Required | Description`). This heading format is required by the validator. Example:
+   ```
+   ## Entidade: User
+   | Campo | Tipo | Obrigatório | Descrição |
+   |-------|------|-------------|-----------|
+   | Id | Guid | Sim | Identificador único |
+   | CreatedAt | DateTime | Sim | Data de criação |
+   | UpdatedAt | DateTime | Sim | Data de última atualização |
+   ```
+5. **Error codes**: every error code specific to this feature, as constants/enum
+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.
+
+Additional rules:
+- Define event schemas, entities, enums
+- Include field types and required/optional
+- Include business rules (idempotency, validation)
+- Code comments MUST have accents (ex: `// Validação padrão`, NOT `// Validacao padrao`)
+
+#### tasks.md
+- **IMPORTANT**: use the EXACT repo name as declared in `projects.yml` as heading `## repo-name`. E.g., `## todo-app-api`, NOT `## Backend`. The `open-spec-kit validate` command checks that headings match repos from projects.yml (Rule 21).
+- Group tasks by repo (from `projects.yml`) — each `## repo` heading is one **execution unit** (1 agent or 1 dev)
+- **Validate repos**: every repo referenced in tasks.md MUST exist in `projects.yml`. If a task references a repo not in projects.yml, **add it** with `status: planned` and `url: null`. The /osk-build will auto-create it in Phase A.1. Log: "Repo '{name}' adicionado ao projects.yml com status: planned."
+- Within each `## repo` block, list tasks in execution order — the list order IS the dependency order (no need to annotate dependencies between tasks of the same block)
+- **Parallelism between blocks**: if a repo block depends ONLY on contracts (already defined in contracts.md) and NOT on the implementation of another block, mark with `[P]` — it can start in parallel. Example: `### todo-front [P] — can start after contracts are defined`
+- **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, /osk-discover 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
+- Link to Confluence feature page
+- Empty PR table with this schema (filled by /osk-build during implementation):
+
+```markdown
+## PRs
+
+| Repo | Branch | MR/PR | Status |
+|------|--------|-------|--------|
+```
+
+Status values: `open`, `em-review`, `merged`, `closed`. The /osk-build uses the Status column to detect merged MRs for post-merge Phase D.
+
+#### ✅ Artifact checklist (MANDATORY — verify before proceeding to self-review)
+
+Confirm you generated all **5 files** for this feature:
+
+- [ ] `brief.md` — problem, solution, out of scope
+- [ ] `scenarios.md` — Given/When/Then per behavior
+- [ ] `contracts.md` — endpoints, entities, enums, rules
+- [ ] `tasks.md` — checklist per repo (use EXACT repo name from projects.yml as heading `##`)
+- [ ] `links.md` — Confluence URL + PR table ← **frequently forgotten; /osk-build depends on this file**
+
+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 — /osk-build 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.
+
+**Checks:**
+
+1. **Traceability matrix**: for each REQ-NNN in the PRD, confirm at least one CT-XX exists in scenarios.md. For each CT-XX, confirm it references a valid REQ-NNN. List any orphans and fix them.
+2. **RN coverage**: for each RN listed as relevant in brief.md, confirm at least one CT-XX references it. If a relevant RN has no scenario, add one.
+3. **Contracts completeness**: for each endpoint in the endpoint table, confirm:
+   - Request type defined (or N/A for GET/DELETE without body)
+   - 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 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.
+
+**Generate audit report**: after completing all checks (and fixing any issues), save the results to `specs/NNN-name/audit-report.md`:
+
+```markdown
+# Audit Report — NNN: Feature Name
+
+| # | Check | Result | Details |
+|---|-------|--------|---------|
+| 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 + 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")
+```
+
+Result values:
+- ✅ = all items pass
+- ⚠️ = partially passing, documented exceptions (include reason)
+- ❌ = failing — MUST be fixed before proceeding (this state should not appear in the final report since all failures are fixed first)
+
+The /osk-build reads this report in Phase A before starting implementation. If it contains ⚠️ items, the dev evaluates whether to proceed or request spec changes.
+
+### 5. Validate Glossary on Confluence (read-only)
+
+> **Ownership rule**: the Glossário is updated ONLY by /osk-discover (exit gate). The /osk-spec only VALIDATES.
+
+Check if the /osk-discover phase identified new terms (see "GLOSSÁRIO" notes on the feature page or in the PRD). If yes:
+1. Read the current Glossário on Confluence (in storage format)
+2. Verify that ALL new terms listed in the PRD section "GLOSSÁRIO: termos novos" are present in the Glossário page
+3. **If any term is MISSING**: **stop** — "Glossário incompleto. O /osk-discover deveria ter adicionado os termos '{missing}' no exit gate. Re-execute /osk-discover para corrigir."
+4. **If all terms are present**: proceed (no update needed)
+
+Do NOT add terms directly — this is /osk-discover's responsibility.
+
+### 6. Generate/update Design Document on Confluence
+
+> **Ownership rule**: the DD is owned by the `design-doc` agent (Labs). The /osk-spec delegates creation/update to it. Only uses MCP directly as a fallback.
+
+Read `projects.yml` → `agents.design_doc`. If configured (not null), use that agent to generate or update the DD on Confluence with:
+- Updated architecture (if feature adds components)
+- New data flows
+- Security considerations
+- Contract definitions
+- Rollout strategy
+
+**Diagram format**: all architecture and data flow diagrams MUST use **Mermaid** blocks. Use `flowchart` for data flows, `sequenceDiagram` for API interactions, `C4Context` for high-level architecture. Never use ASCII art. Example C4:
+  ```mermaid
+  C4Context
+      Person(user, "Usuário")
+      System(api, "API Gateway")
+      System_Ext(ext, "Serviço Externo")
+      Rel(user, api, "Usa")
+      Rel(api, ext, "Consulta")
+  ```
+
+**Fallback**: if `design-doc` agent is not available, update the DD directly no Confluence:
+1. Read the DD page in storage format
+2. Add a new section for this feature with: components, endpoints, data model changes. MUST include Mermaid diagrams for any new data flows or architecture changes.
+3. Update the page (preserving ALL existing content — NEVER use placeholders)
+
+### 7. Close the loop
+
+- Change feature label on Confluence → `em-spec`
+- Notify Google Chat (if `GCHAT_WEBHOOK_URL` is not set, the script skips silently):
+
+      ./scripts/notify-gchat.sh --card \
+        --title "📐 Specs prontas pra review" \
+        --subtitle "{project_name}" \
+        --body "<b>Feature:</b> {feature_name}
+
+      📄 <b>Artefatos gerados:</b>
+      • brief.md — problema e solução
+      • scenarios.md — {scenario_count} cenários BDD
+      • contracts.md — contratos por stack (conforme projects.yml)
+      • tasks.md — {task_count} tasks por repo
+
+      📊 <b>Cobertura:</b> {req_count} REQs → {scenario_count} cenários" \
+        --next "Review técnico antes de iniciar /osk-build" \
+        --button-text "Ver spec no Confluence" \
+        --button-url "{feature_page_url}"
+
+  Replace `{}` placeholders with actual values. Notifications always in pt-BR.
+
+## MCP failure recovery
+
+If a Confluence operation fails mid-flow (updating DD, changing labels, reading Glossary):
+1. Log which operations succeeded and which failed
+2. Save pending operations to `docs/pending-confluence-updates.md` with: target page, content to add/update, operation type, date
+3. Report to dev: "Confluence indisponível — {N} operações pendentes salvas em docs/pending-confluence-updates.md."
+4. On re-execution, check if `docs/pending-confluence-updates.md` exists and attempt to apply pending operations FIRST before proceeding with new work. Remove applied entries from the file.
+
+## Agents used
+
+- Agent configured in `projects.yml` → `agents.design_doc` — to generate/update Design Document on Confluence
+
+## Rules
+
+1. Read existing context before creating anything
+2. Never invent business context — ask the developer
+3. Brief max 1 page
+4. Scenarios use Given/When/Then
+5. Tasks grouped by repo (see `projects.yml`)
+6. Each task = 1 PR
+7. **Language**: ALL generated content — Confluence pages AND local files — MUST be in **Brazilian Portuguese (pt-BR) with correct accents** (e.g., "não" NOT "nao", "autenticação" NOT "autenticacao", "código" NOT "codigo"). Technical terms stay in English. Code comments MUST also have accents (e.g., `// Validação padrão` NOT `// Validacao padrao`).
+8. Apply lessons from `docs/lessons/`
+9. Design Document (DD) is ONE document per project, updated per feature
+10. links.md must link to the Confluence feature page
+11. **Cross-platform scripts**: when running `./scripts/notify-gchat.*`, detect the OS. On Windows use `powershell -ExecutionPolicy Bypass -File ./scripts/notify-gchat.ps1`, on Linux/macOS use `bash ./scripts/notify-gchat.sh`. Parameters are the same for both.
+
+## Validation checklist
+
+### Traceability (MUST pass — do not ship without these)
+- [ ] Every scenario references at least one REQ-NNN
+- [ ] Every REQ-NNN from the PRD has at least one scenario
+- [ ] Every RN referenced in scenarios exists in Domínio/Regras on Confluence
+- [ ] No RN relevant to this feature was left unreferenced
+
+### Scenarios quality
+- [ ] Every scenario has Given/When/Then
+- [ ] Happy path covered for every endpoint/behavior
+- [ ] Failure scenarios covered (validation errors, not found, ownership)
+- [ ] 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
+- [ ] contracts.md has ALL mandatory sections (endpoint table, per-stack contracts, entities, error codes, validation rules, examples, shared types)
+- [ ] Contracts defined for EVERY stack in projects.yml (ex: C# AND TypeScript)
+- [ ] Shared types referenced, not redefined
+
+### Structure
+- [ ] PRD was read from Confluence
+- [ ] Brief is 1 page or less, starts with the problem
+- [ ] Tasks grouped by repo (per projects.yml)
+- [ ] Dependencies between tasks explicit
+- [ ] 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 /osk-build)
+- [ ] Feature label updated on Confluence → `em-spec`
+- [ ] All spec files committed and pushed
+- [ ] GChat notification sent
+- [ ] Lessons from docs/lessons/ applied
+
+## Exit gate (BLOCKING — cannot close the loop without these)
+
+The /osk-spec CANNOT be considered done until ALL of the following are true. If any item fails, fix it before moving to /osk-build.
+
+1. **Design Document exists and is updated on Confluence** — the DD page MUST exist under the project root. If it doesn't exist, create it. If it exists, add/update the section for this feature. NEVER skip this step. Verify by reading the DD page after updating.
+2. **Glossary validated** — if any feature PRD has a "GLOSSÁRIO: termos novos" section, ALL listed terms MUST be present in the Glossário page. Read the Glossário page and verify. If any term is MISSING: **stop** — "Glossário incompleto. Re-execute /osk-discover para adicionar os termos faltantes." The /osk-spec does NOT add terms — it only validates that /osk-discover did its job.
+3. **All decisions resolved** — read `docs/architecture.md` "Decisões em Aberto" section. If ANY decision is still open that blocks /osk-build, the /osk-spec CANNOT close. Technical decisions can be resolved by the dev team. Business decisions must go back to the PO. If an open decision needs resolution, go back to /osk-discover — the /osk-spec does not resolve decisions, only validates.
+4. **Self-review completed** — the traceability matrix (REQ → CT, CT → REQ) MUST be verified. Report what was checked and any fixes applied. Do NOT skip silently.
+5. **Commit and push** — all spec files MUST be committed and pushed to the spec repo before closing. Verify with `git status` that working directory is clean.