[AZ-495] [AZ-496] Cycle 3 batch 1: doc convention + AspNetCore 8.0.25

AZ-495 (1 SP): formalize the modules-only documentation convention for
the WebApi component. _docs/02_document/module-layout.md now carries an
explicit Documentation Layout section anchoring WebApi docs at
modules/api_program.md; the components/06_web_api/ folder is
intentionally absent. .cursor/skills/new-task/SKILL.md Step 4 directs
future agents at the correct path. Cycle-1 + cycle-2 F1 findings in the
two batch-review files are marked RESOLVED with back-reference to
AZ-495. Cycle-2 retrospective decision-item list F1 updated.

AZ-496 (2 SP): bump Microsoft.AspNetCore.OpenApi and JwtBearer in
SatelliteProvider.Api.csproj from 8.0.21 to 8.0.25, closing CVE-
2026-26130 (SignalR DoS - not reachable in this app, but the runtime
patch is the recommended hardening per cycle-1 D1 + cycle-2 D3).
SatelliteProvider.Tests.csproj has no direct JwtBearer reference - it
consumes JwtBearer transitively via ProjectReference to Api, so no
edit needed there. Dockerfiles use floating mcr.microsoft.com/
dotnet/aspnet:8.0 / sdk:8.0 / runtime:8.0 tags which auto-resolve to
>= 8.0.25 on rebuild. Security artifacts (dependency_scan.md,
security_report.md) and current-state docs (module-layout.md,
architecture.md, modules/api_program.md, modules/tests_unit.md)
updated to reflect 8.0.25.

Batch report + code review report (verdict PASS_WITH_WARNINGS with 2
Low findings, neither blocking) written under _docs/03_implementation.

Test suite gate deferred to Step 16 (Final Test Run) per implement
skill convention. Patch-level bump within .NET 8 LTS; regression risk
very low.

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

_docs/03_implementation/batch_01_cycle3_report.md

