From 8ec4e81c7e322b56cb7153de1e5cc656fe362de2 Mon Sep 17 00:00:00 2001 From: Kevin Moore Date: Thu, 8 Oct 2026 18:14:51 +0000 Subject: [PATCH] docs(standards): make shallow findings advisory, CC > 15 the stop rule - Only declarations above cognitive_complexity 15 are work items; stop at max <= 15. - shallow / file_split findings are review prompts, not gates; never run --fail-on-safe-inline. Re-inline only true pass-throughs with no same-shape siblings and no meaningful name or doc comment. - Benchmark hot per-element loops before splitting; prefer a per-declaration `// cognitive_complexity:ignore` with a reason. - Point to the dart-cognitive-complexity skill for details. --- .agents/CODING_STANDARDS.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/.agents/CODING_STANDARDS.md b/.agents/CODING_STANDARDS.md index 8cace37..6545359 100644 --- a/.agents/CODING_STANDARDS.md +++ b/.agents/CODING_STANDARDS.md @@ -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