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