audit

audit

Purpose

Comprehensive project health audit across 8 dimensions (7 project + 1 mesh analytics). Delegates security scanning to sentinel, dependency analysis to dependency-doctor, and code complexity to autopsy, then directly audits architecture, performance, infrastructure, and documentation. Applies framework-specific checks (React/Next.js, Node.js, Python, Go, Rust, React Native/Flutter) based on detected stack. Produces a consolidated health score and prioritized action plan saved to AUDIT-REPORT.md.

Triggers

• /rune audit — manual invocation
• User says "audit", "review project", "health check", "project assessment"

Calls (outbound)

• scout (L2): Phase 0 — project structure and stack discovery
• dependency-doctor (L3): Phase 1 — vulnerability scan and outdated dependency check
• sentinel (L2): Phase 2 — security audit (OWASP Top 10, secrets, config)
• autopsy (L2): Phase 3 — code quality and complexity assessment
• perf (L2): Phase 4 — performance regression check
• db (L2): Phase 5 — database health dimension (schema, migrations, indexes)
• journal (L3): record audit date, overall score, and verdict
• constraint-check (L3): audit HARD-GATE compliance across project skills
• sast (L3): Phase 2 — deep static analysis (Semgrep, Bandit, ESLint security rules)
• retro (L2): Phase 6 — engineering velocity and health dimension (rune:retro)

Called By (inbound)

• cook (L1): pre-implementation audit gate
• launch (L1): pre-launch health check
• User: /rune audit direct invocation

Executable Instructions

Phase 0: Project Discovery

Call rune:scout for a full project map. Then use Read on:

• README.md, CLAUDE.md, CONTRIBUTING.md, .editorconfig (if they exist)

Determine:

• Language(s) and version(s)
• Framework(s) — determines which Framework-Specific Checks below apply
• Package manager, build tool(s), test framework(s), linter/formatter config
• Project type: API/backend | frontend/SPA | fullstack | CLI tool | library | mobile | infra/IaC
• Monorepo setup (workspaces, turborepo, nx, etc.)

Output before proceeding: Brief project profile, stack summary, and which Framework-Specific Checks will be applied.

Phase 0.5: Context-Building (Pure Understanding)

This phase is FORBIDDEN from producing findings. No BLOCKs, no WARNs, no issues. Context-building only. Rushed context = hallucinated vulnerabilities. Slow is fast.

For each critical module (entry points, auth, data layer, core business logic):

1. Read line-by-line. Note at minimum:
   • 3 invariants: What MUST always be true for this code to work? (e.g., "user is authenticated before reaching this handler")
   • 5 assumptions: What does this code assume about its inputs, environment, and callers?
   • 3 risks: What could break if assumptions are violated?
2. Record findings as context notes — these feed into Phases 1-7, NOT into the final report directly

Why: Without this phase, the auditor pattern-matches against known vulnerability lists and hallucinates findings that don't exist in THIS specific codebase. The invariants + assumptions ground all later analysis in reality.

---

Phase 1: Dependency Audit

Delegate to dependency-doctor. The dependency-doctor report covers:

• Vulnerability scan (CVEs by severity)
• Outdated packages (patch / minor / major)
• Unused dependencies
• Dependency health score

Pass the full dependency-doctor report through to the final audit.

---

Phase 2: Security Audit

Delegate to sentinel. Request a full security scan covering:

• Hardcoded secrets, API keys, tokens, passwords in source code
• OWASP Top 10: injection, broken auth, sensitive data exposure, XSS, CSRF, insecure deserialization, broken access control
• Configuration security (debug mode in prod, CORS *, missing HTTP security headers)
• Input validation at API boundaries
• .gitignore coverage of sensitive files

Pass the full sentinel report through to the final audit.

---

Phase 3: Code Quality Audit

Delegate to autopsy for codebase health (complexity, coupling, hotspots, dead code, health score per module).

In addition, use Grep to find supplementary issues autopsy may not cover:

