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 — full 8-dimension project health audit
• /rune audit dx — DX Review Mode (Addy Osmani 8 principles, see below)
• User says "audit", "review project", "health check", "project assessment"
• User says "developer experience", "DX audit", "onboarding experience", "time to hello world"

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
• improve-architecture (L2): Phase 3.5 — architecture sub-score (depth / leverage / locality across top modules)
• 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)
• browser-pilot (L3): DX Review Mode — real browser testing of docs, setup guides, error pages

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)

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.

3.5 Zombie Code Detection

Identify code that is effectively dead but hasn't been formally removed. Zombie code increases surface area, confuses contributors, and accumulates security debt.

Signal	Detection Method	Severity
No commits in 6+ months	git log --since="6 months ago" -- <file> returns empty	MEDIUM
No test coverage	File not imported by any test file (Grep for filename in **/*.test.* / **/*.spec.*)	MEDIUM
No owner	File not in CODEOWNERS, no author active in last 6 months	LOW
Failing tests referencing the module	Test suite has skipped/failing tests for this module	HIGH
Unpatched CVEs in dependencies only this module uses	Cross-reference dependency-doctor CVE list with per-file imports	HIGH
Orphaned docs	README/docs reference files or APIs that no longer exist	LOW

Zombie Code Verdict:

• 3+ signals on same file/module → flag as ZOMBIE in audit report
• Recommend: archive (move to _deprecated/), delete, or assign owner
• Do NOT auto-delete — present zombie list to user for decision

---

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.

---

---

DX Review Mode (Addy Osmani 8 Principles)

Triggered by /rune audit dx. Evaluates developer experience — how easy it is for a new contributor to understand, set up, use, and recover from mistakes in this project. Inspired by Addy Osmani's DX framework.

DX Principle 1: Time to Hello World

Measure: How many steps from git clone to running the project?

1. Read README.md — extract setup instructions
2. Count discrete steps (clone, install, config, build, run)
3. Check: are ALL commands copy-pasteable? (no placeholders without explanation)
4. Check: does `npm start` / `python main.py` / equivalent work immediately after install?
5. If browser-pilot available: attempt to follow the README steps literally

Steps to Run	Score	Verdict
1-2 commands	10/10	Excellent — "clone and go"
3-4 commands	7/10	Good — reasonable setup
5-7 commands	4/10	Fair — friction will lose contributors
8+ commands	2/10	Poor — significant onboarding barrier
Cannot run from README	0/10	Broken — README is lying or incomplete

DX Principle 2: First-Time Setup Friction

Check for common setup traps:

• Missing .env.example → new dev has no idea what env vars are needed
• Missing system dependency docs (e.g., needs Redis/Postgres but README doesn't say)
• Node version mismatch (no .nvmrc or engines field)
• Python version mismatch (no python-version in pyproject.toml)
• Failing install on clean machine (native deps, missing build tools)
• No --help or usage message when running CLI with no args

Score: count friction points. 0 = 10/10, 1-2 = 7/10, 3-4 = 4/10, 5+ = 2/10.

DX Principle 3: Error Message Quality

Sample 5 error paths in the codebase (auth failure, invalid input, missing config, network error, permission denied). For each:

• Does the error message say WHAT went wrong? (not just "Error" or "Something went wrong")
• Does it say WHY? (context: which input, which config key)
• Does it suggest HOW to fix? (actionable: "set X in .env" not "check configuration")

Quality	Score
All 3 (what + why + how)	10/10
What + why, no how	6/10
What only	3/10
Generic errors	1/10

DX Principle 4: CLI Help Quality

If project has a CLI entry point:

1. Run `<cli> --help` — capture output
2. Check: does it list all commands with descriptions?
3. Check: does each subcommand have `--help` with examples?
4. Check: is there a quickstart example in help output?
5. Check: are flags named predictably (--verbose not --v, --output not --o)?

Score: 2 points each for: command listing, subcommand help, examples, consistent naming, error on unknown flag.

If no CLI: score as N/A (does not count toward total).

DX Principle 5: Documentation Navigation

Can a developer find answers in under 60 seconds?

• README has a table of contents or clear section headers
• API endpoints / functions have a reference page or inline docs
• Search works (if docs site): try 3 common queries
• Cross-references between related concepts exist
• No dead links (use Grep for ]( patterns and spot-check 5 links)

If browser-pilot available: navigate the docs site, time how long to find "how to authenticate" and "how to deploy".

DX Principle 6: API Consistency

For the top 10 exported functions / API endpoints:

• Naming convention consistent? (all camelCase, or all snake_case — not mixed)
• Return type pattern consistent? (all return { data, error } or all throw — not mixed)
• Parameter ordering consistent? (required first, optional last — across all functions)
• HTTP methods correct? (GET for reads, POST for creates — no GET with side effects)

Score: consistency percentage across the 10 sampled APIs.

DX Principle 7: Progressive Disclosure

• Simple use case achievable with 1-3 lines of code? (check README examples)
• Advanced config available but not required? (sensible defaults exist)
• Configuration is layered? (env vars → config file → CLI flags → defaults)
• Type hints / IDE completion available? (d.ts files, JSDoc, type stubs)

DX Principle 8: Recovery from Mistakes

• Can the user undo/rollback? (migrations have down, deploys have rollback, git-based workflows)
• Do destructive operations have confirmation prompts? (--force required for dangerous ops)
• Are error states recoverable? (retry guidance, not just "failed")
• Does --dry-run exist for risky operations?

DX Review Output

## DX Review: [Project Name]

| # | Principle | Score | Key Finding |
|---|-----------|-------|-------------|
| 1 | Time to Hello World | ?/10 | [steps count + blocker if any] |
| 2 | Setup Friction | ?/10 | [friction points found] |
| 3 | Error Messages | ?/10 | [quality level + worst example] |
| 4 | CLI Help | ?/10 | [coverage + gaps] |
| 5 | Doc Navigation | ?/10 | [findability + dead links] |
| 6 | API Consistency | ?/10 | [consistency % + violations] |
| 7 | Progressive Disclosure | ?/10 | [simple path exists? defaults?] |
| 8 | Recovery | ?/10 | [undo/rollback/dry-run support] |
| **Overall DX** | | **?/10** | **[verdict]** |

### Quick Wins (fix in <1 hour)
1. [specific, actionable improvement]
2. [specific, actionable improvement]
3. [specific, actionable improvement]

### Structural Improvements (plan needed)
1. [deeper change needed]

Grade thresholds: 9-10 Excellent DX, 7-8 Good DX, 5-6 Fair DX (losing contributors), 3-4 Poor DX (significant barrier), 1-2 Hostile DX.

---

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 the Falsification Pass (../review/SKILL.md → Step 6): drop a finding only when what you read contains direct counter-evidence against its key claim — never merely because you are unsure. A finding you cannot disprove is reported and typed ASSUMED with the unchecked premise named. 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]