create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/tasks/qa-gate.md

@@ -0,0 +1,430 @@
+<!--
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOX Task Format V1.0)
+
+```yaml
+task: qaGate()
+responsável: Quinn (Guardian)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: target
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must exist
+
+- campo: criteria
+  tipo: array
+  origem: config
+  obrigatório: true
+  validação: Non-empty validation criteria
+
+- campo: strict
+  tipo: boolean
+  origem: User Input
+  obrigatório: false
+  validação: Default: true
+
+**Saída:**
+- campo: validation_result
+  tipo: boolean
+  destino: Return value
+  persistido: false
+
+- campo: errors
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: report
+  tipo: object
+  destino: File (.ai/*.json)
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Validation rules loaded; target available for validation
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check validation rules loaded; target available for validation
+    error_message: "Pre-condition failed: Validation rules loaded; target available for validation"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Validation executed; results accurate; report generated
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify validation executed; results accurate; report generated
+    error_message: "Post-condition failed: Validation executed; results accurate; report generated"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Validation rules applied; pass/fail accurate; actionable feedback
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert validation rules applied; pass/fail accurate; actionable feedback
+    error_message: "Acceptance criterion not met: Validation rules applied; pass/fail accurate; actionable feedback"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** validation-engine
+  - **Purpose:** Rule-based validation and reporting
+  - **Source:** .aiox-core/utils/validation-engine.js
+
+- **Tool:** schema-validator
+  - **Purpose:** JSON/YAML schema validation
+  - **Source:** ajv or similar
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** run-validation.js
+  - **Purpose:** Execute validation rules and generate report
+  - **Language:** JavaScript
+  - **Location:** .aiox-core/scripts/run-validation.js
+
+---
+
+## Error Handling
+
+**Strategy:** abort
+
+**Common Errors:**
+
+1. **Error:** Validation Criteria Missing
+   - **Cause:** Required validation rules not defined
+   - **Resolution:** Ensure validation criteria loaded from config
+   - **Recovery:** Use default validation rules, log warning
+
+2. **Error:** Invalid Schema
+   - **Cause:** Target does not match expected schema
+   - **Resolution:** Update schema or fix target structure
+   - **Recovery:** Detailed validation error report
+
+3. **Error:** Dependency Missing
+   - **Cause:** Required dependency for validation not found
+   - **Resolution:** Install missing dependencies
+   - **Recovery:** Abort with clear dependency list
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-15 min (estimated)
+cost_estimated: $0.003-0.010
+token_usage: ~3,000-10,000 tokens
+```
+
+**Optimization Notes:**
+- Break into smaller workflows; implement checkpointing; use async processing where possible
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - quality-assurance
+  - testing
+updated_at: 2025-11-17
+```
+
+---
+
+ Powered by AIOX™ Core -->
+
+---
+tools:
+  - github-cli        # PR review and quality gate management
+  - context7          # Research testing best practices and standards
+checklists:
+  - qa-master-checklist.md
+execution_mode: programmatic  # TOK-3: PTC-eligible — batch lint+typecheck+test in single Bash block
+---
+
+# qa-gate
+
+Create or update a quality gate decision file for a story based on review findings.
+
+## Purpose
+
+Generate a standalone quality gate file that provides a clear pass/fail decision with actionable feedback. This gate serves as an advisory checkpoint for teams to understand quality status.
+
+## Prerequisites
+
+- Story has been reviewed (manually or via review-story task)
+- Review findings are available
+- Understanding of story requirements and implementation
+
+## Gate File Location
+
+**ALWAYS** check the `aiox-core/core-config.yaml` for the `qa.qaLocation/gates`
+
+Slug rules:
+
+- Convert to lowercase
+- Replace spaces with hyphens
+- Strip punctuation
+- Example: "User Auth - Login!" becomes "user-auth-login"
+
+## Minimal Required Schema
+
+```yaml
+schema: 1
+story: '{epic}.{story}'
+gate: PASS|CONCERNS|FAIL|WAIVED
+status_reason: '1-2 sentence explanation of gate decision'
+reviewer: 'Quinn'
+updated: '{ISO-8601 timestamp}'
+top_issues: [] # Empty array if no issues
+waiver: { active: false } # Only set active: true if WAIVED
+```
+
+## Schema with Issues
+
+```yaml
+schema: 1
+story: '1.3'
+gate: CONCERNS
+status_reason: 'Missing rate limiting on auth endpoints poses security risk.'
+reviewer: 'Quinn'
+updated: '2025-01-12T10:15:00Z'
+top_issues:
+  - id: 'SEC-001'
+    severity: high # ONLY: low|medium|high
+    finding: 'No rate limiting on login endpoint'
+    suggested_action: 'Add rate limiting middleware before production'
+  - id: 'TEST-001'
+    severity: medium
+    finding: 'No integration tests for auth flow'
+    suggested_action: 'Add integration test coverage'
+waiver: { active: false }
+```
+
+## Schema when Waived
+
+```yaml
+schema: 1
+story: '1.3'
+gate: WAIVED
+status_reason: 'Known issues accepted for MVP release.'
+reviewer: 'Quinn'
+updated: '2025-01-12T10:15:00Z'
+top_issues:
+  - id: 'PERF-001'
+    severity: low
+    finding: 'Dashboard loads slowly with 1000+ items'
+    suggested_action: 'Implement pagination in next sprint'
+waiver:
+  active: true
+  reason: 'MVP release - performance optimization deferred'
+  approved_by: 'Product Owner'
+```
+
+## Code Intelligence Enhancement (Optional)
+
+> These steps are **conditional** — they only execute when a code intelligence provider is available.
+> If `isCodeIntelAvailable()` returns false, skip silently and proceed with standard gate criteria.
+
+### Code Intelligence: Blast Radius
+
+After completing manual review, if code intelligence is available:
+
+1. Collect the list of modified files from the story's File List
+2. Call `getBlastRadius(files)` from `.aiox-core/core/code-intel/helpers/qa-helper.js`
+3. If result is not null, add a "Blast Radius" section to the gate report:
+   ```
+   ### Blast Radius
+   - Files analyzed: {count}
+   - Total references affected: {blastRadius}
+   - Risk Level: {riskLevel} (LOW/MEDIUM/HIGH)
+   ```
+4. If risk level is HIGH, call `suggestGateInfluence('HIGH')` and include the advisory in the gate decision notes
+
+### Code Intelligence: Test Coverage
+
+After blast radius analysis, if code intelligence is available:
+
+1. Extract symbol names (function/class names) from modified files
+2. Call `getTestCoverage(symbols)` from `qa-helper.js`
+3. If result is not null, add a "Test Coverage" section to the gate report:
+   ```
+   ### Test Coverage (Code Intelligence)
+   | Symbol | Status | Test Count |
+   |--------|--------|------------|
+   | {symbol} | {NO_TESTS/INDIRECT/MINIMAL/GOOD} | {testCount} |
+   ```
+4. Symbols with NO_TESTS status should be flagged as potential CONCERNS
+
+### Code Intelligence: Gate Influence
+
+If blast radius returned HIGH risk:
+
+1. The `suggestGateInfluence('HIGH')` advisory is **informational only**
+2. It suggests CONCERNS but does NOT automatically change the gate verdict
+3. @qa makes the final decision — the advisory is logged in the gate file under `code_intel_advisory`
+
+> **Fallback guarantee:** If code intelligence is unavailable or any call returns null, the gate process continues exactly as before — no sections are added, no errors are raised.
+
+---
+
+## Gate Decision Criteria
+
+### PASS
+
+- All acceptance criteria met
+- No high-severity issues
+- Test coverage meets project standards
+
+### CONCERNS
+
+- Non-blocking issues present
+- Should be tracked and scheduled
+- Can proceed with awareness
+
+### FAIL
+
+- Acceptance criteria not met
+- High-severity issues present
+- Recommend return to InProgress
+
+### WAIVED
+
+- Issues explicitly accepted
+- Requires approval and reason
+- Proceed despite known issues
+
+## Severity Scale
+
+**FIXED VALUES - NO VARIATIONS:**
+
+- `low`: Minor issues, cosmetic problems
+- `medium`: Should fix soon, not blocking
+- `high`: Critical issues, should block release
+
+## Issue ID Prefixes
+
+- `SEC-`: Security issues
+- `PERF-`: Performance issues
+- `REL-`: Reliability issues
+- `TEST-`: Testing gaps
+- `MNT-`: Maintainability concerns
+- `ARCH-`: Architecture issues
+- `DOC-`: Documentation gaps
+- `REQ-`: Requirements issues
+
+## Output Requirements
+
+1. **ALWAYS** create gate file at: `qa.qaLocation/gates` from `aiox-core/core-config.yaml`
+2. **ALWAYS** append this exact format to story's QA Results section:
+
+   ```text
+   Gate: {STATUS} → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
+   ```
+
+3. Keep status_reason to 1-2 sentences maximum
+4. Use severity values exactly: `low`, `medium`, or `high`
+
+## Example Story Update
+
+After creating gate file, append to story's QA Results section:
+
+```markdown
+## QA Results
+
+### Review Date: 2025-01-12
+
+### Reviewed By: Quinn (Test Architect)
+
+[... existing review content ...]
+
+### Gate Status
+
+Gate: CONCERNS → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
+```
+
+## Key Principles
+
+- Keep it minimal and predictable
+- Fixed severity scale (low/medium/high)
+- Always write to standard path
+- Always update story with gate reference
+- Clear, actionable findings
+
+## Handoff
+next_agent: @devops
+next_command: *push
+condition: QA gate verdict is PASS
+alternatives:
+  - agent: @dev, command: *apply-qa-fixes, condition: QA gate verdict is FAIL or CONCERNS
+  - agent: @po, command: *close-story {story-id}, condition: QA gate verdict is WAIVED
+