# console.log in production code
grep -r "console\.log" src/ --include="*.ts" --include="*.js" -l

# TypeScript any types
grep -r ": any" src/ --include="*.ts" -n

# Empty catch blocks
grep -rn "catch.*{" src/ --include="*.ts" --include="*.js" -A 1 | grep -E "^\s*}"

# Python print() in production
grep -r "^print(" . --include="*.py" -l

# Rust .unwrap() outside tests
grep -rn "\.unwrap()" src/ --include="*.rs"

Merge autopsy report + supplementary findings.

---

Phase 4: Architecture Audit

Use Read and Grep to evaluate structural health directly.

4.1 Project Structure

• Logical folder organization (business logic vs infrastructure vs presentation separated?)
• Circular dependencies between modules (A imports B, B imports A)
• Barrel file analysis (excessive re-exports causing bundle bloat)

4.2 Design Patterns & Principles

• Single Responsibility violations (route handlers with direct DB calls, fat controllers)
• Tight coupling between layers

// BAD — route handler directly coupled to database
app.get('/users/:id', async (req, res) => {
  const user = await db.query('SELECT * FROM users WHERE id = $1', [req.params.id]);
  res.json(user);
});
// GOOD — layered architecture
app.get('/users/:id', async (req, res) => {
  const user = await userService.getUser(req.params.id);
  res.json(user);
});

4.3 API Design (if applicable)

• Consistent naming conventions (camelCase vs snake_case in JSON responses)
• Correct HTTP method usage (GET reads, POST creates, PUT/PATCH updates, DELETE removes)
• Consistent error response format across endpoints
• Pagination on collection endpoints
• API versioning strategy

4.4 Database Patterns (if applicable)

• N+1 query patterns

// BAD — N+1
const users = await db.query('SELECT * FROM users');
for (const user of users) {
  user.posts = await db.query('SELECT * FROM posts WHERE user_id = $1', [user.id]);
}
// GOOD — single JOIN
const usersWithPosts = await db.query(`
  SELECT u.*, json_agg(p.*) as posts
  FROM users u LEFT JOIN posts p ON p.user_id = u.id
  GROUP BY u.id
`);

• Missing indexes (check schema/migrations for columns used in WHERE/JOIN)
• Missing LIMIT on user-facing queries

4.5 State Management (frontend only)

• Global state pollution (local state handled globally)
• Prop drilling (>3 levels deep — use Context or composition)
• Data fetching patterns (caching, deduplication, stale-while-revalidate)

---

Phase 5: Performance Audit

5.1 Build & Bundle (frontend)

• Tree-shaking effectiveness (importing entire libraries vs specific modules)

// BAD — imports entire library
import _ from 'lodash';
// GOOD — tree-shakeable import
import get from 'lodash/get';

• Code splitting / lazy loading for routes
• Large unoptimized assets

5.2 Runtime Performance

• Synchronous operations that should be async (file I/O, network calls)
• Memory leak patterns (event listeners not cleaned up, growing caches, unclosed streams)
• Expensive operations in hot paths

// BAD — regex compiled on every call
function validate(input: string) {
  return /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(input);
}
// GOOD — compile once at module level
const EMAIL_REGEX = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
function validate(input: string) { return EMAIL_REGEX.test(input); }

5.3 Database & I/O

• Missing connection pooling
• Unbounded queries (no LIMIT on user-facing endpoints)
• Sequential I/O that could be parallel

// BAD — sequential when independent
const users = await fetchUsers();
const products = await fetchProducts();
// GOOD — parallel
const [users, products] = await Promise.all([fetchUsers(), fetchProducts()]);

---

Phase 6: Infrastructure & DevOps Audit

Use Glob and Read to check:

6.1 CI/CD Pipeline

• CI config exists (.github/workflows/, .gitlab-ci.yml, .circleci/, Jenkinsfile)
• Tests running in CI
• Linting enforced in CI
• Security scanning in pipeline (Dependabot, Snyk, CodeQL)

