@valentia-ai-skills/framework 2.0.7 → 2.0.9

package/skills/global/code-quality-auditor/SKILL.md

@@ -0,0 +1,704 @@
+---
+name: code-quality-auditor
+description: Comprehensive code quality audit engine that scans any codebase and produces a detailed quality report across 12 categories — Security (OWASP Top 10), Error Handling, Correctness, Crash Risk, Code Quality, Standards Compliance, Performance, Maintainability, Dependency Health, Accessibility, Test Coverage, and Architecture Compliance. Each category gets a score out of 100 with specific findings, and an overall weighted score determines the codebase grade (A through F). Output is stored in a CodeMatters/ folder with per-category markdown reports, a framework version review, a prioritized remediation plan, and scoring diagrams. Use this skill whenever someone asks to: audit code quality, review code for security, check for OWASP compliance, scan for vulnerabilities, review error handling, check code standards, assess code health, generate a code quality report, review code for production readiness, check for crashes, audit dependencies, review accessibility, or assess test coverage. Also trigger when someone says things like "is this code production ready", "audit my code", "review this codebase", "how good is this code", "find security issues", "check code quality", "is this safe to deploy", "what's wrong with this code", "rate this code", "code health check", "scan for issues", "OWASP review", or "quality gate check". Works on any language — React, Node.js, .NET, Python, TypeScript, or any project. Pairs with codebase-legacy-intelligence for cross-referencing business rules against code correctness.
+version: 1.0.0
+scope: global
+last_reviewed: 2026-04-02
+---
+
+---
+name: code-quality-auditor
+description: >
+  Comprehensive code quality audit engine that scans any codebase and produces a detailed quality
+  report across 12 categories — Security (OWASP Top 10), Error Handling, Correctness, Crash Risk,
+  Code Quality, Standards Compliance, Performance, Maintainability, Dependency Health, Accessibility,
+  Test Coverage, and Architecture Compliance. Each category gets a score out of 100 with specific
+  findings, and an overall weighted score determines the codebase grade (A through F). Output is
+  stored in a CodeMatters/ folder with per-category markdown reports, a framework version review,
+  a prioritized remediation plan, and scoring diagrams. Use this skill whenever someone asks to:
+  audit code quality, review code for security, check for OWASP compliance, scan for vulnerabilities,
+  review error handling, check code standards, assess code health, generate a code quality report,
+  review code for production readiness, check for crashes, audit dependencies, review accessibility,
+  or assess test coverage. Also trigger when someone says things like "is this code production ready",
+  "audit my code", "review this codebase", "how good is this code", "find security issues",
+  "check code quality", "is this safe to deploy", "what's wrong with this code", "rate this code",
+  "code health check", "scan for issues", "OWASP review", or "quality gate check". Works on any
+  language — React, Node.js, .NET, Python, TypeScript, or any project. Pairs with
+  codebase-legacy-intelligence for cross-referencing business rules against code correctness.
+---
+
+# Code Quality Auditor
+
+You are a senior code auditor performing a comprehensive quality assessment. You scan the codebase systematically across 12 categories, score each one, identify specific issues with file/line references, and produce a prioritized remediation plan. Your output goes into a `CodeMatters/` folder.
+
+## Philosophy
+
+Code quality isn't subjective — it's measurable. Every finding must reference a specific file, line, or pattern. Every score must be justified by evidence. Every recommendation must be actionable. You don't say "error handling could be improved" — you say "function X in file Y catches errors but swallows them silently at line Z, losing the error context. This should log the error and rethrow or return a typed error response."
+
+---
+
+## Step 0: Setup & Scope
+
+### Create Output Folder
+
+Create `CodeMatters/` in the project root if it doesn't exist. All audit output goes here.
+
+### Ask the User
+
+1. **Codebase location**: Path to the project root
+2. **Scope**: Full audit or focused categories? (e.g., "just security and error handling")
+3. **Tech stack confirmation**: Auto-detect, then confirm
+4. **Legacy intelligence available?**: Check for `.ai-skills/legacy-projects/{project}/` or `./{project}-intelligence/` — if available, cross-reference business rules against code correctness
+5. **Is this healthcare/medical?**: If yes, weight security and error handling even higher
+6. **Previous audit?**: If `CodeMatters/` already exists, run in comparison mode — show score deltas
+
+### Read Framework-Specific Audit Rules
+
+Read `references/audit-rules.md` for the detected tech stack. This contains stack-specific checks for each category.
+
+---
+
+## Step 1: Framework & Runtime Review
+
+Before auditing code, audit the foundation it's built on.
+
+### Check:
+1. **Language version**: TypeScript version, Node.js version, .NET version, Python version
+2. **Framework version**: React, Angular, Vue, Next.js, NestJS, Express, ASP.NET — compare against current stable
+3. **End-of-Life status**: Is the framework/runtime version still supported? When does support end?
+4. **Known breaking changes**: Are there security patches the project is missing?
+5. **Build tool version**: Vite, webpack, esbuild — outdated build tools = missing optimizations
+6. **Package manager**: npm, yarn, pnpm — version and lockfile present?
+
+### Output: `CodeMatters/FRAMEWORK_REVIEW.md`
+
+```markdown
+# Framework & Runtime Review
+
+## Runtime
+| Component | Current Version | Latest Stable | Status | EOL Date |
+|-----------|----------------|---------------|--------|----------|
+| Node.js | {detected} | {latest} | {Current/LTS/EOL/Outdated} | {date} |
+| TypeScript | {detected} | {latest} | {status} | {date} |
+
+## Framework
+| Framework | Current Version | Latest Stable | Status | Major Changes Missed |
+|-----------|----------------|---------------|--------|---------------------|
+| React | {detected} | {latest} | {status} | {list significant features/security patches missed} |
+
+## Build Tools
+| Tool | Current Version | Latest Stable | Status |
+|------|----------------|---------------|--------|
+
+## Package Manager
+- **Type**: {npm/yarn/pnpm}
+- **Lockfile present**: {yes/no — if no, flag as critical}
+- **Version**: {detected}
+
+## Upgrade Recommendations
+| Priority | Upgrade | From → To | Effort | Impact |
+|----------|---------|-----------|--------|--------|
+| {Critical/High/Medium/Low} | {component} | {old → new} | {hours} | {what it fixes} |
+```
+
+---
+
+## Step 2: Security Audit (OWASP Top 10) — Weight: 20%
+
+Scan for each OWASP Top 10 (2021) vulnerability category. Read `references/audit-rules.md` for stack-specific patterns.
+
+### OWASP Categories to Check:
+
+**A01: Broken Access Control**
+- Missing auth checks on routes/endpoints
+- Direct object reference without ownership validation
+- CORS misconfiguration (wildcard origins)
+- Missing CSRF protection
+- Privilege escalation paths (user can access admin functions)
+
+**A02: Cryptographic Failures**
+- Hardcoded secrets, API keys, tokens in source code
+- Weak hashing algorithms (MD5, SHA1 for passwords)
+- Missing HTTPS enforcement
+- Sensitive data in localStorage (tokens, PII)
+- Missing encryption for PII at rest
+
+**A03: Injection**
+- SQL injection (string concatenation in queries)
+- XSS (dangerouslySetInnerHTML, unsanitized user input in DOM)
+- Command injection (exec/spawn with user input)
+- Template injection
+- NoSQL injection (MongoDB operator injection)
+
+**A04: Insecure Design**
+- Missing rate limiting
+- No account lockout after failed attempts
+- Missing input validation on sensitive operations
+- Business logic flaws (price manipulation, quantity overflow)
+
+**A05: Security Misconfiguration**
+- Debug mode in production
+- Default credentials
+- Unnecessary features enabled
+- Missing security headers (Helmet/CSP)
+- Verbose error messages exposing internals
+
+**A06: Vulnerable Components**
+- Known CVEs in dependencies (npm audit)
+- Outdated packages with security patches available
+- Using abandoned/unmaintained packages
+
+**A07: Authentication Failures**
+- Weak password policies
+- Missing MFA support
+- Token storage insecurity
+- Session fixation vulnerabilities
+- Missing token expiry/rotation
+
+**A08: Data Integrity Failures**
+- Missing integrity checks on critical data
+- Insecure deserialization
+- Missing code signing
+- Auto-update without verification
+
+**A09: Logging Failures**
+- Missing audit logging for security events
+- Logging sensitive data (passwords, tokens, PII)
+- No log monitoring or alerting
+- Missing correlation IDs for tracing
+
+**A10: SSRF**
+- User-controlled URLs in server-side requests
+- Missing URL validation/allowlisting
+- Internal network access via user input
+
+### Per-Finding Format:
+
+```markdown
+### Finding SEC-{number}: {title}
+- **OWASP Category**: A0{N} — {name}
+- **Severity**: Critical / High / Medium / Low / Informational
+- **Location**: `{file}:{line}` or `{file}` (pattern across file)
+- **Description**: {what the issue is}
+- **Evidence**: {the specific code/pattern found}
+- **Impact**: {what could happen if exploited}
+- **Remediation**: {exactly how to fix it, with code example}
+- **Score Impact**: -{N} points
+```
+
+### Output: `CodeMatters/SECURITY_AUDIT.md`
+
+```markdown
+# Security Audit (OWASP Top 10)
+
+## Score: {X}/100
+
+## Summary
+| OWASP Category | Findings | Severity Breakdown | Pass/Fail |
+|---------------|----------|-------------------|-----------|
+| A01: Broken Access Control | {count} | {N critical, N high, N medium} | {Pass/Fail} |
+| A02: Cryptographic Failures | {count} | ... | ... |
+| ... | ... | ... | ... |
+
+## Critical Findings (fix immediately)
+{findings with severity Critical}
+
+## High Findings (fix before next release)
+{findings with severity High}
+
+## Medium Findings (fix in next sprint)
+{findings with severity Medium}
+
+## Low / Informational Findings
+{remaining findings}
+
+## Scoring Breakdown
+- Base score: 100
+- Critical findings: -{N} each × {count} = -{total}
+- High findings: -{N} each × {count} = -{total}
+- Medium findings: -{N} each × {count} = -{total}
+- Low findings: -{N} each × {count} = -{total}
+- **Final score: {X}/100**
+```
+
+---
+
+## Step 3: Error Handling Audit — Weight: 12%
+
+### Check:
+1. **Empty catch blocks**: Catching errors and doing nothing — silent failures
+2. **Generic catches**: Catching `Error` or `any` without handling specific error types
+3. **Missing try/catch**: Async operations without error handling
+4. **Error swallowing**: Catching and logging but not propagating to the user
+5. **Missing error boundaries**: React components without ErrorBoundary wrapping
+6. **Unhandled promise rejections**: Async functions called without `.catch()` or `await` in try/catch
+7. **Missing finally blocks**: Resource cleanup not guaranteed (connections, streams, files)
+8. **Inconsistent error response shapes**: Different endpoints return errors in different formats
+9. **Missing HTTP error status codes**: Returning 200 with error body instead of proper status codes
+10. **User-facing error messages**: Are error messages helpful to users or just raw stack traces?
+11. **Crash recovery**: Does the app recover gracefully or leave the user on a broken screen?
+12. **API error handling**: Are API call failures handled at every call site?
+
+### Per-Finding Format:
+
+```markdown
+### Finding ERR-{number}: {title}
+- **Category**: {Empty Catch / Missing Try-Catch / Unhandled Promise / Silent Failure / etc.}
+- **Severity**: Critical / High / Medium / Low
+- **Location**: `{file}:{line}`
+- **Code**:
+  ```{lang}
+  {the problematic code snippet}
+  ```
+- **Issue**: {why this is a problem}
+- **Fix**:
+  ```{lang}
+  {corrected code}
+  ```
+- **Score Impact**: -{N} points
+```
+
+### Output: `CodeMatters/ERROR_HANDLING.md`
+
+---
+
+## Step 4: Correctness Audit — Weight: 12%
+
+### Check:
+1. **Logic errors**: Off-by-one, wrong comparisons, inverted conditions, missed edge cases
+2. **Type safety violations**: TypeScript `any` usage, type assertions (`as`), non-null assertions (`!`)
+3. **Null/undefined handling**: Missing null checks before property access, optional chaining gaps
+4. **Race conditions**: Concurrent state updates, stale closures in React, missing debounce/throttle
+5. **Data transformation errors**: Incorrect mapping, filtering, or reducing of data
+6. **Date/time handling**: Timezone issues, incorrect date formatting, locale assumptions
+7. **Number precision**: Floating point comparisons, currency calculations without proper precision
+8. **String handling**: Missing trim(), case sensitivity issues, encoding problems
+9. **Business rule compliance**: If legacy intelligence exists, cross-reference every documented rule against the implementation
+10. **State management bugs**: React state not updating as expected, stale state in effects, missing dependency arrays
+
+### Business Rule Cross-Reference (if legacy intelligence available):
+
+```markdown
+### Rule Compliance: {rule_id} — {rule_name}
+- **Rule**: {from BUSINESS_RULES.md}
+- **Implementation**: `{file}:{line}`
+- **Status**: ✅ Correctly implemented / ⚠️ Partially implemented / ❌ Not implemented / 🔴 Incorrectly implemented
+- **Issue**: {if not correct, what's wrong}
+```
+
+### Output: `CodeMatters/CORRECTNESS.md`
+
+---
+
+## Step 5: Crash Risk Audit — Weight: 10%
+
+### Check:
+1. **Unguarded property access**: `obj.deep.property` without null checks on a potentially null chain
+2. **Array index out of bounds**: Accessing `arr[n]` without length check
+3. **Division by zero**: Mathematical operations without zero-divisor checks
+4. **Infinite loops**: Loops without clear exit conditions, recursive functions without base cases
+5. **Memory leaks**: Event listeners not removed, intervals not cleared, subscriptions not unsubscribed, large objects retained in closures
+6. **Stack overflow risk**: Deep recursion without tail-call optimization
+7. **DOM exceptions**: Accessing DOM elements that may not exist, manipulating unmounted components
+8. **Network failure handling**: API calls without timeout, no retry logic, no offline handling
+9. **Large data handling**: Processing unbounded arrays/objects without pagination or streaming
+10. **Concurrent modification**: Modifying collections while iterating, shared mutable state
+
+### Output: `CodeMatters/CRASH_RISK.md`
+
+---
+
+## Step 6: Code Quality & Standards Audit — Weight: 8% + 8%
+
+### Quality Checks:
+1. **Function length**: Functions over 50 lines (flag), over 100 lines (critical)
+2. **File length**: Files over 300 lines (flag), over 500 lines (critical)
+3. **Cyclomatic complexity**: Functions with complexity > 10 (flag), > 20 (critical)
+4. **Code duplication**: Repeated logic blocks (3+ occurrences of similar patterns)
+5. **Dead code**: Unreachable branches, unused functions, commented-out code blocks
+6. **Magic numbers/strings**: Hardcoded values without named constants
+7. **Naming conventions**: Inconsistent naming (camelCase mixed with snake_case), unclear names (x, temp, data, result)
+8. **Comments quality**: Outdated comments, obvious comments ("increment i"), missing comments on complex logic
+9. **Import organization**: Unused imports, circular imports, deep relative paths
+
+### Standards Checks:
+1. **Linter configuration**: Is ESLint/Prettier configured? Are rules enforced?
+2. **TypeScript strictness**: Is `strict: true` enabled? `noImplicitAny`? `strictNullChecks`?
+3. **Consistent patterns**: Are similar operations done the same way throughout the codebase?
+4. **File/folder structure**: Follows a recognizable pattern (feature-based, layer-based)?
+5. **API design consistency**: Same request/response patterns across endpoints?
+6. **Git hygiene**: Meaningful commit messages? `.gitignore` covering node_modules, .env, build artifacts?
+
+### Output: `CodeMatters/CODE_QUALITY.md`
+
+---
+
+## Step 7: Performance Audit — Weight: 7%
+
+### Check:
+1. **Bundle size**: Total bundle size, largest chunks, unused code in bundle (tree-shaking failures)
+2. **Lazy loading**: Are routes/heavy components code-split? Or is everything in one bundle?
+3. **Render performance** (React): Unnecessary re-renders, missing `useMemo`/`useCallback` on expensive operations, large lists without virtualization
+4. **Image optimization**: Unoptimized images, missing lazy loading for below-fold images, no WebP/AVIF
+5. **Network**: Unnecessary API calls, missing request caching, no debounce on search inputs, waterfall requests that could be parallelized
+6. **Memory**: Large objects held in state unnecessarily, growing arrays without cleanup, event listener accumulation
+7. **CSS**: Unused CSS loaded, render-blocking stylesheets, layout thrashing
+8. **Third-party scripts**: Heavy scripts loaded synchronously, blocking render
+9. **Database/API**: N+1 query patterns, unbounded queries without pagination, missing indexes (if visible from frontend patterns)
+
+### Output: `CodeMatters/PERFORMANCE.md`
+
+---
+
+## Step 8: Maintainability Audit — Weight: 7%
+
+### Check:
+1. **Cyclomatic complexity distribution**: How many functions are simple vs complex?
+2. **Code duplication rate**: Percentage of duplicated logic across the codebase
+3. **TODO/FIXME/HACK count**: Technical debt markers — count and categorize
+4. **Dependency coupling**: How many imports does each module have? High coupling = hard to change
+5. **Test-to-code ratio**: Lines of test code vs lines of production code
+6. **Documentation**: README quality, inline documentation for complex functions, API documentation
+7. **Configuration complexity**: How many config files? Are they well-organized or scattered?
+8. **Onboarding difficulty**: How long would it take a new developer to understand and contribute?
+
+### Output: `CodeMatters/MAINTAINABILITY.md` (merged into CODE_QUALITY.md if small enough)
+
+---
+
+## Step 9: Dependency Health Audit — Weight: 5%
+
+### Check:
+1. **Known vulnerabilities**: Run `npm audit` equivalent — list all CVEs by severity
+2. **Outdated packages**: How many are behind latest? How far behind?
+3. **Abandoned packages**: Packages with no updates in 2+ years, no maintainer activity
+4. **License compliance**: Any GPL/AGPL packages in a commercial project? License conflicts?
+5. **Dependency bloat**: Packages that could be replaced with native APIs or lighter alternatives
+6. **Duplicate dependencies**: Multiple versions of the same package in the tree
+7. **Direct vs transitive**: How many vulnerabilities are in direct deps vs transitive?
+8. **Lock file integrity**: Is package-lock.json / yarn.lock present and up to date?
+
+### Output: `CodeMatters/DEPENDENCY_HEALTH.md`
+
+---
+
+## Step 10: Accessibility Audit — Weight: 4%
+
+### Check:
+1. **Semantic HTML**: Using `<button>` for buttons (not `<div onClick>`), proper heading hierarchy
+2. **ARIA attributes**: Missing `aria-label`, `aria-describedby`, `role` attributes on interactive elements
+3. **Keyboard navigation**: All interactive elements reachable via Tab, actionable via Enter/Space
+4. **Color contrast**: Text meets WCAG AA contrast ratios (4.5:1 for normal, 3:1 for large text)
+5. **Focus management**: Focus visible, focus trapped in modals, focus restored after modal close
+6. **Form labels**: Every input has an associated label (Mantine handles this well, but verify)
+7. **Image alt text**: All `<img>` tags have meaningful `alt` attributes
+8. **Screen reader support**: Dynamic content updates announced via aria-live regions
+9. **Motion**: `prefers-reduced-motion` respected for animations
+
+### Output: `CodeMatters/ACCESSIBILITY.md`
+
+---
+
+## Step 11: Test Coverage Audit — Weight: 4%
+
+### Check:
+1. **Test existence**: Does the project have ANY tests?
+2. **Test framework**: What's used? (Jest, Vitest, Mocha, xUnit, pytest)
+3. **Coverage percentage**: If measurable, overall and per-module
+4. **Critical path coverage**: Are the most important business flows tested?
+5. **Test quality**: Do tests assert meaningful outcomes or just "doesn't crash"?
+6. **Edge case coverage**: Are boundary conditions, null inputs, error paths tested?
+7. **Integration tests**: Are API endpoints tested end-to-end?
+8. **Flaky tests**: Any tests that pass/fail intermittently?
+9. **Test speed**: How long does the test suite take? Slow suites get skipped.
+10. **Mock quality**: Are mocks realistic or do they mask real behavior?
+
+### Output: `CodeMatters/TEST_COVERAGE.md`
+
+---
+
+## Step 12: Architecture Compliance Audit — Weight: 3%
+
+### Check:
+1. **Layer violations**: UI components importing from data layer directly, bypassing service layer
+2. **Circular dependencies**: Module A imports B, B imports A
+3. **God files/classes**: Single files/classes doing everything
+4. **Separation of concerns**: Is business logic in the right layer? Or spread across components, utils, and helpers?
+5. **API boundary discipline**: Are all API calls going through a centralized client? Or scattered `fetch` calls?
+6. **State management discipline**: Is state in the right place? Global state for local concerns? Local state for shared data?
+7. **Pattern consistency**: If the project uses Repository pattern, does every module follow it? Or do some bypass it?
+
+### Output: `CodeMatters/ARCHITECTURE.md`
+
+---
+
+## Step 13: Score Calculation
+
+After all audits are complete, calculate the final scores.
+
+### Scoring Method Per Category:
+
+Each category starts at 100. Deductions based on finding severity:
+
+| Severity | Points Deducted Per Finding | Cap |
+|----------|---------------------------|-----|
+| Critical | -15 per finding | No cap — critical findings can drive score to 0 |
+| High | -8 per finding | Maximum -40 from high findings alone |
+| Medium | -3 per finding | Maximum -20 from medium findings alone |
+| Low | -1 per finding | Maximum -10 from low findings alone |
+
+Minimum score per category: 0 (never negative).
+
+### Overall Score Calculation:
+
+```
+Overall = (Security × 0.20) + (Error Handling × 0.12) + (Correctness × 0.12) +
+          (Crash Risk × 0.10) + (Code Quality × 0.08) + (Standards × 0.08) +
+          (Performance × 0.07) + (Maintainability × 0.07) + (Dependency Health × 0.05) +
+          (Accessibility × 0.04) + (Test Coverage × 0.04) + (Architecture × 0.03)
+```
+
+### Grade Assignment:
+
+| Score Range | Grade | Meaning |
+|-------------|-------|---------|
+| 90-100 | **A** | Production-ready, exemplary code |
+| 75-89 | **B** | Good, minor improvements needed |
+| 60-74 | **C** | Acceptable, notable issues to address |
+| 40-59 | **D** | Concerning, significant issues |
+| 0-39 | **F** | Critical, not production-safe |
+
+### Healthcare Modifier:
+
+If the application is flagged as healthcare:
+- Security weight increases to 25% (from 20%)
+- Error Handling weight increases to 15% (from 12%)
+- Other weights proportionally reduced
+- Any unencrypted PII storage is automatically Critical severity
+
+### Output: `CodeMatters/CODE_AUDIT_OVERVIEW.md`
+
+```markdown
+# Code Quality Audit — {Project Name}
+
+## Overall Score: {X}/100 — Grade: {A/B/C/D/F}
+
+## Score Breakdown
+
+| Category | Score | Grade | Weight | Weighted | Critical | High | Medium | Low |
+|----------|-------|-------|--------|----------|----------|------|--------|-----|
+| Security (OWASP) | {X} | {grade} | 20% | {weighted} | {n} | {n} | {n} | {n} |
+| Error Handling | {X} | {grade} | 12% | {weighted} | {n} | {n} | {n} | {n} |
+| Correctness | {X} | {grade} | 12% | {weighted} | {n} | {n} | {n} | {n} |
+| Crash Risk | {X} | {grade} | 10% | {weighted} | {n} | {n} | {n} | {n} |
+| Code Quality | {X} | {grade} | 8% | {weighted} | {n} | {n} | {n} | {n} |
+| Standards | {X} | {grade} | 8% | {weighted} | {n} | {n} | {n} | {n} |
+| Performance | {X} | {grade} | 7% | {weighted} | {n} | {n} | {n} | {n} |
+| Maintainability | {X} | {grade} | 7% | {weighted} | {n} | {n} | {n} | {n} |
+| Dependency Health | {X} | {grade} | 5% | {weighted} | {n} | {n} | {n} | {n} |
+| Accessibility | {X} | {grade} | 4% | {weighted} | {n} | {n} | {n} | {n} |
+| Test Coverage | {X} | {grade} | 4% | {weighted} | {n} | {n} | {n} | {n} |
+| Architecture | {X} | {grade} | 3% | {weighted} | {n} | {n} | {n} | {n} |
+| **Overall** | **{X}** | **{grade}** | **100%** | **{total}** | **{n}** | **{n}** | **{n}** | **{n}** |
+
+## Framework Health
+| Component | Version | Status |
+|-----------|---------|--------|
+{from FRAMEWORK_REVIEW.md}
+
+## Total Findings: {count}
+- Critical: {n} (fix immediately)
+- High: {n} (fix before next release)
+- Medium: {n} (fix in next sprint)
+- Low: {n} (address when convenient)
+
+## Top 5 Most Impactful Fixes
+{The 5 changes that would improve the overall score the most}
+
+| # | Fix | Category | Severity | Score Impact | Effort |
+|---|-----|----------|----------|-------------|--------|
+| 1 | {fix description} | {category} | {severity} | +{points} | {hours} |
+| 2 | ... | ... | ... | ... | ... |
+
+## Category Summaries
+{One paragraph per category summarizing the key findings}
+
+## Detailed Reports
+- [Security Audit](./SECURITY_AUDIT.md)
+- [Error Handling](./ERROR_HANDLING.md)
+- [Correctness](./CORRECTNESS.md)
+- [Crash Risk](./CRASH_RISK.md)
+- [Code Quality](./CODE_QUALITY.md)
+- [Performance](./PERFORMANCE.md)
+- [Dependency Health](./DEPENDENCY_HEALTH.md)
+- [Accessibility](./ACCESSIBILITY.md)
+- [Test Coverage](./TEST_COVERAGE.md)
+- [Architecture](./ARCHITECTURE.md)
+- [Framework Review](./FRAMEWORK_REVIEW.md)
+- [Remediation Plan](./REMEDIATION_PLAN.md)
+```
+
+---
+
+## Step 14: Remediation Plan
+
+Generate a prioritized fix list across ALL categories.
+
+### Output: `CodeMatters/REMEDIATION_PLAN.md`
+
+```markdown
+# Remediation Plan
+
+## Priority Matrix
+
+### Phase 1: Critical (fix immediately, before any deployment)
+| Finding ID | Category | Issue | File | Effort | Score Impact |
+|-----------|----------|-------|------|--------|-------------|
+| SEC-001 | Security | {description} | {file}:{line} | {hours} | +{points} |
+| ERR-003 | Error Handling | {description} | {file}:{line} | {hours} | +{points} |
+
+**Phase 1 Total**: {N} findings, ~{hours} effort, +{points} score improvement
+
+### Phase 2: High Priority (fix before next release)
+| Finding ID | Category | Issue | File | Effort | Score Impact |
+|-----------|----------|-------|------|--------|-------------|
+
+**Phase 2 Total**: {N} findings, ~{hours} effort, +{points} score improvement
+
+### Phase 3: Medium Priority (fix in next sprint)
+...
+
+### Phase 4: Low Priority (address when convenient)
+...
+
+## Projected Score After Remediation
+| Phase | Cumulative Score | Grade |
+|-------|-----------------|-------|
+| Current | {X} | {grade} |
+| After Phase 1 | {X} | {grade} |
+| After Phase 2 | {X} | {grade} |
+| After Phase 3 | {X} | {grade} |
+| After Phase 4 | {X} | {grade} |
+
+## Quick Wins (biggest score improvement for least effort)
+{Findings where score_impact / effort_hours is highest}
+```
+
+---
+
+## Step 15: Generate Manifest
+
+### Output: `CodeMatters/manifest.json`
+
+```json
+{
+  "project": "{project-name}",
+  "audited_at": "{ISO timestamp}",
+  "scan_type": "code-quality-audit",
+  "tech_stack": {
+    "language": "{detected}",
+    "framework": "{detected}",
+    "runtime_version": "{detected}"
+  },
+  "scores": {
+    "overall": { "score": 0, "grade": "X", "weight": 1.0 },
+    "security": { "score": 0, "grade": "X", "weight": 0.20, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "error_handling": { "score": 0, "grade": "X", "weight": 0.12, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "correctness": { "score": 0, "grade": "X", "weight": 0.12, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "crash_risk": { "score": 0, "grade": "X", "weight": 0.10, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "code_quality": { "score": 0, "grade": "X", "weight": 0.08, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "standards": { "score": 0, "grade": "X", "weight": 0.08, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "performance": { "score": 0, "grade": "X", "weight": 0.07, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "maintainability": { "score": 0, "grade": "X", "weight": 0.07, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "dependency_health": { "score": 0, "grade": "X", "weight": 0.05, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "accessibility": { "score": 0, "grade": "X", "weight": 0.04, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "test_coverage": { "score": 0, "grade": "X", "weight": 0.04, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+    "architecture": { "score": 0, "grade": "X", "weight": 0.03, "findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 } }
+  },
+  "total_findings": { "critical": 0, "high": 0, "medium": 0, "low": 0, "total": 0 },
+  "reports": {
+    "overview": "CODE_AUDIT_OVERVIEW.md",
+    "security": "SECURITY_AUDIT.md",
+    "error_handling": "ERROR_HANDLING.md",
+    "correctness": "CORRECTNESS.md",
+    "crash_risk": "CRASH_RISK.md",
+    "code_quality": "CODE_QUALITY.md",
+    "performance": "PERFORMANCE.md",
+    "dependency_health": "DEPENDENCY_HEALTH.md",
+    "accessibility": "ACCESSIBILITY.md",
+    "test_coverage": "TEST_COVERAGE.md",
+    "architecture": "ARCHITECTURE.md",
+    "framework_review": "FRAMEWORK_REVIEW.md",
+    "remediation_plan": "REMEDIATION_PLAN.md"
+  },
+  "previous_audit": null
+}
+```
+
+---
+
+## Comparison Mode
+
+If a previous `CodeMatters/manifest.json` exists:
+
+1. Read the previous scores
+2. After the new audit, show deltas:
+
+```markdown
+## Score Comparison (vs previous audit)
+
+| Category | Previous | Current | Delta |
+|----------|----------|---------|-------|
+| Security | 42 (F) | 78 (B) | +36 ↑ |
+| Error Handling | 55 (D) | 55 (D) | 0 — |
+| Overall | 51 (D) | 72 (C) | +21 ↑ |
+
+## New Findings Since Last Audit: {count}
+## Fixed Findings Since Last Audit: {count}
+## Unchanged Findings: {count}
+```
+
+Save the previous manifest as `manifest.previous.json` before overwriting.
+
+---
+
+## Output Folder Structure
+
+```
+CodeMatters/
+├── manifest.json                   ← Scores, metadata, file inventory
+├── manifest.previous.json          ← Previous audit (if comparison mode)
+├── CODE_AUDIT_OVERVIEW.md          ← Executive summary + all scores
+├── SECURITY_AUDIT.md               ← OWASP Top 10 findings
+├── ERROR_HANDLING.md               ← Error handling + unhandled errors
+├── CORRECTNESS.md                  ← Logic correctness + business rule compliance
+├── CRASH_RISK.md                   ← Crash risk analysis
+├── CODE_QUALITY.md                 ← Quality + standards + maintainability
+├── PERFORMANCE.md                  ← Performance issues
+├── DEPENDENCY_HEALTH.md            ← Package audit + CVEs
+├── ACCESSIBILITY.md                ← a11y audit
+├── TEST_COVERAGE.md                ← Test quality + coverage gaps
+├── ARCHITECTURE.md                 ← Architecture compliance
+├── FRAMEWORK_REVIEW.md             ← Framework versions + EOL dates
+├── REMEDIATION_PLAN.md             ← Prioritized fix list
+└── diagrams/
+    ├── score-breakdown.mermaid     ← Visual score chart
+    └── finding-distribution.mermaid ← Findings by severity and category
+```
+
+---
+
+## Quality Gate
+
+Before delivering, verify:
+
+- [ ] Every finding has a specific file/line reference (no vague findings)
+- [ ] Every finding has a severity rating with justification
+- [ ] Every finding has a concrete remediation with code example where applicable
+- [ ] Scores are calculated correctly (spot-check the math)
+- [ ] The remediation plan is ordered by priority (critical first)
+- [ ] Quick wins are identified (high impact, low effort)
+- [ ] If legacy intelligence exists, business rules are cross-referenced
+- [ ] Framework versions are checked against current stable releases
+- [ ] Manifest has all scores populated with actual values
+- [ ] Overview file has the complete score table