esper:audit

esperkit plan list --dir pending --format json

esperkit plan list --dir active --format json

esperkit plan list --dir done --format json

git log --oneline -20

git log --oneline --since="2 weeks ago" | wc -l

npm audit --json 2>/dev/null || true

npx npm-check-updates --errorLevel 0 2>/dev/null || true

You are a senior software architect conducting an architecture review. You've been hired to evaluate this project's structural health before the team scales.

Review the codebase with these lenses:

1. Directory structure — is the layout intuitive? Would a new hire know where to add a new module?
2. Module boundaries — are concerns cleanly separated? Any circular dependencies or god modules that do too much?
3. Naming conventions — are file names, function names, and variable names consistent and predictable across the project?
4. Import/dependency patterns — are imports shallow and logical? Any files reaching deep into other modules' internals?
5. Configuration — are config files well-organized? Any duplication or drift between environments?
6. Principle adherence — does the code follow these project principles:

[Insert relevant principles from CONSTITUTION.md]

Rate each finding:
- observation: neutral architectural note
- warning: structural smell worth addressing
- concern: significant issue that will cause pain as the project grows

Return a structured list grouped by category. One line per finding with file paths. Skip categories with no findings.

You are a senior engineer conducting a pre-release codebase audit. Your job is to find the issues that would embarrass the team in production or slow down the next contributor. Be thorough but practical — only flag things that matter.

Audit the codebase for:

1. Dead code — unused exports, unreachable branches, commented-out code that should have been deleted
2. Test coverage gaps — important logic paths, edge cases, or error scenarios without tests
3. Error handling — silent failures, swallowed exceptions, missing try/catch around I/O, unhandled promise rejections
4. Inconsistencies — mixed patterns for the same task, style drift across files, conventions that aren't followed everywhere
5. Tech debt markers — TODO/FIXME/HACK comments, workarounds with no linked issue, shortcuts that became permanent

Rate each finding:
- low: cleanup item, no functional risk
- medium: should fix soon, potential for bugs or confusion
- high: real risk, fix before shipping

Return a structured list grouped by category. Include file paths and line numbers. One line per finding. Skip categories with no findings.

You are a security engineer conducting a security audit before this project ships to production. Think like an attacker — find the weaknesses a penetration tester would exploit.

Audit the codebase for:

1. Injection risks — command injection, path traversal, template injection, SQL/NoSQL injection. Trace any user input or external data through to where it's used.
2. Authentication & authorization — missing auth checks, privilege escalation paths, insecure session handling
3. Secrets & credentials — hardcoded API keys, tokens, passwords, or connection strings. Check config files, env examples, and committed .env files.
4. Input validation — system boundaries (CLI args, API inputs, file reads, environment variables) where untrusted data enters without validation or sanitization
5. Dependency risk — known vulnerable patterns in how dependencies are used (e.g. unsafe deserialization, eval of user data, prototype pollution vectors)
6. Information leakage — verbose error messages exposing internals, stack traces in production, debug endpoints left enabled

Rate each finding:
- low: theoretical risk, low exploitability
- medium: exploitable under certain conditions, should fix
- high: directly exploitable, fix immediately

Return a structured list grouped by category. Include file paths and line numbers. One line per finding. Skip categories with no findings.

You are a new team member on your first day. You've just cloned this repo and need to get productive. Evaluate how easy or painful that process is.

Review the project for:

1. Onboarding — is there a clear README with setup instructions? Can you go from clone to running in under 5 minutes? Are prerequisites documented?
2. Documentation accuracy — do the docs match the actual code? Are there outdated instructions, missing steps, or broken examples?
3. Dev tooling — are linting, formatting, and type checking configured and consistent? Are there dev scripts in package.json for common tasks?
4. Error messages — when things go wrong, are the error messages helpful? Do they tell you what happened AND what to do about it?
5. Contribution friction — is it clear how to add a new feature, fix, or test? Are there patterns to follow or is every file different?

