aidevops 2.52.1 → 2.53.2

package/.agent/tools/code-review/code-standards.md

@@ -1,309 +0,0 @@
----
-description: Documented code quality standards for compliance checking
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: false
-  task: true
----
-
-# Code Standards - Quality Rules Reference
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Purpose**: Reference documentation for code quality standards
-- **Platforms**: SonarCloud, CodeFactor, Codacy, ShellCheck
-- **Target**: A-grade across all platforms, zero critical violations
-
-**Critical Rules (Zero Tolerance)**:
-
-| Rule | Description | Pattern |
-|------|-------------|---------|
-| S7682 | Explicit return statements | `return 0` or `return 1` in every function |
-| S7679 | No direct positional params | `local param="$1"` not `$1` directly |
-| S1192 | Constants for repeated strings | `readonly MSG="text"` for 3+ uses |
-| S1481 | No unused variables | Remove or use declared variables |
-| ShellCheck | Zero violations | All scripts pass `shellcheck` |
-
-**Validation Commands**:
-
-```bash
-# Run local linting
-~/.aidevops/agents/scripts/linters-local.sh
-
-# Check specific rules
-grep -L "return [01]" .agent/scripts/*.sh  # S7682
-grep -n '\$[1-9]' .agent/scripts/*.sh | grep -v 'local.*=.*\$[1-9]'  # S7679
-```
-
-**Workflow Position**: Reference during development, validated by `/linters-local`
-
-<!-- AI-CONTEXT-END -->
-
-## Purpose
-
-This document defines the **authoritative code quality standards** for the aidevops framework. Use this as a reference during development to ensure compliance.
-
-**Related commands**:
-- `/linters-local` - Validates these standards locally
-- `/code-audit-remote` - Validates via external services
-- `/pr` - Orchestrates all checks
-
-## Critical Standards (Zero Tolerance)
-
-### S7682 - Return Statements
-
-Every function MUST have an explicit `return 0` or `return 1`.
-
-```bash
-# CORRECT - Always explicit return
-function_name() {
-    local param="$1"
-    # Function logic
-    return 0  # MANDATORY
-}
-
-# INCORRECT - Missing return statement
-function_name() {
-    local param="$1"
-    # Function logic
-}  # This causes S7682 violation
-```
-
-**Validation**:
-
-```bash
-grep -L "return [01]" .agent/scripts/*.sh
-```
-
-### S7679 - Positional Parameters
-
-NEVER use positional parameters directly. Always assign to local variables first.
-
-```bash
-# CORRECT - Local variable assignment
-main() {
-    local command="${1:-help}"
-    local account_name="$2"
-    local target="$3"
-
-    case "$command" in
-        "list")
-            list_items "$account_name"  # Use local variable
-            ;;
-    esac
-    return 0
-}
-
-# INCORRECT - Direct positional parameter usage
-main() {
-    case "$1" in  # This causes S7679 violation
-        "list")
-            list_items "$2"  # This causes S7679 violation
-            ;;
-    esac
-}
-```
-
-**Validation**:
-
-```bash
-grep -n '\$[1-9]' .agent/scripts/*.sh | grep -v 'local.*=.*\$[1-9]'
-```
-
-### S1192 - String Literals
-
-Define constants for strings used 3 or more times.
-
-```bash
-# CORRECT - Constants at file top
-readonly ERROR_ACCOUNT_REQUIRED="Account name is required"
-readonly ERROR_CONFIG_NOT_FOUND="Configuration file not found"
-readonly SUCCESS_OPERATION_COMPLETE="Operation completed successfully"
-
-# Use constants instead of literals
-print_error "$ERROR_ACCOUNT_REQUIRED"
-print_error "$ERROR_CONFIG_NOT_FOUND"
-
-# INCORRECT - Repeated string literals
-print_error "Account name is required"  # Repeated 3+ times
-print_error "Account name is required"  # Causes S1192 violation
-```
-
-**Validation**:
-
-```bash
-for file in .agent/scripts/*.sh; do
-    echo "=== $file ==="
-    grep -o '"[^"]*"' "$file" | sort | uniq -c | sort -nr | head -5
-done
-```
-
-### S1481 - Unused Variables
-
-Only declare variables that are actually used.
-
-```bash
-# CORRECT - Only used variables
-function_name() {
-    local used_param="$1"
-    echo "$used_param"
-    return 0
-}
-
-# INCORRECT - Unused variable declaration
-function_name() {
-    local used_param="$1"
-    local unused_param="$2"  # This causes S1481 violation
-    echo "$used_param"
-    return 0
-}
-```
-
-### ShellCheck Compliance
-
-All shell scripts must pass ShellCheck with zero violations.
-
-```bash
-# Validate all scripts
-find .agent/scripts/ -name "*.sh" -exec shellcheck {} \;
-
-# Validate single script
-shellcheck script.sh
-```
-
-## Security Hotspots (Acceptable Patterns)
-
-SonarCloud flags these patterns as security hotspots. They are acceptable when properly documented:
-
-### HTTP String Detection (S5332)
-
-When checking for insecure URLs, not using them:
-
-```bash
-# CORRECT - Detection with comment
-# SONAR: Detecting insecure URLs for security audit, not using them
-non_https=$(echo "$data" | jq '[.items[] | select(.url | startswith("http://"))] | length')
-
-# INCORRECT - No documentation
-non_https=$(echo "$data" | jq '[.items[] | select(.url | startswith("http://"))] | length')
-```
-
-### Localhost HTTP Output (S5332)
-
-Local development environments often lack SSL:
-
-```bash
-# CORRECT - Intentional localhost HTTP
-if [[ "$ssl" == "true" ]]; then
-    print_info "Access your app at: https://$domain"
-else
-    # SONAR: Local dev without SSL is intentional
-    print_info "Access your app at: http://$domain"
-fi
-```
-
-### Curl Pipe to Bash (S4423)
-
-For official installers from verified sources:
-
-```bash
-# CORRECT - Documented official installer
-# SONAR: Official Bun installer from verified HTTPS source
-curl -fsSL https://bun.sh/install | bash
-
-# BETTER - Download and inspect first (for new/unknown sources)
-curl -fsSL https://example.com/install.sh -o /tmp/install.sh
-less /tmp/install.sh  # Review script
-bash /tmp/install.sh
-```
-
-**When to suppress vs fix:**
-
-- **Suppress**: Official installers (bun, nvm, rustup), localhost dev, URL detection
-- **Fix**: Actual HTTP usage in production, unverified installer sources
-
-## Platform Targets
-
-### SonarCloud
-
-| Metric | Target |
-|--------|--------|
-| Quality Gate | Passed |
-| Bugs | 0 |
-| Vulnerabilities | 0 |
-| Code Smells | <50 |
-| Technical Debt | <400 minutes |
-| Security Rating | A |
-| Reliability Rating | A |
-| Maintainability Rating | A |
-
-### CodeFactor
-
-| Metric | Target |
-|--------|--------|
-| Overall Grade | A |
-| A-grade Files | >85% |
-| Critical Issues | 0 |
-
-### Codacy
-
-| Metric | Target |
-|--------|--------|
-| Grade | A |
-| Security Issues | 0 |
-| Error Prone | 0 |
-
-## Pre-Commit Checklist
-
-Before committing, verify:
-
-```bash
-# 1. Run local linting
-~/.aidevops/agents/scripts/linters-local.sh
-
-# 2. Check return statements
-grep -L "return [01]" .agent/scripts/*.sh
-
-# 3. Check positional parameters
-grep -n '\$[1-9]' .agent/scripts/*.sh | grep -v 'local.*=.*\$[1-9]'
-
-# 4. Run ShellCheck
-find .agent/scripts/ -name "*.sh" -exec shellcheck {} \;
-
-# 5. Check for secrets
-~/.aidevops/agents/scripts/secretlint-helper.sh scan
-```
-
-## Quality Scripts
-
-| Script | Purpose |
-|--------|---------|
-| `linters-local.sh` | Run all local quality checks |
-| `quality-fix.sh` | Auto-fix common issues |
-| `pre-commit-hook.sh` | Git pre-commit validation |
-| `secretlint-helper.sh` | Secret detection |
-
-## Current Status
-
-**Multi-Platform Excellence Achieved:**
-
-- **SonarCloud**: A-grade maintained
-- **CodeFactor**: A-grade overall
-- **Codacy**: Enterprise-grade compliance
-- **Critical Issues**: S7679 & S1481 = 0 (RESOLVED)
-
-## Related Documentation
-
-- **Local linting**: `scripts/linters-local.sh`
-- **Remote auditing**: `workflows/code-audit-remote.md`
-- **Unified PR review**: `workflows/pr.md`
-- **Automation guide**: `tools/code-review/automation.md`
-- **Best practices**: `tools/code-review/best-practices.md`