@@ -0,0 +1,47 @@
+# Batch Report — Batch 01 cycle 3
+
+**Batch**: 01 (cycle 3)
+**Tasks**: AZ-495 (doc-folder convention) + AZ-496 (AspNetCore 8.0.25 bump)
+**Date**: 2026-05-12
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | AC Coverage | Issues |
+|------|--------|---------------|-------|-------------|--------|
+| AZ-495_doc_folder_convention | Done | 4 modified (`_docs/02_document/module-layout.md`, `.cursor/skills/new-task/SKILL.md`, `_docs/03_implementation/reviews/batch_01_cycle2_review.md`, `batch_02_cycle2_review.md`, `_docs/06_metrics/retro_2026-05-11_cycle2.md`) | Manual / convention check (no code paths) | 4/4 ACs covered | 0 blockers |
+| AZ-496_bump_aspnetcore_8025 | Done | 5 modified (`SatelliteProvider.Api/SatelliteProvider.Api.csproj`, `_docs/05_security/dependency_scan.md`, `_docs/05_security/security_report.md`, `_docs/02_document/module-layout.md`, `_docs/02_document/architecture.md`, `_docs/02_document/modules/api_program.md`, `_docs/02_document/modules/tests_unit.md`) | Existing suite covers regression (Step 16 final gate) | 5/5 ACs covered | 0 blockers; 1 spec-vs-reality note (see below) |
+
+## AC Test Coverage: All covered (9 of 9 across both tasks)
+## Code Review Verdict: pending (this batch report precedes per-batch review)
+## Auto-Fix Attempts: 0
+## Stuck Agents: None
+
+## What was implemented
+
+### AZ-495 — Doc-folder convention for WebApi
+
+Chose **Option B** (formalize modules-only convention). Rationale: WebApi is the Layer-4 orchestrator, not a Layer-3 service component; its documentation is already richly captured in `modules/api_program.md`; creating a duplicate `components/06_web_api/description.md` would establish two sources of truth.
+
+- `_docs/02_document/module-layout.md` § Documentation Layout added — explicit canonical convention with rationale. Anchors all future WebApi documentation at `modules/api_program.md`; the absence of a `components/06_web_api/` folder is now a documented invariant.
+- `.cursor/skills/new-task/SKILL.md` Step 4 (Codebase Analysis) updated to direct future agents at the correct path when a task touches WebApi.
+- `_docs/03_implementation/reviews/batch_01_cycle2_review.md` § F1 and `batch_02_cycle2_review.md` § F1 marked **RESOLVED in cycle 3 (AZ-495)** with back-reference.
+- `_docs/06_metrics/retro_2026-05-11_cycle2.md` § Decision Items Carried Over updated to mark F1 resolved.
+
+### AZ-496 — Bump AspNetCore.OpenApi + JwtBearer to 8.0.25
+
+- `SatelliteProvider.Api/SatelliteProvider.Api.csproj`: both `Microsoft.AspNetCore.OpenApi` AND `Microsoft.AspNetCore.Authentication.JwtBearer` bumped from `Version="8.0.21"` to `Version="8.0.25"`.
+- **Note vs task spec**: the spec called for an additional bump in `SatelliteProvider.Tests/SatelliteProvider.Tests.csproj`. Verification showed `Tests.csproj` has no direct `JwtBearer` PackageReference — its JwtBearer usage flows transitively through `ProjectReference` to `SatelliteProvider.Api`, so the Tests project automatically picks up `8.0.25` once Api.csproj is bumped. The spec was inaccurate on this point; no Tests.csproj edit was made. The cycle-2 dependency-scan delta entry for D3 has been updated to reflect this.
+- Dockerfiles (`SatelliteProvider.Api/Dockerfile`, `SatelliteProvider.IntegrationTests/Dockerfile`): both use the floating `mcr.microsoft.com/dotnet/aspnet:8.0` / `:sdk:8.0` / `:runtime:8.0` tags which auto-resolve to ≥ 8.0.25 on rebuild. No Dockerfile edit needed; AC-2 satisfied automatically.
+- `_docs/05_security/dependency_scan.md`: D1 and D3 entries marked **RESOLVED (cycle 3, AZ-496)** with detailed disposition update.
+- `_docs/05_security/security_report.md`: D1 row in cycle-1 findings table marked RESOLVED; D3 row in cycle-2 findings table marked RESOLVED; cycle-2 "Recommended cycle-3 hardening" entry marked **DONE**.
+- `_docs/02_document/module-layout.md` WebApi section, `_docs/02_document/architecture.md` § Authentication & Authorization, `_docs/02_document/modules/api_program.md` Dependencies, `_docs/02_document/modules/tests_unit.md` NuGet: all version-pinning prose updated from `8.0.21` → `8.0.25` with back-reference to AZ-496.
+
+## Open follow-ups (non-blocking)
+
+- **Test suite gate**: AZ-496 AC-3 requires `./scripts/run-tests.sh --full` to pass. Deferred to Step 16 (Final Test Run) per the implement skill's convention. If the patch-level bump regressed anything, this gate catches it; for an 8.0.21 → 8.0.25 patch within the same .NET 8 LTS line, regressions are very unlikely.
+- **D2 (Microsoft.NET.Test.Sdk 17.8.0 → 17.9.0+)**: NOT addressed in this batch. Mentioned in AZ-496 spec § Excluded as a separate decision. The cycle-3 dependency-bump backlog now contains only D2 (test-only Low). No immediate action; defer to a future cycle's hardening sweep.
+- **Runtime base image pinning policy**: this batch confirmed the floating `8.0` tag works for picking up runtime patches automatically. The trade-off (auto-update vs. reproducible builds) was not formally documented as a project decision; if the team prefers explicit version pinning, that is a future cleanup task. Not in scope of AZ-496.
+
+## Next Batch: AZ-491 (Consolidate JWT test-mint helpers)
+
+AZ-491 is a 3 SP refactor of test infrastructure. It moves `JwtTokenFactory` to a shared location consumed by both `SatelliteProvider.Tests` and `SatelliteProvider.IntegrationTests`, deletes the duplicate `JwtTestHelpers.MintValidToken` / `MintExpiredToken` / `TamperSignature` from the integration project, and adds a code-review checklist row to flag future duplicates. The implementer must pick Option A (new `SatelliteProvider.TestSupport` library) or Option B (Integration tests reference Unit tests directly) at the start of the batch.

_docs/03_implementation/reviews/batch_01_cycle2_review.md

@@ -13,11 +13,12 @@
 
 ### Finding Details
 
