<!--
## 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'
reviewed_revision: '{commit SHA, PR head SHA, or deterministic story-content digest}'
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'
reviewed_revision: 'commit:abc1234'
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'
reviewed_revision: 'commit:abc1234'
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

## Post-Gate Status Update (MANDATORY)

**Reference:** `.claude/rules/story-lifecycle.md` — Status transitions are @qa responsibility during QA gate.

**This step MUST be executed before presenting results to user.**

**Change Log format:** Use `{date: YYYY-MM-DD}` and `{version: MAJOR.MINOR.PATCH}`. Version MUST follow semantic bump rules: major for breaking changes, minor for features, patch for fixes/process updates. HALT if either value cannot be resolved deterministically.

### IF verdict is PASS or CONCERNS:

0. **Pre-check (blocking):**
   - If current Status is not `**InReview**`, HALT and log: "Cannot apply PASS/CONCERNS transition: expected InReview, found {current status}."
   - If Change Log section is missing, HALT and request user to restore template structure.
1. **Update story Status field** in the story file: change `**InReview**` to `**Done**`
2. **Add Change Log entry:**
   ```text
   | {date: YYYY-MM-DD} | {version: MAJOR.MINOR.PATCH} | QA Gate {PASS|CONCERNS} — Status: InReview → Done | @qa |
   ```
3. **Log:** "✅ Story status updated: InReview → Done"

### IF verdict is FAIL:

0. **Pre-check (blocking):**
   - If current Status is not `**InReview**`, HALT and log: "Cannot apply FAIL transition: expected InReview, found {current status}."
   - If Change Log section is missing, HALT and request user to restore template structure.
1. **Update story Status field** in the story file: change `**InReview**` to `**InProgress**`
2. **Add Change Log entry:**
   ```text
   | {date: YYYY-MM-DD} | {version: MAJOR.MINOR.PATCH} | QA Gate FAIL — Status: InReview → InProgress — {reason} | @qa |
   ```
3. **Log:** "❌ Story returned to InProgress — fixes required"

### IF verdict is WAIVED:

0. **Pre-check (blocking):**
   - If current Status is not `**InReview**`, HALT and log: "Cannot apply WAIVED transition: expected InReview, found {current status}."
   - If Change Log section is missing, HALT and request user to restore template structure.
1. **Update story Status field** in the story file: change `**InReview**` to `**Done**`
2. **Add Change Log entry:**
   ```text
   | {date: YYYY-MM-DD} | {version: MAJOR.MINOR.PATCH} | QA Gate WAIVED — Status: InReview → Done — {waiver reason} | @qa |
   ```
3. **Log:** "⚠️ Story status updated: InReview → Done (waived)"

### Rationale

Status transitions defined in `story-lifecycle.md` are advisory (contextual rules). This step makes them imperative (procedural), ensuring agents always execute the transition as part of the workflow rather than relying on contextual rule awareness.

---

## Handoff
next_agent: @devops
next_command: *push
condition: QA gate verdict is PASS or CONCERNS (status updated to Done)
alternatives:
  - agent: @po, command: *review-concerns {story-id}, condition: QA gate verdict is CONCERNS (status updated to Done, has non-blocking issues)
  - agent: @dev, command: *apply-qa-fixes, condition: QA gate verdict is FAIL (status updated to InProgress)
  - agent: @po, command: *close-story {story-id}, condition: QA gate verdict is WAIVED (status updated to Done)