package/.agent/tools/code-review/coderabbit.md

@@ -1,101 +0,0 @@
----
-description: CodeRabbit AI code review integration
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# CodeRabbit Analysis Trigger
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- Purpose: Trigger CodeRabbit AI analysis on pull requests
-- Analysis scope: Shell scripts (.agent/scripts/), MCP configs, docs/
-- Goals: Code quality improvements, framework enhancements, documentation quality
-- Expected fixes: Variable quoting, error handling, return checks, path handling
-- Config validation: JSON schema, env vars, API keys, security
-- Docs fixes: Markdown linting, code blocks, links, formatting
-- Post-analysis: Review suggestions, apply auto-fixes, test, commit, close PR
-<!-- AI-CONTEXT-END -->
-
-This file is created to trigger CodeRabbit analysis and gather auto-fix recommendations.
-
-## 🎯 **Analysis Goals**
-
-### **Code Quality Improvements**
-
-- Identify potential auto-fixes for shell scripts
-- Analyze MCP integration code for best practices
-- Review documentation for consistency and clarity
-- Detect any security or performance issues
-
-### **Framework Enhancements**
-
-- Validate MCP configuration templates
-- Review setup and validation scripts
-- Analyze error handling patterns
-- Check for code duplication or optimization opportunities
-
-### **Documentation Quality**
-
-- Review Markdown formatting and structure
-- Validate code examples and snippets
-- Check for broken links or references
-- Ensure consistency across documentation files
-
-## 🔧 **Expected Auto-Fixes**
-
-### **Shell Script Improvements**
-
-- Variable quoting and expansion
-- Error handling enhancements
-- Function return value checks
-- Path handling improvements
-
-### **Configuration Validation**
-
-- JSON schema validation
-- Environment variable handling
-- API key management best practices
-- Security configuration reviews
-
-### **Documentation Enhancements**
-
-- Markdown linting fixes
-- Code block language specifications
-- Link validation and updates
-- Formatting consistency improvements
-
-## 📊 **Analysis Scope**
-
-This analysis covers:
-
-- All shell scripts in `.agent/scripts/`
-- MCP configuration templates in `configs/mcp-templates/`
-- Documentation files in `docs/`
-- Main README.md and configuration files
-- Setup and validation automation scripts
-
-## 🚀 **Post-Analysis Actions**
-
-After CodeRabbit analysis:
-
-1. Review all suggested improvements
-2. Apply auto-fixes where appropriate
-3. Implement manual fixes for complex issues
-4. Update documentation based on recommendations
-5. Re-run validation scripts to ensure functionality
-6. Commit improvements and close this PR
-
----
-
-**This PR will be closed after CodeRabbit analysis is complete and recommendations are implemented.**

