sinapse-ai 1.15.0 → 1.16.0

package/.sinapse-ai/data/entity-registry.yaml

@@ -1,7 +1,7 @@
 metadata:
   version: 1.0.0
-  lastUpdated: '2026-06-24T13:49:06.535Z'
-  entityCount: 792
+  lastUpdated: '2026-06-24T15:49:40.486Z'
+  entityCount: 794
   checksumAlgorithm: sha256
   resolutionRate: 100
 entities:
@@ -5625,6 +5625,32 @@ entities:
         extensionPoints: []
       checksum: sha256:702907ff987ef8db70bc7dba93aadcf40ba9d080321f8305dad7f9e2de10d1b2
       lastVerified: '2026-06-15T00:26:26.297Z'
+    spec-analyze:
+      path: .sinapse-ai/development/tasks/spec-analyze.md
+      layer: L2
+      type: task
+      purpose: Provar, antes de gastar geração de código, que cada requisito virou task e que nada contradiz a
+      keywords:
+        - spec
+        - analyze
+        - 'pipeline:'
+        - cross-consistency
+      usedBy:
+        - spec-pipeline
+      dependencies:
+        - architect
+      externalDeps: []
+      plannedDeps:
+        - spec
+        - constitution
+        - tasks
+      lifecycle: production
+      adaptability:
+        score: 0.8
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:5a73974cb88ca58274f907416839e8c864a3e35cf832668d3b2c582de3f6b26a
+      lastVerified: '2026-06-24T15:49:40.276Z'
     spec-assess-complexity:
       path: .sinapse-ai/development/tasks/spec-assess-complexity.md
       layer: L2
@@ -5651,6 +5677,29 @@ entities:
         extensionPoints: []
       checksum: sha256:7ef9f00dad98113dcf6c273e0d56333aece4fa892c91fff8935d3c3c552748ae
       lastVerified: '2026-06-15T00:26:26.298Z'
+    spec-clarify:
+      path: .sinapse-ai/development/tasks/spec-clarify.md
+      layer: L2
+      type: task
+      purpose: Desambiguar a especificação ANTES do QA gate e do plano. Roda DEPOIS de `write` (spec escrita)
+      keywords:
+        - spec
+        - clarify
+        - 'pipeline:'
+        - specification
+      usedBy:
+        - spec-pipeline
+      dependencies: []
+      externalDeps: []
+      plannedDeps:
+        - spec
+      lifecycle: production
+      adaptability:
+        score: 0.8
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:e4eee7ea80f146a697433462287aaff138536b148705337f2f32d66d2a83db5c
+      lastVerified: '2026-06-24T15:49:40.277Z'
     spec-critique:
       path: .sinapse-ai/development/tasks/spec-critique.md
       layer: L2
@@ -7418,8 +7467,8 @@ entities:
         score: 0.5
         constraints: []
         extensionPoints: []
-      checksum: sha256:03a71c8a3758864c3d27e4f0865734d986f4259f64af477d9fa4244f8972c7eb
-      lastVerified: '2026-06-15T00:26:26.326Z'
+      checksum: sha256:58207c62ca73c18d9584232bc62ec43ee5f11dc4337d231eee5bf2cc87d15b78
+      lastVerified: '2026-06-24T15:32:36.159Z'
     state-persistence-tmpl:
       path: .sinapse-ai/product/templates/state-persistence-tmpl.yaml
       layer: L2
@@ -13655,6 +13704,7 @@ entities:
         - plan-create-context
         - plan-create-implementation
         - qa-review-build
+        - spec-analyze
         - spec-assess-complexity
         - spec-critique
         - spec-gather-requirements
@@ -15074,7 +15124,9 @@ entities:
         - spec-assess-complexity
         - spec-research-dependencies
         - spec-write-spec
+        - spec-clarify
         - spec-critique
+        - spec-analyze
         - architect
         - analyst
       externalDeps: []
@@ -15086,8 +15138,8 @@ entities:
         score: 0.4
         constraints: []
         extensionPoints: []
-      checksum: sha256:890753d02dd6469441fe82a5eba0ecf48a3ac7969cfda3cd888c94cb74695c39
-      lastVerified: '2026-06-15T00:26:26.489Z'
+      checksum: sha256:d0da3844cdf7e71c59a13b22e6c715b23a0ae55337aaa6dfc7248de99bdc6ff4
+      lastVerified: '2026-06-24T15:32:36.251Z'
     story-development-cycle:
       path: .sinapse-ai/development/workflows/story-development-cycle.yaml
       layer: L2

package/.sinapse-ai/development/tasks/spec-analyze.md

