Readability sweep

Readability Sweep — Three Passes

Code must read through its names, not through narration. Run the passes in order, report per pass. Scope: application source directories only — leave tests, config, and vendor code alone unless explicitly included.

Pass A — Comments

1. Find every inline // and /* */ comment in scope.
2. Apply per comment:
   • What-comment (restates the next line) → delete.
   • Genuine why (race condition, idempotency gate, security rationale, external quirk, legal constraint) → lift into the enclosing method PHPDoc/docstring, then delete the inline form.
   • Commented-out code → delete outright.
   • Bare // placeholders and trailing data annotations → delete; move rationale to class doc if it matters.
3. Class-level doc blocks always stay. Method-level docs only where they carry a why or a non-obvious contract.

Pass B — Extract Method

1. Inside each method, find self-contained blocks of 4+ lines that take input → transform → produce one output.
2. Extract each into a private method with an intent name — the name states what comes out, not how (priorComposites, buildRequestLine, advanceStatus).
3. Do NOT extract — over-extraction reads worse than inline code:
   • guard clauses and early returns
   • single statements or simple assignments
   • blocks mutating two or more enclosing-scope locals
4. Keep paired classes symmetric: if two sibling drivers/paths share a shape, give both the same extractions.

Pass C — Naming

1. For every class and public method in scope: read what it actually does, then judge the name against it.
2. Enforce the house rules:
   • class names carry type suffixes (Controller, Job, Service, Event, Listener, Factory)
   • queued classes carry the Job suffix; trigger-listeners are {Verb}On{Event}Listener
   • plain services use intent-named primary methods (check, create, process, store) — never handle(), which is reserved for framework contracts
   • enum cases are ALL_CAPS_SNAKE_CASE
3. Where a better name exists, propose current → suggested with a one-line justification. Apply renames only after the user picks; a rename is never silent.
4. Renames rot static-analysis baselines (entries embed symbol + path). After any applied rename, flag that the baseline needs regenerating.

Post-flight

Run the project's formatter and full test suite. Both must be clean before reporting.

Output Contract

Per pass: files touched and a compact change list (Pass A: comments deleted/lifted; Pass B: methods extracted with names; Pass C: renames proposed vs applied). Then: formatter + test results, and any baseline-regeneration flag. No essays.