6.2 Environment Configuration

• .env.example exists with placeholder values (not real secrets)
• Environment variables validated at startup

// BAD — silently undefined
const port = process.env.PORT;
// GOOD — validate at startup
const port = process.env.PORT;
if (!port) throw new Error('PORT environment variable is required');

6.3 Containerization (if applicable)

• Dockerfile: multi-stage build, non-root user, minimal base image
• .dockerignore covers node_modules, .git, .env

6.4 Logging & Monitoring

• Structured logging (JSON format, not raw console.log)
• Error tracking integration (Sentry, Datadog, etc.)
• Health check endpoints (/health, /ready)
• No sensitive data in logs (passwords, tokens, PII)

---

Phase 7: Documentation Audit

Use Glob and Read to check:

7.1 Project Documentation

• README completeness: description, prerequisites, setup, usage, deployment, contributing
• API documentation (OpenAPI/Swagger spec, or documented endpoints)
• Can a new developer get running from README alone?
• Architecture Decision Records (ADRs) for non-obvious choices

7.2 Code Documentation

• Public API / exported functions documented
• Complex business logic with explanatory comments
• CHANGELOG.md maintained
• LICENSE file present

---

Framework-Specific Checks

Apply only if the framework was detected in Phase 0. Skip entirely if not relevant.

React / Next.js (detect: react or next in package.json)

• useEffect with missing dependencies (stale closures)
• State updates during render (infinite loop pattern)
• List items using index as key on reorderable lists
• Props drilled through 3+ levels
• Client-side hooks in Server Components (Next.js App Router)
• Components exceeding 200 JSX lines

Node.js / Express / Fastify (detect: express, fastify, koa, @nestjs/core)

• Missing rate limiting on public endpoints
• Missing request timeout configuration
• Error messages leaking internal details to clients
• Unbounded SELECT * without pagination
• Missing authentication middleware on protected routes
• Synchronous operations blocking the event loop

Python (Django / Flask / FastAPI) (detect: django, flask, fastapi in requirements)

• Django: missing permission_classes, DEBUG=True in production, missing CSRF middleware
• Flask: app.run(debug=True) without environment check
• FastAPI: missing Pydantic models for request/response
• Mutable default arguments (def func(items=[]))
• Missing type hints on public functions (if project uses mypy/pyright)

Go (detect: go.mod)

• Ignored errors (file, _ := os.Open(filename))
• Goroutine leaks (goroutines without cancellation context)
• Missing defer for resource cleanup (files, locks, connections)
• Race conditions (shared state without mutex or channels)

Rust (detect: Cargo.toml)

• .unwrap() / .expect() in non-test production code (use ? operator)
• unsafe blocks without safety comments

Mobile (React Native / Flutter) (detect: react-native in package.json or pubspec.yaml)

• FlatList without keyExtractor or getItemLayout
• Missing React.memo on list item components
• Flutter: missing const constructors, missing dispose() for controllers and streams

---

Phase 8: Mesh Analytics (H3 Intelligence)

Goal: Surface insights about skill usage, chain patterns, and mesh health from accumulated metrics.

Data source: .rune/metrics/ directory (populated by hooks automatically).

1. Check if .rune/metrics/ exists. If not, emit INFO: "No metrics data yet — run a few cook sessions first."
2. Read .rune/metrics/skills.json — extract per-skill invocation counts, last used dates
3. Read .rune/metrics/sessions.jsonl — extract session count, avg duration, avg tool calls
4. Read .rune/metrics/chains.jsonl — extract most common skill chains
5. Read .rune/metrics/routing-overrides.json (if exists) — list active routing overrides

Compute and report:

• Top 10 most-used skills (by total invocations)
• Unused skills (0 invocations across all tracked sessions) — potential dead nodes
• Most common skill chains (top 5 patterns from chains.jsonl)
• Average session stats (duration, tool calls, skill invocations)
• Active routing overrides and their application count
• Mesh density check: cross-reference invocation data with declared connections — skills that are declared as "Called By" but never actually invoked may indicate broken mesh paths

