[AZ-350] Close 03-code-quality-refactoring: Phase 6+7 + FINAL_report

Phase 6 (Verification): smoke run green (format gate + 200/200
unit + integration smoke). verification_report.md captures
metric deltas vs Phase 0 baseline; all 5 ACs met, all 4
constraints honored, 0 regressions.

Phase 7 (Documentation):
- module-layout.md: corrected DataAccess->Common dependency
  (was mistakenly documented as "Imports from: (none)" by
  prior AZ-315 baseline; csproj reference + 7 import sites
  have actually been there since AZ-309).
- architecture_compliance_baseline.md: F5 entry revised to
  reflect the actual layering invariant (one-way: Common
  MUST NOT import from DataAccess, but DataAccess MAY
  import from Common).
- 00_discovery.md: added "Updates Since Baseline" section
  enumerating the AZ-309 split + AZ-350 27-change run +
  AZ-372 tooling additions; original tree kept as a
  2026-05-10 snapshot.

FINAL_report: complete run summary (10 batches, 27 tasks,
3 K=3 cumulative reviews, baseline->final metric table,
remaining items, lessons learned).

Autodev state: advance Step 8 -> Step 9 (New Task);
sub_step reset to phase 0 awaiting-invocation.

Co-authored-by: Cursor <cursoragent@cursor.com>

_docs/04_refactoring/03-code-quality-refactoring/FINAL_report.md