package/.agent/tools/code-review/management.md

@@ -1,155 +0,0 @@
----
-description: Quality management and monitoring specification
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# Quality Management Specification
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- Methodology: Zero technical debt through systematic resolution
-- Core principle: Enhance functionality, never delete to fix issues
-- Priority order: S7679 (critical) -> S1481 -> S1192 -> S7682 -> ShellCheck
-- S7679 fix: Use `printf '%s50/month\n' '$'` instead of `echo "$50/month"`
-- S1481 fix: Enhance usage of variable or remove if truly unused
-- S1192 fix: Create `readonly CONSTANT="repeated string"` at file top
-- Key scripts: linters-local.sh, quality-fix.sh, quality-cli-manager.sh
-- Achievement: 349 -> 42 issues (88% reduction), 100% critical resolved
-- Success: Zero S7679/S1481, <10 S1192, 100% feature retention
-<!-- AI-CONTEXT-END -->
-
-## Zero Technical Debt Methodology
-
-> **Note**: This document is supplementary to the [AGENTS.md](../AGENTS.md).
-> For any conflicts, the main AGENTS.md takes precedence as the single source of truth.
-
-### Overview
-
-This document provides detailed methodology and historical context for our systematic approach to achieving zero technical debt. Current status: SonarCloud issues reduced from 349 to 66 (81% reduction) while enhancing functionality.
-
-### Core Principles
-
-#### 1. Functionality Enhancement Over Deletion
-
-- **Never remove functionality** to fix quality issues
-- **Enhance existing code** to resolve violations
-- **Add value** while addressing technical debt
-- **Preserve all user-facing features** throughout quality improvements
-
-#### 2. Systematic Priority-Based Resolution
-
-**Priority Order (SonarCloud Rule Severity):**
-
-1. **S7679 (Positional Parameters)** - Critical shell interpretation issues
-2. **S1481 (Unused Variables)** - Code clarity and maintenance
-3. **S1192 (String Literals)** - Code duplication and maintainability
-4. **S7682 (Return Statements)** - Function consistency
-5. **ShellCheck Issues** - Best practices and style
-
-#### 3. Automation-First Approach
-
-- **Create reusable tools** for each issue type
-- **Batch process** similar violations across files
-- **Document patterns** for future maintenance
-- **Build quality gates** into development workflow
-
-### Issue Resolution Patterns
-
-#### Positional Parameters (S7679) - RESOLVED ✅
-
-**Problem**: Shell interpreting `$50`, `$200` as positional parameters
-**Solution**: Use printf format strings
-
-```bash
-# ❌ BEFORE (triggers S7679)
-echo "Price: $50/month"
-
-# ✅ AFTER (compliant)
-printf 'Price: %s50/month\n' '$'
-```
-
-#### Unused Variables (S1481) - RESOLVED ✅
-
-**Problem**: Variables assigned but never used
-**Solutions**:
-
-1. **Enhance functionality** (preferred)
-2. **Remove if truly unused**
-3. **Use in logging/debugging**
-
-```bash
-# ❌ BEFORE (unused variable)
-local port
-read -r port
-
-# ✅ AFTER (enhanced functionality)
-local port
-read -r port
-if [[ -n "$port" && "$port" != "22" ]]; then
-    ssh -p "$port" "$host"
-else
-    ssh "$host"
-fi
-```
-
-#### String Literals (S1192) - MAJOR PROGRESS 📊
-
-**Problem**: Repeated string literals (3+ occurrences)
-**Solution**: Create readonly constants
-
-```bash
-# ❌ BEFORE (repeated literals)
-curl -H "Content-Type: application/json"
-curl -H "Content-Type: application/json"
-curl -H "Content-Type: application/json"
-
-# ✅ AFTER (constant usage)
-readonly CONTENT_TYPE_JSON="Content-Type: application/json"
-curl -H "$CONTENT_TYPE_JSON"
-curl -H "$CONTENT_TYPE_JSON"
-curl -H "$CONTENT_TYPE_JSON"
-```
-
-### Quality Tools & Scripts
-
-#### Automated Quality Tools
-
-- **linters-local.sh**: Comprehensive multi-platform quality validation
-- **fix-content-type.sh**: Content-Type header consolidation
-- **fix-auth-headers.sh**: Authorization header standardization
-- **fix-error-messages.sh**: Common error message constants
-- **markdown-formatter.sh**: Markdown quality compliance
-
-#### Quality CLI Integration
-
-- **CodeRabbit CLI**: AI-powered code review
-- **Codacy CLI v2**: Comprehensive static analysis
-- **SonarScanner CLI**: SonarCloud integration
-- **quality-cli-manager.sh**: Unified CLI management
-
-### Measurement & Tracking
-
-#### Key Metrics
-
-- **SonarCloud Issues**: 349 → 42 (88% reduction)
-- **Critical Violations**: S7679 & S1481 = 0 (100% resolved)
-- **String Literals**: 50+ violations eliminated
-- **Code Quality**: A-grade maintained across platforms
-
-#### Success Criteria
-
-- **Zero Critical Issues**: S7679, S1481 completely resolved
-- **Minimal String Duplication**: <10 S1192 violations
-- **ShellCheck Compliance**: <5 critical violations per file
-- **Functionality Preservation**: 100% feature retention