@@ -0,0 +1,460 @@
+# Spec Pipeline: Analyze Cross-Consistency
+
+> **Phase:** 7 - Analyze (final, READ-ONLY)
+> **Owner Agent:** @quality-gate
+> **Pipeline:** spec-pipeline
+
+---
+
+## Purpose
+
+Provar, antes de gastar geração de código, que cada requisito virou task e que nada contradiz a
+constituição do projeto. Roda DEPOIS de `plan` (fase final do pipeline) e ANTES do handoff para
+implementação. É um gate **READ-ONLY**: não modifica nenhum arquivo — apenas lê spec ↔ plan ↔ tasks
+↔ constitution, roda 6 passes de detecção e emite uma matriz requisito→task com lacunas e
+inconsistências classificadas por severidade. Qualquer conflito constitucional é automaticamente
+CRITICAL e bloqueia a implementação.
+
+---
+
+## autoClaude
+
+```yaml
+autoClaude:
+  version: '3.0'
+  pipelinePhase: spec-analyze
+
+  elicit: false
+  deterministic: true # Same artifacts = same findings
+  composable: true
+
+  readOnly: true # Contract: never mutate any file
+  selfCritique:
+    required: false
+
+  inputs:
+    - name: storyId
+      type: string
+      required: true
+
+    - name: spec
+      type: file
+      path: docs/stories/{storyId}/spec/spec.md
+      required: true
+
+    - name: plan
+      type: file
+      path: docs/stories/{storyId}/spec/plan.json
+      required: true
+
+    - name: tasks
+      type: file
+      path: docs/stories/{storyId}/spec/tasks.md
+      required: false
+
+    - name: constitution
+      type: file
+      path: .sinapse-ai/constitution.md
+      required: true
+
+  outputs:
+    - name: analyze-report.json
+      type: file
+      path: docs/stories/{storyId}/spec/analyze-report.json
+      schema: analyze-report-schema
+
+  verification:
+    type: gate
+    blocking: true
+    verdict_field: gate
+
+  contextRequirements:
+    projectContext: true
+    filesContext: true
+    implementationPlan: true
+    spec: true
+```
+
+---
+
+## Read-Only Contract
+
+```yaml
+read_only_contract:
+  rule: 'This task MUST NOT modify any file. Findings become recommendations, never auto-fixes.'
+  rationale: 'An audit that edits the artifacts it audits cannot be trusted.'
+  violations:
+    - Editing spec.md / plan.json / tasks.md / constitution.md
+    - Applying "auto-fixes" to resolve findings
+  when_change_needed: 'Recommend the change; adjustment is done by the owner agent in a later pass.'
+```
+
+---
+
+## Detection Passes (6)
+
+Cruze 4 artefatos: `spec.md` (FR-###, SC-###, user stories, edge cases) ↔ `plan.json`
+(arquitetura, data model, fases) ↔ `tasks.md` (IDs, fases, marcador `[P]`, file paths) ↔
+`constitution.md` (princípios MUST/SHOULD).
+
+```yaml
+passes:
+  - id: pass-1
+    name: 'Duplication'
+    detects: 'Near-duplicate requirements; the same behavior specified twice'
+    default_severity: MEDIUM
+
+  - id: pass-2
+    name: 'Ambiguity'
+    detects: 'Vague adjectives (fast/scalable/secure) without a metric; TODO/??? placeholders; open [NEEDS CLARIFICATION] markers'
+    default_severity: HIGH
+
+  - id: pass-3
+    name: 'Underspecification'
+    detects: 'Requirement with no object/outcome; task referencing an undefined file/path'
+    default_severity: HIGH
+
+  - id: pass-4
+    name: 'Constitution Alignment'
+    detects: 'Conflict with a MUST principle; a mandatory constitution section absent'
+    default_severity: CRITICAL # Always
+
+  - id: pass-5
+    name: 'Coverage Gaps'
+    detects: 'Requirement (FR-*) with zero tasks; task with no mapped requirement; Success Criterion (SC-*) with no task'
+    default_severity: HIGH
+
+  - id: pass-6
+    name: 'Inconsistency'
+    detects: 'Terminology drift; entity in plan absent from spec; contradictory task ordering'
+    default_severity: MEDIUM
+```
+
+---
+
+## Severity Rules
+
+```yaml
+severity:
+  levels: [CRITICAL, HIGH, MEDIUM, LOW]
+
+  rules:
+    - 'Constitution conflict (pass-4) is ALWAYS CRITICAL — never downgraded, reinterpreted, or silently ignored.'
+    - 'Coverage gap on a P0/P1 requirement -> escalate to CRITICAL.'
+    - 'Ambiguity / Underspecification default HIGH; cosmetic-only -> LOW.'
+    - 'Duplication / Inconsistency default MEDIUM.'
+
+  max_findings: 50
+```
+
+---
+
+## Output: Findings Table + Metrics
+
+A saída humana é uma tabela de findings seguida do Coverage Summary. O artefato persistido é
+`analyze-report.json` (schema abaixo).
+
+```markdown
+## Analyze Report — {storyId}
+
+| ID  | Category | Severity | Location | Summary | Recommendation |
+| --- | -------- | -------- | -------- | ------- | -------------- |
+| A-1 | Constitution Alignment | CRITICAL | spec.md#3.1 ↔ constitution.md#Art-IV | Spec invents an unsourced feature | Remove or trace to FR-*/research; do not dilute Art. IV |
+| A-2 | Coverage Gaps | HIGH | FR-3 ↔ tasks.md | FR-3 has zero tasks | Add a task covering FR-3 |
+
+### Coverage Summary
+
+- Total Requirements: {n}
+- Total Tasks: {n}
+- Coverage: {covered}/{total} ({pct}%)
+- Ambiguity findings: {n}
+- Duplication findings: {n}
+- CRITICAL count: {n}
+```
+
+---
+
+## Gate
+
+```yaml
+gate:
+  order: 'Run AFTER plan, as the final phase, BEFORE handoff to implementation'
+  blocking: true
+
+  verdict:
+    PASS:
+      condition: 'No CRITICAL findings'
+      next_action: 'Proceed to implementation (@developer *develop)'
+    BLOCKED:
+      condition: 'One or more CRITICAL findings (includes ANY constitution conflict)'
+      next_action: |
+        Resolve CRITICAL findings before /implement by ADJUSTING spec / plan / tasks.
+        A constitution conflict MUST NOT be diluted, reinterpreted, or silently ignored.
+      escalate_to: '@architect'
+```
+
+---
+
+## Execution Flow
+
+### Step 1: Load Artifacts (read-only)
+
+```yaml
+load:
+  action: gather_all_artifacts
+  files:
+    - spec.md (required)
+    - plan.json (required)
+    - tasks.md (optional)
+    - constitution.md (required)
+  guard: 'Open read-only. No write handles.'
+```
+
+### Step 2: Build Requirement→Task Matrix
+
+```yaml
+build_matrix:
+  action: map_requirements_to_tasks
+  process: |
+    1. Extract FR-*, NFR-*, SC-* from spec.md
+    2. Extract task IDs + their referenced requirement from tasks.md
+    3. Build a bidirectional map (requirement <-> tasks)
+```
+
+### Step 3: Run 6 Detection Passes
+
+```yaml
+run_passes:
+  for_each: pass in [Duplication, Ambiguity, Underspecification, Constitution Alignment, Coverage Gaps, Inconsistency]
+  process: |
+    1. Execute detection over the relevant artifact pair(s)
+    2. Record each finding (location, summary)
+    3. Assign severity (constitution conflict ALWAYS CRITICAL)
+    4. Cap total findings at 50
+```
+
+### Step 4: Compute Metrics
+
+```yaml
+metrics:
+  action: compute_coverage
+  fields:
+    - totalRequirements
+    - totalTasks
+    - coveragePct
+    - ambiguityCount
+    - duplicationCount
+    - criticalCount
+```
+
+### Step 5: Emit Report + Verdict
+
+```yaml
+emit:
+  action: write_analyze_report
+  outputs:
+    - findings table (markdown, to user)
+    - analyze-report.json (persisted artifact)
+  verdict: 'BLOCKED if criticalCount > 0, else PASS'
+```
+
+---
+
+## Output Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["storyId", "analyzedAt", "gate", "findings", "metrics"],
+  "properties": {
+    "storyId": { "type": "string" },
+    "analyzedAt": { "type": "string", "format": "date-time" },
+    "analyzedBy": { "type": "string", "default": "@quality-gate" },
+    "readOnly": { "type": "boolean", "const": true },
+    "gate": { "enum": ["PASS", "BLOCKED"] },
+    "gateReason": { "type": "string" },
+    "findings": {
+      "type": "array",
+      "maxItems": 50,
+      "items": {
+        "type": "object",
+        "required": ["id", "category", "severity", "location", "summary", "recommendation"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^A-\\d+$" },
+          "category": {
+            "enum": [
+              "Duplication",
+              "Ambiguity",
+              "Underspecification",
+              "Constitution Alignment",
+              "Coverage Gaps",
+              "Inconsistency"
+            ]
+          },
+          "severity": { "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"] },
+          "location": { "type": "string" },
+          "summary": { "type": "string" },
+          "recommendation": { "type": "string" }
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "required": ["totalRequirements", "totalTasks", "coveragePct", "criticalCount"],
+      "properties": {
+        "totalRequirements": { "type": "integer", "minimum": 0 },
+        "totalTasks": { "type": "integer", "minimum": 0 },
+        "coveragePct": { "type": "number", "minimum": 0, "maximum": 100 },
+        "ambiguityCount": { "type": "integer", "minimum": 0 },
+        "duplicationCount": { "type": "integer", "minimum": 0 },
+        "criticalCount": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Integration
+
+### Command Integration (@quality-gate)
+
+```yaml
+command:
+  name: '*analyze-spec'
+  syntax: '*analyze-spec {story-id}'
+  agent: qa
+
+  examples:
+    - '*analyze-spec STORY-42'
+```
+
+### Pipeline Integration
+
+```yaml
+pipeline:
+  phase: analyze
+  previous_phase: plan
+  next_phase: none # Final phase - hands off to implementation (SDC)
+
+  requires:
+    - spec.md
+    - plan.json
+    - constitution.md
+
+  optional:
+    - tasks.md
+
+  gate: true # Blocking gate
+  readOnly: true
+
+  on_verdict:
+    PASS:
+      action: handoff_to_implementation
+    BLOCKED:
+      action: halt
+      escalate_to: '@architect'
+```
+
+---
+
+## Error Handling
+
+```yaml
+errors:
+  - id: missing-spec
+    condition: 'spec.md not found'
+    action: 'Halt - cannot analyze without a spec'
+    blocking: true
+
+  - id: missing-plan
+    condition: 'plan.json not found'
+    action: 'Halt - analyze runs after plan'
+    blocking: true
+
+  - id: missing-tasks
+    condition: 'tasks.md not found'
+    action: 'Run with reduced coverage analysis; flag tasks coverage as UNKNOWN'
+    blocking: false
+
+  - id: missing-constitution
+    condition: 'constitution.md not found'
+    action: 'Halt - constitution alignment pass cannot run'
+    blocking: true
+```
+
+---
+
+## Examples
+
+### Example: BLOCKED on constitution conflict + coverage gap
+
+**Input:** spec.md adds a feature with no FR source; FR-3 has no task.
+
+**Output:**
+
+```json
+{
+  "storyId": "STORY-42",
+  "analyzedBy": "@quality-gate",
+  "readOnly": true,
+  "gate": "BLOCKED",
+  "gateReason": "1 CRITICAL (constitution conflict) + 1 HIGH (coverage gap)",
+  "findings": [
+    {
+      "id": "A-1",
+      "category": "Constitution Alignment",
+      "severity": "CRITICAL",
+      "location": "spec.md#3.1 ↔ constitution.md#Article-IV",
+      "summary": "Spec includes a feature with no FR/research source (No Invention)",
+      "recommendation": "Remove the feature or trace it to a requirement; do not dilute Article IV"
+    },
+    {
+      "id": "A-2",
+      "category": "Coverage Gaps",
+      "severity": "HIGH",
+      "location": "FR-3 ↔ tasks.md",
+      "summary": "FR-3 has zero tasks",
+      "recommendation": "Add at least one task covering FR-3"
+    }
+  ],
+  "metrics": {
+    "totalRequirements": 5,
+    "totalTasks": 7,
+    "coveragePct": 80,
+    "ambiguityCount": 0,
+    "duplicationCount": 0,
+    "criticalCount": 1
+  }
+}
+```
+
+---
+
+## Metadata
+
+```yaml
+metadata:
+  story: '3.7'
+  epic: 'Epic 3 - Spec Pipeline'
+  created: '2026-06-24'
+  author: '@quality-gate (Litmus)'
+  version: '1.0.0'
+  source: 'GitHub Spec Kit — templates/commands/analyze.md'
+  tags:
+    - spec-pipeline
+    - analyze
+    - consistency
+    - constitution
+    - read-only
+    - quality-gate
+```
+
+## Handoff
+next_agent: @developer
+next_command: *develop {story-id}
+condition: Analyze gate is PASS (no CRITICAL findings)
+alternatives:
+  - agent: @architect, command: *analyze-impact, condition: Analyze gate is BLOCKED (CRITICAL findings open)

package/.sinapse-ai/development/tasks/spec-clarify.md

@@ -0,0 +1,374 @@
+# Spec Pipeline: Clarify Specification
+
+> **Phase:** 4b - Clarify
+> **Owner Agent:** @project-lead
+> **Pipeline:** spec-pipeline
+
+---
+
+## Purpose
+
+Desambiguar a especificação ANTES do QA gate e do plano. Roda DEPOIS de `write` (spec escrita)
+e ANTES de `critique`. Varre o `spec.md` por uma taxonomia de 9 categorias de cobertura, faz no
+máximo 5 perguntas guiadas por (Impacto × Incerteza) — uma de cada vez — e integra cada resposta
+atomicamente no `spec.md`. Sub-especificação descoberta tarde é o retrabalho mais caro do pipeline;
+o clarify ataca isso cedo, perguntando apenas o que muda decisão downstream.
+
+---
+
+## autoClaude
+
+```yaml
+autoClaude:
+  version: '3.0'
+  pipelinePhase: spec-clarify
+
+  elicit: true # Interactive - asks the user clarifying questions
+  deterministic: false # Output depends on user answers
+  composable: true
+
+  selfCritique:
+    required: false
+
+  inputs:
+    - name: storyId
+      type: string
+      required: true
+
+    - name: spec
+      type: file
+      path: docs/stories/{storyId}/spec/spec.md
+      required: true
+
+    - name: requirements
+      type: file
+      path: docs/stories/{storyId}/spec/requirements.json
+      required: false
+
+  outputs:
+    - name: spec.md
+      type: file
+      path: docs/stories/{storyId}/spec/spec.md
+      mutation: append # Adds/updates the `## Clarifications` section + target sections
+
+  verification:
+    type: gate
+    blocking: false # Skippable with explicit rework-risk warning
+    completion_field: clarificationComplete
+
+  contextRequirements:
+    projectContext: true
+    filesContext: true
+    implementationPlan: false
+    spec: true
+```
+
+---
+
+## Coverage Taxonomy (9 categories)
+
+Varra o `spec.md` e marque cada categoria como **Clear / Partial / Missing**. Perguntas só nascem
+de categorias `Partial` ou `Missing` cujo esclarecimento muda uma decisão downstream.
+
+```yaml
+taxonomy:
+  - id: tax-1
+    name: 'Functional Scope & Behavior'
+    looks_for: 'Core actions, in/out of scope, behavioral edges'
+
+  - id: tax-2
+    name: 'Domain & Data Model'
+    looks_for: 'Entities, attributes, relationships, identity, lifecycle/state'
+
+  - id: tax-3
+    name: 'Interaction & UX Flow'
+    looks_for: 'Steps, states, error/empty states, accessibility intent'
+
+  - id: tax-4
+    name: 'Non-Functional Quality Attributes'
+    looks_for: 'Performance, scale, latency, availability, security targets (quantified)'
+
+  - id: tax-5
+    name: 'Integration & External Dependencies'
+    looks_for: 'External services, APIs, contracts, failure modes of integrations'
+
+  - id: tax-6
+    name: 'Edge Cases & Failure Handling'
+    looks_for: 'Boundary conditions, invalid input, partial failure, recovery'
+
+  - id: tax-7
+    name: 'Constraints & Tradeoffs'
+    looks_for: 'Hard constraints, rejected alternatives, explicit tradeoffs'
+
+  - id: tax-8
+    name: 'Terminology & Consistency'
+    looks_for: 'Consistent naming, no synonym drift, defined glossary terms'
+
+  - id: tax-9
+    name: 'Completion Signals'
+    looks_for: 'Measurable done criteria, acceptance signals, Success Criteria present'
+
+  - id: tax-misc
+    name: 'Misc / Signals'
+    looks_for: 'TODO / ??? placeholders, unquantified adjectives (fast/scalable/secure), [NEEDS CLARIFICATION] markers'
+```
+
+---
+
+## Question Selection (Impact × Uncertainty)
+
+```yaml
+selection:
+  heuristic: 'Impact × Uncertainty'
+
+  rule: |
+    Only include questions whose answers materially impact architecture, data modeling,
+    task decomposition, test design, UX behavior, operational readiness, or compliance
+    validation. Discard cosmetic questions that do not change a downstream decision.
+
+  prioritize:
+    - High impact + high uncertainty (ask first)
+    - High impact + medium uncertainty
+  discard:
+    - Low impact (any uncertainty)
+    - Already Clear in the taxonomy scan
+```
+
+---
+
+## Question Format
+
+```yaml
+question_format:
+  max_questions: 5
+  one_at_a_time: true # Ask, wait for answer, integrate, then next
+
+  styles:
+    - type: multiple_choice
+      options: '2 to 5 mutually exclusive options'
+      include_recommendation: true # Mark the recommended option
+    - type: short_answer
+      constraint: 'answer in <= 5 words'
+```
+
+---
+
+## Integration (atomic)
+
+Cada resposta é integrada IMEDIATAMENTE antes da próxima pergunta — registro + aplicação na seção-alvo.
+
+```yaml
+integration:
+  log_section:
+    create_if_missing: '## Clarifications'
+    subsection: '### Session {YYYY-MM-DD}'
+    entry_format: '- Q: {question} -> A: {answer}'
+
+  apply_change:
+    description: 'Apply the answer to the target section of the spec'
+    targets:
+      - Functional Requirements (FR-*)
+      - Key Entities / Data Model
+      - Success Criteria (SC-*)
+      - Edge Cases
+      - Constraints (CON-*)
+    rule: 'Never log an answer without applying it to the target section'
+```
+
+---
+
+## Stop Criteria
+
+```yaml
+stop_when:
+  any_of:
+    - 'All critical ambiguities resolved'
+    - 'User says proceed / done / skip'
+    - 'Reached 5 questions'
+    - 'No critical ambiguity detected in the taxonomy scan (zero questions is valid)'
+```
+
+---
+
+## Gate
+
+```yaml
+gate:
+  order: 'Run (and complete) clarify BEFORE the plan phase'
+  blocking: false
+
+  on_skip:
+    allowed: true
+    required_action: |
+      Warn explicitly: downstream rework risk increases when clarification is skipped.
+    message: |
+      ⚠️ Skipping clarification. Ambiguities in the spec may surface during plan/implement,
+      increasing rework cost. Proceeding at user request.
+```
+
+---
+
+## Execution Flow
+
+### Step 1: Scan Coverage
+
+```yaml
+scan:
+  action: scan_spec_against_taxonomy
+  for_each: category in taxonomy
+  process: |
+    1. Read spec.md
+    2. Mark category Clear / Partial / Missing
+    3. Note specific gap location (section)
+```
+
+### Step 2: Select Questions
+
+```yaml
+select:
+  action: rank_by_impact_uncertainty
+  process: |
+    1. Build candidate questions from Partial/Missing categories
+    2. Apply the materially-impacts filter (discard cosmetic)
+    3. Rank by Impact x Uncertainty
+    4. Cap the queue at 5
+```
+
+### Step 3: Ask & Integrate Loop
+
+```yaml
+ask_loop:
+  for_each: question in selected (max 5)
+  process: |
+    1. Ask ONE question (multiple-choice 2-5 opts w/ recommendation, OR short answer <=5 words)
+    2. Wait for the answer
+    3. Append `- Q: ... -> A: ...` under `## Clarifications` / `### Session {date}`
+    4. Apply the answer to the target spec section
+    5. Re-check stop criteria; break if met
+```
+
+### Step 4: Finalize
+
+```yaml
+finalize:
+  action: confirm_clarification_complete
+  process: |
+    1. Ensure every asked question was both logged AND applied
+    2. Set clarificationComplete = true
+    3. Hand off to critique
+```
+
+---
+
+## Integration
+
+### Command Integration (@project-lead)
+
+```yaml
+command:
+  name: '*clarify-spec'
+  syntax: '*clarify-spec {story-id}'
+  agent: pm
+
+  examples:
+    - '*clarify-spec STORY-42'
+```
+
+### Pipeline Integration
+
+```yaml
+pipeline:
+  phase: clarify
+  previous_phase: spec
+  next_phase: critique
+
+  requires:
+    - spec.md
+
+  optional:
+    - requirements.json
+
+  gate: true # Order gate: complete before plan
+  blocking: false # Skippable with rework-risk warning
+
+  pass_to_next:
+    - spec.md
+```
+
+---
+
+## Error Handling
+
+```yaml
+errors:
+  - id: missing-spec
+    condition: 'spec.md not found'
+    action: 'Halt - cannot clarify without a spec'
+    blocking: true
+
+  - id: no-ambiguity
+    condition: 'Taxonomy scan finds zero critical ambiguities'
+    action: 'Skip questions, set clarificationComplete=true, proceed to critique'
+    blocking: false
+
+  - id: user-defers
+    condition: 'User declines to answer / says proceed'
+    action: 'Warn of rework risk, set clarificationComplete=false, proceed'
+    blocking: false
+```
+
+---
+
+## Examples
+
+### Example: Clarify a vague NFR
+
+**Input:** spec.md says "the endpoint should be fast" (tax-4 = Partial, unquantified adjective)
+
+**Interaction:**
+
+```
+Q: What is the acceptable p95 latency for the endpoint?
+   A) < 100ms   B) < 300ms (recommended)   C) < 1s   D) No target needed
+A: B
+```
+
+**Spec mutation:**
+
+```markdown
+## Clarifications
+
+### Session 2026-06-24
+
+- Q: What is the acceptable p95 latency for the endpoint? → A: < 300ms (p95)
+
+<!-- and NFR section updated: -->
+| Category    | Requirement              | Target        |
+| ----------- | ------------------------ | ------------- |
+| Performance | Endpoint response (p95)  | < 300ms       |
+```
+
+---
+
+## Metadata
+
+```yaml
+metadata:
+  story: '3.4b'
+  epic: 'Epic 3 - Spec Pipeline'
+  created: '2026-06-24'
+  author: '@project-lead (Axis)'
+  version: '1.0.0'
+  source: 'GitHub Spec Kit — templates/commands/clarify.md'
+  tags:
+    - spec-pipeline
+    - clarify
+    - ambiguity
+    - elicitation
+    - product-lead
+```
+
+## Handoff
+next_agent: @quality-gate
+next_command: *critique-spec {story-id}
+condition: Clarification complete (no critical ambiguities open) OR user proceeds with rework-risk warning

package/.sinapse-ai/development/workflows/spec-pipeline.yaml

@@ -4,8 +4,10 @@ workflow:
   version: "1.0"
   description: >-
     Pipeline completo que transforma requisitos informais em especificações
-    executáveis. Orquestra 5 fases: Gather → Assess → Research → Write → Critique.
-    Adapta as fases baseado na complexidade do requisito.
+    executáveis. Orquestra as fases: Gather → Assess → Research → Write → Clarify →
+    Critique → Plan → Analyze. Adapta as fases baseado na complexidade do requisito.
+    Clarify desambigua a spec antes do QA gate; Analyze faz a consistência cruzada
+    (read-only) antes da implementação.
 
     Part of the Auto-Claude ADE (Autonomous Development Engine) infrastructure.
 
@@ -51,11 +53,21 @@ workflow:
       action: run_phase
       phase: spec
 
+    - event: command
+      command: "*clarify-spec"
+      action: run_phase
+      phase: clarify
+
     - event: command
       command: "*critique-spec"
       action: run_phase
       phase: critique
 
+    - event: command
+      command: "*analyze-spec"
+      action: run_phase
+      phase: analyze
+
   # ═══════════════════════════════════════════════════════════════════════════════════
   #                              CONFIGURATION
   # ═══════════════════════════════════════════════════════════════════════════════════
@@ -86,15 +98,17 @@ workflow:
 
   phases:
     # SIMPLE: Minimal pipeline for straightforward tasks
+    # Includes clarify (cheap, avoids rework) but skips analyze.
     SIMPLE:
       description: "Tarefa direta, padrões existentes"
       steps:
         - gather
         - spec
+        - clarify
         - critique
       estimated_time: "30-60 min"
 
-    # STANDARD: Full pipeline for moderate complexity
+    # STANDARD: Full pipeline for moderate complexity (clarify + analyze)
     STANDARD:
       description: "Complexidade moderada, alguma pesquisa necessária"
       steps:
@@ -102,11 +116,13 @@ workflow:
         - assess
         - research
         - spec
+        - clarify
         - critique
         - plan
+        - analyze
       estimated_time: "2-4 hours"
 
-    # COMPLEX: Extended pipeline with revision loop
+    # COMPLEX: Extended pipeline with revision loop (clarify + analyze)
     COMPLEX:
       description: "Alta complexidade, múltiplas iterações"
       steps:
@@ -114,10 +130,12 @@ workflow:
         - assess
         - research
         - spec
+        - clarify
         - critique_1
         - revise
         - critique_2
         - plan
+        - analyze
       estimated_time: "4-8 hours"
       flags:
         - "Architectural review recommended"
@@ -293,12 +311,54 @@ workflow:
 
       on_success:
         log: "📝 Specification written: docs/stories/{storyId}/spec/spec.md"
-        next: critique
+        next: clarify
 
       on_failure:
         action: halt
         error: "Failed to write specification"
 
+    # ═════════════════════════════════════════════════════════════════════════════════
+    # PHASE 4b: CLARIFY SPECIFICATION
+    # ═════════════════════════════════════════════════════════════════════════════════
+
+    - step: clarify
+      phase: "4b"
+      phase_name: "Clarify Specification"
+      agent: pm
+
+      description: >-
+        Interactive ambiguity resolution BEFORE the QA gate. Scans the spec across a
+        9-category coverage taxonomy, asks at most 5 questions (one at a time, guided by
+        Impact × Uncertainty), and integrates each answer atomically into spec.md
+        (## Clarifications section). Reduces costly downstream rework.
+
+      task: spec-clarify.md
+
+      inputs:
+        storyId: "{storyId}"
+        spec: "docs/stories/{storyId}/spec/spec.md"
+        requirements: "docs/stories/{storyId}/spec/requirements.json"
+
+      outputs:
+        - spec.md (updated)
+
+      elicit: true  # Requires user interaction
+
+      gate: true  # Order gate: complete BEFORE plan
+      blocking: false  # Skippable with explicit rework-risk warning
+
+      on_success:
+        log: "💬 Clarification complete: {clarify.questionsAsked} questions resolved"
+        next: critique
+
+      on_skip:
+        log: "⚠️ Clarification skipped - downstream rework risk increases"
+        next: critique
+
+      on_failure:
+        action: continue
+        fallback: "Proceed to critique; flag open ambiguities as risks"
+
     # ═════════════════════════════════════════════════════════════════════════════════
     # PHASE 5: CRITIQUE SPECIFICATION
     # ═════════════════════════════════════════════════════════════════════════════════
@@ -435,7 +495,50 @@ workflow:
 
       on_success:
         log: "📋 Implementation plan created"
-        complete: true
+        next: analyze
+
+    # ═════════════════════════════════════════════════════════════════════════════════
+    # PHASE 7: ANALYZE CROSS-CONSISTENCY (final, READ-ONLY)
+    # ═════════════════════════════════════════════════════════════════════════════════
+
+    - step: analyze
+      phase: 7
+      phase_name: "Analyze Cross-Consistency"
+      agent: qa
+
+      description: >-
+        READ-ONLY cross-consistency gate. Cross-references spec ↔ plan ↔ tasks ↔ constitution
+        in 6 detection passes (Duplication, Ambiguity, Underspecification, Constitution Alignment,
+        Coverage Gaps, Inconsistency) and emits a findings table + coverage metrics. Does not
+        modify any file. CRITICAL findings (any constitution conflict) block implementation.
+
+      condition: "complexity.result !== 'SIMPLE'"  # SIMPLE skips analyze
+
+      task: spec-analyze.md
+
+      inputs:
+        storyId: "{storyId}"
+        spec: "docs/stories/{storyId}/spec/spec.md"
+        plan: "docs/stories/{storyId}/spec/plan.json"
+        tasks: "docs/stories/{storyId}/spec/tasks.md"
+        constitution: ".sinapse-ai/constitution.md"
+
+      outputs:
+        - analyze-report.json
+
+      gate: true  # Blocking gate
+      read_only: true  # Never mutates artifacts
+
+      on_verdict:
+        PASS:
+          log: "✅ Analyze PASS (coverage: {analyze.metrics.coveragePct}%, 0 CRITICAL)"
+          action: continue
+          complete: true
+
+        BLOCKED:
+          log: "🛑 Analyze BLOCKED: {analyze.metrics.criticalCount} CRITICAL finding(s)"
+          action: halt
+          escalate_to: "@architect"
 
   # ═══════════════════════════════════════════════════════════════════════════════════
   #                              WORKFLOW COMPLETION
@@ -458,6 +561,7 @@ workflow:
          • docs/stories/{storyId}/spec/research.json
          • docs/stories/{storyId}/spec/spec.md
          • docs/stories/{storyId}/spec/critique.json
+         • docs/stories/{storyId}/spec/analyze-report.json
 
       📌 Next Steps:
          • Review spec.md
@@ -470,11 +574,13 @@ workflow:
       - research.json
       - spec.md
       - critique.json
+      - analyze-report.json
 
     next_steps:
       - "Review specification: docs/stories/{storyId}/spec/spec.md"
       - "Start development: @developer *develop {storyId}"
       - "View critique: docs/stories/{storyId}/spec/critique.json"
+      - "View analyze report: docs/stories/{storyId}/spec/analyze-report.json"
 
   # ═══════════════════════════════════════════════════════════════════════════════════
   #                              ERROR HANDLING
@@ -519,15 +625,21 @@ workflow:
         state: research_complete
       - after: spec
         state: spec_written
+      - after: clarify
+        state: clarification_complete
       - after: critique
         state: critique_complete
+      - after: plan
+        state: plan_complete
 
     resume_from:
       requirements_gathered: assess
       complexity_assessed: research
       research_complete: spec
-      spec_written: critique
+      spec_written: clarify
+      clarification_complete: critique
       critique_complete: plan
+      plan_complete: analyze
 
   # ═══════════════════════════════════════════════════════════════════════════════════
   #                              INTEGRATION
@@ -568,7 +680,9 @@ workflow:
       - spec-assess-complexity.md
       - spec-research-dependencies.md
       - spec-write-spec.md
+      - spec-clarify.md
       - spec-critique.md
+      - spec-analyze.md
     tags:
       - spec-pipeline
       - workflow

package/.sinapse-ai/install-manifest.yaml

@@ -7,9 +7,9 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.15.0
+version: 1.16.0
 generator: scripts/generate-install-manifest.js
-file_count: 1150
+file_count: 1152
 files:
   - path: cli/commands/config/index.js
     hash: sha256:bfa83cb1dc111b0b30dd298dc0abc2150b73f939b6cd4458effa8e6d407bc9e2
@@ -1344,9 +1344,9 @@ files:
     type: data
     size: 9602
   - path: data/entity-registry.yaml
-    hash: sha256:1754430439419493ac7b1c5a6c3473bfafb08a6f2bdb94826188f3dfcfb86849
+    hash: sha256:5afcfac2ecfcbda210a85f77a18829c23a0dd80a0be5fc42c5081d419a3ac73b
     type: data
-    size: 547841
+    size: 549348
   - path: data/learned-patterns.yaml
     hash: sha256:1a4cd045c087b9dfd7046ff1464a9d2edb85fba77cf0b6fba14f4bb9004c741e
     type: data
@@ -2547,10 +2547,18 @@ files:
     hash: sha256:702907ff987ef8db70bc7dba93aadcf40ba9d080321f8305dad7f9e2de10d1b2
     type: task
     size: 18077
+  - path: development/tasks/spec-analyze.md
+    hash: sha256:5a73974cb88ca58274f907416839e8c864a3e35cf832668d3b2c582de3f6b26a
+    type: task
+    size: 11675
   - path: development/tasks/spec-assess-complexity.md
     hash: sha256:7ef9f00dad98113dcf6c273e0d56333aece4fa892c91fff8935d3c3c552748ae
     type: task
     size: 10451
+  - path: development/tasks/spec-clarify.md
+    hash: sha256:e4eee7ea80f146a697433462287aaff138536b148705337f2f32d66d2a83db5c
+    type: task
+    size: 8932
   - path: development/tasks/spec-critique.md
     hash: sha256:7d0243ab61b08e5c70fdd12ead90a2403b7dd3659ce3a68e54f4274b3347b07a
     type: task
@@ -2988,9 +2996,9 @@ files:
     type: workflow
     size: 2606
   - path: development/workflows/spec-pipeline.yaml
-    hash: sha256:890753d02dd6469441fe82a5eba0ecf48a3ac7969cfda3cd888c94cb74695c39
+    hash: sha256:d0da3844cdf7e71c59a13b22e6c715b23a0ae55337aaa6dfc7248de99bdc6ff4
     type: workflow
-    size: 23746
+    size: 28350
   - path: development/workflows/story-development-cycle.yaml
     hash: sha256:137fc6d2a7aedb50bbebfa045e877c382399604708ce03477f358f282b76727f
     type: workflow
@@ -4188,9 +4196,9 @@ files:
     type: template
     size: 16666
   - path: product/templates/spec-tmpl.md
-    hash: sha256:03a71c8a3758864c3d27e4f0865734d986f4259f64af477d9fa4244f8972c7eb
+    hash: sha256:58207c62ca73c18d9584232bc62ec43ee5f11dc4337d231eee5bf2cc87d15b78
     type: template
-    size: 3403
+    size: 4220
   - path: product/templates/state-persistence-tmpl.yaml
     hash: sha256:3f8bb48230df89cf987330f7c9aff19edbc35a65a9cbff799e28480155dd8919
     type: template

package/.sinapse-ai/product/templates/spec-tmpl.md

@@ -7,6 +7,11 @@
 
 ---
 
+> **Marking uncertainty:** For any point that is genuinely undefined, inline the marker
+> `[NEEDS CLARIFICATION: <the specific question>]` instead of guessing. Ceiling: **3 markers**.
+> If more than 3 are needed, the spec is too ambiguous to proceed — run the clarify gate
+> (`*clarify-spec {story-id}`) before continuing.
+
 ## 1. Overview
 
 ### 1.1 Summary
@@ -63,6 +68,19 @@
 - {{this}}
   {{/each}}
 
+### 2.5 Success Criteria
+
+> Measurable, **technology-agnostic** outcomes — describe the observable result, never the
+> implementation. No tool, framework, or library names here (e.g. "user completes checkout in
+> < 3s", not "Stripe call returns in < 3s").
+
+| ID     | Success Criterion                          | How it's measured |
+| ------ | ------------------------------------------ | ----------------- |
+
+{{#each success-criteria}}
+| {{id}} | {{criterion}} | {{measure}} |
+{{/each}}
+
 ---
 
 ## 3. Technical Approach

package/AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md
 
 > SINAPSE AI -- AI-Orchestrated System for Full Stack Development
-> 17 squads · 172 agents (all `@`-resolvable in Codex) · 1,410 task files, 1,348 resolvable via the parametric activator
+> 17 squads · 172 agents (all `@`-resolvable in Codex) · 1,412 task files, 1,348 resolvable via the parametric activator
 >
 > Codex resolves every agent and its real tasks at runtime from source (no frozen
 > snapshot): `node .codex/scripts/resolve-codex-agent.js <agent> [command]`.

package/CHANGELOG.md

@@ -1,9 +1,8 @@
-## [1.15.0](https://github.com/caioimori/sinapse-ai/compare/1.14.0...1.15.0) (2026-06-24)
+## [1.16.0](https://github.com/caioimori/sinapse-ai/compare/1.15.0...1.16.0) (2026-06-25)
 
 ### Features
 
-* **chrome-brain:** scripts nativos Node, ensure que nao mata janela boa, janela fixa + login ([e1f921b](https://github.com/caioimori/sinapse-ai/commit/e1f921b76627fe9eb2322fa81e35c31dfffe3862))
-* **statusline:** selos de identidade de agente + banner de install ([a80a353](https://github.com/caioimori/sinapse-ai/commit/a80a3532eb5143d882872301aad2aadc7e9abe79))
+* add clarify and analyze gates to Spec Pipeline ([#280](https://github.com/caioimori/sinapse-ai/issues/280)) ([18b643f](https://github.com/caioimori/sinapse-ai/commit/18b643fe6d4038bb5a9967dccdd7b34bf3b9f6cc))
 
 # Changelog
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 17 squads, 172 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",