--- # story: e51s04 # story: e45s18 # story: e45s31 name: audit-code model: haiku effort: standard description: Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check. --- # Audit Code > **HARD GATE** — **HARD GATE** — Audit must check for: bugs (correctness), security, performance, and clarity. Do NOT skip security review if the code touches user data, auth, or external APIs. Run this self-review before asking anyone else to look at the code. The goal is to catch everything that is clearly wrong or missing — so the reviewer can focus on design and architecture, not hygiene. **Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes. ## Look-here-first (churn heuristic) Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size. ```bash bash scripts/bp-churn-rank.sh --since 90.days --limit 15 ``` Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope. ## Modes - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. - --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree: ```bash bash scripts/lib/parallel-review-worktrees.sh audit-code ``` ## Checklist ### Supply Chain & Security - [ ] slopcheck run for new dependencies; packages tagged in plan-work: `[OK]`, `[SUS]`, or `[SLOP]` - [ ] No `[SLOP]` packages without documented human approval - [ ] No secrets in diff (`sk-`, `ghp_`, `AKIA`, `.env` values) — see `guard-git` patterns - [ ] OWASP Top 10 spot-check: injection, broken auth, sensitive data exposure, misconfiguration (see `docs/references/security-threats.md`) - [ ] Security: diff scanned — no unaddressed HIGH findings (or deviations documented in `specs/security/EXCEPTIONS.md`) ### Provenance & Metadata - [ ] New plan artefacts include `type:` and `context:` metadata - [ ] Implementation steps reference ADR or commit SHA where decisions were made ### Law of Demeter - [ ] No method chains through unrelated objects (e.g. `a.getB().getC().doX()`) - [ ] Collaborators talk to immediate neighbors only; law violations need explicit justification ### CONVENTIONS.md Compliance - [ ] All output files are in `specs/` (no docs written to project root) - [ ] No `gh issue create` calls anywhere in new/modified skills or scripts - [ ] `gh` used only for PRs and repo clone operations - [ ] No GitHub REST API called directly (no curl/fetch to api.github.com) ### Scope - [ ] Changes are limited to what was asked — nothing extra refactored or reorganized - [ ] No speculative features added - [ ] No files touched outside the stated scope - [ ] **Discovered defects:** Reproducible gate failures (Preflight, CI, golden suite) require fix-or-log — `quick-fix` or `fix-bug` — even when "outside" the story scope. Scope-minimization does not waive Always Green. - [ ] Boy Scout Rule applies to files opened to fix a gate failure; it does not excuse skipping red Preflight ### Boy Scout Rule - [ ] Every file I touched is cleaner than when I found it - [ ] No dead code left behind - [ ] No commented-out code blocks ### Types and Safety - [ ] No `any` types introduced (TypeScript) or untyped public functions (Python/Go/etc.) - [ ] No `@ts-ignore` or `// eslint-disable` added - [ ] No `as unknown as X` casts that bypass type safety ### Test Coverage - [ ] Every new function has at least one test - [ ] Every bug fix has a regression test - [ ] Tests verify behavior through public interfaces (not implementation details) - [ ] Tests are F.I.R.S.T compliant (per CONVENTIONS.md §Tests; use `enforce-first` if unsure) ### SOLID and Heuristics - [ ] Single Responsibility: no function or module doing two unrelated things - [ ] Open/Closed: extended through interfaces, not by modifying stable code - [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable - [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T) ### Refactoring Smells (Fowler) Explicitly name any detected smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man. ### Code Style (CONVENTIONS.md) - [ ] Functions: 4–20 lines; split if longer - [ ] Functions: descend exactly one level of abstraction (The Stepdown Rule / G34) - [ ] Files: under 300 lines (ideally 200–300) - [ ] Names: specific and unique (grep returns < 5 hits for each name) - [ ] No duplication — shared logic extracted (DRY / G5) - [ ] Early returns over nested ifs; max 2 levels of indentation - [ ] Conditionals: expressed as positives (G29) - [ ] Comments explain WHY, not WHAT ### Red Flags Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly. ## Output Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs to be fixed. If all items pass: suggest running `request-review` for an independent second opinion. If any items fail: fix them before proceeding. In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT--.md`. ## Verify → verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review` ## Handoff Gate: READY -> next: commit-message Writes: state.yaml handoff.next_skill = commit-message