Windsurf rules

1---
2name: audit-code
3model: haiku
4description: "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."
5---
6 
7# Audit Code
8> **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.
9 
10 
11Run 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.
12 
13**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.
14 
15## Look-here-first (churn heuristic)
16 
17Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size.
18 
19```bash
20bash scripts/bp-churn-rank.sh --since 90.days --limit 15
21```
22 
23Apply 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.
24 
25## Modes
26 
27- Default: full checklist
28- --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
29- --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.
30- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree:
31 
32```bash
33bash scripts/lib/parallel-review-worktrees.sh audit-code
34```
35 
36 
37## Checklist
38 
39### Supply Chain & Security
40 
41- [ ] slopcheck run for new dependencies; packages tagged in plan-work: `[OK]`, `[SUS]`, or `[SLOP]`
42- [ ] No `[SLOP]` packages without documented human approval
43- [ ] No secrets in diff (`sk-`, `ghp_`, `AKIA`, `.env` values) — see `guard-git` patterns
44- [ ] OWASP Top 10 spot-check: injection, broken auth, sensitive data exposure, misconfiguration (see `docs/references/security-threats.md`)
45- [ ] Security: diff scanned — no unaddressed HIGH findings (or deviations documented in `specs/security/EXCEPTIONS.md`)
46 
47### Provenance & Metadata
48 
49- [ ] New plan artefacts include `type:` and `context:` metadata
50- [ ] Implementation steps reference ADR or commit SHA where decisions were made
51 
52### Law of Demeter
53 
54- [ ] No method chains through unrelated objects (e.g. `a.getB().getC().doX()`)
55- [ ] Collaborators talk to immediate neighbors only; law violations need explicit justification
56 
57### CONVENTIONS.md Compliance
58 
59- [ ] All output files are in `specs/` (no docs written to project root)
60- [ ] No `gh issue create` calls anywhere in new/modified skills or scripts
61- [ ] `gh` used only for PRs and repo clone operations
62- [ ] No GitHub REST API called directly (no curl/fetch to api.github.com)
63 
64### Scope
65 
66- [ ] Changes are limited to what was asked — nothing extra refactored or reorganized
67- [ ] No speculative features added
68- [ ] No files touched outside the stated scope
69- [ ] **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.
70- [ ] Boy Scout Rule applies to files opened to fix a gate failure; it does not excuse skipping red Preflight
71 
72### Boy Scout Rule
73 
74- [ ] Every file I touched is cleaner than when I found it
75- [ ] No dead code left behind
76- [ ] No commented-out code blocks
77 
78### Types and Safety
79 
80- [ ] No `any` types introduced (TypeScript) or untyped public functions (Python/Go/etc.)
81- [ ] No `@ts-ignore` or `// eslint-disable` added
82- [ ] No `as unknown as X` casts that bypass type safety
83 
84### Test Coverage
85 
86- [ ] Every new function has at least one test
87- [ ] Every bug fix has a regression test
88- [ ] Tests verify behavior through public interfaces (not implementation details)
89- [ ] Tests are F.I.R.S.T compliant (per CONVENTIONS.md §Tests; use `enforce-first` if unsure)
90 
91### SOLID and Heuristics
92 
93- [ ] Single Responsibility: no function or module doing two unrelated things
94- [ ] Open/Closed: extended through interfaces, not by modifying stable code
95- [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable
96- [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T)
97 
98### Refactoring Smells (Fowler)
99 
100Explicitly name any detected smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man.
101 
102### Code Style (CONVENTIONS.md)
103 
104- [ ] Functions: 4–20 lines; split if longer
105- [ ] Functions: descend exactly one level of abstraction (The Stepdown Rule / G34)
106- [ ] Files: under 300 lines (ideally 200–300)
107- [ ] Names: specific and unique (grep returns < 5 hits for each name)
108- [ ] No duplication — shared logic extracted (DRY / G5)
109- [ ] Early returns over nested ifs; max 2 levels of indentation
110- [ ] Conditionals: expressed as positives (G29)
111- [ ] Comments explain WHY, not WHAT
112 
113### Red Flags
114 
115Before 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.
116 
117## Output
118 
119Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs to be fixed.
120 
121If all items pass: suggest running `request-review` for an independent second opinion.
122If any items fail: fix them before proceeding.
123 
124In `--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-<epic>-<story>.md`.
125 
126## Verify
127 
128→ verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review`
129 
130## Handoff
131 
132Gate: READY -> next: commit-message
133Writes: state.yaml handoff.next_skill = commit-message
134 
135 
136<!-- story: e01s02 -->
137<!-- story: e06s03 -->
138<!-- story: e07s01 -->
139 
140---
141 
142# Clean Code Heuristics (Chapter 17)
143 
144A summary of Robert C. Martin's catalogue of code smells and heuristics, used as the technical benchmark for `audit-code`.
145 
146## Comments (C)
147- **C1: Inappropriate Information**: Comments should only hold technical notes. Metadata (author, change history) belongs in Git.
148- **C2: Obsolete Comment**: Update or delete comments that are no longer accurate.
149- **C3: Redundant Comment**: Don't describe code that adequately describes itself (e.g., `i++; // increment i`).
150- **C4: Poorly Written Comment**: If you write a comment, spend time making it the best it can be.
151- **C5: Commented-Out Code**: Delete it. Git remembers it.
152 
153## Environment (E)
154- **E1: Build Requires More Than One Step**: Building should be a single trivial operation (e.g., `bash install.sh`).
155- **E2: Tests Require More Than One Step**: Running all tests should be one simple command (e.g., `npm test`).
156 
157## Functions (F)
158- **F1: Too Many Arguments**: 0 is ideal, 1-2 is fine, 3 requires special justification. Never > 3.
159- **F2: Output Arguments**: Avoid them. If a function changes state, it should change the state of its owning object.
160- **F3: Flag Arguments**: Boolean arguments are a smell that the function does > 1 thing.
161- **F4: Dead Function**: Discard methods that are never called.
162 
163## General (G)
164- **G1: Multiple Languages in One Source File**: Try to minimize the mixing of languages (e.g., HTML inside Java).
165- **G5: Duplication (DRY)**: **The root of all evil.** Every time you see duplication, it's a missed opportunity for abstraction.
166- **G6: Code at Wrong Level of Abstraction**: High-level concepts in base classes; low-level details in derivatives.
167- **G25: Replace Magic Numbers with Named Constants**: No "naked" numbers or strings.
168- **G28: Encapsulate Conditionals**: Prefer `if (shouldBePublished())` over complex boolean logic.
169- **G29: Avoid Negative Conditionals**: Prefer `if (buffer.shouldCompact())` over `if (!buffer.shouldNotCompact())`.
170- **G30: Functions Should Do One Thing**: If a function can be split into sections, it's doing too much.
171- **G31: Hidden Temporal Couplings**: If execution order matters, make the dependency explicit via arguments.
172- **G34: Functions Should Descend Only One Level of Abstraction**: The Stepdown Rule.
173 
174## Naming (N)
175- **N1: Choose Descriptive Names**: Names should reveal intent and be updated as code evolves.
176- **N4: Unambiguous Names**: Names should make the working of a function/variable clear.
177- **N7: Names Should Describe Side-Effects**: Describe everything the function is or does.
178 
179## Tests (T)
180- **T1: Insufficient Tests**: A test suite should test everything that could possibly break.
181- **T4: An Ignored Test Is a Question about an Ambiguity**: Document the reason for `@Ignore`.
182- **T5: Test Boundary Conditions**: Most bugs happen at the boundaries; test them exhaustively.
183- **T8: Test Coverage Patterns Can Be Revealing**: Analyze what code is *not* executed to find gaps.
184- **T9: Tests Should Be Fast**: Slow tests don't get run.
185