mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-27 07:21:14 +00:00
[AZ-1132] [AZ-1133] Cycle 15 closeout and cycle 16 task setup
Doc ripple for FluentValidation bump, cycle 15 retro, and AZ-1133 perf preflight task queued for cycle 16. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -207,7 +207,7 @@ The authoritative source/flight markers are the `tiles.source` and `tiles.flight
|
|||||||
Every public HTTP endpoint MUST reject malformed or out-of-range payloads with HTTP 400 + RFC 7807 `ValidationProblemDetails`. The shared infrastructure landed in AZ-795 (cycle 7) is two collaborating layers:
|
Every public HTTP endpoint MUST reject malformed or out-of-range payloads with HTTP 400 + RFC 7807 `ValidationProblemDetails`. The shared infrastructure landed in AZ-795 (cycle 7) is two collaborating layers:
|
||||||
|
|
||||||
1. **Deserializer-level rejection** — `JsonSerializerOptions.UnmappedMemberHandling.Disallow` configured in `Program.cs` (`ConfigureHttpJsonOptions`) catches unknown fields, type mismatches, and malformed JSON. The framework wraps the resulting `JsonException` in `BadHttpRequestException`; `GlobalExceptionHandler` extracts the JSON path and emits a structured `ValidationProblemDetails` body.
|
1. **Deserializer-level rejection** — `JsonSerializerOptions.UnmappedMemberHandling.Disallow` configured in `Program.cs` (`ConfigureHttpJsonOptions`) catches unknown fields, type mismatches, and malformed JSON. The framework wraps the resulting `JsonException` in `BadHttpRequestException`; `GlobalExceptionHandler` extracts the JSON path and emits a structured `ValidationProblemDetails` body.
|
||||||
2. **Business-rule rejection** — `FluentValidation` 12.0.0 validators registered via `AddValidatorsFromAssemblyContaining<Program>()` and wired through the generic `ValidationEndpointFilter<T>` (`SatelliteProvider.Api/Validators/ValidationEndpointFilter.cs`). Endpoints opt in via `RouteHandlerBuilder.WithValidation<T>()`; the filter calls `Results.ValidationProblem(result.ToDictionary())` on failure.
|
2. **Business-rule rejection** — `FluentValidation` 12.1.1 validators registered via `AddValidatorsFromAssemblyContaining<Program>()` and wired through the generic `ValidationEndpointFilter<T>` (`SatelliteProvider.Api/Validators/ValidationEndpointFilter.cs`). Endpoints opt in via `RouteHandlerBuilder.WithValidation<T>()`; the filter calls `Results.ValidationProblem(result.ToDictionary())` on failure.
|
||||||
|
|
||||||
Both layers produce the wire shape documented in `_docs/02_document/contracts/api/error-shape.md` (v1.0.0).
|
Both layers produce the wire shape documented in `_docs/02_document/contracts/api/error-shape.md` (v1.0.0).
|
||||||
|
|
||||||
|
|||||||
@@ -14,7 +14,7 @@ Defines the uniform RFC 7807 ProblemDetails / ValidationProblemDetails shape eve
|
|||||||
The contract is enforced by two collaborating pieces of shared infrastructure:
|
The contract is enforced by two collaborating pieces of shared infrastructure:
|
||||||
|
|
||||||
1. **Deserializer-level rejection** — `JsonSerializerOptions.UnmappedMemberHandling.Disallow` (.NET 8+) catches unknown fields, type mismatches, and malformed JSON. The framework's `BadHttpRequestException` carries a `System.Text.Json.JsonException` as its inner exception; `GlobalExceptionHandler` (`SatelliteProvider.Api/GlobalExceptionHandler.cs`) extracts the JSON path and emits a `ValidationProblemDetails` body.
|
1. **Deserializer-level rejection** — `JsonSerializerOptions.UnmappedMemberHandling.Disallow` (.NET 8+) catches unknown fields, type mismatches, and malformed JSON. The framework's `BadHttpRequestException` carries a `System.Text.Json.JsonException` as its inner exception; `GlobalExceptionHandler` (`SatelliteProvider.Api/GlobalExceptionHandler.cs`) extracts the JSON path and emits a `ValidationProblemDetails` body.
|
||||||
2. **Business-rule rejection** — `FluentValidation` (12.0.0) validators wired through the generic `ValidationEndpointFilter<T>` (`SatelliteProvider.Api/Validators/ValidationEndpointFilter.cs`). Endpoints opt in via `RouteHandlerBuilder.WithValidation<T>()`. The filter calls `Results.ValidationProblem(result.ToDictionary())`, which produces an identically-shaped body.
|
2. **Business-rule rejection** — `FluentValidation` (12.1.1) validators wired through the generic `ValidationEndpointFilter<T>` (`SatelliteProvider.Api/Validators/ValidationEndpointFilter.cs`). Endpoints opt in via `RouteHandlerBuilder.WithValidation<T>()`. The filter calls `Results.ValidationProblem(result.ToDictionary())`, which produces an identically-shaped body.
|
||||||
|
|
||||||
Both paths produce `Content-Type: application/problem+json`. Both populate the same `errors` map keyed by request-body field path.
|
Both paths produce `Content-Type: application/problem+json`. Both populate the same `errors` map keyed by request-body field path.
|
||||||
|
|
||||||
|
|||||||
@@ -141,7 +141,7 @@ The cycle-1 (AZ-487) and cycle-2 (AZ-488) code reviews each surfaced an F1 (Low
|
|||||||
- `SatelliteProvider.Api/Grpc/RouteTileDeliveryGrpcService.cs` (added cycle 9 — AZ-1074; server-streaming gRPC adapter over `IRouteTileDeliveryOrchestrator`)
|
- `SatelliteProvider.Api/Grpc/RouteTileDeliveryGrpcService.cs` (added cycle 9 — AZ-1074; server-streaming gRPC adapter over `IRouteTileDeliveryOrchestrator`)
|
||||||
- **Internal**: (none)
|
- **Internal**: (none)
|
||||||
- **Owns**: `SatelliteProvider.Api/**`
|
- **Owns**: `SatelliteProvider.Api/**`
|
||||||
- **PackageReferences (added by AZ-487, bumped by AZ-496, then by AZ-500; AZ-795 added FluentValidation)**: `Microsoft.AspNetCore.Authentication.JwtBearer` 10.0.7 (pinned to the same minor patch as `Microsoft.AspNetCore.OpenApi` 10.0.7; AZ-496 bumped both packages from 8.0.21 → 8.0.25 in cycle 3 to close cycle-1 D1 + cycle-2 D3 supply-chain findings, then AZ-500 bumped both 8.0.25 → 10.0.7 in cycle 4 as part of the .NET 8 → .NET 10 migration; AZ-500 also bumped `Swashbuckle.AspNetCore` 6.6.2 → 10.1.7 here to land Microsoft.OpenApi 2.x compat required by ASP.NET Core 10). `FluentValidation` + `FluentValidation.DependencyInjectionExtensions` 12.0.0 added by AZ-795 to back the strict-input-validation epic.
|
- **PackageReferences (added by AZ-487, bumped by AZ-496, then by AZ-500; AZ-795 added FluentValidation; AZ-1132 bumped FluentValidation cycle 15)**: `Microsoft.AspNetCore.Authentication.JwtBearer` 10.0.7 (pinned to the same minor patch as `Microsoft.AspNetCore.OpenApi` 10.0.7; AZ-496 bumped both packages from 8.0.21 → 8.0.25 in cycle 3 to close cycle-1 D1 + cycle-2 D3 supply-chain findings, then AZ-500 bumped both 8.0.25 → 10.0.7 in cycle 4 as part of the .NET 8 → .NET 10 migration; AZ-500 also bumped `Swashbuckle.AspNetCore` 6.6.2 → 10.1.7 here to land Microsoft.OpenApi 2.x compat required by ASP.NET Core 10). `FluentValidation` + `FluentValidation.DependencyInjectionExtensions` 12.1.1 (added at 12.0.0 by AZ-795; bumped 12.0.0 → 12.1.1 by AZ-1132 cycle 15).
|
||||||
- **Imports from**: Common (incl. AZ-488 UAV DTOs + `UavQualityConfig`), DataAccess, TileDownloader (incl. AZ-488 `IUavTileUploadHandler`), RegionProcessing, RouteManagement, GrpcContracts (cycle 9)
|
- **Imports from**: Common (incl. AZ-488 UAV DTOs + `UavQualityConfig`), DataAccess, TileDownloader (incl. AZ-488 `IUavTileUploadHandler`), RegionProcessing, RouteManagement, GrpcContracts (cycle 9)
|
||||||
- **Consumed by**: (none — top-level entry point)
|
- **Consumed by**: (none — top-level entry point)
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,18 @@
|
|||||||
|
# Ripple Log — Cycle 15
|
||||||
|
|
||||||
|
Task: AZ-1132 (FluentValidation 12.0.0 → 12.1.1 — D-AZ795-1 closure)
|
||||||
|
|
||||||
|
## Docs updated directly (task scope)
|
||||||
|
|
||||||
|
- `_docs/02_document/modules/api_program.md` — NuGet pin 12.1.1 (implementation batch)
|
||||||
|
- `_docs/02_document/modules/tests_unit.md` — FluentValidation.TestHelper pin 12.1.1 (implementation batch)
|
||||||
|
|
||||||
|
## Import-graph ripple (Step 0.5)
|
||||||
|
|
||||||
|
- `_docs/02_document/module-layout.md` — PackageReferences FluentValidation version 12.0.0 → 12.1.1
|
||||||
|
- `_docs/02_document/contracts/api/error-shape.md` — FluentValidation version reference
|
||||||
|
- `_docs/02_document/architecture.md` — FluentValidation version reference
|
||||||
|
|
||||||
|
## System-level / component docs
|
||||||
|
|
||||||
|
- None — no API, schema, or runtime behavior change
|
||||||
@@ -226,7 +226,8 @@
|
|||||||
| Cycle 12 — AZ-1124 PT-10 gRPC stream perf (perf harness + unit) | 1 perf (PT-10) + 3 unit (`PerfBootstrapPt10Tests`) + integration bootstrap (`SatelliteProvider.IntegrationTests --run-pt10`) | 6/6 in-scope (AZ-1124 AC-1..AC-6); 1 AC gated at Step 15 (AC-3); 1 doc-verified at Step 13 (AC-5) | — |
|
| Cycle 12 — AZ-1124 PT-10 gRPC stream perf (perf harness + unit) | 1 perf (PT-10) + 3 unit (`PerfBootstrapPt10Tests`) + integration bootstrap (`SatelliteProvider.IntegrationTests --run-pt10`) | 6/6 in-scope (AZ-1124 AC-1..AC-6); 1 AC gated at Step 15 (AC-3); 1 doc-verified at Step 13 (AC-5) | — |
|
||||||
| Cycle 13 — AZ-1126 capturedAt DateTimeOffset (integration + unit + blackbox + contract patch) | 1 integration method (`UavUploadValidationTests.ItemCapturedAtOffsetLess_Returns400`) + 4 unit files (`UtcOffsetRequiredDateTimeOffsetConverterTests`, updated UAV validator/gate/handler tests) + 1 blackbox (BT-34 with 2 sub-cases) + `uav-tile-upload.md` v1.2.1 patch | 4/4 in-scope (AZ-1126 AC-1..AC-4); 1 doc-verified at Step 13 (AC-4); closes F-AZ810-2 | — |
|
| Cycle 13 — AZ-1126 capturedAt DateTimeOffset (integration + unit + blackbox + contract patch) | 1 integration method (`UavUploadValidationTests.ItemCapturedAtOffsetLess_Returns400`) + 4 unit files (`UtcOffsetRequiredDateTimeOffsetConverterTests`, updated UAV validator/gate/handler tests) + 1 blackbox (BT-34 with 2 sub-cases) + `uav-tile-upload.md` v1.2.1 patch | 4/4 in-scope (AZ-1126 AC-1..AC-4); 1 doc-verified at Step 13 (AC-4); closes F-AZ810-2 | — |
|
||||||
| Cycle 14 — AZ-1131 environment.md integration command (doc-only) | doc-only (`environment.md`, `README.md`, `AGENTS.md` integration-test orchestration) | 3/3 in-scope (AZ-1131 AC-1..AC-3); doc-verified at Step 13; smoke regression Step 11 | — |
|
| Cycle 14 — AZ-1131 environment.md integration command (doc-only) | doc-only (`environment.md`, `README.md`, `AGENTS.md` integration-test orchestration) | 3/3 in-scope (AZ-1131 AC-1..AC-3); doc-verified at Step 13; smoke regression Step 11 | — |
|
||||||
| **Total** | **174** | **137/137 in-scope (100%); 3 ACs gated at Step 15 (2 AZ-504 + 1 AZ-1124 AC-3); 14 prior-cycle ACs doc-verified at Step 13 (2 cycle-7 + 8 cycle-8 + 1 AZ-1124 AC-5 + 3 AZ-1131); 2 advisory non-tested (cycle-8 AZ-809 AC-9/AC-10)** | **8/8 (100%)** |
|
| Cycle 15 — AZ-1132 FluentValidation bump (dependency + security) | structural (`SatelliteProvider.Api.csproj` pins) + validator unit regression (`SatelliteProvider.Tests/Validators/*`) + validation integration regression (inventory, region, route, upload, latlon) + security scan artifacts | 5/5 in-scope (AZ-1132 AC-1..AC-5); AC-5 in `_docs/05_security/` cycle-15 artifacts; full suite Step 11 | — |
|
||||||
|
| **Total** | **174** | **142/142 in-scope (100%); 3 ACs gated at Step 15 (2 AZ-504 + 1 AZ-1124 AC-3); 14 prior-cycle ACs doc-verified at Step 13 (2 cycle-7 + 8 cycle-8 + 1 AZ-1124 AC-5 + 3 AZ-1131); 2 advisory non-tested (cycle-8 AZ-809 AC-9/AC-10)** | **8/8 (100%)** |
|
||||||
|
|
||||||
**Coverage shape notes (Cycle 5 — AZ-503 foundation):**
|
**Coverage shape notes (Cycle 5 — AZ-503 foundation):**
|
||||||
- AZ-503 was split mid-cycle (Option C, autodev Step 10 batch 2): 7 of 12 original ACs land here; 5 (AC-5, AC-6, AC-9, AC-10, AC-12) are deferred to AZ-505 with a `Blocks` link in Jira and an entry in `_docs/02_tasks/_dependencies_table.md`. The deferred rows above are marked `◐ deferred → AZ-505` so the matrix surfaces the scope boundary explicitly.
|
- AZ-503 was split mid-cycle (Option C, autodev Step 10 batch 2): 7 of 12 original ACs land here; 5 (AC-5, AC-6, AC-9, AC-10, AC-12) are deferred to AZ-505 with a `Blocks` link in Jira and an entry in `_docs/02_tasks/_dependencies_table.md`. The deferred rows above are marked `◐ deferred → AZ-505` so the matrix surfaces the scope boundary explicitly.
|
||||||
@@ -299,6 +300,17 @@
|
|||||||
| AZ-1131 AC-1 | `environment.md` § Test Execution matches `run-tests.sh` Step 2 (`docker-compose.tests.yml` only) | doc-state AC; `rg` zero stale dual-compose matches; verified at Step 13 | ✓ |
|
| AZ-1131 AC-1 | `environment.md` § Test Execution matches `run-tests.sh` Step 2 (`docker-compose.tests.yml` only) | doc-state AC; `rg` zero stale dual-compose matches; verified at Step 13 | ✓ |
|
||||||
| AZ-1131 AC-2 | `README.md` + `AGENTS.md` point to `./scripts/run-tests.sh` (no stale dual-compose) | doc-state AC; `rg` zero stale dual-compose matches; verified at Step 13 | ✓ |
|
| AZ-1131 AC-2 | `README.md` + `AGENTS.md` point to `./scripts/run-tests.sh` (no stale dual-compose) | doc-state AC; `rg` zero stale dual-compose matches; verified at Step 13 | ✓ |
|
||||||
| AZ-1131 AC-3 | No runtime change — smoke regression unchanged | `./scripts/run-tests.sh --smoke` Step 11 (EXIT:0) | ✓ |
|
| AZ-1131 AC-3 | No runtime change — smoke regression unchanged | `./scripts/run-tests.sh --smoke` Step 11 (EXIT:0) | ✓ |
|
||||||
|
| AZ-1132 AC-1 | Both FluentValidation packages pinned to 12.1.1 in `SatelliteProvider.Api.csproj` | Structural: csproj `PackageReference` versions; lockstep bump of `FluentValidation` + `FluentValidation.DependencyInjectionExtensions` | ✓ |
|
||||||
|
| AZ-1132 AC-2 | Validator unit tests pass unchanged | `SatelliteProvider.Tests/Validators/*` at Step 11 (144 passed per batch report) | ✓ |
|
||||||
|
| AZ-1132 AC-3 | Validation integration tests pass unchanged | Inventory, region, route, upload, latlon validation integration suites at Step 11 full `./scripts/run-tests.sh` (457 unit + integration) | ✓ |
|
||||||
|
| AZ-1132 AC-4 | Production FluentValidation absent from vulnerable-package scan | `dotnet list SatelliteProvider.sln package --vulnerable` (batch closure); `dependency_scan_cycle15.md` | ✓ |
|
||||||
|
| AZ-1132 AC-5 | Security finding D-AZ795-1 resolved | `_docs/05_security/dependency_scan_cycle15.md` + `security_report_cycle15.md` — Resolved, references AZ-1132 | ✓ |
|
||||||
|
|
||||||
|
**Coverage shape notes (Cycle 15 — AZ-1132 FluentValidation bump):**
|
||||||
|
- Dependency-only patch bump (12.0.0 → 12.1.1) — no new HTTP routes, wire contracts, validation rules, or perf/security harness scenarios. Closes the last open Low production dependency carry-over from the AZ-795 epic footprint (D-AZ795-1).
|
||||||
|
- No new blackbox, perf, or security test scenarios. Existing BT-27..BT-34 + SEC-* rows remain the binding functional evidence; Step 11 full suite is the regression gate for AC-2/AC-3.
|
||||||
|
- The `AZ-795 (epic)` row above still names FluentValidation 12.0.0 as the cycle-7 baseline pin — preserved per cycle-update rule 4. AZ-1132 supersedes the production pin to 12.1.1 without changing observable validation behavior.
|
||||||
|
- Step 14 (Security) and Step 15 (Performance) appropriately **skipped** — no new attack surface or latency-sensitive path (per cycles 11/14 precedent for dependency/doc-only themes).
|
||||||
|
|
||||||
**Coverage shape notes (Cycle 14 — AZ-1131 environment.md integration command):**
|
**Coverage shape notes (Cycle 14 — AZ-1131 environment.md integration command):**
|
||||||
- Documentation-only cycle — closes cycle 12/13 retro carry-over (stale `docker-compose.yml` + `docker-compose.tests.yml` dual-file command in operator docs while `run-tests.sh` uses self-contained `docker-compose.tests.yml`).
|
- Documentation-only cycle — closes cycle 12/13 retro carry-over (stale `docker-compose.yml` + `docker-compose.tests.yml` dual-file command in operator docs while `run-tests.sh` uses self-contained `docker-compose.tests.yml`).
|
||||||
|
|||||||
@@ -266,6 +266,13 @@ Step 9 cycle 12: 1 task created (AZ-1124 = 3 pts) — PT-10 gRPC `DeliverRouteTi
|
|||||||
Step 9 cycle 13: 1 task created (AZ-1126 = 2 pts) — `DateTime` → `DateTimeOffset` on `UavTileMetadata.capturedAt` (F-AZ810-2). Child of AZ-795.
|
Step 9 cycle 13: 1 task created (AZ-1126 = 2 pts) — `DateTime` → `DateTimeOffset` on `UavTileMetadata.capturedAt` (F-AZ810-2). Child of AZ-795.
|
||||||
Step 9 cycle 14: 1 task created (AZ-1131 = 1 pt) — align `environment.md` integration command with `run-tests.sh` (cycle 13 retro carry-over).
|
Step 9 cycle 14: 1 task created (AZ-1131 = 1 pt) — align `environment.md` integration command with `run-tests.sh` (cycle 13 retro carry-over).
|
||||||
Step 9 cycle 15: 1 task created (AZ-1132 = 1 pt) — bump FluentValidation 12.0.0 → 12.1.1 (D-AZ795-1). Child of AZ-795.
|
Step 9 cycle 15: 1 task created (AZ-1132 = 1 pt) — bump FluentValidation 12.0.0 → 12.1.1 (D-AZ795-1). Child of AZ-795.
|
||||||
|
Step 9 cycle 16: 1 task created (AZ-1133 = 1 pt) — perf gate preflight before PT-01 (cycle 14/15 retro carry-over).
|
||||||
|
|
||||||
|
### Step 9 cycle 16 (perf gate preflight — AZ-1133)
|
||||||
|
|
||||||
|
| Task | Epic | SP | Status |
|
||||||
|
|------|------|-----|--------|
|
||||||
|
| AZ-1133 Perf gate preflight — health-check before PT-01 | — | 1 | Todo |
|
||||||
|
|
||||||
### Step 9 cycle 15 (FluentValidation bump — AZ-1132)
|
### Step 9 cycle 15 (FluentValidation bump — AZ-1132)
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,95 @@
|
|||||||
|
# Perf gate preflight — health-check before PT-01
|
||||||
|
|
||||||
|
**Task**: AZ-1133_perf_gate_preflight
|
||||||
|
**Name**: Perf gate preflight — health-check before PT-01
|
||||||
|
**Description**: Add a preflight reachability check to `scripts/run-performance-tests.sh` so Step 15 fails fast with actionable instructions when the perf compose stack is not running.
|
||||||
|
**Complexity**: 1 point
|
||||||
|
**Dependencies**: AZ-492 (perf harness), AZ-1123 (perf compose documentation)
|
||||||
|
**Component**: test tooling — `scripts/run-performance-tests.sh` + deployment/test env docs
|
||||||
|
**Tracker**: AZ-1133
|
||||||
|
**Epic**: None
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
Cycle 13 Step 15 first run failed at PT-01 because `API_URL` (`https://localhost:18980`) was unreachable — the perf overlay (`docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d`) had not been started. The script proceeded through JWT mint/bootstrap and only surfaced the failure as a cryptic PT-01 HTTP error / non-zero exit, wasting operator time. This carry-over appears in cycle 13, 14, and 15 retros.
|
||||||
|
|
||||||
|
## Outcome
|
||||||
|
|
||||||
|
- `run-performance-tests.sh` verifies API reachability after JWT mint and before PT-01
|
||||||
|
- Unreachable API exits with exit code **7** and prints the canonical compose-up command
|
||||||
|
- Reachable API proceeds to PT-01 unchanged
|
||||||
|
- `environment.md` and `containerization.md` document the preflight behavior
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
### Included
|
||||||
|
|
||||||
|
- Add `preflight_api_reachable` (or equivalent) helper in `scripts/run-performance-tests.sh`:
|
||||||
|
- Probe `$API_URL` with the same `CURL_OPTS` / TLS trust as PT-01 (e.g. `curl --connect-timeout 5` to a lightweight endpoint — authenticated `GET /api/satellite/tiles/latlon` with valid coords is acceptable since JWT is already minted)
|
||||||
|
- On connection failure / empty response → print error + `docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build` and `exit 7`
|
||||||
|
- Update `_docs/02_document/tests/environment.md` § Performance tests — mention script preflight + exit 7
|
||||||
|
- Update `_docs/02_document/deployment/containerization.md` § Compose overlays — cross-link preflight
|
||||||
|
|
||||||
|
### Excluded
|
||||||
|
|
||||||
|
- Auto-starting the compose stack from the script (operator still starts it explicitly)
|
||||||
|
- Changing PT-01..PT-10 thresholds or scenario logic
|
||||||
|
- CI integration (perf remains local-only per `ci_cd_pipeline.md`)
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
**AC-1: Preflight runs before PT-01**
|
||||||
|
Given `run-performance-tests.sh` with valid `JWT_SECRET` / iss / aud
|
||||||
|
When the script reaches the performance scenarios section
|
||||||
|
Then a reachability probe executes after JWT mint and before the PT-01 banner.
|
||||||
|
|
||||||
|
**AC-2: Unreachable API fails fast with instructions**
|
||||||
|
Given the perf compose stack is not running (`API_URL` connection refused or timeout)
|
||||||
|
When `run-performance-tests.sh` is executed
|
||||||
|
Then the script exits with code **7**, stderr/stdout includes the perf overlay `docker compose … up` command, and PT-01 does not run.
|
||||||
|
|
||||||
|
**AC-3: Reachable API proceeds unchanged**
|
||||||
|
Given the perf stack is up and `API_URL` accepts authenticated requests
|
||||||
|
When `run-performance-tests.sh` is executed
|
||||||
|
Then preflight passes silently (or with a single "API reachable" line) and PT-01..PT-10 behave as before.
|
||||||
|
|
||||||
|
**AC-4: Documentation reflects preflight**
|
||||||
|
Given the post-task docs
|
||||||
|
When `environment.md` and `containerization.md` are read
|
||||||
|
Then both mention the script preflight and exit code 7 when the stack is down.
|
||||||
|
|
||||||
|
## Non-Functional Requirements
|
||||||
|
|
||||||
|
**Reliability**
|
||||||
|
- Preflight must use the same TLS trust path as the rest of the script (`CURL_OPTS` / `certs/api.crt`).
|
||||||
|
|
||||||
|
**Compatibility**
|
||||||
|
- No change to default env vars (`API_URL`, `PERF_REPEAT_COUNT`, etc.).
|
||||||
|
|
||||||
|
## Unit Tests
|
||||||
|
|
||||||
|
| AC Ref | What to Test | Required Outcome |
|
||||||
|
|--------|-------------|-----------------|
|
||||||
|
| — | Shell-only change; no new C# unit tests required | N/A |
|
||||||
|
|
||||||
|
## Blackbox Tests
|
||||||
|
|
||||||
|
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|
||||||
|
|--------|------------------------|-------------|-------------------|----------------|
|
||||||
|
| AC-2 | Perf stack stopped; JWT env set | `./scripts/run-performance-tests.sh` | Exit 7 + compose instruction; no PT-01 timing output | Reliability |
|
||||||
|
| AC-3 | Perf stack running | `./scripts/run-performance-tests.sh` (smoke: `PERF_REPEAT_COUNT=1` if needed) | Exit 0 or threshold fail only after PT-01 starts | Compatibility |
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
|
||||||
|
- Preserve `set -euo pipefail` globally — preflight must not mask real curl failures in scenario bodies.
|
||||||
|
- Exit code **7** is reserved for "stack not up" to match cycle 13 perf report convention.
|
||||||
|
|
||||||
|
## Risks & Mitigation
|
||||||
|
|
||||||
|
**Risk 1: False negative when API returns 401/403**
|
||||||
|
- *Risk*: Preflight treats auth errors as "reachable" vs connection errors as "down" — must distinguish connection/TLS failure from HTTP 4xx.
|
||||||
|
- *Mitigation*: Use curl exit code / `--connect-timeout`; treat HTTP responses (even 401) as reachable.
|
||||||
|
|
||||||
|
**Risk 2: Preflight adds latency to every perf run**
|
||||||
|
- *Risk*: Extra round-trip before 10 scenarios.
|
||||||
|
- *Mitigation*: Single lightweight GET; acceptable vs minutes-long perf suite.
|
||||||
@@ -0,0 +1,41 @@
|
|||||||
|
# Retrospective — Cycle 15 (2026-06-26)
|
||||||
|
|
||||||
|
**Tasks**: AZ-1132 (FluentValidation bump, 1 SP). **1 task, 1 SP, 1 batch.**
|
||||||
|
**Mode**: cycle-end. Steps 14–16 **skipped** (dependency-only; no new attack surface or perf path).
|
||||||
|
**Previous retro**: `retro_2026-06-26_cycle14.md`
|
||||||
|
|
||||||
|
## Implementation Summary
|
||||||
|
|
||||||
|
| Metric | Cycle 15 | Δ vs cycle 14 |
|
||||||
|
|--------|----------|---------------|
|
||||||
|
| Tasks implemented | **1** | unchanged |
|
||||||
|
| Total complexity delivered | **1 SP** | unchanged |
|
||||||
|
| Blocked tasks | **0** | unchanged |
|
||||||
|
| Auto-fix attempts | **0** | unchanged |
|
||||||
|
|
||||||
|
## Quality
|
||||||
|
|
||||||
|
| Gate | Result |
|
||||||
|
|------|--------|
|
||||||
|
| Code review | PASS (batch_01_cycle15 — dependency-only) |
|
||||||
|
| Step 11 full suite | **PASS** (`run-tests.sh`, 457 unit + integration) |
|
||||||
|
| Step 12 traceability | **PASS** — AZ-1132 AC-1..AC-5 rows added |
|
||||||
|
| Step 13 docs ripple | **PASS** — `ripple_log_cycle15.md`; version pins in module-layout, error-shape, architecture |
|
||||||
|
| Step 14 security | **SKIPPED** (dependency-only; D-AZ795-1 closed in implementation batch artifacts) |
|
||||||
|
| Step 15 perf | **SKIPPED** (dependency-only precedent) |
|
||||||
|
| Step 16 deploy | **SKIPPED** |
|
||||||
|
|
||||||
|
## Cycle 15 delta
|
||||||
|
|
||||||
|
- **D-AZ795-1 closed** — cycle 14 retro Action #1 shipped as sole cycle theme; last open Low prod dependency from AZ-795 footprint resolved.
|
||||||
|
- **Zero behavioral delta** — validator unit (144) + full integration suite green; no contract version bump required.
|
||||||
|
|
||||||
|
## Top 3 Improvement Actions (cycle 16 candidates)
|
||||||
|
|
||||||
|
1. **Perf gate preflight** — script-check or document perf compose stack health before PT-01 (~0.5 SP) — carried from cycle 14
|
||||||
|
2. **PT-09 shell harness promotion** — optional hardening of inventory perf sub-check (~0.5 SP) — carried from cycle 14
|
||||||
|
3. **Ripple version pins on dependency bumps** — extend AZ-1132 doc ripple checklist to `module-layout.md` + `architecture.md` + `error-shape.md` in the implement batch closure template (~0 SP process)
|
||||||
|
|
||||||
|
## Cycle 15 Verdict
|
||||||
|
|
||||||
|
**Successful dependency-hygiene cycle** — FluentValidation production pin at 12.1.1; security posture no longer PASS_WITH_WARNINGS on D-AZ795-1. Full regression green.
|
||||||
@@ -41,6 +41,12 @@ If the enum's wire string happens to match a member name case-insensitively (e.g
|
|||||||
Source: _docs/06_metrics/perf_2026-06-26_cycle12.md
|
Source: _docs/06_metrics/perf_2026-06-26_cycle12.md
|
||||||
- [2026-06-26] [process] Docs-only cycles that close a named retro carry-over (stale command in `environment.md` / `README.md` / `AGENTS.md`) ship cleanly as a 1 SP sole theme with Steps 14–15 skipped and smoke as Step 11 regression evidence — cycle 14 AZ-1131 closed the cycle 12/13 integration-compose doc mismatch in one batch.
|
- [2026-06-26] [process] Docs-only cycles that close a named retro carry-over (stale command in `environment.md` / `README.md` / `AGENTS.md`) ship cleanly as a 1 SP sole theme with Steps 14–15 skipped and smoke as Step 11 regression evidence — cycle 14 AZ-1131 closed the cycle 12/13 integration-compose doc mismatch in one batch.
|
||||||
Source: _docs/06_metrics/retro_2026-06-26_cycle14.md
|
Source: _docs/06_metrics/retro_2026-06-26_cycle14.md
|
||||||
|
- [2026-06-26] [dependencies] Sole-theme dependency bumps (FluentValidation 12.0.0 → 12.1.1) ship cleanly in one 1 SP batch when security scan artifacts are updated in the same commit — D-AZ795-1 closed with full suite regression and Steps 14–15 skipped (cycle 15: AZ-1132).
|
||||||
|
Source: _docs/06_metrics/retro_2026-06-26_cycle15.md
|
||||||
|
- [2026-06-26] [process] Dependency bumps should ripple version pins through `module-layout.md`, `architecture.md`, and `error-shape.md` in Step 13 — leaving 12.0.0 references in those files after AZ-1132 required a doc-sync pass (cycle 15).
|
||||||
|
Source: _docs/06_metrics/retro_2026-06-26_cycle15.md
|
||||||
|
- [2026-06-26] [process] Cycle 14 retro Action #1 (D-AZ795-1) closed end-to-end when phrased as a concrete tracker ticket + ≤2 SP sole theme — same pattern as cycle 13 F-AZ810-2 and cycle 10 F-AZ795-* (cycle 15).
|
||||||
|
Source: _docs/06_metrics/retro_2026-06-26_cycle15.md
|
||||||
## Ring buffer (last 15 entries — newest at top)
|
## Ring buffer (last 15 entries — newest at top)
|
||||||
|
|
||||||
- [2026-06-26] [process] Multi-cycle security carry-overs that name a concrete finding ID and fit ≤2 SP ship cleanly as a sole cycle theme — cycle 12 retro Action #1 → cycle 13 AZ-1126 closed F-AZ810-2 in one batch with full security + perf gate coverage.
|
- [2026-06-26] [process] Multi-cycle security carry-overs that name a concrete finding ID and fit ≤2 SP ship cleanly as a sole cycle theme — cycle 12 retro Action #1 → cycle 13 AZ-1126 closed F-AZ810-2 in one batch with full security + perf gate coverage.
|
||||||
|
|||||||
@@ -2,20 +2,20 @@
|
|||||||
|
|
||||||
## Current Step
|
## Current Step
|
||||||
flow: existing-code
|
flow: existing-code
|
||||||
step: 11
|
step: 10
|
||||||
name: Run Tests
|
name: Implement
|
||||||
status: completed
|
status: in_progress
|
||||||
sub_step:
|
sub_step:
|
||||||
phase: 0
|
phase: 1
|
||||||
name: awaiting-invocation
|
name: prerequisite-check
|
||||||
detail: ""
|
detail: ""
|
||||||
retry_count: 0
|
retry_count: 0
|
||||||
cycle: 15
|
cycle: 16
|
||||||
tracker: jira
|
tracker: jira
|
||||||
auto_push: true
|
auto_push: true
|
||||||
|
|
||||||
## Last Completed Cycle
|
## Last Completed Cycle
|
||||||
cycle: 14
|
cycle: 15
|
||||||
step_10_implement: completed
|
step_10_implement: completed
|
||||||
step_11_run_tests: completed
|
step_11_run_tests: completed
|
||||||
step_12_test_spec_sync: completed
|
step_12_test_spec_sync: completed
|
||||||
|
|||||||
Reference in New Issue
Block a user