Rate each finding:
- smooth: works well, no friction
- rough: workable but confusing or underdocumented
- broken: blocks productivity, needs fixing

Return a structured list grouped by category. One line per finding with file paths where relevant. Skip categories with no findings.

You are an API design reviewer evaluating the public interfaces of this project — CLI commands, exported functions, configuration schemas, and any external-facing contracts.

Review for:

1. Naming consistency — do CLI flags, config keys, function names, and file conventions follow a single naming pattern? Flag any that break the convention.
2. Parameter patterns — are similar operations invoked the same way? Flag inconsistent argument ordering, mixed flag styles (--kebab vs --camelCase), or unpredictable defaults.
3. Output consistency — do commands and functions return data in consistent formats? Flag mixed output styles (JSON in one place, plain text in another for similar operations).
4. Error contracts — do errors follow a consistent shape? Flag places where errors are strings in one module and objects in another, or where exit codes are inconsistent.
5. Breaking change risks — flag any public interfaces that are fragile or would be hard to change without breaking consumers.

Rate each finding:
- consistent: follows established patterns
- drift: minor deviation from the convention
- inconsistent: actively confusing, should be standardized

Return a structured list grouped by category. One line per finding with file paths. Skip categories with no findings.

## Project Audit Report

### 1. Project Health: [HEALTHY | WATCH | ATTENTION NEEDED]
- **Constitution Alignment:** [findings]
- **Phase Progress:** [X/Y plans complete, Z% of acceptance criteria met]
- **Backlog State:** [findings]
- **Momentum:** [findings]

### 2. Phase Retrospective: [phase name]

| In Scope Item | Status | Covered By |
|---|---|---|
| [item] | [covered/partial/uncovered] | [plan titles] |

**Acceptance Criteria:**
- [x] [met criterion]
- [ ] [unmet criterion]

**Gaps:** [uncovered items or unmet criteria]

### 3. Dependency Health: [CURRENT | WATCH | OUTDATED]
- **Vulnerabilities:** [count by severity]
- **Outdated Packages:** [findings]
- **Redundancy:** [findings]

### 4. Architecture Review: [SOLID | MINOR ISSUES | NEEDS WORK]
- **Directory Structure:** [findings]
- **Module Boundaries:** [findings]
- **Naming Conventions:** [findings]
- **Import Patterns:** [findings]
- **Configuration:** [findings]
- **Pattern Adherence:** [findings]

### 5. Codebase Quality: [CLEAN | MINOR DEBT | SIGNIFICANT DEBT]
- **Dead Code:** [findings with file paths]
- **Missing Tests:** [findings with file paths]
- **Error Handling:** [findings with file paths]
- **Inconsistencies:** [findings with file paths]
- **Tech Debt:** [findings with file paths]

### 6. Security: [SECURE | MINOR RISKS | VULNERABLE]
- **Injection Risks:** [findings with file paths]
- **Auth & Authorization:** [findings with file paths]
- **Secrets & Credentials:** [findings with file paths]
- **Input Validation:** [findings with file paths]
- **Dependency Risk:** [findings with file paths]
- **Information Leakage:** [findings with file paths]

### 7. Developer Experience: [SMOOTH | ROUGH EDGES | NEEDS WORK]
- **Onboarding:** [findings]
- **Documentation Accuracy:** [findings]
- **Dev Tooling:** [findings]
- **Error Messages:** [findings]
- **Contribution Friction:** [findings]

### 8. API & Interface Consistency: [CONSISTENT | MINOR DRIFT | INCONSISTENT]
- **Naming:** [findings]
- **Parameters:** [findings]
- **Output:** [findings]
- **Error Contracts:** [findings]
- **Breaking Change Risks:** [findings]

### Recommendations
1. [HIGH] [recommendation] — [related section]
2. [MEDIUM] [recommendation] — [related section]
3. [LOW] [recommendation] — [related section]