@northbridge-security/secureai 0.1.13

package/docs/guides/agents.sonar.md

@@ -0,0 +1,857 @@
+# SonarQube Integration Guide for AI Agents
+
+This guide explains how AI agents can integrate with SonarQube/SonarCloud for automated code quality analysis, security scanning, and PR review workflows. Target audience: AI code assistants working with repositories that use SonarQube for quality gates.
+
+## Overview
+
+SonarQube provides automated code quality and security analysis integrated into CI/CD workflows. AI agents can download analysis results programmatically, review findings, and fix issues automatically without requiring manual SonarCloud UI access.
+
+**Key capabilities:**
+
+- Download complete analysis results via GoTask commands
+- Parse issues and security hotspots from downloaded reports
+- Address findings programmatically (fix real issues, suppress false positives)
+- Integrate with `/pr:fix` workflow for automated PR remediation
+- Track quality gate status and blocking issues
+
+**Supported workflows:**
+
+- **PR-based analysis**: Get issues specific to a pull request
+- **Branch analysis**: Get issues for default branch
+- **Local scanning**: Run sonar-scanner locally before pushing
+- **Automated fixes**: Bulk remediation of security hotspots and code smells
+
+## Prerequisites
+
+### Repository Requirements
+
+**Minimum setup** (may not exist in all repositories):
+
+- `sonar-project.properties` file in repository root
+- `SONAR_TOKEN` environment variable or secret
+- GitHub Actions workflow with SonarQube step (optional)
+
+**Typical structure:**
+
+```text
+repository/
+├── sonar-project.properties    # SonarQube configuration
+├── .github/
+│   ├── workflows/
+│   │   └── ci.yml             # CI workflow with SonarQube job
+│   └── actions/
+│       └── sonar/
+│           └── action.yml      # Reusable SonarQube action
+├── .env                        # Local secrets (gitignored)
+└── tasks/
+    └── sonar.yml              # GoTask automation (if using GoTask)
+```
+
+**If repository lacks SonarQube setup:**
+
+The repository may not have SonarQube configured. Check for these files before attempting analysis:
+
+```bash
+# Check for sonar-project.properties
+[ -f sonar-project.properties ] && echo "SonarQube configured" || echo "No SonarQube"
+
+# Check for SonarQube GitHub Action
+grep -r "sonar" .github/workflows/ 2>/dev/null
+```
+
+If not configured, skip SonarQube analysis or suggest setup (see [Setting Up SonarQube](#setting-up-sonarqube)).
+
+### Token Setup
+
+**For local analysis:**
+
+Add to `.env` file (gitignored):
+
+```bash
+# SonarQube/SonarCloud authentication token
+SONAR_TOKEN=your-token-here
+
+# Or use 1Password reference
+SONAR_TOKEN=op://Private/SonarCloud/API Token/token
+```
+
+**For CI/CD:**
+
+Token should be configured as GitHub secret:
+
+- **Secret name**: `SONAR_TOKEN`
+- **Where**: Repository Settings → Secrets and variables → Actions
+
+## GoTask Integration
+
+### Available Commands
+
+**Analysis commands:**
+
+```bash
+# Download complete analysis results (recommended)
+task sonar:download
+
+# View most recent downloaded report
+task sonar:issues
+
+# Run local scan (requires sonar-scanner installed)
+task sonar:scan
+```
+
+**Setup commands:**
+
+```bash
+# Install sonar-scanner CLI (macOS/Linux)
+task sonar:setup
+
+# Show all available commands
+task sonar:help
+```
+
+### Download Analysis Results
+
+The `sonar:download` command fetches complete analysis results from SonarQube API and generates a human-readable report.
+
+**What it does:**
+
+1. Detects PR context (or default branch if no PR)
+2. Fetches issues, security hotspots, and quality gate status
+3. Generates timestamped report in `.logs/sonar/`
+4. Opens report in VSCode (if available)
+
+**Example output:**
+
+```bash
+$ task sonar:download
+
+ℹ Analyzing PR #4: feat(installer): Phase 2 - Agent installation
+ℹ Project: northbridge-security_ai-toolkit
+ℹ Branch: feat/installer-ph2 → main
+
+❌ Quality Gate: ERROR
+ℹ Downloaded 237 issues + 49 hotspots → .logs/sonar/issues-20251118-115543.txt
+```
+
+**Report structure:**
+
+```text
+SonarQube Analysis Report
+=========================
+Project: northbridge-security_ai-toolkit
+Analysis: PR #4
+Date: 2025-11-18 11:55:43
+
+Quality Gate: ERROR
+Failed Conditions:
+  - coverage: 65.2% (threshold: 80%)
+  - duplicated_lines_density: 9.1% (threshold: 3%)
+
+Issues: 237
+By Severity:
+  Blocker: 4
+  Critical: 73
+  Major: 76
+  Minor: 78
+
+Security Hotspots: 49
+  To Review: 49
+  Reviewed: 0
+
+═══════════════════════════════════════════════════════════════
+DETAILED ISSUES
+═══════════════════════════════════════════════════════════════
+
+[BLOCKER] .github/workflows/approve.yml:24
+Type: CODE_SMELL
+Rule: javascript:S2076
+Message: Make sure that executing this OS command is safe here.
+───────────────────────────────────────────────────────────────
+...
+```
+
+### Programmatic Analysis
+
+**Read downloaded reports:**
+
+```bash
+# Most recent report
+REPORT=$(ls -t .logs/sonar/issues-*.txt 2>/dev/null | head -1)
+
+# Count issues by severity
+BLOCKER=$(grep "^\[BLOCKER\]" "$REPORT" | wc -l)
+CRITICAL=$(grep "^\[CRITICAL\]" "$REPORT" | wc -l)
+
+# Extract specific file issues
+grep "src/tasks/bash/utils.ts" "$REPORT"
+```
+
+**Parse raw JSON data:**
+
+```bash
+# Raw API responses are also saved
+RAW_JSON=$(ls -t .logs/sonar/issues-*-raw.json 2>/dev/null | head -1)
+
+# Extract high-severity issues
+jq '.issues[] | select(.severity == "BLOCKER" or .severity == "CRITICAL")' "$RAW_JSON"
+
+# Group by file
+jq -r '.issues[] | "\(.component | split(":")[1]):\(.line)"' "$RAW_JSON" | sort | uniq -c
+```
+
+## Analyzing Findings
+
+### Issue Categories
+
+**By severity:**
+
+- **BLOCKER**: Breaks core functionality, must fix immediately
+- **CRITICAL**: High-impact bugs or security vulnerabilities
+- **MAJOR**: Moderate-impact issues (complexity, maintainability)
+- **MINOR**: Low-impact code smells (style, minor improvements)
+
+**By type:**
+
+- **BUG**: Logic errors, incorrect behavior
+- **VULNERABILITY**: Security weaknesses
+- **CODE_SMELL**: Maintainability issues
+- **SECURITY_HOTSPOT**: Code requiring security review
+
+### Security Hotspots
+
+Security hotspots require manual review to determine if they're real vulnerabilities or false positives.
+
+**Hotspot workflow:**
+
+1. **Download report**: `task sonar:download`
+2. **Review each hotspot**: Check the code context
+3. **Determine action**:
+   - **Real issue**: Fix the vulnerability
+   - **False positive**: Add suppression comment with justification
+4. **Document decision**: Add inline comments explaining why
+
+**Hotspot severity levels:**
+
+- **HIGH**: Likely security vulnerability, immediate attention
+- **MEDIUM**: Potential security issue, review carefully
+- **LOW**: Minor security concern, low risk
+
+**Example hotspot review:**
+
+```typescript
+// Security hotspot: Command injection warning
+// Line 37: execSync('shfmt -d "' + file + '"')
+
+// Analysis:
+// - file variable comes from discoverFiles() function
+// - discoverFiles() returns file paths from filesystem
+// - Filenames could contain special characters like quotes, semicolons
+// - This creates a command injection vulnerability
+
+// FIX: Use proper shell escaping
+import { escapeShellArg } from "./utils";
+execSync("shfmt -d " + escapeShellArg(file));
+```
+
+**Example false positive:**
+
+```typescript
+// Security hotspot: Hard-coded password
+// Line 76: const token = 'github_pat_1234567890abcd';
+
+// Analysis:
+// - This is a test file (tests/integration/github-mcp.test.ts)
+// - Token is clearly a fake placeholder (sequential characters)
+// - Not a real secret
+
+// SUPPRESSION: Document false positive
+// nosemgrep: generic.secrets.security.detected-generic-secret.detected-generic-secret
+const token = "github_pat_1234567890abcd"; // Test fixture, not real secret
+```
+
+### Suppression Patterns
+
+**When to suppress:**
+
+- Test fixtures with fake credentials
+- Hardcoded commands with no user input
+- Simple regex patterns flagged as ReDoS
+- Permission checks in test cleanup code
+- Math.random() used for non-security purposes
+
+**Suppression format:**
+
+```typescript
+// SECURITY: [Explanation of why this is safe]
+// nosemgrep: [rule-id]
+[code that triggered warning]
+```
+
+**Common suppression rules:**
+
+| Issue Type         | Semgrep Rule ID                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| Generic secrets    | `generic.secrets.security.detected-generic-secret.detected-generic-secret`           |
+| Command injection  | `javascript.lang.security.audit.unsafe-exec.unsafe-exec`                             |
+| ReDoS              | `javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp` |
+| Weak crypto        | `javascript.lang.security.audit.detect-pseudorandom-usage.detect-pseudorandom-usage` |
+| Unsafe permissions | `javascript.lang.security.audit.unsafe-permissions.unsafe-permissions`               |
+
+## The /pr:fix Workflow
+
+The `/pr:fix` slash command integrates SonarQube analysis into automated PR remediation.
+
+**Workflow overview:**
+
+1. **Detect PR context** - Identifies current branch and PR number
+2. **Download PR comments** - Fetches GitHub PR review comments
+3. **Download workflow logs** - Gets CI/CD failure details
+4. **Download SonarQube analysis** - Runs `task sonar:download`
+5. **Analyze findings** - Categorizes issues by priority
+6. **Fix blocking issues** - Addresses critical/blocker issues automatically
+7. **Update PR review documentation** - Tracks progress in `.pr.review.local.md`
+
+**Usage:**
+
+```bash
+# Run in repository with open PR
+/pr:fix
+```
+
+**What it does with SonarQube:**
+
+```typescript
+// Phase 3: Download SonarQube analysis
+await bash("task sonar:download");
+
+// Read downloaded report
+const report = readFile(".logs/sonar/issues-*.txt");
+
+// Parse findings
+const blockers = parseIssues(report, "BLOCKER");
+const criticals = parseIssues(report, "CRITICAL");
+const hotspots = parseSecurityHotspots(report);
+
+// Prioritize fixes
+const mustFix = [...blockers, ...hotspots.filter((h) => h.severity === "HIGH")];
+
+// Fix each issue programmatically
+for (const issue of mustFix) {
+  await fixIssue(issue);
+}
+
+// Update documentation
+await updatePRReview({ fixed: mustFix.length, remaining: criticals.length });
+```
+
+**Example `/pr:fix` output:**
+
+```text
+Phase 3: Downloading SonarQube analysis...
+✓ Downloaded 237 issues + 49 hotspots
+
+Analyzing findings:
+- 4 BLOCKER issues (immediate fix required)
+- 73 CRITICAL issues (high priority)
+- 49 security hotspots (11 HIGH, 8 MEDIUM, 30 LOW)
+
+Fixing BLOCKER issues:
+✓ Fixed: .github/workflows/approve.yml:24 (command injection)
+✓ Fixed: .github/actions/sonar/action.yml:92 (command injection)
+✓ Fixed: src/tasks/bash/utils.ts:24 (command injection)
+✓ Fixed: src/tasks/json/utils.ts:208 (incomplete escaping)
+
+Addressing HIGH priority security hotspots:
+✓ Fixed: src/tasks/bash/format-check.ts:37 (added escapeShellArg)
+✓ Fixed: src/tasks/bash/format.ts:44 (added escapeShellArg)
+✓ Fixed: src/tasks/bash/lint.ts:34 (added escapeShellArg)
+✓ Documented: tests/integration/github-mcp.test.ts:76 (test fixture)
+
+Updated: .pr.review.local.md
+```
+
+**Result:**
+
+- All blocking issues fixed
+- Progress tracked in `.pr.review.local.md`
+- PR ready for review with clean quality gate
+
+## Setting Up SonarQube
+
+If repository doesn't have SonarQube configured, here's how to set it up.
+
+### SonarCloud Project Setup
+
+**1. Create SonarCloud project:**
+
+- Go to https://sonarcloud.io
+- Log in with GitHub account
+- Click "+ " → "Analyze new project"
+- Select repository
+- Choose "With GitHub Actions" setup method
+
+**2. Configure GitHub secret:**
+
+- Copy SonarCloud token from setup page
+- Go to GitHub repo → Settings → Secrets and variables → Actions
+- Create new secret:
+  - **Name**: `SONAR_TOKEN`
+  - **Value**: [paste token]
+
+### Configuration File
+
+Create `sonar-project.properties` in repository root:
+
+```properties
+# SonarCloud Configuration
+sonar.projectKey=organization_repository-name
+sonar.organization=organization-name
+
+# Project metadata
+sonar.projectName=Repository Name
+sonar.projectVersion=1.0
+
+# Source code
+sonar.sources=src
+sonar.tests=tests
+sonar.sourceEncoding=UTF-8
+
+# Language-specific settings
+sonar.javascript.lcov.reportPaths=.logs/coverage/lcov.info
+sonar.testExecutionReportPaths=.logs/test-results/junit.xml
+
+# Exclusions
+sonar.exclusions=\
+  **/node_modules/**,\
+  **/dist/**,\
+  **/coverage/**,\
+  **/.logs/**,\
+  **/tests/**/*.test.ts
+
+sonar.test.inclusions=\
+  tests/**/*.test.ts,\
+  **/*.test.ts
+
+# Coverage exclusions
+sonar.coverage.exclusions=\
+  tests/**,\
+  **/*.test.ts,\
+  **/types/**
+
+# Quality gate
+sonar.qualitygate.wait=false
+```
+
+**Key settings:**
+
+| Property                            | Purpose                 | Example                    |
+| ----------------------------------- | ----------------------- | -------------------------- |
+| `sonar.projectKey`                  | Unique identifier       | `org_repo-name`            |
+| `sonar.organization`                | SonarCloud organization | `your-org`                 |
+| `sonar.sources`                     | Source code directory   | `src`                      |
+| `sonar.tests`                       | Test directory          | `tests`                    |
+| `sonar.javascript.lcov.reportPaths` | Coverage report path    | `.logs/coverage/lcov.info` |
+
+### GitHub Actions Integration
+
+**Create reusable action** (`.github/actions/sonar/action.yml`):
+
+```yaml
+name: "SonarQube Analysis"
+description: "Runs SonarQube/SonarCloud analysis with sonar-scanner CLI"
+
+inputs:
+  github-token:
+    description: "GitHub token for authentication"
+    required: true
+  sonar-token:
+    description: "SonarQube/SonarCloud token for authentication"
+    required: true
+  sonar-host-url:
+    description: "SonarQube/SonarCloud host URL"
+    required: false
+    default: "https://sonarcloud.io"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install sonar-scanner
+      shell: bash
+      run: |
+        curl -sSL https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-4.8.0.2856-linux.zip -o /tmp/sonar-scanner.zip
+        unzip -q /tmp/sonar-scanner.zip -d /tmp/
+        echo "/tmp/sonar-scanner-4.8.0.2856-linux/bin" >> $GITHUB_PATH
+
+    - name: Run SonarQube analysis
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+        SONAR_TOKEN: ${{ inputs.sonar-token }}
+        HEAD_REF: ${{ github.head_ref }}
+        BASE_REF: ${{ github.base_ref }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+      run: |
+        SCANNER_ARGS="-Dsonar.host.url=${{ inputs.sonar-host-url }}"
+
+        # Add PR-specific parameters
+        if [ -n "$PR_NUMBER" ]; then
+          SCANNER_ARGS="$SCANNER_ARGS \
+            -Dsonar.pullrequest.key=${PR_NUMBER} \
+            -Dsonar.pullrequest.branch=${HEAD_REF} \
+            -Dsonar.pullrequest.base=${BASE_REF}"
+        fi
+
+        sonar-scanner $SCANNER_ARGS
+```
+
+**Add to CI workflow** (`.github/workflows/ci.yml`):
+
+```yaml
+jobs:
+  # Run SonarQube code quality analysis
+  sonarqube:
+    name: SonarQube Analysis
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    if: github.event_name == 'pull_request' && secrets.SONAR_TOKEN != ''
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for better analysis
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests with coverage
+        run: bun test --coverage
+
+      - name: Run SonarQube analysis
+        uses: ./.github/actions/sonar
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          sonar-token: ${{ secrets.SONAR_TOKEN }}
+```
+
+### GoTask Integration
+
+**Create task file** (`tasks/sonar.yml`):
+
+```yaml
+version: "3"
+
+vars:
+  SONAR_HOST: '{{.SONAR_HOST | default "https://sonarcloud.io"}}'
+
+tasks:
+  download:
+    desc: Download SonarQube analysis results
+    dotenv: [".env"]
+    cmds:
+      - |
+        # Read project key from sonar-project.properties
+        PROJECT_KEY=$(grep "^sonar.projectKey=" sonar-project.properties | cut -d'=' -f2)
+
+        # Detect PR context
+        PR_NUMBER=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number' 2>/dev/null || echo "")
+
+        # Fetch issues from SonarQube API
+        if [ -n "$PR_NUMBER" ]; then
+          ISSUES_API="{{.SONAR_HOST}}/api/issues/search?pullRequest=$PR_NUMBER&componentKeys=$PROJECT_KEY&ps=500"
+        else
+          ISSUES_API="{{.SONAR_HOST}}/api/issues/search?componentKeys=$PROJECT_KEY&ps=500"
+        fi
+
+        curl -s -X GET "$ISSUES_API" -H "Authorization: Bearer $SONAR_TOKEN" > .logs/sonar/issues.json
+```
+
+## Best Practices
+
+### For AI Agents
+
+**Always use task commands:**
+
+```bash
+# ✓ GOOD - Use task commands (logged, cached, consistent)
+task sonar:download
+
+# ✗ BAD - Direct API calls (no caching, harder to debug)
+curl -X GET "https://sonarcloud.io/api/issues/search?..." -H "Authorization: Bearer $SONAR_TOKEN"
+```
+
+**Check for SonarQube setup before using:**
+
+```typescript
+// Check if sonar-project.properties exists
+const hasSonar = existsSync("sonar-project.properties");
+
+if (!hasSonar) {
+  console.log("⚠️  SonarQube not configured in this repository");
+  return; // Skip SonarQube analysis
+}
+
+// Proceed with analysis
+await bash("task sonar:download");
+```
+
+**Parse reports programmatically:**
+
+```typescript
+// Read downloaded report
+const report = readFileSync(".logs/sonar/issues-20251118-115543.txt", "utf-8");
+
+// Extract issues by pattern matching
+const blockers = report
+  .split("\n")
+  .filter((line) => line.startsWith("[BLOCKER]"))
+  .map((line) => parseIssueLine(line));
+
+// Fix each issue
+for (const issue of blockers) {
+  await fixIssue(issue);
+}
+```
+
+**Document all suppressions:**
+
+```typescript
+// ALWAYS add explanation for suppressions
+// ✓ GOOD
+// SECURITY: Test fixture with fake GitHub token format, not a real secret
+// nosemgrep: generic.secrets.security.detected-generic-secret.detected-generic-secret
+const token = "github_pat_test123";
+
+// ✗ BAD
+// nosemgrep: generic.secrets.security.detected-generic-secret.detected-generic-secret
+const token = "github_pat_test123";
+```
+
+**Prioritize fixes:**
+
+1. **BLOCKER**: Fix immediately (breaks core functionality)
+2. **HIGH security hotspots**: Review and fix real vulnerabilities
+3. **CRITICAL**: Fix after blockers
+4. **MEDIUM/LOW hotspots**: Document false positives, defer real issues
+5. **MAJOR/MINOR**: Address in follow-up PRs
+
+### For Repository Maintainers
+
+**Quality gate targets:**
+
+- **Coverage**: ≥80% code coverage
+- **Duplication**: ≤3% duplicated code
+- **Security**: 0 vulnerabilities, 0 HIGH hotspots
+- **Maintainability**: No BLOCKER/CRITICAL code smells
+
+**Custom quality gates:**
+
+Edit in SonarCloud UI → Project → Administration → Quality Gate
+
+**Branch protection:**
+
+Require SonarQube check to pass before merging:
+
+1. GitHub → Settings → Branches
+2. Add rule for `main` branch
+3. Check "Require status checks to pass"
+4. Select "SonarQube Analysis"
+
+## Troubleshooting
+
+### Token Not Set
+
+**Error:**
+
+```text
+❌ SONAR_TOKEN not set
+Add to .env: SONAR_TOKEN=your-token
+```
+
+**Solution:**
+
+```bash
+# Add to .env file (gitignored)
+echo "SONAR_TOKEN=your-token-here" >> .env
+
+# Or use 1Password
+echo "SONAR_TOKEN=op://Private/SonarCloud/API Token/token" >> .env
+```
+
+### No Reports Found
+
+**Error:**
+
+```text
+❌ No reports found
+Run: task sonar:download
+```
+
+**Solution:**
+
+```bash
+# Download analysis first
+task sonar:download
+
+# Then view results
+task sonar:issues
+```
+
+### PR Analysis Not Found
+
+**Warning:**
+
+```text
+⚠️  PR analysis not found, showing default branch analysis
+```
+
+**Why:** SonarQube PR analysis only runs after CI completes. If viewing results before CI finishes, default branch analysis is shown instead.
+
+**Solution:** Wait for CI to complete, then run `task sonar:download` again.
+
+### Quality Gate Failed
+
+**Error:**
+
+```text
+❌ Quality Gate: ERROR
+Failed Conditions:
+  - coverage: 65.2% (threshold: 80%)
+```
+
+**Solution:**
+
+```bash
+# Check what needs to be fixed
+task sonar:download
+
+# Fix coverage
+bun test --coverage
+
+# Fix duplication
+# (Refactor duplicated code blocks)
+
+# Re-run analysis
+task sonar:scan
+```
+
+### sonar-scanner Not Found
+
+**Error:**
+
+```text
+sonar-scanner: command not found
+```
+
+**Solution:**
+
+```bash
+# Install sonar-scanner
+task sonar:setup
+
+# Verify installation
+sonar-scanner --version
+```
+
+## Examples
+
+### Example 1: Fix All Blocker Issues
+
+```bash
+# Download analysis
+task sonar:download
+
+# Read report
+REPORT=$(ls -t .logs/sonar/issues-*.txt | head -1)
+
+# Extract blocker issues
+grep "^\[BLOCKER\]" "$REPORT" | while read -r line; do
+  # Parse file and line number
+  FILE=$(echo "$line" | sed 's/\[BLOCKER\] \(.*\):.*/\1/')
+  LINE=$(echo "$line" | sed 's/.*:\([0-9]*\).*/\1/')
+
+  echo "Fixing $FILE:$LINE"
+
+  # Open in editor or apply automated fix
+  # ... implementation ...
+done
+```
+
+### Example 2: Review Security Hotspots by Priority
+
+```bash
+# Download analysis
+task sonar:download
+
+# Find HIGH priority hotspots in report
+REPORT=$(ls -t .logs/sonar/issues-*.txt | head -1)
+
+# Extract HIGH severity hotspots
+grep -A3 "^\[HIGH\]" "$REPORT" | while read -r line; do
+  case "$line" in
+    \[HIGH\]*)
+      FILE=$(echo "$line" | sed 's/\[HIGH\] \(.*\):.*/\1/')
+      echo "Review: $FILE"
+      ;;
+    Message:*)
+      echo "  → ${line#Message: }"
+      ;;
+  esac
+done
+```
+
+### Example 3: Track Fix Progress
+
+```typescript
+// Track fixes in PR review documentation
+interface FixProgress {
+  total: number;
+  fixed: number;
+  remaining: number;
+  categories: {
+    blocker: number;
+    critical: number;
+    hotspots: { high: number; medium: number; low: number };
+  };
+}
+
+async function trackProgress(): Promise<FixProgress> {
+  // Download latest analysis
+  await bash("task sonar:download");
+
+  // Read report
+  const report = readFileSync(".logs/sonar/issues-latest.txt", "utf-8");
+
+  // Count by severity
+  const blockers = (report.match(/^\[BLOCKER\]/gm) || []).length;
+  const criticals = (report.match(/^\[CRITICAL\]/gm) || []).length;
+  const highHotspots = (report.match(/^\[HIGH\].*hotspot/gim) || []).length;
+
+  return {
+    total: blockers + criticals + highHotspots,
+    fixed: 0, // Updated as fixes are applied
+    remaining: blockers + criticals + highHotspots,
+    categories: {
+      blocker: blockers,
+      critical: criticals,
+      hotspots: { high: highHotspots, medium: 0, low: 0 },
+    },
+  };
+}
+```
+
+## Related Documentation
+
+- [GoTask Usage Guide](./agents.gotask.md) - Task automation patterns
+- [Markdown Standards](./agents.markdown.md) - Documentation formatting
+- [GitHub MCP Integration](./github-mcp.md) - PR and issue management
+- [QA Standards](../QA.md) - Quality assurance guidelines
+- [SonarCloud Documentation](https://docs.sonarcloud.io) - Official docs
+
+---
+
+**For AI Agents**: Always use `task sonar:download` to fetch analysis results programmatically. Never require manual UI access. Parse downloaded reports to address findings automatically.