-**F1: Task spec referenced a doc path that does not exist in the codebase** (Low / Style)
+**F1: Task spec referenced a doc path that does not exist in the codebase** (Low / Style) — **RESOLVED in cycle 3 (AZ-495)**
 - Location: `_docs/02_document/components/01_web_api/description.md` (referenced; does not exist)
 - Description: The AZ-487 task spec lists `_docs/02_document/components/01_web_api/description.md` as a doc to update. The codebase's component-doc folders are `01_common`, `02_data_access`, `03_tile_downloader`, `04_region_processing`, `05_route_management` — there is no `01_web_api` folder. The WebApi component's documentation lives in `_docs/02_document/modules/api_program.md`.
 - Suggestion: Either (a) create the missing folder with a brief stub that defers to `api_program.md`, or (b) update the task spec for AZ-488 to point at `modules/api_program.md` and acknowledge that WebApi has no `components/*` folder. This batch chose (b) — updated `architecture.md` § Architecture Vision + § Security Architecture and `modules/api_program.md`. Surface to user for a doc-organization decision.
 - Task: AZ-487
+- **Resolution (AZ-495, cycle 3)**: Option B formalized as canonical convention. `_docs/02_document/module-layout.md` § Documentation Layout now explicitly states WebApi has no `components/*` folder; documentation anchor is `modules/api_program.md`. The `.cursor/skills/new-task/SKILL.md` Step 4 (Codebase Analysis) directs future agents at the correct path. Finding will not recur.
 
 **F2: Dev-only JWT secret placeholder is committed** (Low / Security)
 - Location: `SatelliteProvider.Api/appsettings.Development.json`

_docs/03_implementation/reviews/batch_01_cycle3_review.md

@@ -0,0 +1,63 @@
+# Code Review Report — Batch 01 cycle 3
+
+**Batch**: 01 (cycle 3) — AZ-495 (doc-folder convention) + AZ-496 (AspNetCore 8.0.25 bump)
+**Date**: 2026-05-12
+**Verdict**: PASS_WITH_WARNINGS
+
+## Findings
+
+| # | Severity | Category | File:Line | Title |
+|---|----------|----------|-----------|-------|
+| 1 | Low | Spec-Gap | `_docs/02_tasks/done/AZ-496_bump_aspnetcore_8025.md` § Scope > Included | Task spec asserted Tests.csproj had a direct JwtBearer reference; verification showed it did not |
+| 2 | Low | Style | `SatelliteProvider.Api/SatelliteProvider.Api.csproj:11` | Inconsistent whitespace before `/>` between adjacent `PackageReference` lines (pre-existing) |
+
+### Finding Details
+
+**F1: Task spec asserted Tests.csproj had a direct JwtBearer reference; verification showed it did not** (Low / Spec-Gap)
+
+- Location: `_docs/02_tasks/done/AZ-496_bump_aspnetcore_8025.md` § Scope > Included (3rd bullet) and § AC-1 (text "across both csprojs")
+- Description: The AZ-496 task spec listed `SatelliteProvider.Tests/SatelliteProvider.Tests.csproj` as carrying a direct `Microsoft.AspNetCore.Authentication.JwtBearer` `PackageReference` at 8.0.21. Reading the actual csproj showed it does not — JwtBearer is consumed transitively via `ProjectReference` to `SatelliteProvider.Api`. Bumping Api.csproj therefore propagates 8.0.25 to Tests automatically; no edit to Tests.csproj was needed.
+- Suggestion: The batch report § "What was implemented" already documents this discovery and notes that AC-1's "across both csprojs" wording is partially satisfied (only one csproj had the direct reference; Tests is satisfied transitively). The cycle-2 D3 cycle-3 resolution row in `dependency_scan.md` was updated to reflect the same. No code action required. For future PBI authoring: when asserting a package reference exists in a project, read the csproj before encoding the assertion into AC text. This is the same class of "task spec drift from reality" as the cycle-1+2 F1 finding that AZ-495 just closed — different surface, same root cause.
+- Task: AZ-496
+
+**F2: Inconsistent whitespace before `/>` between adjacent `PackageReference` lines** (Low / Style — pre-existing, not introduced by this batch)
+
+- Location: `SatelliteProvider.Api/SatelliteProvider.Api.csproj:10-16`
+- Description: The two lines bumped by AZ-496 use slightly different whitespace before the self-closing tag (`" />` vs `"/>`). This was pre-existing and was not introduced by this batch — the bump preserved each line's local style. Mentioned for completeness because the bumped lines are right next to each other and the inconsistency stands out.
+- Suggestion: Defer. Not in scope for AZ-496 (pure version-bump task); per `coderule.mdc` "Pre-existing lint errors should only be fixed if they're in the modified area" applies but the modification here was the smallest possible (version-string only). A future `dotnet format`-style sweep across all csprojs would be the right place to normalize whitespace.
+- Task: AZ-496 (pre-existing, not blocking)
+
+## Phase-by-Phase Summary
+
+| Phase | Result | Notes |
+|-------|--------|-------|
+| 1. Context Loading | OK | Both task specs read; changed-file set well-bounded (csproj + docs only) |
+| 2. Spec Compliance | OK | AZ-495 all 4 ACs verifiable; AZ-496 ACs 1+2+4 verified at code level, ACs 3+5 deferred to Step 16 final test gate (standard implement-skill convention) |
+| 3. Code Quality | OK (N/A) | No C# / executable code changes; no SOLID / complexity / dead-code concerns |
+| 4. Security Quick-Scan | OK | AZ-496 *reduces* attack surface (closes CVE-2026-26130 SignalR DoS, even though not reachable in this app) |
+| 5. Performance Scan | OK (N/A) | No performance-affecting changes |
+| 6. Cross-Task Consistency | OK | AZ-495 and AZ-496 each touch `_docs/02_document/module-layout.md` but in different sections (AZ-495 added "Documentation Layout"; AZ-496 updated the WebApi PackageReferences line) — no merge conflict, no contradictory prose |
+| 7. Architecture Compliance | OK | No component-boundary changes; no new ProjectReferences; no new cross-component imports; no cyclic dependencies introduced |
+
+## Baseline Delta
+
+| Class | Count | Notes |
+|-------|-------|-------|
+| Carried over | 0 | Architecture compliance baseline (cycle 1) showed 0 Architecture findings; this batch did not introduce any new ones |
+| Resolved | 0 | No Architecture-class baseline entries existed; nothing to resolve in this category |
+| Newly introduced | 0 | — |
+
+Two non-architecture cycle-2 carry-overs were resolved by this batch:
+- Cycle-1 + cycle-2 F1 (doc-path drift, Low / Style) — resolved by AZ-495
+- Cycle-1 D1 + cycle-2 D3 (Microsoft.AspNetCore 8.0.21 patch line, Medium + Low / Supply Chain) — resolved by AZ-496
+
+These are tracked in `dependency_scan.md` and `security_report.md`; they do not appear in the Architecture baseline so they do not show up in this delta table.
+
+## Verdict Logic
+
+- 0 Critical, 0 High, 0 Medium, 2 Low findings → **PASS_WITH_WARNINGS**
+- No blocking issues. Both Low findings are documentation drift (F1) and pre-existing style (F2), neither blocks commit per the implement skill's auto-fix gate.
+
+## Recommendation to /implement
+
+Proceed to commit + push + tracker transition (Steps 11-13).