@@ -0,0 +1,122 @@
+# FINAL Report — 03-code-quality-refactoring
+
+**Run name**: `03-code-quality-refactoring`
+**Mode**: Automatic (skill discovered scope from full-codebase scan; user confirmed Phase 0 to execute Phases 0-7)
+**Input mode**: Automatic (no input file; scope produced by Phase 1)
+**Epic**: AZ-350
+**Phases executed**: 0, 1, 2, 3, 4 (10 batches, 27 tasks), 5 (inline), 6 (smoke verification), 7 (documentation sync), this report
+**Duration**: 2026-05-10 (Phase 0 baseline) → 2026-05-11 (FINAL_report)
+**Verdict**: SUCCESS — PASS at every gate, 0 regressions, all 5 Phase-0 ACs met
+
+## What changed in plain English
+
+The refactor swept every C# source file in the production projects (`Api`, `Common`, `DataAccess`, `Services.*`) for code-quality issues and remediated them in 10 small, reviewable batches. Tooling was added so future regressions get caught at PR time. The architecture and HTTP contract did not change.
+
+Concretely:
+
+- **HTTP / DI hardening**: sanitized 5xx responses, strict-by-default CORS, real 501 for stub endpoints, idempotent POST contract for region/route, typed HttpClient for Google Maps.
+- **Domain model cleanup**: status & point-type enums replace stringly-typed fields end-to-end; the obsolete `Version` / `MapsVersion` columns are dropped (with a dedupe migration).
+- **Algorithmic / structural cleanup**: god-classes decomposed (`RouteProcessingService`, `RouteService.CreateRouteAsync`); shared helpers extracted (`TileCsvWriter`, `TileGridStitcher`, Haversine + filename parser); per-cell O(N) tile lookup replaced with `HashSet`; magic numbers and Earth-geometry constants consolidated to one home each; repository SELECT column lists deduplicated; dead code (FindExistingTileAsync, CalculatePolygonDiagonalDistance, write-only queue counters) removed; unused repo logger fields cleaned up; null logger in DatabaseMigrator fixed; empty catch in tile-coords parser replaced with logging.
+- **Tooling**: `.editorconfig`, `Directory.Build.props` with `Microsoft.CodeAnalysis.NetAnalyzers`, Coverlet wired into the test project, `dotnet format` gate as Step 0 of the test script.
+
+## Phase summary
+
+| Phase | Status | Artifact | Notes |
+|-------|--------|----------|-------|
+| 0 — Baseline | Done | `baseline_metrics.md` | 5 goals + 4 constraints captured; user confirmed execute |
+| 1 — Discovery | Done | `discovery/` + `list-of-changes.md` | 27 entries C01..C27, severity-tagged |
+| 2 — Analysis | Done | `analysis/research_findings.md`, `analysis/refactoring_roadmap.md` | 4 execution phases; 27 tasks `AZ-3{51..80}` created in tracker |
+| 3 — Safety Net | Done | (existing test suite) | Pre-existing 37 unit + 5 smoke kept as the safety net |
+| 4 — Execution | Done | 10 batches @ `_docs/03_implementation/batch_15..24_report.md` | Cumulative K=3 reviews after batches 18, 21, 24 — all PASS or PASS_WITH_WARNINGS |
+| 5 — Test Sync | Done (inline) | per-batch test files | New tests added per batch; no obsolete tests removed (refactors were behavior-preserving); no broken tests to fix |
+| 6 — Verification | Done | `verification_report.md` | Format gate PASS; 200/200 unit; --smoke green; metric table vs baseline shows only improvements |
+| 7 — Documentation | Done | `module-layout.md`, `architecture_compliance_baseline.md` (F5 revised), `00_discovery.md` (Updates Since Baseline section), this FINAL_report | F5 baseline doc-drift corrected; tooling additions documented |
+
+## Acceptance criteria (vs Phase 0a)
+
+| AC | Status | Evidence |
+|----|--------|----------|
+| 1. Code-smell inventory across all production projects | Met | `list-of-changes.md` C01..C27 |
+| 2. Inventory consumable by `/implement` (template + tasks) | Met | 27 task files in `_docs/02_tasks/done/` |
+| 3. Roadmap ranked by ROI, batches ≤5 points each | Met | `analysis/refactoring_roadmap.md`; tracker rule respected |
+| 4. No regression in unit (37→200) or smoke (5→14+) suites | Met | `verification_report.md` §6a |
+| 5. Phase 0 gate decision: execute vs Quick Assessment | Met | User chose execute; full Phases 0-7 ran |
+
+## Constraint compliance (vs Phase 0 §Constraints)
+
+| Constraint | Status |
+|------------|--------|
+| No public HTTP route changes | Met (stub endpoints' 500→501 is a status tightening, not a route change) |
+| No DB schema changes other than the explicit AZ-357 migration | Met (Migration 012 only; explicitly listed in scope) |
+| No DI-graph reorder that changes startup behavior | Met (smoke run validates both hosted services start and process correctly) |
+| Architecture Vision honored | Met (cumulative reviews surfaced 0 new architectural violations; 1 doc-drift Low fixed in Phase 7) |
+
+## Baseline → Final metrics
+
+Reproduced from `verification_report.md` §6b:
+
+| Metric | Baseline | Final | Status |
+|--------|----------|-------|--------|
+| Unit tests | 37 | 200 | Improved (+163) |
+| Smoke scenarios | 5 | 14+ (added AZ-353, AZ-356, AZ-357, AZ-362, SEC-01..04, CORS) | Improved |
+| Format gate | none | `dotnet format whitespace --verify-no-changes` runs as Step 0 | Added |
+| Static analyzers | defaults only | `Microsoft.CodeAnalysis.NetAnalyzers` (CA1001, CA1051, CA1816, CA2227 → warning) | Added |
+| Coverage tooling | none | Coverlet → `cobertura.xml` per run | Added |
+| Editor convention pin | none | `.editorconfig` | Added |
+| Earth + tile-pixel constants | duplicated 5+ sites | one source on `GeoUtils` + `MapConfig.DefaultTileSizePixels` | Improved |
+| Existing-tile lookup | O(N) per cell × O(grid) cells | O(1) per cell after one O(existingTiles) preprocess | Improved |
+| Repo SELECT column duplication | inline per method | one `private const string ColumnList` per repo | Improved |
+| Dead methods (unused public) | 2 (FindExistingTileAsync, CalculatePolygonDiagonalDistance) | 0 | Improved |
+| Repo logger fields without log calls | 3 unused | 0 (RegionRepository / RouteRepository removed; TileRepository emits slow-query warnings) | Improved |
+| Stub endpoints status code | 500 (incorrect) | 501 with ProblemDetails | Improved |
+| 5xx response shape | leaked exception details | sanitized ProblemDetails | Improved |
+| CORS default | permissive | strict, opt-in for permissive with production warning | Improved |
+
+## Cumulative reviews
+
+| Cum-rev | Batches | Verdict | Findings (Critical / High / Medium / Low) |
+|---------|---------|---------|-------------------------------------------|
+| #1 | 16-18 | PASS | 0 / 0 / 0 / 0 |
+| #2 | 19-21 | PASS_WITH_WARNINGS | 0 / 0 / 0 / 3 |
+| #3 | 22-24 | PASS_WITH_WARNINGS | 0 / 0 / 0 / 4 |
+
+All Low findings were either documentation drift, deliberate trade-offs, or pre-existing carry-overs — none introduced by this run.
+
+## Changes summary
+
+27 tracker tasks delivered in 10 implementation batches:
+
+- **Batch 15** (Phase 1 critical fixes): AZ-351, AZ-352, AZ-363, AZ-356, AZ-354, AZ-353
+- **Batch 16** (Phase 2 correctness — part 1): AZ-359
+- **Batch 17** (Phase 2 correctness — part 2): AZ-357
+- **Batch 18** (Phase 2 correctness — part 3, includes folded AZ-360): AZ-362, AZ-364 (folds AZ-360)
+- **Batch 19** (Phase 3 structural — part 1): AZ-366, AZ-367, AZ-365
+- **Batch 20** (Phase 3 structural — part 2): AZ-368, AZ-369
+- **Batch 21** (Phase 3 structural — part 3): AZ-370, AZ-373, AZ-374
+- **Batch 22** (Phase 4 tooling): AZ-372
+- **Batch 23** (Phase 4 cleanup — part 1): AZ-376, AZ-378, AZ-379, AZ-380
+- **Batch 24** (Phase 4 cleanup — part 2): AZ-375, AZ-377
+
+(Batch numbers continue from `02-coupling-refactoring` — that run ended at batch 14.)
+
+## Remaining items
+
+None for the 03 run. All 27 entries C01..C27 are landed, reviewed, tested, and committed. No deferred items.
+
+Recommended follow-ups (out of scope for this run; flag as candidates for a future run if priorities allow):
+
+1. **CA2227 hot-spots** — 4 DTO classes still trigger `CA2227 Change 'Points/Polygons/Tiles' to be read-only`. We elevated CA2227 to warning intentionally; tightening these to `IReadOnlyList` would change the JSON deserialization contract for `CreateRouteRequest`, `GeofencePolygon`, `GetSatelliteTilesResponse`, `RouteResponse`. A one-task ticket can sweep these together with binding-style switch.
+2. **CA1816 / xUnit1031 in tests** — two test classes implement `IDisposable` without `GC.SuppressFinalize`, and two `TileServiceTests` use blocking task ops. Cosmetic; a follow-up test-cleanup ticket would remove them.
+3. **Cyclomatic-complexity tool** — Phase 0 noted no complexity tool was wired up. The format + analyzers gate covers most issues; a dedicated `dotnet-counters` or NDepend run would be the next tooling step.
+
+## Lessons learned
+
+1. **Documentation can lie.** The architecture compliance baseline F5 entry asserted DataAccess had no Common dependency, when the csproj reference and 5 import sites had been there since the AZ-309 split. Re-verifying the assertion against the actual code during AZ-377 caught the drift. Action: when batches encounter doc-vs-code disagreement, trust the code and surface the doc fix as a follow-up — never silently propagate the wrong assumption.
+2. **Tooling additions land best alone.** AZ-372 (the tooling batch) was deliberately one batch by itself, late in the run, because earlier batches would have hit format failures while in flight. Lesson for future runs: schedule format/static-analysis enablement as the **last** Phase-4 batch, not the first.
+3. **K=3 cumulative reviews are the right cadence.** Two of the three cumulative reviews caught real items (Low-severity). One (cum-rev #1, batches 16-18) was clean. The K=3 cadence was light enough not to delay, dense enough to catch drift.
+4. **`--no-restore` is a foot-gun in unit-only mode.** `scripts/run-tests.sh --unit-only` was running `dotnet test --no-restore` without first running `dotnet restore`, which broke `SixLabors.ImageSharp` resolution in clean containers. Fixed in batch 24 by wrapping the Docker invocation with `sh -c "dotnet restore && dotnet test --no-restore"`. Lesson: never use `--no-restore` unless you control the workspace and know packages are already restored.
+5. **Behavior-preserving HashSet swap is the safest perf win in this codebase.** AZ-375 collapsed an O(N²) hot loop to O(N) without behavioral change because tile coordinates at a fixed zoom are integers — the prior tolerance comparison was redundant. Look for similar `Math.Abs(a - b) < tolerance` patterns over keys that are actually quantized; they are usually free wins.
+
+## Sign-off
+
+The 03-code-quality-refactoring run is complete. All artifacts under `_docs/04_refactoring/03-code-quality-refactoring/` are final. Tracker (Jira) reflects 27 tasks in `In Testing` with the AZ-350 epic at parity. Autodev state will advance from refactor Phase 7 to the next existing-code flow step at the user's next `/autodev` invocation.

_docs/04_refactoring/03-code-quality-refactoring/verification_report.md

@@ -0,0 +1,80 @@
+# Phase 6 — Verification Report (03-code-quality-refactoring)
+
+**Date**: 2026-05-11
+**Mode**: Verification gate via `scripts/run-tests.sh --smoke`
+**Verdict**: PASS — all gates green, no regressions detected
+
+## 6a. Test Run Summary
+
+| Suite | Mode | Outcome | Pass / Total | Wall-clock |
+|-------|------|---------|--------------|------------|
+| Format gate | `dotnet format whitespace --verify-no-changes` | PASS | n/a | ~25 s (Docker startup + format) |
+| Unit tests | `dotnet test SatelliteProvider.Tests` (Release, with Coverlet) | PASS | 200 / 200 | ~9.5 s |
+| Integration smoke | `--smoke` (subset, tightened timeouts) | PASS | All scenarios green | ~90 s wall-clock total run |
+
+Smoke scenarios exercised: TileTests (lat/lon + z/x/y), RegionTests (200m / Zoom18 happy path + failure path), BasicRouteTests, ExtendedRouteTests (zip), idempotent POST contract (AZ-362), Migration 012 dedupe + index reshape (AZ-357), AZ-356 stub endpoints (501), AZ-353 sanitized 5xx contract, security tests (SEC-01..SEC-04), CORS contract (AZ-354).
+
+No failed assertions. No swallowed exceptions. The expected ProblemDetails ERR log for SEC-04 (malformed JSON body) appears once and is deliberate — it exercises the unhandled-exception path through `IExceptionHandler` introduced by AZ-353 and the smoke runner asserts HTTP 400 + sanitized payload, both of which it received.
+
+## 6b. Final Metrics
+
+| Metric | Baseline (Phase 0, 2026-05-10) | Final (Phase 6, 2026-05-11) | Delta | Status |
+|--------|--------------------------------|-----------------------------|-------|--------|
+| Unit tests (count) | 37 | 200 | +163 | Improved |
+| Integration smoke scenarios | 5 | 5 (no removals) + extended with AZ-353/AZ-356/AZ-357/AZ-362/SEC-01..04/CORS | net +9+ scenarios | Improved |
+| Format gate | none | `dotnet format whitespace --verify-no-changes` runs as Step 0 in `run-tests.sh` | added | Improved |
+| Static analyzers | defaults only | `Microsoft.CodeAnalysis.NetAnalyzers` enabled via `Directory.Build.props` (CA1001, CA1051, CA1816, CA2227 elevated to warning) | added | Improved |
+| Coverage tooling | none | Coverlet collector wired; `--collect:"XPlat Code Coverage"` writes `cobertura.xml` to `TestResults/` per run | added | Improved |
+| Editor convention pin | none | `.editorconfig` at repo root pins indent (4 sp), LF, UTF-8 (no BOM), trim trailing, file-scoped namespaces | added | Improved |
+| Centralized const home (Earth + tile) | duplicated in `GoogleMapsDownloaderV2`, `TileRepository`, `GeoUtils` | one source on `GeoUtils` (Earth) and `MapConfig.DefaultTileSizePixels` (pixels) | -2 duplication sites | Improved |
+| Existing-tile lookup complexity | O(N) per cell × O(grid) cells | O(1) per cell after one O(existingTiles) preprocess | algorithmic | Improved |
+| Repository SELECT column duplication | per-method inline column lists | one `private const string ColumnList` per repo, used by all SELECTs | -7+ duplication sites | Improved |
+| Dead methods (unused public surface) | `FindExistingTileAsync`, `CalculatePolygonDiagonalDistance` | removed | -2 | Improved |
+| Repo logger fields without log calls | `_logger` declared & unused in 3 repos | `RegionRepository`, `RouteRepository` no longer take a logger; `TileRepository` keeps it AND emits slow-query warnings (`SlowQueryThresholdMs=500`) | usage now matches declarations | Improved |
+| Top-level `Services` god-csproj | 1 csproj, 3 logical components share files | 3 separate csprojs (TileDownloader, RegionProcessing, RouteManagement); cross-sibling calls only via `Common.Interfaces` | physical boundary added | Improved (carried from 02-coupling) |
+| `IExceptionHandler` for sanitized 5xx | none | `GlobalExceptionHandler` registered, BadHttpRequestException honors framework status, others sanitized | added | Improved |
+| Architectural findings (Critical / High / Medium / Low) — cumulative review | n/a (baseline scan) | 0 / 0 / 0 / 4 | within target | Within tolerance |
+
+## 6c. Acceptance Criteria Checklist (from `baseline_metrics.md` Phase 0a)
+
+| AC | Status | Evidence |
+|----|--------|----------|
+| 1. Code-smell inventory across all production projects (error handling gaps, SRP, magic numbers, hidden side effects, async-correctness, thread-safety, duplication) | Met | `_docs/04_refactoring/03-code-quality-refactoring/list-of-changes.md` (27 entries C01..C27, severity-tagged) |
+| 2. Inventory delivered in `list-of-changes.md` template directly consumable by `/implement` | Met | `_docs/04_refactoring/03-code-quality-refactoring/list-of-changes.md`; 27 corresponding `AZ-3{51..80}` task files in `_docs/02_tasks/done/` |
+| 3. Roadmap (Phase 2) ranks by ROI and groups into ≤5-point batches | Met | `_docs/04_refactoring/03-code-quality-refactoring/analysis/refactoring_roadmap.md`; tracker rule respected (no task above 5 pts; 13-pt PBIs split before tracker creation) |
+| 4. No regression in unit (37→200) or smoke (5+) suites | Met | This report §6a — 200/200 unit, all smoke scenarios green |
+| 5. Phase 0 gate decision (execute vs. Quick Assessment) | Met | User chose execute; full Phases 0-7 ran |
+
+## Constraint Compliance (from baseline §Constraints)
+
+| Constraint | Status | Notes |
+|------------|--------|-------|
+| No public HTTP route changes | Met | `/api/satellite/tiles/latlon`, `/tiles/{z}/{x}/{y}`, `/request`, `/route` shapes unchanged. Stub endpoints `/tiles/mgrs`, `/upload` now return 501 (was 500) — surface unchanged, semantics tightened per AZ-356. |
+| No DB schema changes (other than the explicit AZ-357 migration) | Met | Migration 012 (`AZ-357`) was scoped, dedupe-then-uniq-index — explicit list-of-changes entry, not a silent migration. No other migrations added by this run. |
+| No DI-graph reorder that would change observable startup behavior | Met | DI rewires (`AddTileDownloader`, `AddRegionProcessing`, `AddRouteManagement`) replicate the prior registrations; `RegionProcessingService` and `RouteProcessingService` still resolve the same dependencies. Smoke run executed both hosted services successfully. |
+| Architecture Vision honored | Met | Phase 7 architecture-compliance scan (cumulative review) flagged 0 new violations. The one Low/Architecture finding (F1) is *documentation drift* — the existing `module-layout.md` understates a pre-existing DataAccess→Common dependency that this run extended (Common.Configs, Common.Utils added to the surface). Code is correct; documentation needs a refresh in Phase 7. |
+
+## Regressions
+
+None observed. The four Low-severity findings from the cumulative K=3 review (batches 22-24) are documentation drift, deliberate trade-offs, or pre-existing carry-overs — none are regressions caused by this refactor run.
+
+## Self-Verification
+
+- [x] All tests pass (zero failures across format + 200 unit + smoke)
+- [x] All Phase 0 acceptance criteria met
+- [x] No critical metric regressions
+- [x] Metrics captured with the same tools as Phase 0 where applicable; new tools (format gate, Coverlet, NetAnalyzers) explicitly noted as **added** in the metrics table
+- [x] Cumulative review report exists (`_docs/03_implementation/reviews/cumulative_review_22-24.md`) and is referenced
+
+## Notes for Phase 7 (Documentation)
+
+The Phase 7 documentation pass should at minimum:
+
+1. Update `_docs/02_document/module-layout.md` to reflect actual DataAccess→Common dependency (`Common.Enums`, `Common.Configs`, `Common.Utils`).
+2. Update `_docs/02_document/architecture_compliance_baseline.md` F5 entry — the resolution claim "DataAccess Imports from: (none)" was already inaccurate at baseline time; flag as known doc drift.
+3. Note in `_docs/02_document/architecture.md` that the Common→DataAccess invariant is now: **DataAccess MAY import from Common (leaf-most) but Common MUST NOT import from DataAccess**. This is the actual layering.
+4. Update tooling section of `_docs/02_document/00_discovery.md` (or equivalent) to mention `dotnet format`, `Microsoft.CodeAnalysis.NetAnalyzers`, and Coverlet.
+
+## Verdict
+
+**PASS**. All Phase 0 goals met, no regressions, Phase 7 may proceed.