Propose routing overrides: If patterns suggest inefficiency (e.g., debug consistently called 3+ times in a chain for the same session), propose a new routing override for user approval.

Output as a section in the final audit report:

### Mesh Analytics
| Skill | Invocations | Last Used | Chains Containing |
|-------|-------------|-----------|-------------------|
| cook  | 47          | 2026-02-28| 34                |
| scout | 89          | 2026-02-28| 42                |
| ...   | ...         | ...       | ...               |

**Common Chains**:
1. cook → scout → plan → test → fix → quality → verify (34x)
2. debug → scout → fix → verification (12x)

**Session Stats**: 23 sessions, avg 35min, avg 52 tool calls
**Unused Skills**: [list or "none"]
**Routing Overrides**: [count] active

Shortcut: /rune metrics invokes ONLY this phase, not the full 7-phase audit.

---

Final Report

After all phases complete:

Use Write to save AUDIT-REPORT.md to the project root with the full findings from all phases.

Call rune:journal to record: audit date, overall health score, verdict, and CRITICAL count.

Weighted Composite Scoring

Each dimension score feeds into a weighted composite formula that produces a single comparable health score. Use this formula to compute Overall Health — not a simple average.

Scoring Formula

Overall = (Security × 0.25) + (Code Quality × 0.20) + (Architecture × 0.15)
        + (Dependencies × 0.15) + (Performance × 0.10) + (Infrastructure × 0.08)
        + (Documentation × 0.07)

Mesh Analytics (Phase 8) is advisory — it contributes 0 to the weighted score but informs the verdict narrative.

Grade Thresholds

Score Range	Grade	Verdict	Action
90–100	Excellent	PASS	Routine audit in 3 months
75–89	Good	PASS	Address MEDIUM items next sprint
60–74	Fair	WARNING	Fix HIGH items within 2 weeks
40–59	Poor	FAIL	Fix CRITICAL + HIGH within 1 week
0–39	Critical	FAIL	Emergency response — CRITICAL items block all new work

Why Weighted (not average)

Security issues cause exponential blast — a 3/10 security score with all other dimensions at 9/10 = overall 72 (Fair), not 8.1 (Good). The formula ensures security and code quality dominate the verdict. Comparable across runs: if Overall moves from 68 → 74 after fixes, the project measurably improved.

Severity Levels

CRITICAL — Must fix immediately. Security vulnerabilities, data loss, broken builds.
HIGH     — Should fix soon. Performance bottlenecks, CVEs, major code smells.
MEDIUM   — Plan to fix. Code duplication, missing tests, outdated deps.
LOW      — Nice to have. Style inconsistencies, minor refactors, doc gaps.
INFO     — Observation only. Architecture notes, tech debt acknowledgment.

