aios-core 2.1.6 → 2.2.1

package/.aios-core/development/tasks/github-devops-pre-push-quality-gate.md

@@ -1,733 +1,733 @@
-# pre-push-quality-gate.md
-
-**Task**: Pre-Push Quality Gate Validation (Repository-Agnostic)
-
-**Purpose**: Execute comprehensive quality checks before pushing code to remote repository, ensuring code quality, tests, and security standards are met.
-
-**When to use**: Before pushing code to GitHub, always via `@github-devops *pre-push` command.
-
-## 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: githubDevopsPrePushQualityGate()
-responsável: Gage (Automator)
-responsavel_type: Agente
-atomic_layer: Organism
-
-**Entrada:**
-- campo: task
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be registered task
-
-- campo: parameters
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid task parameters
-
-- campo: mode
-  tipo: string
-  origem: User Input
-  obrigatório: false
-  validação: yolo|interactive|pre-flight
-
-**Saída:**
-- campo: execution_result
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: logs
-  tipo: array
-  destino: File (.ai/logs/*)
-  persistido: true
-
-- campo: state
-  tipo: object
-  destino: State management
-  persistido: true
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Task is registered; required parameters provided; dependencies met
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check task is registered; required parameters provided; dependencies met
-    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Task completed; exit code 0; expected outputs created
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify task completed; exit code 0; expected outputs created
-    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Task completed as expected; side effects documented
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert task completed as expected; side effects documented
-    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** task-runner
-  - **Purpose:** Task execution and orchestration
-  - **Source:** .aios-core/core/task-runner.js
-
-- **Tool:** logger
-  - **Purpose:** Execution logging and error tracking
-  - **Source:** .aios-core/utils/logger.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** execute-task.js
-  - **Purpose:** Generic task execution wrapper
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/execute-task.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Task Not Found
-   - **Cause:** Specified task not registered in system
-   - **Resolution:** Verify task name and registration
-   - **Recovery:** List available tasks, suggest similar
-
-2. **Error:** Invalid Parameters
-   - **Cause:** Task parameters do not match expected schema
-   - **Resolution:** Validate parameters against task definition
-   - **Recovery:** Provide parameter template, reject execution
-
-3. **Error:** Execution Timeout
-   - **Cause:** Task exceeds maximum execution time
-   - **Resolution:** Optimize task or increase timeout
-   - **Recovery:** Kill task, cleanup resources, log state
-
----
-
-## 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:
-  - automation
-  - workflow
-updated_at: 2025-11-17
-```
-
----
-
-
-## Prerequisites
-- Git repository with changes to push
-- package.json with npm scripts (gracefully handles missing scripts)
-- Repository context detected (run `aios init` if needed)
-
-## Quality Gate Checks
-
-### 1. Repository Context Detection
-
-```javascript
-const { detectRepositoryContext } = require('./../scripts/repository-detector');
-
-const context = detectRepositoryContext();
-if (!context) {
-  console.error('❌ Unable to detect repository context');
-  console.error('Run "aios init" to configure installation mode');
-  process.exit(1);
-}
-
-console.log(`\n🚀 Pre-Push Quality Gate`);
-console.log(`Repository: ${context.repositoryUrl}`);
-console.log(`Mode: ${context.mode}`);
-console.log(`Package: ${context.packageName} v${context.packageVersion}\n`);
-```
-
-### 2. Check for Uncommitted Changes
-
-```bash
-git status --porcelain
-```
-
-If output is not empty, fail with message:
-```
-❌ Uncommitted changes detected!
-
-Please commit or stash changes before pushing:
-  git add .
-  git commit -m "your message"
-```
-
-### 3. Check for Merge Conflicts
-
-```bash
-git diff --check
-```
-
-If conflicts detected, fail with message:
-```
-❌ Merge conflicts detected!
-
-Resolve conflicts before pushing.
-```
-
-### 4. Run npm run lint (if script exists)
-
-```javascript
-function runNpmScript(scriptName, projectRoot) {
-  const packageJsonPath = path.join(projectRoot, 'package.json');
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-
-  if (!packageJson.scripts || !packageJson.scripts[scriptName]) {
-    console.log(`⚠️  Script "${scriptName}" not found - skipping`);
-    return { skipped: true };
-  }
-
-  try {
-    execSync(`npm run ${scriptName}`, {
-      cwd: projectRoot,
-      stdio: 'inherit'
-    });
-    console.log(`✓ ${scriptName} PASSED`);
-    return { passed: true };
-  } catch (error) {
-    console.error(`❌ ${scriptName} FAILED`);
-    return { passed: false, error };
-  }
-}
-```
-
-### 5. Run npm test (if script exists)
-
-Same logic as lint, but for `npm test`.
-
-### 6. Run npm run typecheck (if script exists)
-
-Same logic as lint, but for `npm run typecheck`.
-
-### 7. Run npm run build (if script exists)
-
-Same logic as lint, but for `npm run build`.
-
-### 8. Run CodeRabbit CLI Review (TR-3.14.12)
-
-```javascript
-const { execSync } = require('child_process');
-
-function runCodeRabbitReview(projectRoot) {
-  console.log('\n🐰 Running CodeRabbit CLI Review...');
-  console.log('⏱️  This may take 7-30 minutes. Please wait...\n');
-
-  try {
-    // Construct WSL command with proper paths
-    const wslProjectPath = projectRoot
-      .replace(/\\/g, '/')
-      .replace(/^([A-Z]):/, (match, drive) => `/mnt/${drive.toLowerCase()}`);
-
-    const coderabbitCommand = `wsl bash -c 'cd ${wslProjectPath} && ~/.local/bin/coderabbit --prompt-only -t uncommitted'`;
-
-    console.log(`Executing: ${coderabbitCommand}\n`);
-
-    // Execute with 15-minute timeout
-    const output = execSync(coderabbitCommand, {
-      cwd: projectRoot,
-      encoding: 'utf8',
-      timeout: 900000, // 15 minutes
-      stdio: 'pipe',
-      maxBuffer: 10 * 1024 * 1024 // 10MB buffer
-    });
-
-    // Parse CodeRabbit output
-    const results = parseCodeRabbitOutput(output);
-
-    console.log(`\n✅ CodeRabbit Review Complete:`);
-    console.log(`  - CRITICAL: ${results.critical}`);
-    console.log(`  - HIGH: ${results.high}`);
-    console.log(`  - MEDIUM: ${results.medium}`);
-    console.log(`  - LOW: ${results.low}`);
-
-    // Determine gate impact
-    const gateImpact = determineCodeRabbitGate(results);
-
-    return { gateImpact, results, rawOutput: output };
-  } catch (error) {
-    // Handle timeout
-    if (error.killed && error.signal === 'SIGTERM') {
-      console.error('❌ CodeRabbit review timed out after 15 minutes');
-      console.error('   Review may still be processing. Check manually.');
-      return { gateImpact: 'FAIL', error: 'Timeout', timeout: true };
-    }
-
-    // Handle authentication errors
-    if (error.stderr && error.stderr.includes('not authenticated')) {
-      console.error('❌ CodeRabbit not authenticated');
-      console.error('   Run: wsl bash -c "~/.local/bin/coderabbit auth status"');
-      return { gateImpact: 'FAIL', error: 'Not authenticated' };
-    }
-
-    // Handle command not found
-    if (error.stderr && error.stderr.includes('command not found')) {
-      console.error('❌ CodeRabbit CLI not found in WSL');
-      console.error('   Expected location: ~/.local/bin/coderabbit');
-      console.error('   Verify: wsl bash -c "~/.local/bin/coderabbit --version"');
-      return { gateImpact: 'FAIL', error: 'Not installed' };
-    }
-
-    // Generic error with output for debugging
-    console.error('❌ CodeRabbit review failed:', error.message);
-    if (error.stdout) {
-      console.log('Output:', error.stdout.toString().substring(0, 500));
-    }
-    return { gateImpact: 'CONCERNS', error: error.message };
-  }
-}
-
-function parseCodeRabbitOutput(output) {
-  // CodeRabbit outputs issues with type markers
-  const lines = output.split('\n');
-
-  let critical = 0;
-  let high = 0;
-  let medium = 0;
-  let low = 0;
-
-  for (const line of lines) {
-    // Check for issue type markers
-    if (line.includes('Type: critical') || line.match(/\bCRITICAL\b/i)) {
-      critical++;
-    } else if (line.includes('Type: high') || line.match(/\bHIGH\b/i)) {
-      high++;
-    } else if (line.includes('Type: potential_issue') || line.match(/\bMEDIUM\b/i)) {
-      medium++;
-    } else if (line.includes('Type: refactor_suggestion') || line.match(/\bLOW\b/i)) {
-      low++;
-    }
-  }
-
-  return { critical, high, medium, low };
-}
-
-function determineCodeRabbitGate(results) {
-  // CRITICAL issues = auto-fail (block push)
-  if (results.critical > 0) {
-    console.log(`\n❌ FAIL: ${results.critical} CRITICAL issue(s) found - MUST FIX`);
-    return 'FAIL';
-  }
-
-  // HIGH issues = concerns (warn but allow push)
-  if (results.high > 0) {
-    console.log(`\n⚠️  CONCERNS: ${results.high} HIGH issue(s) found - recommend fix`);
-    return 'CONCERNS';
-  }
-
-  // Only MEDIUM or LOW = pass with notes
-  if (results.medium > 0 || results.low > 0) {
-    console.log(`\n✅ PASS: Only ${results.medium} MEDIUM and ${results.low} LOW issues`);
-  } else {
-    console.log(`\n✅ PASS: No issues found`);
-  }
-
-  return 'PASS';
-}
-```
-
-**Usage in pre-push flow:**
-```javascript
-const coderabbitResult = runCodeRabbitReview(process.cwd());
-
-if (coderabbitResult.gateImpact === 'FAIL') {
-  console.error('\n❌ CodeRabbit quality gate FAILED - cannot push');
-  process.exit(1);
-}
-
-if (coderabbitResult.gateImpact === 'CONCERNS') {
-  // Ask user for confirmation
-  const { confirm } = await inquirer.prompt([{
-    type: 'confirm',
-    name: 'confirm',
-    message: 'CodeRabbit found HIGH issues. Continue anyway?',
-    default: false
-  }]);
-
-  if (!confirm) {
-    console.log('Push cancelled - please address HIGH issues');
-    process.exit(2);
-  }
-}
-```
-
-### 9. Run Security Scan (TR-3.14.11)
-
-```javascript
-const { execSync } = require('child_process');
-const path = require('path');
-
-function runSecurityScan(storyId, storyPath, projectRoot) {
-  console.log('\n🔒 Running Security Scan (SAST)...\n');
-
-  try {
-    // Execute security-scan.md task
-    const securityScanPath = path.join(__dirname, 'security-scan.md');
-
-    // For now, run security checks directly
-    const results = {
-      audit: runNpmAudit(projectRoot),
-      eslint: runESLintSecurity(projectRoot),
-      secrets: runSecretDetection(projectRoot)
-    };
-
-    // Determine gate impact
-    const gateImpact = determineSecurityGate(results);
-
-    console.log(`\nSecurity Scan Complete: ${gateImpact}`);
-
-    return { gateImpact, results };
-  } catch (error) {
-    console.error('❌ Security scan failed:', error.message);
-    return { gateImpact: 'FAIL', error };
-  }
-}
-
-function runNpmAudit(projectRoot) {
-  try {
-    const output = execSync('npm audit --audit-level=moderate --json', {
-      cwd: projectRoot
-    }).toString();
-
-    const results = JSON.parse(output);
-    const vulns = results.metadata?.vulnerabilities || {};
-
-    return {
-      critical: vulns.critical || 0,
-      high: vulns.high || 0,
-      moderate: vulns.moderate || 0,
-      low: vulns.low || 0,
-      gate: vulns.critical > 0 ? 'FAIL' : (vulns.high > 0 ? 'CONCERNS' : 'PASS')
-    };
-  } catch (error) {
-    // npm audit exits with 1 if vulnerabilities found
-    if (error.stdout) {
-      const results = JSON.parse(error.stdout.toString());
-      const vulns = results.metadata?.vulnerabilities || {};
-
-      return {
-        critical: vulns.critical || 0,
-        high: vulns.high || 0,
-        moderate: vulns.moderate || 0,
-        low: vulns.low || 0,
-        gate: vulns.critical > 0 ? 'FAIL' : (vulns.high > 0 ? 'CONCERNS' : 'PASS')
-      };
-    }
-
-    console.warn('⚠️  npm audit failed - skipping dependency check');
-    return { gate: 'PASS', skipped: true };
-  }
-}
-
-function runESLintSecurity(projectRoot) {
-  // Check if ESLint security config exists
-  const eslintConfigPath = path.join(projectRoot, '.eslintrc.security.json');
-
-  if (!fs.existsSync(eslintConfigPath)) {
-    console.log('⚠️  .eslintrc.security.json not found - skipping ESLint security');
-    return { gate: 'PASS', skipped: true };
-  }
-
-  try {
-    execSync('npx eslint . --ext .js,.ts --config .eslintrc.security.json', {
-      cwd: projectRoot,
-      stdio: 'pipe'
-    });
-
-    return { gate: 'PASS', issues: 0 };
-  } catch (error) {
-    // ESLint exits with 1 if issues found
-    const output = error.stdout?.toString() || '';
-    const errorCount = (output.match(/error/g) || []).length;
-    const warningCount = (output.match(/warning/g) || []).length;
-
-    return {
-      gate: errorCount > 0 ? 'FAIL' : (warningCount > 0 ? 'CONCERNS' : 'PASS'),
-      errors: errorCount,
-      warnings: warningCount
-    };
-  }
-}
-
-function runSecretDetection(projectRoot) {
-  try {
-    execSync('npx secretlint "**/*"', {
-      cwd: projectRoot,
-      stdio: 'pipe'
-    });
-
-    return { gate: 'PASS', secretsFound: 0 };
-  } catch (error) {
-    // secretlint exits with 1 if secrets found
-    return { gate: 'FAIL', secretsFound: 1 };
-  }
-}
-
-function determineSecurityGate(results) {
-  // Secrets are auto-fail
-  if (results.secrets.gate === 'FAIL') return 'FAIL';
-
-  // Any FAIL → overall FAIL
-  if (results.audit.gate === 'FAIL' || results.eslint.gate === 'FAIL') return 'FAIL';
-
-  // Any CONCERNS → overall CONCERNS
-  if (results.audit.gate === 'CONCERNS' || results.eslint.gate === 'CONCERNS') return 'CONCERNS';
-
-  // All PASS → overall PASS
-  return 'PASS';
-}
-```
-
-### 10. Verify Story Status (Optional - if using story-driven workflow)
-
-```javascript
-function checkStoryStatus(storyPath) {
-  if (!storyPath || !fs.existsSync(storyPath)) {
-    console.log('⚠️  No story file specified - skipping story status check');
-    return { skipped: true };
-  }
-
-  const storyContent = fs.readFileSync(storyPath, 'utf8');
-
-  // Look for status: "Done" or status: "Ready for Review"
-  const statusMatch = storyContent.match(/status:\s*["']?(Done|Ready for Review|InProgress)["']?/i);
-
-  if (!statusMatch) {
-    console.log('⚠️  Unable to determine story status - skipping');
-    return { skipped: true };
-  }
-
-  const status = statusMatch[1];
-
-  if (status === 'Done' || status === 'Ready for Review') {
-    console.log(`✓ Story status: ${status}`);
-    return { passed: true, status };
-  } else {
-    console.log(`⚠️  Story status: ${status} (expected Done or Ready for Review)`);
-    return { passed: false, status };
-  }
-}
-```
-
-## Summary Report
-
-After all checks complete, present summary:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🚀 Pre-Push Quality Gate Summary
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Repository:  {repositoryUrl}
-Package:     {packageName} v{version}
-Mode:        {framework-development | project-development}
-
-Quality Checks:
-  ✓ No uncommitted changes
-  ✓ No merge conflicts
-  ✓ npm run lint         PASSED
-  ✓ npm test             PASSED
-  ✓ npm run typecheck    PASSED
-  ✓ npm run build        PASSED
-  ✓ Security scan        PASSED
-  ⚠️ Story status         SKIPPED (no story file)
-
-Security Scan Results:
-  ✓ Dependencies: 0 critical, 0 high, 2 moderate, 5 low
-  ✓ Code patterns: No security issues
-  ✓ Secrets: No secrets detected
-
-Overall Status: ✅ READY TO PUSH
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Proceed with push to remote? (Y/n)
-```
-
-### If FAIL status:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-❌ Pre-Push Quality Gate FAILED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Quality Checks:
-  ❌ npm test             FAILED
-  ❌ Security scan        FAILED (CRITICAL vulnerabilities)
-
-Security Issues:
-  ❌ Dependencies: 2 CRITICAL, 5 HIGH vulnerabilities
-  ❌ Secrets: 1 API key detected in config/db.js
-
-Overall Status: ❌ BLOCKED - Cannot push to remote
-
-Action Required:
-  1. Fix failing tests
-  2. Run: npm audit fix --force
-  3. Remove secrets from codebase
-  4. Re-run quality gate
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### If CONCERNS status:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚠️  Pre-Push Quality Gate: CONCERNS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Quality Checks:
-  ✓ All tests passed
-  ⚠️ Security scan        CONCERNS (HIGH vulnerabilities)
-
-Security Issues:
-  ⚠️ Dependencies: 0 CRITICAL, 3 HIGH, 10 MODERATE vulnerabilities
-  ⚠️ Code patterns: 2 medium-severity issues
-
-Overall Status: ⚠️  CONCERNS - Review recommended
-
-Recommendations:
-  - Address HIGH vulnerabilities before production
-  - Review medium-severity code patterns
-  - Consider running: npm audit fix
-
-Proceed with push anyway? (y/N)
-```
-
-## User Approval
-
-```javascript
-async function requestPushApproval(gateStatus) {
-  if (gateStatus === 'FAIL') {
-    console.log('\n❌ Quality gate FAILED. Cannot proceed with push.');
-    process.exit(1);
-  }
-
-  const { confirm } = await inquirer.prompt([
-    {
-      type: 'confirm',
-      name: 'confirm',
-      message: gateStatus === 'PASS'
-        ? 'Proceed with push to remote?'
-        : 'Quality gate has CONCERNS. Proceed anyway?',
-      default: gateStatus === 'PASS'
-    }
-  ]);
-
-  return confirm;
-}
-```
-
-## Integration with @github-devops Agent
-
-Called via `@github-devops *pre-push` command.
-
-## Exit Codes
-
-- `0` - All checks passed, user approved
-- `1` - Quality gate failed (blocking)
-- `2` - User declined to push
-
-## Notes
-
-- Works with ANY repository (framework or project)
-- Gracefully handles missing npm scripts
-- Security scan is mandatory (TR-3.14.11)
-- User always has final approval
-- Detailed logging for troubleshooting
+# pre-push-quality-gate.md
+
+**Task**: Pre-Push Quality Gate Validation (Repository-Agnostic)
+
+**Purpose**: Execute comprehensive quality checks before pushing code to remote repository, ensuring code quality, tests, and security standards are met.
+
+**When to use**: Before pushing code to GitHub, always via `@github-devops *pre-push` command.
+
+## 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: githubDevopsPrePushQualityGate()
+responsável: Gage (Automator)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## 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:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Prerequisites
+- Git repository with changes to push
+- package.json with npm scripts (gracefully handles missing scripts)
+- Repository context detected (run `aios init` if needed)
+
+## Quality Gate Checks
+
+### 1. Repository Context Detection
+
+```javascript
+const { detectRepositoryContext } = require('./../scripts/repository-detector');
+
+const context = detectRepositoryContext();
+if (!context) {
+  console.error('❌ Unable to detect repository context');
+  console.error('Run "aios init" to configure installation mode');
+  process.exit(1);
+}
+
+console.log(`\n🚀 Pre-Push Quality Gate`);
+console.log(`Repository: ${context.repositoryUrl}`);
+console.log(`Mode: ${context.mode}`);
+console.log(`Package: ${context.packageName} v${context.packageVersion}\n`);
+```
+
+### 2. Check for Uncommitted Changes
+
+```bash
+git status --porcelain
+```
+
+If output is not empty, fail with message:
+```
+❌ Uncommitted changes detected!
+
+Please commit or stash changes before pushing:
+  git add .
+  git commit -m "your message"
+```
+
+### 3. Check for Merge Conflicts
+
+```bash
+git diff --check
+```
+
+If conflicts detected, fail with message:
+```
+❌ Merge conflicts detected!
+
+Resolve conflicts before pushing.
+```
+
+### 4. Run npm run lint (if script exists)
+
+```javascript
+function runNpmScript(scriptName, projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+  if (!packageJson.scripts || !packageJson.scripts[scriptName]) {
+    console.log(`⚠️  Script "${scriptName}" not found - skipping`);
+    return { skipped: true };
+  }
+
+  try {
+    execSync(`npm run ${scriptName}`, {
+      cwd: projectRoot,
+      stdio: 'inherit'
+    });
+    console.log(`✓ ${scriptName} PASSED`);
+    return { passed: true };
+  } catch (error) {
+    console.error(`❌ ${scriptName} FAILED`);
+    return { passed: false, error };
+  }
+}
+```
+
+### 5. Run npm test (if script exists)
+
+Same logic as lint, but for `npm test`.
+
+### 6. Run npm run typecheck (if script exists)
+
+Same logic as lint, but for `npm run typecheck`.
+
+### 7. Run npm run build (if script exists)
+
+Same logic as lint, but for `npm run build`.
+
+### 8. Run CodeRabbit CLI Review (TR-3.14.12)
+
+```javascript
+const { execSync } = require('child_process');
+
+function runCodeRabbitReview(projectRoot) {
+  console.log('\n🐰 Running CodeRabbit CLI Review...');
+  console.log('⏱️  This may take 7-30 minutes. Please wait...\n');
+
+  try {
+    // Construct WSL command with proper paths
+    const wslProjectPath = projectRoot
+      .replace(/\\/g, '/')
+      .replace(/^([A-Z]):/, (match, drive) => `/mnt/${drive.toLowerCase()}`);
+
+    const coderabbitCommand = `wsl bash -c 'cd ${wslProjectPath} && ~/.local/bin/coderabbit --prompt-only -t uncommitted'`;
+
+    console.log(`Executing: ${coderabbitCommand}\n`);
+
+    // Execute with 15-minute timeout
+    const output = execSync(coderabbitCommand, {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 900000, // 15 minutes
+      stdio: 'pipe',
+      maxBuffer: 10 * 1024 * 1024 // 10MB buffer
+    });
+
+    // Parse CodeRabbit output
+    const results = parseCodeRabbitOutput(output);
+
+    console.log(`\n✅ CodeRabbit Review Complete:`);
+    console.log(`  - CRITICAL: ${results.critical}`);
+    console.log(`  - HIGH: ${results.high}`);
+    console.log(`  - MEDIUM: ${results.medium}`);
+    console.log(`  - LOW: ${results.low}`);
+
+    // Determine gate impact
+    const gateImpact = determineCodeRabbitGate(results);
+
+    return { gateImpact, results, rawOutput: output };
+  } catch (error) {
+    // Handle timeout
+    if (error.killed && error.signal === 'SIGTERM') {
+      console.error('❌ CodeRabbit review timed out after 15 minutes');
+      console.error('   Review may still be processing. Check manually.');
+      return { gateImpact: 'FAIL', error: 'Timeout', timeout: true };
+    }
+
+    // Handle authentication errors
+    if (error.stderr && error.stderr.includes('not authenticated')) {
+      console.error('❌ CodeRabbit not authenticated');
+      console.error('   Run: wsl bash -c "~/.local/bin/coderabbit auth status"');
+      return { gateImpact: 'FAIL', error: 'Not authenticated' };
+    }
+
+    // Handle command not found
+    if (error.stderr && error.stderr.includes('command not found')) {
+      console.error('❌ CodeRabbit CLI not found in WSL');
+      console.error('   Expected location: ~/.local/bin/coderabbit');
+      console.error('   Verify: wsl bash -c "~/.local/bin/coderabbit --version"');
+      return { gateImpact: 'FAIL', error: 'Not installed' };
+    }
+
+    // Generic error with output for debugging
+    console.error('❌ CodeRabbit review failed:', error.message);
+    if (error.stdout) {
+      console.log('Output:', error.stdout.toString().substring(0, 500));
+    }
+    return { gateImpact: 'CONCERNS', error: error.message };
+  }
+}
+
+function parseCodeRabbitOutput(output) {
+  // CodeRabbit outputs issues with type markers
+  const lines = output.split('\n');
+
+  let critical = 0;
+  let high = 0;
+  let medium = 0;
+  let low = 0;
+
+  for (const line of lines) {
+    // Check for issue type markers
+    if (line.includes('Type: critical') || line.match(/\bCRITICAL\b/i)) {
+      critical++;
+    } else if (line.includes('Type: high') || line.match(/\bHIGH\b/i)) {
+      high++;
+    } else if (line.includes('Type: potential_issue') || line.match(/\bMEDIUM\b/i)) {
+      medium++;
+    } else if (line.includes('Type: refactor_suggestion') || line.match(/\bLOW\b/i)) {
+      low++;
+    }
+  }
+
+  return { critical, high, medium, low };
+}
+
+function determineCodeRabbitGate(results) {
+  // CRITICAL issues = auto-fail (block push)
+  if (results.critical > 0) {
+    console.log(`\n❌ FAIL: ${results.critical} CRITICAL issue(s) found - MUST FIX`);
+    return 'FAIL';
+  }
+
+  // HIGH issues = concerns (warn but allow push)
+  if (results.high > 0) {
+    console.log(`\n⚠️  CONCERNS: ${results.high} HIGH issue(s) found - recommend fix`);
+    return 'CONCERNS';
+  }
+
+  // Only MEDIUM or LOW = pass with notes
+  if (results.medium > 0 || results.low > 0) {
+    console.log(`\n✅ PASS: Only ${results.medium} MEDIUM and ${results.low} LOW issues`);
+  } else {
+    console.log(`\n✅ PASS: No issues found`);
+  }
+
+  return 'PASS';
+}
+```
+
+**Usage in pre-push flow:**
+```javascript
+const coderabbitResult = runCodeRabbitReview(process.cwd());
+
+if (coderabbitResult.gateImpact === 'FAIL') {
+  console.error('\n❌ CodeRabbit quality gate FAILED - cannot push');
+  process.exit(1);
+}
+
+if (coderabbitResult.gateImpact === 'CONCERNS') {
+  // Ask user for confirmation
+  const { confirm } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'confirm',
+    message: 'CodeRabbit found HIGH issues. Continue anyway?',
+    default: false
+  }]);
+
+  if (!confirm) {
+    console.log('Push cancelled - please address HIGH issues');
+    process.exit(2);
+  }
+}
+```
+
+### 9. Run Security Scan (TR-3.14.11)
+
+```javascript
+const { execSync } = require('child_process');
+const path = require('path');
+
+function runSecurityScan(storyId, storyPath, projectRoot) {
+  console.log('\n🔒 Running Security Scan (SAST)...\n');
+
+  try {
+    // Execute security-scan.md task
+    const securityScanPath = path.join(__dirname, 'security-scan.md');
+
+    // For now, run security checks directly
+    const results = {
+      audit: runNpmAudit(projectRoot),
+      eslint: runESLintSecurity(projectRoot),
+      secrets: runSecretDetection(projectRoot)
+    };
+
+    // Determine gate impact
+    const gateImpact = determineSecurityGate(results);
+
+    console.log(`\nSecurity Scan Complete: ${gateImpact}`);
+
+    return { gateImpact, results };
+  } catch (error) {
+    console.error('❌ Security scan failed:', error.message);
+    return { gateImpact: 'FAIL', error };
+  }
+}
+
+function runNpmAudit(projectRoot) {
+  try {
+    const output = execSync('npm audit --audit-level=moderate --json', {
+      cwd: projectRoot
+    }).toString();
+
+    const results = JSON.parse(output);
+    const vulns = results.metadata?.vulnerabilities || {};
+
+    return {
+      critical: vulns.critical || 0,
+      high: vulns.high || 0,
+      moderate: vulns.moderate || 0,
+      low: vulns.low || 0,
+      gate: vulns.critical > 0 ? 'FAIL' : (vulns.high > 0 ? 'CONCERNS' : 'PASS')
+    };
+  } catch (error) {
+    // npm audit exits with 1 if vulnerabilities found
+    if (error.stdout) {
+      const results = JSON.parse(error.stdout.toString());
+      const vulns = results.metadata?.vulnerabilities || {};
+
+      return {
+        critical: vulns.critical || 0,
+        high: vulns.high || 0,
+        moderate: vulns.moderate || 0,
+        low: vulns.low || 0,
+        gate: vulns.critical > 0 ? 'FAIL' : (vulns.high > 0 ? 'CONCERNS' : 'PASS')
+      };
+    }
+
+    console.warn('⚠️  npm audit failed - skipping dependency check');
+    return { gate: 'PASS', skipped: true };
+  }
+}
+
+function runESLintSecurity(projectRoot) {
+  // Check if ESLint security config exists
+  const eslintConfigPath = path.join(projectRoot, '.eslintrc.security.json');
+
+  if (!fs.existsSync(eslintConfigPath)) {
+    console.log('⚠️  .eslintrc.security.json not found - skipping ESLint security');
+    return { gate: 'PASS', skipped: true };
+  }
+
+  try {
+    execSync('npx eslint . --ext .js,.ts --config .eslintrc.security.json', {
+      cwd: projectRoot,
+      stdio: 'pipe'
+    });
+
+    return { gate: 'PASS', issues: 0 };
+  } catch (error) {
+    // ESLint exits with 1 if issues found
+    const output = error.stdout?.toString() || '';
+    const errorCount = (output.match(/error/g) || []).length;
+    const warningCount = (output.match(/warning/g) || []).length;
+
+    return {
+      gate: errorCount > 0 ? 'FAIL' : (warningCount > 0 ? 'CONCERNS' : 'PASS'),
+      errors: errorCount,
+      warnings: warningCount
+    };
+  }
+}
+
+function runSecretDetection(projectRoot) {
+  try {
+    execSync('npx secretlint "**/*"', {
+      cwd: projectRoot,
+      stdio: 'pipe'
+    });
+
+    return { gate: 'PASS', secretsFound: 0 };
+  } catch (error) {
+    // secretlint exits with 1 if secrets found
+    return { gate: 'FAIL', secretsFound: 1 };
+  }
+}
+
+function determineSecurityGate(results) {
+  // Secrets are auto-fail
+  if (results.secrets.gate === 'FAIL') return 'FAIL';
+
+  // Any FAIL → overall FAIL
+  if (results.audit.gate === 'FAIL' || results.eslint.gate === 'FAIL') return 'FAIL';
+
+  // Any CONCERNS → overall CONCERNS
+  if (results.audit.gate === 'CONCERNS' || results.eslint.gate === 'CONCERNS') return 'CONCERNS';
+
+  // All PASS → overall PASS
+  return 'PASS';
+}
+```
+
+### 10. Verify Story Status (Optional - if using story-driven workflow)
+
+```javascript
+function checkStoryStatus(storyPath) {
+  if (!storyPath || !fs.existsSync(storyPath)) {
+    console.log('⚠️  No story file specified - skipping story status check');
+    return { skipped: true };
+  }
+
+  const storyContent = fs.readFileSync(storyPath, 'utf8');
+
+  // Look for status: "Done" or status: "Ready for Review"
+  const statusMatch = storyContent.match(/status:\s*["']?(Done|Ready for Review|InProgress)["']?/i);
+
+  if (!statusMatch) {
+    console.log('⚠️  Unable to determine story status - skipping');
+    return { skipped: true };
+  }
+
+  const status = statusMatch[1];
+
+  if (status === 'Done' || status === 'Ready for Review') {
+    console.log(`✓ Story status: ${status}`);
+    return { passed: true, status };
+  } else {
+    console.log(`⚠️  Story status: ${status} (expected Done or Ready for Review)`);
+    return { passed: false, status };
+  }
+}
+```
+
+## Summary Report
+
+After all checks complete, present summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🚀 Pre-Push Quality Gate Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Repository:  {repositoryUrl}
+Package:     {packageName} v{version}
+Mode:        {framework-development | project-development}
+
+Quality Checks:
+  ✓ No uncommitted changes
+  ✓ No merge conflicts
+  ✓ npm run lint         PASSED
+  ✓ npm test             PASSED
+  ✓ npm run typecheck    PASSED
+  ✓ npm run build        PASSED
+  ✓ Security scan        PASSED
+  ⚠️ Story status         SKIPPED (no story file)
+
+Security Scan Results:
+  ✓ Dependencies: 0 critical, 0 high, 2 moderate, 5 low
+  ✓ Code patterns: No security issues
+  ✓ Secrets: No secrets detected
+
+Overall Status: ✅ READY TO PUSH
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Proceed with push to remote? (Y/n)
+```
+
+### If FAIL status:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+❌ Pre-Push Quality Gate FAILED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Quality Checks:
+  ❌ npm test             FAILED
+  ❌ Security scan        FAILED (CRITICAL vulnerabilities)
+
+Security Issues:
+  ❌ Dependencies: 2 CRITICAL, 5 HIGH vulnerabilities
+  ❌ Secrets: 1 API key detected in config/db.js
+
+Overall Status: ❌ BLOCKED - Cannot push to remote
+
+Action Required:
+  1. Fix failing tests
+  2. Run: npm audit fix --force
+  3. Remove secrets from codebase
+  4. Re-run quality gate
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### If CONCERNS status:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  Pre-Push Quality Gate: CONCERNS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Quality Checks:
+  ✓ All tests passed
+  ⚠️ Security scan        CONCERNS (HIGH vulnerabilities)
+
+Security Issues:
+  ⚠️ Dependencies: 0 CRITICAL, 3 HIGH, 10 MODERATE vulnerabilities
+  ⚠️ Code patterns: 2 medium-severity issues
+
+Overall Status: ⚠️  CONCERNS - Review recommended
+
+Recommendations:
+  - Address HIGH vulnerabilities before production
+  - Review medium-severity code patterns
+  - Consider running: npm audit fix
+
+Proceed with push anyway? (y/N)
+```
+
+## User Approval
+
+```javascript
+async function requestPushApproval(gateStatus) {
+  if (gateStatus === 'FAIL') {
+    console.log('\n❌ Quality gate FAILED. Cannot proceed with push.');
+    process.exit(1);
+  }
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: gateStatus === 'PASS'
+        ? 'Proceed with push to remote?'
+        : 'Quality gate has CONCERNS. Proceed anyway?',
+      default: gateStatus === 'PASS'
+    }
+  ]);
+
+  return confirm;
+}
+```
+
+## Integration with @github-devops Agent
+
+Called via `@github-devops *pre-push` command.
+
+## Exit Codes
+
+- `0` - All checks passed, user approved
+- `1` - Quality gate failed (blocking)
+- `2` - User declined to push
+
+## Notes
+
+- Works with ANY repository (framework or project)
+- Gracefully handles missing npm scripts
+- Security scan is mandatory (TR-3.14.11)
+- User always has final approval
+- Detailed logging for troubleshooting