Skip to content

docs(standards): make shallow findings advisory, CC > 15 the stop rule #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kevmoo merged 1 commit into from
Oct 9, 2026
Merged

docs(standards): make shallow findings advisory, CC > 15 the stop rule #69

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions .agents/CODING_STANDARDS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,16 +56,19 @@
`dart run api_summary@^1.1.0 -o /tmp/api_before.txt` before refactoring and
`diff -u /tmp/api_before.txt /tmp/api_after.txt` after, requiring zero diff
unless a public API change was requested.
- **Internal Decomposition & Shallow-Helper Guardrail (`lib/src/`)**: When
decomposing functions to satisfy `cognitive_complexity <= 15`, forbid stateful
`_Populator` / `_Runner` helper classes that mutate caller maps/sets in-place;
require **file-private pure functions (`_computeX(input) -> output`)** inside
the same library or narrow internal modules with zero out-parameters. Stop
decomposing once a function reaches the **Target Zone (`8-15`, not `0`)**, cap
extracted helpers at `<= 4` parameters (`<= 3` preferred,
`sliceScoreAtRoot >= 3`), and run
`dart run cognitive_complexity:shallow@^1.0.0 lib/` to detect and re-inline
single-caller `SAFE_INLINE` helpers (`CallerCCAfter <= 15`).
- **Internal Decomposition & Shallow-Helper Guardrail (`lib/src/`)**: **Stop
rule:** only declarations above `cognitive_complexity` 15 are work items; stop
once the max is `<= 15` (Target Zone `8-15`, not `0`). When decomposing,
forbid stateful `_Populator` / `_Runner` helper classes that mutate caller
maps/sets in-place; require **file-private pure functions
(`_computeX(input) -> output`)** with zero out-parameters and `<= 4`
parameters (`<= 3` preferred). `shallow` / `file_split` findings are advisory
review prompts, not gates (never run `--fail-on-safe-inline`): re-inline a
`SAFE_INLINE` helper only when it is a true pass-through with no same-shape
siblings and no meaningful name or doc comment. Benchmark hot per-element
loops before splitting them; prefer a per-declaration
`// cognitive_complexity:ignore` with a reason comment. Details: the
`dart-cognitive-complexity` skill.
- **Load-Bearing Library Boundary Rule (`part` / `part of` vs. Separate
Libraries)**:
- **Core Principle**: Prefer the boundary the language compiler enforces
Expand Down