docs: SAST complexity refactors can drop uncovered branches

[CybotTM]

Summary

Adds one learning from a cross-session retrospective (2026-06-27) to references/static-analysis-tools.md: SAST maintainability/complexity findings — SonarCloud S3776 (cognitive complexity) and S1142 (too many returns) — whose fix extracts or reorders methods are behavior-risky. An extraction can silently drop a branch (e.g. a fallback-to-default path on an empty/invalid response).

The key insight: PHP-CS-Fixer, PHPStan, and a passing unit suite will not catch a dropped branch if that path isn't unit-covered — in a real 2026-06-27 cleanup only a human code reviewer did.

Guidance added

• Before trusting green gates on a complexity refactor, diff the control-flow branches of the refactored method against the original (is every return/else/early-exit preserved?).
• Add a unit test for the previously-uncovered branch FIRST, then refactor.
• Often it's better to accept subjective complexity findings on controller/service/command layers (mark won't-fix with a comment) than perform a risky extraction.

Placement

New section appended to the existing SAST reference skills/php-modernization/references/static-analysis-tools.md, which is already linked from SKILL.md (Reference routing → "Static analysis"). Matches the file's existing narrative "hazard" style with a seen-in-practice anecdote. SKILL.md is untouched (no bloat, stays under its ~500-word ceiling).

Version decision

No version bump. This is a references-only addition to an already-linked file; SKILL.md, plugin.json, and composer.json are unchanged, so the check-version-parity hook stays green (all three remain at 1.19.1).

Validation

Local pre-commit run on the changed file: markdownlint-cli2 Passed, validate-skill (all files) Passed, check-version-parity Passed, plus trailing-whitespace/end-of-file/merge-conflict/large-file checks Passed. Commit is signed (ED25519) with Signed-off-by.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[gemini-code-assist]

Code Review

This pull request adds a new section to the static analysis tools documentation, warning about the risks of silently dropping branches during SAST maintainability refactors. The feedback suggests refining the advice on diffing control-flow branches to focus on tracing logical paths rather than counting return statements, as reducing return statements is often the goal of such refactors.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud