From a0449f79d0778f55055108246e786fb05e9004b7 Mon Sep 17 00:00:00 2001 From: Oleksandr Bezdieniezhnykh Date: Fri, 26 Jun 2026 11:08:24 +0300 Subject: [PATCH] [AZ-1123] Cycle 11 closeout: traceability, deploy, retro Co-authored-by: Cursor --- .../02_document/modules/tests_integration.md | 3 +- _docs/02_document/ripple_log_cycle11.md | 10 ++++ .../02_document/tests/traceability-matrix.md | 11 +++- _docs/03_implementation/deploy_cycle11.md | 51 +++++++++++++++++++ _docs/06_metrics/retro_2026-06-25_cycle11.md | 35 +++++++++++++ _docs/LESSONS.md | 4 +- _docs/_autodev_state.md | 17 ++++--- 7 files changed, 119 insertions(+), 12 deletions(-) create mode 100644 _docs/02_document/ripple_log_cycle11.md create mode 100644 _docs/03_implementation/deploy_cycle11.md create mode 100644 _docs/06_metrics/retro_2026-06-25_cycle11.md diff --git a/_docs/02_document/modules/tests_integration.md b/_docs/02_document/modules/tests_integration.md index 0931a46..d3a178a 100644 --- a/_docs/02_document/modules/tests_integration.md +++ b/_docs/02_document/modules/tests_integration.md @@ -52,7 +52,8 @@ Console application that runs end-to-end integration tests against a live API in - ProjectReferences: `SatelliteProvider.Api` (running service for the integration runner), `SatelliteProvider.TestSupport` (canonical `JwtTokenFactory` + `IntegrationTestResetGuard`), `SatelliteProvider.Common` (added by AZ-503 so the `MultiSourceCoexistence_AZ484_Cycle2` seeder can compute `location_hash` via `Uuidv5.Create` instead of duplicating the UUIDv5 algorithm in T-SQL fixtures), `SatelliteProvider.GrpcContracts` (added cycle 9 — generated gRPC client stubs for `RouteTileDeliveryGrpcTests`). ## Consumers -- `docker-compose.tests.yml` — runs as a container that depends on the API service +- `docker-compose.tests.yml` — runs as a container that depends on the API service (self-contained stack; no host postgres port — see `deployment/containerization.md` §Compose overlays) +- Perf tests against a host-published API use `docker-compose.yml` + `docker-compose.perf.yml` — documented in `tests/environment.md` and `deployment/containerization.md` ## Configuration - `API_URL` environment variable (set in docker-compose.tests.yml to `https://api:8080`) diff --git a/_docs/02_document/ripple_log_cycle11.md b/_docs/02_document/ripple_log_cycle11.md new file mode 100644 index 0000000..385db18 --- /dev/null +++ b/_docs/02_document/ripple_log_cycle11.md @@ -0,0 +1,10 @@ +# Ripple Log — Cycle 11 + +Tasks: AZ-1123 (perf compose documentation) + +- `_docs/02_document/deployment/containerization.md` — compose overlays + `docker-compose.perf.yml` playbook (changed by AZ-1123) +- `_docs/02_document/tests/environment.md` — perf orchestration row + cross-link (changed by AZ-1123) +- `_docs/02_document/modules/tests_integration.md` — compose overlay pointer for perf vs integration (Step 13) +- `_docs/02_document/tests/traceability-matrix.md` — AZ-1123 AC-1..AC-3 doc-verified rows (test-spec sync) + +No import-graph ripple — documentation-only task. No blackbox/perf/security spec additions. diff --git a/_docs/02_document/tests/traceability-matrix.md b/_docs/02_document/tests/traceability-matrix.md index ccf3d5f..3442b2f 100644 --- a/_docs/02_document/tests/traceability-matrix.md +++ b/_docs/02_document/tests/traceability-matrix.md @@ -217,7 +217,8 @@ | Cycle 8 — AZ-808 + AZ-809 + AZ-810 + AZ-811 + AZ-812 strict validation sweep + region OSM rename (integration + unit + blackbox + contracts) | 4 integration files (`RegionRequestValidationTests`, `CreateRouteValidationTests`, `UavUploadValidationTests`, `GetTileByLatLonValidationTests` — ≥ 45 failure methods + 4 happy paths) + 5 unit files (`RegionRequestValidatorTests`, `CreateRouteRequestValidatorTests`, `RoutePointValidatorTests`, `GeofencePolygonValidatorTests`, `UavTileMetadataValidatorTests`, `UavTileBatchMetadataPayloadValidatorTests`, `GetTileByLatLonQueryValidatorTests` — ≥ 35 methods across the 4 endpoints) + 4 blackbox (BT-28..BT-31 with ≥ 41 sub-cases) + 4 new contracts (`region-request.md` v1.0.0, `route-creation.md` v1.0.0, `tile-latlon.md` v1.0.0, `uav-tile-upload.md` v1.2.0 bump) + 4 probe scripts | 41/41 in-scope (AZ-808 AC-1..AC-8, AZ-809 AC-1..AC-8, AZ-810 AC-1..AC-9, AZ-811 AC-1..AC-9, AZ-812 AC-1..AC-6); 8 ACs are `◐ doc-verified at Step 13` (per-endpoint OpenAPI / system-flows updates) + 2 advisory non-tested (AZ-809 AC-9, AC-10 — naming consistency surfaced for parent-suite). AZ-810 AC-9 (no AZ-488 regression) verified after the AZ-810 test-data coord-clamp fix (commit `b763da3`) — the original "traced by source" verification was a false-PASS; the green full-suite re-run is the binding evidence. | — | | Cycle 9 — AZ-1074 + AZ-1075 gRPC RouteTileDelivery (integration + unit + blackbox) | 1 integration file (`RouteTileDeliveryGrpcTests`) + orchestrator unit tests + 1 blackbox (BT-32 with 6 sub-cases) + `SatelliteProvider.GrpcContracts` | 7/7 (AZ-1074 AC-1..AC-4, AZ-1075 AC-1..AC-3) | — | | Cycle 10 — AZ-1113 REST 400 error message sanitization (integration + unit + blackbox + contract patch) | 3 integration assertion paths (inventory deserializer, latlon bind, UAV metadata) + 3 unit methods (`GlobalExceptionHandlerTests` ×2, `UavTileUploadHandlerTests` ×1) + 1 blackbox (BT-33 with 3 sub-cases) + 3 security (SEC-14..SEC-16) + `error-shape.md` v1.0.1 patch | 5/5 in-scope (AZ-1113 AC-1..AC-5) | — | -| **Total** | **170** | **121/121 in-scope (100%); 2 AZ-504 ACs gated at Step 15; 10 prior-cycle ACs doc-verified at Step 13 (2 cycle-7 + 8 cycle-8); 2 advisory non-tested (cycle-8 AZ-809 AC-9/AC-10)** | **8/8 (100%)** | +| Cycle 11 — AZ-1123 perf compose documentation (deployment + test env docs) | doc-only (`containerization.md` compose overlays, `environment.md` perf cross-link) | 3/3 in-scope (AZ-1123 AC-1..AC-3); doc-verified at Step 13 | — | +| **Total** | **170** | **124/124 in-scope (100%); 2 AZ-504 ACs gated at Step 15; 10 prior-cycle ACs doc-verified at Step 13 (2 cycle-7 + 8 cycle-8); 2 advisory non-tested (cycle-8 AZ-809 AC-9/AC-10)** | **8/8 (100%)** | **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. @@ -278,6 +279,14 @@ | AZ-1113 AC-3 | `UavUploadValidationFilter` metadata parse → static `errors["metadata"]` | SEC-16, BT-33 sub-case 3 (blackbox); `UavUploadValidationTests.MetadataNotAnObject_Returns400` (integration; asserts no `System.` in body) | ✓ | | AZ-1113 AC-4 | `UavTileUploadHandler` defense-in-depth metadata parse → static envelope error | `UavTileUploadHandlerTests.HandleAsync_InvalidMetadataJson_ReturnsEnvelopeError` (unit) | ✓ | | AZ-1113 AC-5 | `error-shape.md` v1.0.1 Information Disclosure section documents static strings | doc-state AC; verified at Step 13 (Update Docs) | ✓ | +| AZ-1123 AC-1 | `containerization.md` documents 5433 conflict + `docker-compose.perf.yml` command | doc-state AC; verified at Step 13 (`deployment/containerization.md` §Compose overlays) | ✓ | +| AZ-1123 AC-2 | `environment.md` names perf overlay and links to containerization playbook | doc-state AC; verified at Step 13 (`tests/environment.md`) | ✓ | +| AZ-1123 AC-3 | Integration (`docker-compose.tests.yml` only) vs perf overlay distinction documented | doc-state AC; verified at Step 13 (both deployment + test env docs) | ✓ | + +**Coverage shape notes (Cycle 11 — AZ-1123 perf compose documentation):** +- Documentation-only cycle — no new runtime tests, blackbox scenarios, perf thresholds, or security findings. Cycle-update adds traceability rows only; existing Step 11 smoke (450/450) is regression evidence. +- Closes cycle 9/10 retro action to document `docker-compose.perf.yml` (file landed cycle 10; playbook landed cycle 11). +- Step 14 (Security) and Step 15 (Performance) **skipped** — no code or compose behavior change. **Coverage shape notes (Cycle 9 — AZ-1074 + AZ-1075 gRPC RouteTileDelivery):** - Cycle 9 adds the first gRPC blackbox surface alongside the existing REST suite. BT-32 is the binding blackbox spec; integration coverage lives in `RouteTileDeliveryGrpcTests` wired into both smoke and full suites via `Program.cs`. diff --git a/_docs/03_implementation/deploy_cycle11.md b/_docs/03_implementation/deploy_cycle11.md new file mode 100644 index 0000000..3963c3e --- /dev/null +++ b/_docs/03_implementation/deploy_cycle11.md @@ -0,0 +1,51 @@ +# Deploy Report — Cycle 11 (AZ-1123) + +**Date**: 2026-06-25 +**Cycle**: 11 +**Scope**: Document `docker-compose.perf.yml` host-port conflict playbook. + +## What is shipping + +### Code changes + +**None** — documentation only. + +| Doc | Change | +|-----|--------| +| `deployment/containerization.md` | Compose overlays table + perf overlay command | +| `tests/environment.md` | Perf orchestration row + cross-link | +| `modules/tests_integration.md` | Pointer to overlay playbook | + +### Database migrations + +**None.** + +### Configuration changes + +**None.** + +## Verification gates + +| Gate | Result | Evidence | +|------|--------|----------| +| Step 11 — Functional tests | **PASS** | 450/450 smoke EXIT:0 | +| Step 12 — Test-Spec Sync | **PASS** | Traceability AZ-1123 AC-1..AC-3 (doc-verified) | +| Step 13 — Update Docs | **PASS** | `ripple_log_cycle11.md`, module doc pointer | +| Step 14 — Security Audit | **Skipped** | No code surface change | +| Step 15 — Performance Test | **Skipped** | No runtime change | + +## Operator runbook + +No deploy action required beyond pulling latest `dev` docs. Operators running Step 15 locally should use: + +```bash +docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build +``` + +when host port 5433 is occupied. + +## Release note + +Step 16.5 (Release) **skipped** — no release harness (cycles 1–10 pattern). + +**Verdict**: Cleared for retrospective (Step 17). diff --git a/_docs/06_metrics/retro_2026-06-25_cycle11.md b/_docs/06_metrics/retro_2026-06-25_cycle11.md new file mode 100644 index 0000000..0318748 --- /dev/null +++ b/_docs/06_metrics/retro_2026-06-25_cycle11.md @@ -0,0 +1,35 @@ +# Retrospective — Cycle 11 (2026-06-25) + +**Tasks**: AZ-1123 (perf compose docs, 1 SP). **1 task, 1 SP, 1 batch.** +**Mode**: cycle-end. Step 16.5 (Release) **skipped**. +**Previous retro**: `retro_2026-06-25_cycle10.md` + +## Implementation Summary + +| Metric | Cycle 11 | Δ vs cycle 10 | +|--------|----------|---------------| +| Tasks implemented | **1** | unchanged | +| Total complexity delivered | **1 SP** | -1 SP | +| Blocked tasks | **0** | unchanged | + +## Quality + +| Gate | Result | +|------|--------| +| Code review | PASS (docs only) | +| Step 11 smoke | **PASS** 450/450 | +| Security / Perf | Skipped (appropriate for doc-only) | + +## Trend + +Cycle 10 retro Action #1 **completed** — `docker-compose.perf.yml` documented end-to-end. + +## Top 3 Improvement Actions (cycle 12 candidates) + +1. **F-AZ810-2** `DateTime` → `DateTimeOffset` on `capturedAt` (~1 SP) +2. **PT-10 gRPC stream perf scenario** (~3 SP) +3. **Align `environment.md` integration command** with `run-tests.sh` (uses `docker-compose.tests.yml` only) (~0.5 SP) + +## Cycle 11 Verdict + +**Successful doc cycle** — closes a two-cycle carry-over from host-port 5433 conflicts. Minimal blast radius; gates appropriately skipped. diff --git a/_docs/LESSONS.md b/_docs/LESSONS.md index a4948a1..cade7d6 100644 --- a/_docs/LESSONS.md +++ b/_docs/LESSONS.md @@ -35,6 +35,8 @@ If the enum's wire string happens to match a member name case-insensitively (e.g --- +- [2026-06-25] [process] Documentation-only autodev cycles should still run Step 12 traceability rows (doc-verified ACs) and Step 13 ripple logs, while Steps 14–15 are appropriately skipped when no code surface changes — avoids empty cycle artifacts without running meaningless security/perf gates (cycle 11: AZ-1123). + Source: _docs/06_metrics/retro_2026-06-25_cycle11.md ## Ring buffer (last 15 entries — newest at top) - [2026-06-25] [testing] PT-07 cold-vs-warm region latency is sensitive to outlier cold p95 on a warm compose volume — the perf gate should drain the region queue before the warm pass and accept warm p50 < cold p50 when p95 is within noise (cycle 10: two marginal PT-07 FAILs before harness fix; AZ-1113 did not touch region paths). @@ -65,5 +67,3 @@ If the enum's wire string happens to match a member name case-insensitively (e.g Source: _docs/06_metrics/retro_2026-05-22_cycle7.md - [2026-05-12] [tooling] Kestrel `HttpProtocols.Http1AndHttp2` silently serves only HTTP/1.1 over a plaintext listener — ALPN requires TLS, so any "enable HTTP/2" task without TLS in its definition-of-done will downgrade transparently and the only log line is at INFO; tasks that mention HTTP/2 / h2 / multiplexing / ALPN MUST resolve the TLS-vs-h2c choice at spec-write time and the test gate MUST assert `HttpVersion == 2.0` not just a 200 (cycle 6: AZ-505 AC-5 first landed on h2c plaintext, required a post-merge TLS+ALPN pivot with dev-cert plumbing across compose/tests/perf/docs). Source: _docs/06_metrics/retro_2026-05-12_cycle6.md -- [2026-05-12] [testing] When a test bypasses Dapper to gain access to a feature Dapper doesn't expose (e.g. `ANY($1::uuid[])` array params, raw `NpgsqlCommand` for performance fixtures), the test owns the Npgsql type-conversion contract that Dapper used to handle silently — `DateTime.Kind=Utc` must be converted to `Unspecified` before binding into a `timestamp without time zone` column (cycle 6: AZ-505 introduced two Dapper-bypassing paths and all three new test files hit the same `Cannot write DateTime with Kind=UTC` error until `DateTime.SpecifyKind(..., Unspecified)` was added at the bind sites). - Source: _docs/06_metrics/retro_2026-05-12_cycle6.md diff --git a/_docs/_autodev_state.md b/_docs/_autodev_state.md index 74629f1..c52f69b 100644 --- a/_docs/_autodev_state.md +++ b/_docs/_autodev_state.md @@ -2,20 +2,21 @@ ## Current Step flow: existing-code -step: 11 -name: Run Tests -status: in_progress +step: 9 +name: New Task +status: not_started sub_step: - phase: 1 - name: test-run - detail: "doc-only cycle 11 — sanity gate" + phase: 0 + name: awaiting-invocation + detail: "" retry_count: 0 -cycle: 11 +cycle: 12 tracker: jira auto_push: true ## Last Completed Cycle -cycle: 10 +cycle: 11 step_16_deploy: completed step_16_5_release: skipped (no release harness) step_17_retrospective: completed +verdict: cycle_complete_operator_deploy