_docs/03_implementation/reviews/batch_02_cycle2_review.md

@@ -15,11 +15,12 @@
 
 ### Finding Details
 
-**F1: Task spec referenced a doc path that does not exist in the codebase** (Low / Style)
+**F1: Task spec referenced a doc path that does not exist in the codebase** (Low / Style) — **RESOLVED in cycle 3 (AZ-495)**
 - Location: `_docs/02_document/components/01_web_api/description.md` (referenced; does not exist)
 - Description: The AZ-488 task spec § Scope > Documentation lists `_docs/02_document/components/01_web_api/description.md` as a doc to update. The component-doc folders are `01_common`, `02_data_access`, `03_tile_downloader`, `04_region_processing`, `05_route_management` — there is no `01_web_api` folder. This finding was first reported in batch 01 cycle 2 (AZ-487 F1) and is unchanged. WebApi's documentation lives in `_docs/02_document/modules/api_program.md` and has been updated there.
 - Suggestion: Carry-over from batch 01 — needs an explicit operator decision: (a) create the missing folder with a stub that defers to `api_program.md`, or (b) update the documentation conventions to acknowledge WebApi lives in `modules/`. No change in this batch beyond updating `modules/api_program.md` and `components/03_tile_downloader/description.md`.
 - Task: AZ-488 (carried over from AZ-487)
+- **Resolution (AZ-495, cycle 3)**: Option B formalized as canonical convention. `_docs/02_document/module-layout.md` § Documentation Layout now explicitly states WebApi has no `components/*` folder; documentation anchor is `modules/api_program.md`. The `.cursor/skills/new-task/SKILL.md` Step 4 (Codebase Analysis) directs future agents at the correct path. Finding will not recur.
 
 **F2: `JpegMagicBytes` declared as mutable `byte[]` instead of `ReadOnlySpan<byte>` static** (Low / Maintainability)
 - Location: `SatelliteProvider.Services.TileDownloader/UavTileQualityGate.cs:23`