/ln-54-codebase-auditor

name: ln-54-codebase-auditor
description: "Audits cross-cutting codebase health, security and maintainability; not a single-change review or specialist audit."

Codebase Auditor

**Goal:** Perform a broad, read-only production-code health audit. Find concrete cross-cutting failure, security, delivery, and maintenance risks without turning detector matches or personal style preferences into findings. Do not substitute for documentation trust, test-portfolio, whole-architecture, or persistence-specific review.

**Execution contract:** The checklist defines completion. Track each item internally as `PENDING`, `PROVEN` with evidence, `CLEARED` with evidence its condition is absent, or `UNPROVEN` with a gap; reading, delegation, or tool failure is not proof. Reconcile after each section. Before returning, resolve all `PENDING`, count only `PROVEN` and `CLEARED`, and apply verdict and approval rules to every gap. Preserve intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without skipping checks. Preserve dependency and safety order; otherwise choose an appropriate verification method. Accept equivalent user or repository evidence; no other skill, named artifact, or complete lifecycle is required. Preserve source requirement and decision IDs. Bind reused evidence to relevant source versions, dirty changes, configuration, and environment; invalidate only affected claims. On continuation, reconcile task, authorization, current state, and unresolved evidence. For long work, return a compact continuation record or update an already authorized artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and external-action authority. Prepare authorized work before required approval. If blocked by an instruction, cite its exact source and unresolved boundary; do not invent approval gates from caution.

Tool Routing

| Need | Preferred tool | Use it when | Fallback | |---|---|---|---| | Repository map and stack detection | Native file listing, manifests, build files, and repository instructions | Establishing scope, generated areas, entrypoints, supported runtimes, and commands | Targeted tree inspection and known entrypoints | | Symbols, callers, ownership, and data flow | Language server or host-native code intelligence | A finding depends on symbol identity, references, overrides, route wiring, or cross-file behavior | Narrow text search plus direct inspection of every relevant match | | Current changes and historical context | Git status, diff, log, and blame | Separating current work, regressions, intentional constraints, and dead compatibility paths | Current implementation and explicit decision records | | Delivery health | Repository-defined build, lint, type, test, and smoke commands | Establishing whether the project can ship in its documented environment | Inspect CI and scripts; mark execution unavailable | | Dependency and security state | Native package-manager audit, manifests, lockfiles, and official advisories | Checking known vulnerabilities, unsupported versions, and dependency health | Official registry and vendor sources; never guess severity | | Runtime evidence | Existing logs, metrics, traces, profiles, and diagnostics | Static analysis cannot establish frequency, reachability, or operational impact | Call-path analysis with an explicit static-only limitation | | Current external behavior | Official specifications, vendor documentation, and release notes | A finding depends on current API, runtime, or standard behavior | Primary-source web research; otherwise mark `UNVERIFIED` |

Start with summary-level discovery and narrow before reading deeply. Run only repository-defined or clearly safe diagnostic commands; never publish, deploy, migrate production data, rotate secrets, or rewrite files during the audit.

Evidence Rules

• A pattern match is a candidate, not a finding. Confirm reachability, context, and consequence.
• Runtime failure or deterministic command output outweighs static suspicion; static evidence remains valid when execution is unavailable and the limitation is explicit.
• Generated, vendored, fixture, migration-history, and intentionally compatible code require context-specific treatment.
• External best practice is actionable only when it addresses a concrete repository defect or risk.
• Score or count only findings with distinct root causes; deduplicate symptoms that share one correction.

Checklist

1. Establish Scope and Baseline

• [ ] Detect languages, frameworks, package managers, entrypoints, deployment model, generated areas, and the repository's supported verification commands.
• [ ] Classify each runtime surface as long-running service, CLI, library, job, serverless function, or platform-managed component before requiring probes, telemetry, signal handling, or shutdown behavior.
• [ ] Read applicable instructions and identify security boundaries, critical business paths, public interfaces, and irreversible operations.
• [ ] Inspect Git state so the audit does not overwrite, misattribute, or ignore unrelated user changes.
• [ ] Establish feasible build, lint, type, test, and smoke baselines; record executed scope, environment, exit status, and evidence. Verify required work ran rather than succeeding with no selected tests or skipped gates.
• [ ] Define exclusions and depth based on risk rather than scanning every file with equal effort.
• [ ] Keep the audit read-only. Allow only permitted caches and build artifacts and disclose them when created.

2. Audit Security and Delivery Boundaries

• [ ] Search for committed secrets, unsafe credential patterns, sensitive defaults, debug bypasses, and accidental exposure through logs or errors.
• [ ] For credential findings, never expose the raw value: distinguish live material from placeholders, fixtures, examples, and allo