trinity-method-sdk 2.0.0

package/dist/templates/shared/claude-commands/trinity-audit.md.template

@@ -0,0 +1,646 @@
+---
+description: Launch comprehensive, deterministic codebase audit with JUNO
+---
+
+# Trinity Audit
+
+**Purpose:** Launch JUNO to perform systematic, framework-agnostic codebase audit.
+
+**Primary Use Case:** Comprehensive quality assessment of any codebase (JavaScript, Python, Rust, Go, etc.)
+
+**IMPORTANT:** When the user invokes `/trinity-audit`, proceed immediately with systematic analysis. The audit is deterministic and reproducible.
+
+---
+
+## Overview
+
+`/trinity-audit` invokes **JUNO (Quality Auditor)** to perform systematic analysis using:
+- **Automated tool execution** (linters, coverage, security scanners)
+- **Universal code patterns** (works on any language)
+- **Baseline tracking** (compare against previous audits)
+- **Objective metrics** (not subjective observations)
+
+**What Makes This Audit Different:**
+- ✅ **Deterministic:** Same code = same results every time
+- ✅ **Framework-agnostic:** Works on Node.js, Python, Rust, Go, etc.
+- ✅ **Baseline tracking:** Second audit shows only NEW or PERSISTENT issues
+- ✅ **Completeness guarantee:** Explicit coverage metrics (100% of files analyzed)
+- ✅ **Tool-based:** Uses actual linters/scanners, not just file reading
+
+**Deliverable:**
+- `trinity/reports/CODEBASE-AUDIT-{date}.md` (human-readable report)
+- `trinity/reports/AUDIT-BASELINE-{date}.json` (machine-readable baseline for future comparisons)
+
+---
+
+## When to Use
+
+### ✅ Use /trinity-audit When:
+
+1. **First time auditing a codebase**
+   - Creates baseline for future comparisons
+   - Identifies ALL current issues systematically
+
+2. **After fixing audit issues**
+   - Verify fixes resolved the problems
+   - Ensure no new issues were introduced
+   - See progress: "X issues fixed, 0 new issues"
+
+3. **Before major refactoring**
+   - Establish quality baseline
+   - Track improvements over time
+
+4. **Periodic quality checks**
+   - Monthly/quarterly codebase health review
+   - Track technical debt accumulation
+
+### ⚠️ Second Audit Behavior:
+
+When a baseline exists (`trinity/reports/AUDIT-BASELINE-*.json`):
+- **FIXED issues:** ✅ Marked as resolved (celebrate!)
+- **NEW issues:** ⚠️ Flagged as introduced since last audit
+- **PERSISTENT issues:** 🔴 Still present from previous audit
+
+**Goal:** Second audit should show "0 new issues, 0 persistent issues" if you fixed everything.
+
+---
+
+## JUNO's Deterministic Audit Protocol
+
+JUNO follows a **strict, repeatable process** to ensure consistent results:
+
+### Phase 0: Baseline Check & Comparison
+
+**CRITICAL:** Load previous audit baseline if it exists.
+
+```bash
+# Check for existing baseline
+IF trinity/reports/AUDIT-BASELINE-*.json exists:
+  - Load previous findings
+  - Track what's been fixed ✅
+  - Track what's new ⚠️
+  - Track what's persistent 🔴
+  - Report: "Comparing against baseline from {date}"
+ELSE:
+  - This is first audit
+  - Create new baseline
+  - Report: "Creating new audit baseline"
+```
+
+**Output:**
+- State whether baseline exists
+- If comparing: Show baseline date
+- Set audit mode: BASELINE or COMPARISON
+
+---
+
+### Phase 1: Stack Detection (Framework-Agnostic)
+
+**Systematic discovery** of project type, language, and available tools.
+
+**Steps (execute ALL, skip none):**
+
+1. **Detect Language & Framework:**
+   ```bash
+   Check for package.json → Node.js/JavaScript/TypeScript
+   Check for Cargo.toml → Rust
+   Check for go.mod → Go
+   Check for requirements.txt, setup.py, pyproject.toml → Python
+   Check for Gemfile → Ruby
+   Check for pom.xml, build.gradle → Java
+   Check for pubspec.yaml → Flutter/Dart
+   Check for *.csproj → C#
+   ```
+
+2. **Identify ALL Source Directories:**
+   ```bash
+   Scan for: src/, lib/, app/, pkg/, internal/
+   Ignore: node_modules/, dist/, build/, target/, vendor/
+   ```
+
+3. **Count Files by Extension:**
+   ```bash
+   .js, .ts, .jsx, .tsx → JavaScript/TypeScript count
+   .py → Python count
+   .rs → Rust count
+   .go → Go count
+   .rb → Ruby count
+   .java → Java count
+   .cs → C# count
+   ```
+
+4. **Calculate Total LOC:**
+   ```bash
+   Use Bash tool: find . -name "*.{ext}" -exec wc -l {} + | tail -1
+   ```
+
+5. **Identify Available Tools:**
+   ```bash
+   Check if eslint exists: which eslint || npm list eslint
+   Check if pytest exists: which pytest
+   Check if cargo exists: which cargo
+   Check if go exists: which go
+   Document which tools are available vs unavailable
+   ```
+
+**Output:**
+```json
+{
+  "language": "JavaScript/TypeScript",
+  "framework": "Node.js",
+  "source_dirs": ["src/", "tests/"],
+  "file_counts": {"ts": 49, "json": 12},
+  "total_loc": 4632,
+  "tools_available": ["eslint", "jest", "npm"],
+  "tools_unavailable": ["cargo", "go", "pytest"]
+}
+```
+
+---
+
+### Phase 2: Automated Tool Execution (Opportunistic)
+
+**RUN ACTUAL TOOLS** to get objective metrics. Do NOT skip this phase.
+
+**For Each Available Tool:**
+
+#### If `npm run lint` or `eslint` exists:
+```bash
+npm run lint 2>&1 | tee audit-lint-output.txt
+# OR
+eslint . --format json > audit-eslint.json
+
+Parse output:
+- Count total warnings/errors
+- Extract ALL specific issues (file:line:rule)
+- Group by severity (error vs warning)
+- Save to findings array
+```
+
+#### If `npm test` or test framework exists:
+```bash
+npm run test:coverage 2>&1 | tee audit-coverage-output.txt
+# OR pytest --cov
+# OR cargo test
+# OR go test -cover
+
+Parse output:
+- Extract coverage percentage
+- Identify uncovered files
+- Count total tests passing/failing
+```
+
+#### If `npm audit` or dependency checker exists:
+```bash
+npm audit --json > audit-dependencies.json
+# OR pip-audit
+# OR cargo audit
+
+Parse output:
+- List vulnerabilities with CVE IDs
+- Group by severity (critical/high/medium/low)
+- Note outdated packages
+```
+
+#### If TypeScript compiler exists:
+```bash
+tsc --noEmit 2>&1 | tee audit-tsc-output.txt
+
+Parse output:
+- Count type errors
+- Extract specific errors (file:line)
+```
+
+**Output:**
+```json
+{
+  "tools_executed": {
+    "lint": {"run": true, "errors": 13, "warnings": 44},
+    "coverage": {"run": true, "percentage": 67},
+    "audit": {"run": true, "vulnerabilities": 0},
+    "typecheck": {"run": true, "errors": 0}
+  }
+}
+```
+
+**IMPORTANT:** Document which tools ran and which couldn't run. This is critical for reproducibility.
+
+---
+
+### Phase 3: Universal Code Analysis (Language-Agnostic)
+
+**These checks work on ANY codebase**, regardless of language or tooling.
+
+**Execute ALL checks systematically:**
+
+1. **TODO/FIXME/HACK Comments:**
+   ```bash
+   grep -rn "TODO\|FIXME\|HACK" src/ --exclude-dir=node_modules
+
+   For each match:
+   - Record file:line
+   - Extract comment text
+   - Flag as technical debt
+   ```
+
+2. **Hardcoded Secrets Detection:**
+   ```bash
+   grep -rniE "(api_key|apikey|secret|password|token|auth.*=).*['\"][a-zA-Z0-9]{20,}" src/ --exclude-dir=node_modules
+
+   Patterns to check:
+   - API_KEY = "..."
+   - password = "..."
+   - secret = "..."
+   - Bearer tokens
+   ```
+
+3. **Large File Detection:**
+   ```bash
+   find src/ -name "*.{js,ts,py,rs,go}" -exec wc -l {} + | awk '$1 > 500 {print}'
+
+   Flag files >500 LOC for review
+   ```
+
+4. **Directory Structure Depth:**
+   ```bash
+   find src/ -type d | awk -F/ 'NF > 5 {print}'
+
+   Flag deeply nested directories (>5 levels)
+   ```
+
+5. **Missing Documentation:**
+   ```bash
+   Check for README.md in root
+   Check for CONTRIBUTING.md
+   Check for API documentation (docs/ or similar)
+   ```
+
+6. **Environment File Exposure:**
+   ```bash
+   Check if .env exists AND .env.example does NOT exist
+   Check if .env is in .gitignore
+   ```
+
+**Output:**
+```json
+{
+  "universal_checks": {
+    "todo_comments": 12,
+    "hardcoded_secrets": 0,
+    "large_files": 2,
+    "deep_nesting": 0,
+    "missing_docs": false,
+    "env_exposure_risk": false
+  }
+}
+```
+
+---
+
+### Phase 4: Language-Specific Pattern Detection
+
+**Based on detected language**, check for common anti-patterns:
+
+#### JavaScript/TypeScript:
+```bash
+grep -rn "eval(" src/
+grep -rn "innerHTML.*=" src/
+grep -rn " == " src/  # Suggest === instead
+```
+
+#### Python:
+```bash
+grep -rn "exec(" src/
+grep -rn "input()" src/  # Check for validation
+```
+
+#### Rust:
+```bash
+grep -rn "unsafe" src/
+```
+
+#### Go:
+```bash
+grep -rn "go func" src/  # Check for goroutine leaks
+```
+
+**Output:** List of pattern matches with file:line
+
+---
+
+### Phase 5: Baseline Comparison (If Baseline Exists)
+
+**CRITICAL PHASE:** Compare current findings against previous audit.
+
+```json
+IF baseline exists:
+  FOR EACH issue in previous_baseline:
+    IF issue NOT in current_findings:
+      status = "FIXED" ✅
+    ELSE:
+      status = "PERSISTENT" 🔴
+
+  FOR EACH issue in current_findings:
+    IF issue NOT in previous_baseline:
+      status = "NEW" ⚠️
+    ELSE:
+      status = "PERSISTENT" 🔴
+
+  Report summary:
+  - Fixed: X issues ✅
+  - Persistent: Y issues 🔴
+  - New: Z issues ⚠️
+```
+
+**This is what prevents infinite audit cycles.**
+
+---
+
+### Phase 6: Completeness Verification
+
+**Explicitly state what was analyzed** to guarantee thoroughness.
+
+**Required Metrics:**
+
+```json
+{
+  "completeness": {
+    "files_analyzed": "49/49 (100%)",
+    "tools_executed": "3/5 available tools",
+    "universal_checks": "6/6 checks completed",
+    "language_patterns": "4/4 patterns checked",
+    "baseline_comparison": "yes" or "no (first audit)",
+    "confidence_level": "HIGH" or "MEDIUM" or "LOW"
+  }
+}
+```
+
+**Confidence Levels:**
+- **HIGH:** All available tools ran successfully, 100% file coverage
+- **MEDIUM:** Some tools unavailable, but all files analyzed
+- **LOW:** Many tools unavailable, manual analysis only
+
+---
+
+### Phase 7: Generate Findings Report
+
+**Structure findings by priority** (based on objective criteria):
+
+#### CRITICAL (P0):
+- Security vulnerabilities (CVE with CVSS > 7.0)
+- Hardcoded secrets found
+- Authentication/authorization bypasses
+- SQL injection, XSS, RCE vulnerabilities
+
+#### HIGH (P1):
+- Lint errors (not warnings)
+- Failed tests
+- Coverage below 50%
+- Outdated dependencies with known vulnerabilities
+- Type errors (if TypeScript)
+
+#### MEDIUM (P2):
+- Lint warnings
+- Coverage 50-80%
+- TODO/FIXME comments
+- Large files (>500 LOC)
+- Cyclomatic complexity >15
+
+#### LOW (P3):
+- Documentation gaps
+- Deep directory nesting
+- Minor code style issues
+
+**Each finding must include:**
+- File path
+- Line number (if applicable)
+- Issue description
+- Tool that detected it (or "manual analysis")
+- Recommendation for fix
+- Estimated effort
+
+---
+
+### Phase 8: Save Outputs
+
+**Two files created:**
+
+#### 1. Human-Readable Report: `trinity/reports/CODEBASE-AUDIT-{date}.md`
+
+```markdown
+# Codebase Audit Report
+
+**Audit Date:** {timestamp}
+**Audit Mode:** {BASELINE | COMPARISON}
+**Baseline Date:** {previous-audit-date} (if comparison)
+
+## Executive Summary
+
+**Project Type:** {type}
+**Language:** {language}
+**Framework:** {framework}
+**Total LOC:** {loc}
+**Files Analyzed:** {count}
+
+### Audit Results
+
+- **Fixed Issues:** {count} ✅ (if comparison mode)
+- **Persistent Issues:** {count} 🔴 (if comparison mode)
+- **New Issues:** {count} ⚠️ (if comparison mode)
+- **Total Issues:** {count}
+
+### Completeness Metrics
+
+- Files analyzed: 100% (49/49)
+- Tools executed: 3/5 available
+- Confidence: HIGH
+
+## Findings by Priority
+
+### 🔴 CRITICAL (Fix Immediately)
+[List with file:line references]
+
+### 🟡 HIGH (Fix This Week)
+[List with file:line references]
+
+### 🟢 MEDIUM (Improvements)
+[List with file:line references]
+
+### 💡 QUICK WINS
+[Easy fixes, <30min each]
+
+## Tool Execution Details
+
+### ESLint Results
+- Errors: {count}
+- Warnings: {count}
+[Specific issues...]
+
+### Test Coverage
+- Percentage: {percent}%
+- Uncovered files: [list]
+
+### Dependency Audit
+- Vulnerabilities: {count}
+[Specific CVEs if any...]
+
+## Universal Analysis
+
+- TODO comments: {count}
+- Large files: {count}
+- Hardcoded secrets: {count}
+
+## Recommendations
+
+[Prioritized list of actionable next steps]
+
+## Next Audit
+
+Run `/trinity-audit` again after fixing issues.
+Expected result: "0 new issues, 0 persistent issues, X fixed issues"
+
+---
+
+**Audit Complete:** {timestamp}
+**Confidence:** {HIGH|MEDIUM|LOW}
+**Baseline Saved:** trinity/reports/AUDIT-BASELINE-{date}.json
+```
+
+#### 2. Machine-Readable Baseline: `trinity/reports/AUDIT-BASELINE-{date}.json`
+
+```json
+{
+  "audit_id": "2025-12-21-001",
+  "timestamp": "2025-12-21T12:00:00Z",
+  "project": {
+    "language": "JavaScript/TypeScript",
+    "framework": "Node.js",
+    "total_loc": 4632,
+    "files_analyzed": 49
+  },
+  "tools": {
+    "lint": {"run": true, "errors": 13, "warnings": 44},
+    "coverage": {"run": true, "percentage": 67},
+    "audit": {"run": true, "vulnerabilities": 0}
+  },
+  "findings": [
+    {
+      "id": "lint-001",
+      "file": "src/cli/commands/deploy/configuration.ts",
+      "line": 31,
+      "severity": "HIGH",
+      "category": "complexity",
+      "description": "Cyclomatic complexity 21 exceeds limit of 15",
+      "tool": "eslint"
+    }
+    // ... all findings
+  ],
+  "completeness": {
+    "file_coverage": "100%",
+    "tools_available": 3,
+    "tools_unavailable": 2,
+    "confidence": "HIGH"
+  }
+}
+```
+
+---
+
+## Work Order Creation
+
+**After audit completes**, create work order files for CRITICAL and HIGH issues.
+
+**Naming:** `WO-AUDIT-{XXX}-{short-desc}-{date}.md`
+
+**Create ONE work order per issue type:**
+- WO-AUDIT-001-fix-cyclomatic-complexity-2025-12-21.md
+- WO-AUDIT-002-increase-test-coverage-2025-12-21.md
+- WO-AUDIT-003-remove-unused-code-2025-12-21.md
+
+**Each work order includes:**
+- Specific files/lines affected
+- Objective acceptance criteria
+- Estimated effort
+- Testing requirements
+
+---
+
+## Example: Second Audit (Comparison Mode)
+
+```bash
+User: /trinity-audit
+
+JUNO: Loading previous audit baseline...
+
+✅ Baseline found: AUDIT-BASELINE-2025-12-20.json
+📊 Comparing current state against previous audit
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Audit Results:**
+
+✅ FIXED: 3 issues
+   - Cyclomatic complexity in configuration.ts (FIXED)
+   - Unused variables in deploy.ts (FIXED)
+   - Missing return type in metrics.ts (FIXED)
+
+🔴 PERSISTENT: 0 issues
+   (All previously identified issues have been resolved!)
+
+⚠️ NEW: 0 issues
+   (No new problems introduced since last audit!)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Summary:**
+✨ Codebase quality improved since last audit!
+✨ All identified issues resolved
+✨ No regressions detected
+
+**Recommendation:** You're done! The codebase is in excellent shape.
+
+**Audit saved:** trinity/reports/CODEBASE-AUDIT-2025-12-21.md
+**Baseline updated:** trinity/reports/AUDIT-BASELINE-2025-12-21.json
+```
+
+**This is how the cycle ends.**
+
+---
+
+## Summary
+
+### Key Principles
+
+1. **Deterministic:** Same code = same findings (tool-based, not subjective)
+2. **Framework-Agnostic:** Works on any language
+3. **Baseline Tracking:** Second audit shows only changes
+4. **Completeness Guarantee:** Explicit metrics (100% coverage stated)
+5. **Objective Criteria:** Linting errors, not "feels complex"
+
+### Typical Workflow
+
+```bash
+# First audit (creates baseline)
+/trinity-audit
+# → Finds 10 issues, creates baseline
+
+# Fix all issues
+/trinity-orchestrate @WO-AUDIT-001.md
+/trinity-orchestrate @WO-AUDIT-002.md
+
+# Second audit (comparison mode)
+/trinity-audit
+# → Result: "10 fixed, 0 persistent, 0 new" ✅ DONE
+```
+
+### When Are You Done?
+
+You're done when the second audit shows:
+- **0 persistent issues** (everything from first audit fixed)
+- **0 new issues** (fixes didn't introduce problems)
+
+**No infinite loop. Clear completion criteria.**
+
+---
+
+**Next:** After audit, execute work orders with `/trinity-orchestrate @WO-AUDIT-XXX.md`