aios-core 2.1.6 → 2.2.1

package/.aios-core/development/tasks/qa-gate.md

@@ -1,374 +1,374 @@
-<!--
-## 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 (AIOS 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:** .aios-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:** .aios-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 AIOS™ Core -->
-
----
-tools:
-  - github-cli        # PR review and quality gate management
-  - context7          # Research testing best practices and standards
-checklists:
-  - qa-master-checklist.md
----
-
-# 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 `aios-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'
-```
-
-## 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 `aios-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
+<!--
+## 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 (AIOS 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:** .aios-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:** .aios-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 AIOS™ Core -->
+
+---
+tools:
+  - github-cli        # PR review and quality gate management
+  - context7          # Research testing best practices and standards
+checklists:
+  - qa-master-checklist.md
+---
+
+# 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 `aios-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'
+```
+
+## 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 `aios-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