aios-core 2.1.0

package/.aios-core/development/tasks/qa-run-tests.md

@@ -0,0 +1,277 @@
+---
+name: run-tests
+agent: qa
+requires:
+  - jest
+  - coderabbit
+---
+
+# Run Tests (with Code Quality Gate)
+
+Execute test suite and validate code quality before marking tests complete.
+
+## 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: qaRunTests()
+responsável: Quinn (Guardian)
+responsavel_type: Agente
+atomic_layer: Config
+
+**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:** retry
+
+**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: 2-10 min (estimated)
+cost_estimated: $0.001-0.008
+token_usage: ~800-2,500 tokens
+```
+
+**Optimization Notes:**
+- Validate configuration early; use atomic writes; implement rollback checkpoints
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - quality-assurance
+  - testing
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Steps
+
+### 1. Run Unit Tests
+```bash
+cd api
+npm run test
+```
+
+**Expected**: All tests pass, coverage >= 80%
+
+### 2. Run Integration Tests
+```bash
+npm run test:integration
+```
+
+### 3. Code Quality Review
+```bash
+# Review code that was tested
+coderabbit --prompt-only -t uncommitted
+```
+
+**Parse output**:
+- If CRITICAL or HIGH issues found → FAIL
+- If only MEDIUM/LOW → WARN but PASS
+
+### 4. Generate QA Report
+
+Use template: `qa-gate-tmpl.yaml`
+
+Include:
+- Test results (pass/fail, coverage %)
+- CodeRabbit summary (issues by severity)
+- Recommendation (approve/reject story)
+
+### 5. Update Story Status
+
+If all pass:
+- [ ] Mark story testing complete
+- [ ] Add QA approval comment
+- [ ] Move to "Ready for Deploy"
+
+If failures:
+- [ ] Document failures in story
+- [ ] Create tech debt issues for MEDIUM
+- [ ] Request fixes from @dev
+
+## Integration with CodeRabbit
+
+**CodeRabbit helps @qa agent**:
+- Catch issues tests might miss (logic errors, race conditions)
+- Validate security patterns (SQL injection, hardcoded secrets)
+- Enforce coding standards automatically
+- Generate quality metrics
+
+## Config
+
+```yaml
+codeRabbit:
+  enabled: true
+  severity_threshold: high
+  auto_fix: false  # QA reviews but doesn't auto-fix
+  report_location: docs/qa/coderabbit-reports/
+```

package/.aios-core/development/tasks/qa-test-design.md

@@ -0,0 +1,388 @@
+<!--
+## 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: qaTestDesign()
+responsável: Quinn (Guardian)
+responsavel_type: Agente
+atomic_layer: Config
+
+**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:** retry
+
+**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: 2-10 min (estimated)
+cost_estimated: $0.001-0.008
+token_usage: ~800-2,500 tokens
+```
+
+**Optimization Notes:**
+- Validate configuration early; use atomic writes; implement rollback checkpoints
+
+---
+
+## 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:
+  - browser           # E2E testing and UI scenario validation
+  - context7          # Research testing frameworks and patterns
+  - github-cli        # Test report generation and tracking
+checklists:
+  - qa-master-checklist.md
+---
+
+# test-design
+
+Create comprehensive test scenarios with appropriate test level recommendations for story implementation.
+
+## Inputs
+
+```yaml
+required:
+  - story_id: '{epic}.{story}' # e.g., "1.3"
+  - story_path: '{devStoryLocation}/{epic}.{story}.*.md' # Path from core-config.yaml
+  - story_title: '{title}' # If missing, derive from story file H1
+  - story_slug: '{slug}' # If missing, derive from title (lowercase, hyphenated)
+```
+
+## Purpose
+
+Design a complete test strategy that identifies what to test, at which level (unit/integration/e2e), and why. This ensures efficient test coverage without redundancy while maintaining appropriate test boundaries.
+
+## Dependencies
+
+```yaml
+data:
+  - test-levels-framework.md # Unit/Integration/E2E decision criteria
+  - test-priorities-matrix.md # P0/P1/P2/P3 classification system
+```
+
+## Process
+
+### 1. Analyze Story Requirements
+
+Break down each acceptance criterion into testable scenarios. For each AC:
+
+- Identify the core functionality to test
+- Determine data variations needed
+- Consider error conditions
+- Note edge cases
+
+### 2. Apply Test Level Framework
+
+**Reference:** Load `test-levels-framework.md` for detailed criteria
+
+Quick rules:
+
+- **Unit**: Pure logic, algorithms, calculations
+- **Integration**: Component interactions, DB operations
+- **E2E**: Critical user journeys, compliance
+
+### 3. Assign Priorities
+
+**Reference:** Load `test-priorities-matrix.md` for classification
+
+Quick priority assignment:
+
+- **P0**: Revenue-critical, security, compliance
+- **P1**: Core user journeys, frequently used
+- **P2**: Secondary features, admin functions
+- **P3**: Nice-to-have, rarely used
+
+### 4. Design Test Scenarios
+
+For each identified test need, create:
+
+```yaml
+test_scenario:
+  id: '{epic}.{story}-{LEVEL}-{SEQ}'
+  requirement: 'AC reference'
+  priority: P0|P1|P2|P3
+  level: unit|integration|e2e
+  description: 'What is being tested'
+  justification: 'Why this level was chosen'
+  mitigates_risks: ['RISK-001'] # If risk profile exists
+```
+
+### 5. Validate Coverage
+
+Ensure:
+
+- Every AC has at least one test
+- No duplicate coverage across levels
+- Critical paths have multiple levels
+- Risk mitigations are addressed
+
+## Outputs
+
+### Output 1: Test Design Document
+
+**Save to:** `qa.qaLocation/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md`
+
+```markdown
+# Test Design: Story {epic}.{story}
+
+Date: {date}
+Designer: Quinn (Test Architect)
+
+## Test Strategy Overview
+
+- Total test scenarios: X
+- Unit tests: Y (A%)
+- Integration tests: Z (B%)
+- E2E tests: W (C%)
+- Priority distribution: P0: X, P1: Y, P2: Z
+
+## Test Scenarios by Acceptance Criteria
+
+### AC1: {description}
+
+#### Scenarios
+
+| ID           | Level       | Priority | Test                      | Justification            |
+| ------------ | ----------- | -------- | ------------------------- | ------------------------ |
+| 1.3-UNIT-001 | Unit        | P0       | Validate input format     | Pure validation logic    |
+| 1.3-INT-001  | Integration | P0       | Service processes request | Multi-component flow     |
+| 1.3-E2E-001  | E2E         | P1       | User completes journey    | Critical path validation |
+
+[Continue for all ACs...]
+
+## Risk Coverage
+
+[Map test scenarios to identified risks if risk profile exists]
+
+## Recommended Execution Order
+
+1. P0 Unit tests (fail fast)
+2. P0 Integration tests
+3. P0 E2E tests
+4. P1 tests in order
+5. P2+ as time permits
+```
+
+### Output 2: Gate YAML Block
+
+Generate for inclusion in quality gate:
+
+```yaml
+test_design:
+  scenarios_total: X
+  by_level:
+    unit: Y
+    integration: Z
+    e2e: W
+  by_priority:
+    p0: A
+    p1: B
+    p2: C
+  coverage_gaps: [] # List any ACs without tests
+```
+
+### Output 3: Trace References
+
+Print for use by trace-requirements task:
+
+```text
+Test design matrix: qa.qaLocation/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
+P0 tests identified: {count}
+```
+
+## Quality Checklist
+
+Before finalizing, verify:
+
+- [ ] Every AC has test coverage
+- [ ] Test levels are appropriate (not over-testing)
+- [ ] No duplicate coverage across levels
+- [ ] Priorities align with business risk
+- [ ] Test IDs follow naming convention
+- [ ] Scenarios are atomic and independent
+
+## Key Principles
+
+- **Shift left**: Prefer unit over integration, integration over E2E
+- **Risk-based**: Focus on what could go wrong
+- **Efficient coverage**: Test once at the right level
+- **Maintainability**: Consider long-term test maintenance
+- **Fast feedback**: Quick tests run first
+