aios-core
Version:
Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework
430 lines (315 loc) • 10.8 kB
Markdown
<!--
## 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
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 `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'
```
## 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 `.aios-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 `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
## Handoff
next_agent: @devops
next_command:
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