Apply confidence filtering: only report findings with >80% confidence. Consolidate similar issues (e.g., "12 functions missing error handling in src/services/" — not 12 separate findings). Adapt judgment to project type (a console.log in a CLI tool is fine; in a production API handler, it's not).

Output Format

## Audit Report: [Project Name]

- **Verdict**: PASS | WARNING | FAIL
- **Overall Health**: [score]/10
- **Total Findings**: [n] (CRITICAL: [n], HIGH: [n], MEDIUM: [n], LOW: [n])
- **Framework Checks Applied**: [list]

### Health Score
| Dimension      | Score    | Notes              |
|----------------|:--------:|--------------------|
| Security       |   ?/10   | [brief note]       |
| Code Quality   |   ?/10   | [brief note]       |
| Architecture   |   ?/10   | [brief note]       |
| Performance    |   ?/10   | [brief note]       |
| Dependencies   |   ?/10   | [brief note]       |
| Infrastructure |   ?/10   | [brief note]       |
| Documentation  |   ?/10   | [brief note]       |
| Mesh Analytics |   ?/10   | [brief note]       |
| **Overall**    | **?/10** | **[verdict]**      |

### Phase Breakdown
| Phase          | Issues |
|----------------|--------|
| Dependencies   | [n]    |
| Security       | [n]    |
| Code Quality   | [n]    |
| Architecture   | [n]    |
| Performance    | [n]    |
| Infrastructure | [n]    |
| Documentation  | [n]    |
| Mesh Analytics | [n]    |

### Composite Score
- **Formula**: (Security×0.25) + (Code Quality×0.20) + (Architecture×0.15) + (Dependencies×0.15) + (Performance×0.10) + (Infrastructure×0.08) + (Documentation×0.07)
- **Weighted Score**: [computed value] → Grade: [Excellent/Good/Fair/Poor/Critical]

### Top Priority Actions
1. [action] — [file:line] — [why it matters]

### Positive Findings
- [at least 3 things the project does well]

### Follow-up Timeline
- FAIL → re-audit in 1-2 weeks after CRITICAL fixes
- WARNING → re-audit in 1 month
- PASS → routine audit in 3 months

Report saved to: AUDIT-REPORT.md

Constraints

1. MUST complete all 8 phases (Phase 8 may report "no data" if .rune/metrics/ doesn't exist yet) — if any phase is skipped, state explicitly which phase and why
2. MUST delegate Phase 1 to dependency-doctor and Phase 2 to sentinel — no manual replacements
3. MUST apply confidence filter — only report findings with >80% confidence; consolidate similar issues
4. MUST include at least 3 positive findings — an audit with no positives is incomplete
5. MUST produce quantified health scores (1-10 per dimension) — not vague "needs work"
6. MUST NOT fabricate findings — every finding requires a specific file:line citation
7. MUST save AUDIT-REPORT.md before declaring completion

Mesh Gates

Gate	Requires	If Missing
Discovery Gate	Phase 0 project profile completed before Phase 1	Run scout and read config files first
Security Gate	sentinel report received before assembling final report	Invoke rune:sentinel — do not skip
Deps Gate	dependency-doctor report received before assembling final report	Invoke rune:dependency-doctor — do not skip
Report Gate	All 8 phases completed before writing AUDIT-REPORT.md	Complete all phases, note skipped ones

Returns

Artifact	Format	Location
Audit report	Markdown	AUDIT-REPORT.md (project root)
8-dimension health score	Markdown table	AUDIT-REPORT.md + inline
Weighted composite score + grade	Markdown	inline + AUDIT-REPORT.md
Mesh analytics section	Markdown table	inline + AUDIT-REPORT.md
Journal entry	Text	.rune/adr/ (via rune:journal)

Sharp Edges

Failure Mode	Severity	Mitigation
Generating health scores from file name patterns instead of actual reads	CRITICAL	Phase 0 scout run is mandatory — never score without reading actual code
Skipping a phase because "there are no changes in that area"	HIGH	All 7 phases run for every audit — partial audits produce misleading scores
Health score inflation — no negative findings in any dimension	MEDIUM	CONSTRAINT: minimum 3 positive AND 3 improvement areas required
Dependency-doctor or sentinel sub-call times out → skipped silently	MEDIUM	Mark phase as "incomplete — tool timeout" with N/A score, do not fabricate

Done When

• All 8 phases completed (or explicitly marked N/A with reason)
• Health score calculated from actual file reads per dimension (not estimated)
• At least 3 positive findings and 3 improvement areas documented
• AUDIT-REPORT.md written to project root
• Journal entry recorded with audit date, score, and CRITICAL count
• Structured report emitted with overall health score and verdict

Cost Profile

~8000-20000 tokens input, ~3000-6000 tokens output. Sonnet orchestrating; sentinel (sonnet/opus) and autopsy (opus) are the expensive sub-calls. Full audit runs 4 sub-skills. Most thorough L2 skill — run on demand, not on every cycle.