From eef3bdf7db4e5fe5d4e8a99a1f40d759493c293b Mon Sep 17 00:00:00 2001 From: Oleksandr Bezdieniezhnykh Date: Wed, 13 May 2026 04:15:37 +0300 Subject: [PATCH] [AZ-509][AZ-510][AZ-511] Cycle 3 closure: deploy + retro + state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Steps 16 (Deploy) and 17 (Retrospective) outputs for cycle 3. - 03_implementation/deploy_cycle3_report.md — ui/ dev pushed (15838c5..09449bd, 5 commits); stage/prod cutover deferred per push-scope gate option A. - 06_metrics/retro_2026-05-13_cycle3.md — cycle 3 retro: 6/9 pts shipped (AZ-510, AZ-511); AZ-512 deferred to backlog at cross-workspace prereq gate (AZ-513 filed on admin/). - 06_metrics/structure_2026-05-13.md — structural snapshot referenced by retro. - LESSONS.md — appended 3 cycle-3 lessons (process x2, architecture x1). - _autodev_state.md — cycle 3 closed; cycle 4 Step 9 not started. Co-authored-by: Cursor --- .../03_implementation/deploy_cycle3_report.md | 68 ++++++ _docs/06_metrics/retro_2026-05-13_cycle3.md | 202 ++++++++++++++++++ _docs/06_metrics/structure_2026-05-13.md | 91 ++++++++ _docs/LESSONS.md | 30 +++ _docs/_autodev_state.md | 12 +- 5 files changed, 398 insertions(+), 5 deletions(-) create mode 100644 _docs/03_implementation/deploy_cycle3_report.md create mode 100644 _docs/06_metrics/retro_2026-05-13_cycle3.md create mode 100644 _docs/06_metrics/structure_2026-05-13.md diff --git a/_docs/03_implementation/deploy_cycle3_report.md b/_docs/03_implementation/deploy_cycle3_report.md new file mode 100644 index 0000000..5e60f97 --- /dev/null +++ b/_docs/03_implementation/deploy_cycle3_report.md @@ -0,0 +1,68 @@ +# Cycle 3 Step 16 — Deploy Report + +**Date**: 2026-05-13 +**Cycle**: 3 (autodev existing-code Step 16) +**Mode chosen**: real cutover (option A in the cycle-3 deploy gate) +**Push scope chosen**: ui/ dev only (option A in the push-scope sub-gate; B/C/D not selected) +**Outcome**: ui/ dev pushed; stage/prod cutover deferred to a later turn; admin/ dev NOT pushed. + +## What was actually deployed + +| Repo | Branch | Commits pushed | Pipeline triggered | +|------|--------|----------------|--------------------| +| `ui/` | `dev` (`15838c5..09449bd`) | 5 | Woodpecker dev build for `ui/` | +| `admin/` | — | 0 (locally ahead by 1) | none | + +### Commits pushed to `ui/` `origin/dev` + +``` +09449bd [AZ-510][AZ-511][AZ-512][AZ-513] Cycle 3 Steps 12-15 + admin prereq +6c7e297 [AZ-512] Defer to backlog at cross-workspace BLOCKING gate +c368f60 [AZ-511] classColors carve-out to src/class-colors/ (closes F3) +70fb452 [AZ-510] Auth bootstrap: POST refresh + chained /users/me +098a556 [AZ-509][AZ-510][AZ-511][AZ-512] Cycle 3 new-task: epic + 3 task specs +``` + +## What was NOT done (deferred / pending) + +| ID | Item | Reason | Owner | +|----|------|--------|-------| +| D-CY3-STAGE | `ui/` `dev → stage → push origin/stage` | User chose option A (dev-only) at the push-scope gate. Stage cutover deferred to a later autodev / manual run. | User | +| D-CY3-MAIN | `ui/` `stage → main → push origin/main` (prod cutover) | Same reason as above. Devices will not auto-pull cycle-3 changes until this completes. | User | +| D-CY3-ADMIN-PUSH | `admin/` `dev push origin/dev` | User did not select option D at the push-scope gate. The AZ-513 task spec sits locally on `admin/` `dev`. Docs-only commit — no admin/ build trigger expected even when pushed. | User | +| D-CY3-AZ513-IMPL | Implementation of AZ-513 (admin/ POST + PATCH + DELETE /classes routes) | New cross-workspace dependency: admin/ workspace must implement before AZ-512 can ship. Filed in Jira (AZ-513, parent epic AZ-509, Blocks AZ-512). | admin/ team | + +## Carry-forward from cycle 2 + +The cycle-2 `deploy_planning_sync_cycle2.md` deferred 3 items to leftovers in `_docs/_process_leftovers/2026-05-12_az-498-deploy-and-key-revocations.md`. Cycle 3 did NOT close any of them: + +| ID (cycle 2) | Item | Status as of 2026-05-13 | +|----|------|-------| +| L-AZ-498-DEPLOY | UI tile-swap prod cutover | Still deferred — cross-workspace satellite-provider gate unchanged; UI prod cutover would now ship cycle-3 + cycle-2 simultaneously. | +| L-AZ-499-OWM-REVOKE | OWM key revocation at owm dashboard | Still pending — manual third-party action; owner: user. | +| L-AZ-501-GOOGLE-REVOKE | Google Geocode key revocation at Google Cloud Console | Still pending — manual third-party action; owner: user. | + +These leftovers need a status sweep at the start of the next `/autodev` invocation per `tracker.mdc` Leftovers Mechanism. + +## Cycle-3 deployment-doc deltas (NOT written this cycle) + +In strict autodev terms, Step 16 in this cycle was a real cutover (option A), not a planning sync. The cycle-2 pattern of patching `_docs/02_document/deployment/*` was therefore skipped here because: + +- AZ-510 and AZ-511 introduced **no** changes to Dockerfile, `.woodpecker/`, env vars, or nginx (verified via `git diff --stat 70fb452^..HEAD -- nginx.conf Dockerfile .woodpecker/ e2e/ .env.example mission-planner/.env.example` — empty). +- AZ-510 wire-shape change is internal to the auth path; the production admin/ service already serves POST `/api/admin/auth/refresh` (used by the existing 401-retry path in `src/api/client.ts:88-99`) and `GET /api/admin/users/me`, so deployment-side configuration is already correct. +- AZ-512 (deferred) introduced no source changes. + +If a future cycle adds env vars, infra changes, or new services, the cycle-2 planning-sync pattern (update `environment_strategy.md`, `ci_cd_pipeline.md`, `containerization.md`, `observability.md`) should be applied. + +## Verification + +- `git push origin dev` for `ui/` returned `15838c5..09449bd dev -> dev` (5 commits, fast-forward). +- `git status -sb` for `ui/` confirms `dev` and `origin/dev` are synced post-push (no `[ahead N]`). +- Functional test suite green pre-push (231 passed, 13 quarantined skips — see `test-output/summary.csv` and `test-output/fast-report.xml`). +- Static perf NFT-PERF-01 green pre-push (290 575 B gzipped vs ≤ 2 097 152 B threshold — see `test-output/performance-summary.txt`). +- Security cycle-3 delta verdict PASS_WITH_WARNINGS pre-push (see `_docs/05_security/security_report_cycle3_delta.md`). +- No nginx/Docker/CI config changes in cycle 3 (verified via `git diff --stat 70fb452^..HEAD -- nginx.conf Dockerfile .woodpecker/ e2e/ .env.example mission-planner/.env.example` empty). + +## Auto-chain + +→ Step 17 (Retrospective) for cycle 3. diff --git a/_docs/06_metrics/retro_2026-05-13_cycle3.md b/_docs/06_metrics/retro_2026-05-13_cycle3.md new file mode 100644 index 0000000..edfaf93 --- /dev/null +++ b/_docs/06_metrics/retro_2026-05-13_cycle3.md @@ -0,0 +1,202 @@ +# Retrospective — 2026-05-13 (Phase B Cycle 3) + +**Mode**: cycle-end (autodev existing-code Step 17) +**Scope**: Phase B, cycle 3 (`state.cycle = 3`) +**Epic**: AZ-509 (UI workspace cycle 3 — Auth bootstrap fix + classColors carve-out + admin edit) +**Cycle duration**: 3 batches over 1 working day (2026-05-13) +**Previous retro**: `_docs/06_metrics/retro_2026-05-12_cycle2.md` (cycle 2) + +## Implementation Summary + +| Metric | Value | Δ vs cycle 2 | +|--------|-------|--------------| +| Tasks attempted | 3 (AZ-510, AZ-511, AZ-512) | +1 | +| Tasks delivered | 2 (AZ-510, AZ-511) | 0 | +| Tasks deferred at spec gate | 1 (AZ-512 — cross-workspace prereq) | +1 (new pattern) | +| Total batches | 3 (batch 13, 14, 15) | +1 | +| Total complexity points planned | 9 (3+3+3) | −2 | +| Total complexity points delivered | 6 (3+3) | −5 (cycle 2 shipped 11) | +| Avg tasks per batch | 1 | −1 | +| Avg complexity per (completed) batch | 3 | −2.5 | +| Source files mutated | ~37 production + test (AZ-510 ~25, AZ-511 ~12, AZ-512 0) + 9 docs | n/a (different shape) | + +Sources: `batch_13_cycle3_report.md`, `batch_14_cycle3_report.md`, `batch_15_cycle3_report.md`, `implementation_report_auth_classcolors_cycle3.md`, `implementation_completeness_cycle3_report.md`, `deploy_cycle3_report.md`, `security_report_cycle3_delta.md`. + +## Quality Metrics + +### Code Review Results + +| Verdict | Count | Percentage | Δ vs cycle 2 | +|---------|-------|-----------|--------------| +| PASS | 2 (batches 13, 14) | 67 % | +2 | +| PASS_WITH_WARNINGS | 0 | 0 % | −1 | +| FAIL | 0 | 0 % | 0 | +| (no formal review — deferred at gate) | 1 (batch 15) | 33 % | n/a | + +Note: batch 15 (AZ-512) hit a spec-defined Cross-Workspace Verification BLOCKING gate before implementation began. No source code was written, no review fired. The "no review" row is **not** a process gap — it is the spec working correctly. + +### Findings by Severity (code review only) + +| Severity | Count | Δ vs cycle 2 | +|----------|-------|--------------| +| Critical | 0 | 0 | +| High | 0 | 0 | +| Medium | 0 | 0 | +| Low | 0 | **−1** ✓ (cycle 2's pre-existing trim-trailing-slash F1 was not re-flagged because cycle 3 did not touch the affected files) | + +### Findings by Category (code review) + +| Category | Count | Top Files | +|----------|-------|-----------| +| Bug | 0 | — | +| Spec-Gap | 0 | — | +| Security | 0 (in code review; security audit fires separately — see below) | — | +| Performance | 0 | — | +| Maintainability | 0 | — | +| Style | 0 | — | +| Scope | 0 | — | + +### Security-Audit Findings (Step 14 — cycle 3 delta against cycle 2 baseline) + +12 carried + 1 new = 13 total. Cycle 3 net delta: + +| Status change | Count | Notable IDs | +|---------------|-------|-------------| +| Closed (HIGH → resolved) | 2 | F-DEP-1 (Vite/PostCSS CVEs — closed by cycle-2-tail `bun update`), OWASP A07 cold-load gap (closed by AZ-510) | +| Strengthened (defense-in-depth) | 1 | STC-ARCH-01 exemption removed (closed by AZ-511) | +| Newly introduced (LOW) | 1 | F-SAST-CY3-1 — `__resetBootstrapInflightForTests` exposed via `src/auth` barrel (AZ-510) | +| Carried forward unchanged (HIGH) | 1 | F-SAST-1 (Google key in `mission-planner/` git history; production exposure NONE — see cycle 2 leftover L-AZ-501-GOOGLE-REVOKE) | +| Carried forward unchanged (MEDIUM) | 7 | F-SAST-2/3, F-INF-1..4 (infra hardening backlog) | + +**Security verdict trajectory**: cycle 2 verdict FAIL → cycle 3 verdict **PASS_WITH_WARNINGS** (driver: all HIGH findings closed; one LOW hygiene item introduced; one HIGH carried at git-history layer with NONE production exposure). + +OWASP A06 (Vulnerable & Outdated Components): FAIL → **PASS**. +OWASP A07 (Identification & Authentication Failures): PASS_WITH_KNOWN → **PASS**. + +## Structural Metrics + +Source: `_docs/06_metrics/structure_2026-05-13.md` (this cycle), compared against `structure_2026-05-12.md` (cycle 1 close — cycle 2 introduced no structural changes). + +| Metric | Cycle 1 close | Cycle 2 close | Cycle 3 close | Δ vs cycle 2 | +|--------|--------------|--------------|--------------|--------------| +| Component count | 12 | 12 | 12 | 0 | +| Public-API barrels | 11 / 11 (100 %) | 11 / 11 (100 %) | 11 / 11 (100 %) | 0 | +| STC-ARCH-01 carve-out exemptions | 1 (`classColors`) | 1 | **0** | **−1** ✓ | +| Commit-time static gates | 31 / 31 PASS | 33 / 33 PASS | 33 / 33 PASS | 0 (STC-ARCH-01 *strengthened*, no new gates added) | +| Architecture cycles | 0 | 0 | 0 | 0 | +| Architecture findings open (baseline F1–F9) | 7 of 9 | 7 of 9 | **6 of 9** | **−1** ✓ (F3 closed) | +| Newly introduced architecture violations | 0 | 0 | 0 | 0 | +| Net architecture delta this cycle | −2 | 0 | **−1** | continued improvement | +| Wire-contract assertions (`endpoints.test.ts`) | 36 | 36 | **37** | +1 (`endpoints.admin.usersMe`) | +| Fast-profile suite | 209 PASS / 13 SKIP / 0 FAIL | 229 PASS / 13 SKIP / 0 FAIL | **231 PASS / 13 SKIP / 0 FAIL** | +2 PASS | +| Bundle (gzipped initial JS) | not measured | 290 465 B | 290 575 B | +110 B (+0.04 %; ~14 % budget) | + +### Auto-lesson triggers (per skill Step 1) + +- Net Architecture delta > 0? **No** — delta is −1 (improvement). No `architecture` regression lesson required. +- Structural metric regression > 20 %? **No** — every structural metric held or improved. +- Contract coverage % decreased? **No** — wire-contract assertions +1 (37 vs 36). +- New finding category emerged? **No** — security audit ran in delta mode against the cycle 2 baseline; categories are stable. + +## Efficiency + +| Metric | Value | Δ vs cycle 2 | +|--------|-------|--------------| +| Blocked tasks (cycle-internal) | 0 | 0 | +| Tasks deferred to backlog at spec gate | 1 (AZ-512) | +1 (new pattern) | +| Cross-workspace prerequisite tickets filed | 1 (AZ-513 on `admin/`) | +1 (new pattern) | +| Pre-existing bugs surfaced as side observations | 1 (`AdminPage.tsx` add+delete buttons broken end-to-end against live admin/) | +1 | +| Tasks pending external user action (cycle-3 close) | **7** | +4 vs cycle 2's 3 | +| Tasks requiring fixes after review | 0 | 0 | +| Batch with most findings | none — 0 findings cycle-wide | n/a | +| Auto-fix loops invoked | 0 | 0 | +| Stuck-agent incidents | 0 | 0 | +| Unplanned implementation-time test stabilization loops | 4 in batch 13 (AZ-510 module-scoped state ripple) | +4 (new pattern) | + +### Blocker Analysis + +| Blocker Type | Count | Prevention | +|--------------|-------|-----------| +| Spec-defined cross-workspace BLOCKING gate (AZ-512) | 1 | Working as intended; the spec design (Cross-Workspace Verification gate) is the prevention. Codify as a reusable task spec template — see Improvement Action #1. | +| Cycle-2 manual third-party action (key revocation) | 2 (carry; not actioned this cycle) | Action #1 from cycle 2 retro still valid; user-action backlog grew rather than drained. See Improvement Action #3. | +| Cycle-2 cross-workspace deploy gate (satellite-provider) | 1 (carry; not actioned this cycle) | Same as above. | +| Cycle-3 deploy push deferred (stage / main / admin/ dev) | 3 (new) | User chose option A (real cutover) but option A in push-scope (ui/ dev only); intentional, but adds to the backlog. | + +### User-action backlog at cycle close (NEW METRIC — see Improvement Action #3) + +| Category | Count | Items | +|----------|-------|-------| +| Manual third-party console action | 2 | L-AZ-499-OWM-REVOKE, L-AZ-501-GOOGLE-REVOKE (carry from cycle 2) | +| Cross-workspace deploy gate | 1 | L-AZ-498-DEPLOY (carry from cycle 2) | +| Cross-workspace prerequisite ticket awaiting sibling-team work | 1 | AZ-513 implementation on `admin/` (new this cycle; blocks AZ-512 in `_docs/02_tasks/backlog/`) | +| Cycle-3 deploy push pending | 3 | D-CY3-STAGE, D-CY3-MAIN, D-CY3-ADMIN-PUSH (new this cycle) | +| **Total** | **7** | (cycle 1 close: 0 → cycle 2 close: 3 → cycle 3 close: 7) | + +This metric is monotonically growing across cycles. The growth is **not** a process regression — every item is a deliberate conservative-path choice (file prereq ticket vs. invent workaround; defer prod cutover vs. push without satellite-provider gate; etc.) — but the trajectory means the cost of those choices accumulates without an offsetting drain mechanism. + +### User-decision points (cycle 3 only) + +- AZ-512 BLOCKING gate (Cross-Workspace Verification): user **skipped** the prompt → autodev defaulted to **Option A** (file prereq ticket on admin/, pause AZ-512). Spec-aligned, conservative, reversible. +- Cycle-3 deploy gate (real cutover vs plan-only): user chose **A** (real cutover) — first time across cycles 1-3 the user chose anything other than plan-only. +- Cycle-3 push-scope sub-gate: user chose **A** (ui/ dev only). Stage/main and admin/ dev push deferred. +- Step 14 verdict (PASS_WITH_WARNINGS): no remediation gate fired (only LOW finding); auto-chained. +- Step 15 (Performance Test): no separate report produced; static perf check confirmed green at deploy time (290 575 B / 14 % of budget). + +## Trend Comparison + +| Trend | Cycle 1 | Cycle 2 | Cycle 3 | Direction | +|-------|---------|---------|---------|-----------| +| Code review pass rate (formally-reviewed batches) | 100 % | 50 % (1 PASS_WITH_WARNINGS, 1 no-review sub-step) | **100 %** (2/2 reviewed batches PASS) | ⬆ recovered to cycle-1 baseline | +| Test count (cumulative this cycle delta) | +46 | +20 | +2 | declining; cycle 3 was deeper-fix-narrower-surface | +| Static gate count | +2 | +2 | 0 (STC-ARCH-01 strengthened, no new gates) | held | +| Architecture findings open (baseline) | 7 (−2) | 7 (0) | **6 (−1)** | ⬆ resumed monotonic decrease | +| STC-ARCH-01 exemptions | 1 | 1 | **0** | first cycle to reach zero | +| Wire-contract assertions | 36 | 36 | **37** (+1) | first growth since cycle 1 | +| Pending USER actions at cycle close | 0 | 3 | **7** | ⬆ ⬆ — accumulating | +| Tasks deferred to backlog at spec gate | 0 | 0 | **1** (AZ-512) | new pattern (working as designed) | + +The cycle 3 user-action backlog growth is a **structural side-effect of running spec-defined BLOCKING gates correctly**, not a process regression. AZ-512's gate caught a cross-workspace dependency that would otherwise have shipped a UI form against a 404 endpoint. The cost is one new entry in the backlog; the alternative was a production-broken affordance. + +## Top 3 Improvement Actions + +1. **Codify "Cross-Workspace Verification BLOCKING gate" as a reusable task spec template**. + AZ-512's spec is the canonical example: pre-implementation gate that requires the implementer to verify a sibling-workspace endpoint exists, with a spec invariant ("Do not invent a workaround that bypasses the missing endpoint") and a fallback-A priority (file prereq ticket on the sibling workspace). Without that gate, batch 15 would have shipped a UI affordance against a 404 endpoint. Future tasks that touch UI ↔ admin / UI ↔ satellite-provider / UI ↔ annotations-service boundaries should always include this gate. + - Impact: high — directly addresses the recurring cross-workspace coordination cost; prevents a class of "ships visibly broken in production" bugs that the AZ-512 / `AdminPage.tsx` add+delete side observation showed already exists in pre-AZ-512 code. + - Effort: low — add `_docs/02_tasks/_templates/cross_workspace_dependency.md` with the gate scaffold (verify-step + spec invariant + 3-option fallback ladder) and reference from `.cursor/skills/new-task/SKILL.md` "Task Type Detection" section. + +2. **Standardize a "module-scoped state introduction" task template / batch checklist**. + AZ-510's `bootstrapInflight` module-scoped promise was the right architectural choice for StrictMode-safe bootstrap dedupe but cost ~4 separate fix loops in test setup during implementation: (a) `ProtectedRoute.test.tsx` hangs from leaked never-resolving promise → fix via test-only reset hook; (b) STC-ARCH-01 violation when `tests/setup.ts` deep-imported the helper → fix via barrel re-export; (c) widespread test crashes from default MSW `/users/me` handler missing `permissions` field → fix via defensive `hasPermission` + handler seeding; (d) bulk handler swap in 15 test files (`http.get('/api/admin/auth/refresh')` → `http.post`) needed because POST production behavior bypassed the existing GET overrides. Each was straightforward in isolation but compounded the batch's wall-clock cost. A pre-implementation checklist would have caught (a)+(b) before code was written. + - Impact: medium — directly reduces ripple-cost of architecturally-correct module-scoped state introductions; the pattern recurs anywhere React 18 StrictMode dedupe is needed. + - Effort: low — add `_docs/02_tasks/_templates/module_scoped_state_introduction.md` (NEW) with the 4-item checklist (reset-hook plan, afterEach audit, default-fixture invariant check, mock ripple plan); cite AZ-510 as canonical example. + +3. **Track "user-action backlog at cycle close" as a first-class retrospective metric**. + Backlog grew 0 → 3 → 7 across cycles 1-3. Each item is a deliberate conservative-path choice (file prereq ticket; defer prod cutover; defer key revocation), but the monotonic accumulation is a process-shape signal. Without a per-cycle measurement and a draining mechanism, the backlog will keep growing and the "cost of conservative defaults" stays invisible. The drain mechanism could be a "Step 0 leftover sweep" in each cycle's first invocation (already partially defined in `tracker.mdc` Leftovers Mechanism), but today the autodev does not measure whether the sweep actually moved the backlog count down. + - Impact: medium — surfaces accumulating debt that today is only visible by reading the leftovers folder. Makes user-action items first-class deliverables of the process, not silent drag. + - Effort: low — extend `.cursor/skills/retrospective/SKILL.md` Step 1 metric collection with a "user-action backlog" subsection (categories: manual third-party / cross-workspace prereq / cross-workspace deploy / push pending), and add to the retrospective-report template. + +## Suggested Rule / Skill Updates + +| File | Change | Rationale | +|------|--------|-----------| +| `_docs/02_tasks/_templates/cross_workspace_dependency.md` | NEW file. Pre-implementation BLOCKING gate (verify the prerequisite exists in `` source); spec invariant ("Do not invent a workaround that bypasses the missing endpoint"); fallback-A priority (file prereq ticket on sibling, pause until lands); options B/C/D for the user; AZ-512 ↔ AZ-513 as canonical example. | §Top 3 Improvement Action #1. | +| `.cursor/skills/new-task/SKILL.md` (Task Type Detection) | Add "cross-workspace-dependent" trigger phrase set ("touches `admin/`", "depends on `satellite-provider`", "needs new endpoint in ``", "calls `/api/admin/`") that suggests the new template. | §Top 3 Improvement Action #1 enablement. | +| `_docs/02_tasks/_templates/module_scoped_state_introduction.md` | NEW file. 4-item pre-implementation checklist: (a) plan test-only reset hook in same batch; (b) audit `afterEach` hooks in `tests/setup.ts`; (c) check default test fixtures still satisfy invariants if helpers consume them; (d) plan ripple swaps in handler mocks (HTTP method / wire shape changes). Cite AZ-510 as canonical example. | §Top 3 Improvement Action #2. | +| `.cursor/skills/retrospective/SKILL.md` (Step 1 metrics) | Add **"User-action backlog at cycle close"** metric: count of unresolved leftover items, broken down by category (manual third-party / cross-workspace prereq / cross-workspace deploy / push pending). Also add cross-workspace prerequisite tickets count and pre-existing bugs surfaced as side observations. | §Top 3 Improvement Action #3. | +| `.cursor/skills/retrospective/templates/retrospective-report.md` | Add a "User-action backlog at cycle close" subsection under Efficiency with the same category breakdown; include trend across previous cycles. | §Top 3 Improvement Action #3. | +| `_docs/LESSONS.md` (top) | Append the 3 lessons in §LESSONS Append below; trim to ≤ 15 entries. | Skill Step 4. | + +## Notes — Step 16 outcome + +Step 16 (Deploy) ran in **real-cutover mode (option A)** for the first time across cycles 1-3. Push scope was ui/ `dev` only (5 commits, fast-forward `15838c5..09449bd`). Stage / main / admin/ `dev` pushes were deferred at the push-scope sub-gate (user chose option A — ui/ dev only). + +- Devices will not auto-pull cycle-3 changes until `dev → stage → main` completes (D-CY3-STAGE, D-CY3-MAIN). +- AZ-513 task spec sits locally on `admin/` `dev` — admin/ team cannot pick it up until D-CY3-ADMIN-PUSH lands. +- No Dockerfile / `.woodpecker/` / nginx / env changes in cycle 3, so no deployment-doc rewrites this cycle (verified via `git diff --stat 70fb452^..HEAD` on those paths — empty). + +These four items add to the user-action backlog; see §Efficiency → User-action backlog table. + +## LESSONS Append (top 3, single-sentence, tagged) + +1. **[process]** When a task spec defines a Cross-Workspace Verification BLOCKING gate and the user skips the choice prompt, the autodev MUST default to the most conservative spec-aligned option (Option A: file prerequisite ticket on the sibling workspace, park the task in `backlog/`) — never invent a workaround that bypasses the missing dependency, never silently ship a UI affordance against a non-existent endpoint, and always preserve the user's ability to override at the next invocation, exactly as AZ-512 → AZ-513 demonstrated. +2. **[architecture]** Introducing a module-scoped state guard in production source (e.g., a top-level `let bootstrapInflight: Promise | null = null` for React 18 StrictMode dedupe) requires the same batch to ship 4 coupled changes — (a) a test-only reset hook re-exported via the public barrel (STC-ARCH-01 compliance), (b) an `afterEach` reset in `tests/setup.ts`, (c) a defensive default-fixture invariant check (e.g., MSW handler must seed required nullable fields the helper consumes), (d) a planned ripple swap in handler mocks for any HTTP method or wire-shape change — skipping any one costs a separate test-stabilization loop, as AZ-510's ~4-attempt arc demonstrated. +3. **[process]** Track "user-action backlog at cycle close" as a first-class retrospective metric (count of leftover items broken down by manual-third-party / cross-workspace-prerequisite / cross-workspace-deploy / push-pending categories) — backlog grew monotonically 0 → 3 → 7 across cycles 1-3 and that accumulation is a process-shape signal, not noise; surfacing it makes the cost of conservative-path defaults visible per cycle and creates pressure for an explicit drain mechanism (Step 0 sweep that actually closes items, not just notices them). diff --git a/_docs/06_metrics/structure_2026-05-13.md b/_docs/06_metrics/structure_2026-05-13.md new file mode 100644 index 0000000..be0381b --- /dev/null +++ b/_docs/06_metrics/structure_2026-05-13.md @@ -0,0 +1,91 @@ +# Structural Snapshot — 2026-05-13 (Phase B Cycle 3 close) + +**Cycle**: Phase B, cycle 3 (`state.cycle = 3`) +**Source-of-truth files**: `_docs/02_document/module-layout.md`, `_docs/02_document/architecture_compliance_baseline.md`, `scripts/check-arch-imports.mjs`, `scripts/run-tests.sh`, `src/api/endpoints.test.ts`. +**Previous snapshot**: `_docs/06_metrics/structure_2026-05-12.md` (Phase B cycle 1 close). + +## Component Inventory + +| Metric | Cycle 1 close | Cycle 3 close | Δ | +|--------|--------------|--------------|---| +| Component count | 12 | 12 | 0 | +| Components with Public API barrels | 11 | 11 | 0 | +| Barrel coverage (eligible components) | 11 / 11 = 100 % | 11 / 11 = 100 % | 0 | +| Documented feature→feature edges (grandfathered) | 1 (`07_dataset → 06_annotations`) | 1 (unchanged) | 0 | +| Documented STC-ARCH-01 carve-out exemptions | 1 (`classColors` direct path) | **0** | **−1** ✓ | +| Cycles in component import graph | 0 | 0 | 0 | + +The single STC-ARCH-01 exemption that survived cycles 1–2 is gone. AZ-511 carved out `classColors` to its own `src/class-colors/` component with a public barrel, and `scripts/check-arch-imports.mjs` `ARCH_IMPORTS_EXEMPT_RE` now equals `null`. The 5-coupled-places carry-over surface logged in cycle 1's retro is fully retired. + +## Architecture Gates (cycle 3 close) + +| Gate | Added in | Enforces | Status (cycle 3 close) | +|------|----------|----------|------------------------| +| `STC-ARCH-01` | Cycle 1 / AZ-485 | No cross-component deep imports; barrels are the Public API | PASS (now with **zero exemptions**) | +| `STC-ARCH-02` | Cycle 1 / AZ-486 | No hardcoded `/api//...` literals in production source | PASS | +| `STC-SEC1C` | Cycle 2 / AZ-499 | Banned literal: OpenWeatherMap key | PASS | +| `STC-SEC1D` | Cycle 2 / AZ-501 | Banned literal: Google Geocode key | PASS | + +Total commit-time static gates: **33** (cycle 2 close = 33; cycle 3 close = 33 — no new gates this cycle). STC-ARCH-01 was *strengthened* (exemption removed), not added new. + +## Architecture Baseline Delta vs `architecture_compliance_baseline.md` + +| Finding | Category | Cycle 1 close | Cycle 2 close | Cycle 3 close | +|---------|----------|---------------|---------------|---------------| +| F1 — mission-planner vs flights duplication | Architecture | Open | Open | Open | +| F2 — cross-feature edge `07_dataset → 06_annotations` | Architecture | Open (grandfathered) | Open | Open | +| F3 — classColors physical/logical owner split | Architecture | Open | Open | **RESOLVED (AZ-511)** | +| F4 — No Public API barrels | Architecture | RESOLVED (AZ-485) | RESOLVED | RESOLVED | +| F5 — Pre-existing cycle inside `mission-planner` | Architecture | Open | Open | Open | +| F6 — No `src/shared/` | Architecture | Open | Open | Open | +| F7 — Hardcoded `/api//` literals | Architecture | RESOLVED (AZ-486) | RESOLVED | RESOLVED | +| F8 — Layering-table inconsistency | Architecture | Open | Open | Open | +| F9 — Inert second Vite entry tree | Architecture | Open | Open | Open | + +Plus the per-cycle verification-log finding **B3** (Auth bootstrap missing `credentials:'include'`) was tracked in `_docs/02_document/04_verification_log.md` and **closed by AZ-510 in cycle 3**. + +- **Resolved this cycle**: 1 baseline finding (F3) + 1 verification-log finding (B3) +- **Newly introduced this cycle**: 0 +- **Architecture findings open at cycle 3 close**: 6 of 9 baseline (F1, F2, F5, F6, F8, F9) +- **Net architecture delta cycle 3**: −1 baseline (improvement) + +## Contract Coverage + +- `_docs/02_document/contracts/` does NOT exist; project uses **code-derived contracts pattern** via `src/api/endpoints.test.ts`. +- Wire-contract assertions count: cycle 1 = 36, cycle 2 = 36, cycle 3 = **37** (+1; AZ-510 added `endpoints.admin.usersMe()`). + +## Test Suite Snapshot + +| Profile | Cycle 1 close | Cycle 2 close | Cycle 3 close | Δ vs cycle 2 | +|---------|---------------|---------------|---------------|--------------| +| Fast (count) | 209 PASS / 13 SKIP / 0 FAIL | 229 PASS / 13 SKIP / 0 FAIL | **231 PASS / 13 SKIP / 0 FAIL** | +2 PASS, 0 SKIP | +| Static (gates) | 31 / 31 PASS | 33 / 33 PASS | 33 / 33 PASS | 0 | +| Build | green (no circular warnings) | green | green | 0 | +| Bundle (gzipped initial JS) | not measured | 290 465 B | **290 575 B** | +110 B (+0.04 %) | + +Bundle delta is well within budget (≤ 2 097 152 B threshold; ~14 % utilization). + +## Cycle 3 Source-of-Truth Mutations + +| File / area | Mutation | Driver | +|-------------|----------|--------| +| `src/auth/AuthContext.tsx` | POST refresh + chained `/users/me` + module-scoped `bootstrapInflight` + test-only reset hook | AZ-510 (B3 / Vision P3) | +| `src/auth/index.ts` | Re-exports `__resetBootstrapInflightForTests` | AZ-510 (STC-ARCH-01 compliance) | +| `src/api/endpoints.ts` | Added `usersMe: () => '/api/admin/users/me'` builder | AZ-510 (STC-ARCH-02 compliance) | +| `src/class-colors/` | New component directory: `classColors.ts` (`git mv` from `src/features/annotations/`) + `index.ts` (new barrel) | AZ-511 (F3) | +| `src/components/DetectionClasses.tsx`, `src/features/annotations/{CanvasEditor,AnnotationsSidebar,AnnotationsPage}.tsx` | Import path swap to barrel | AZ-511 (F3) | +| `src/features/annotations/index.ts` | Removed F3 carry-over comment block | AZ-511 (cleanup) | +| `scripts/check-arch-imports.mjs` | `ARCH_IMPORTS_EXEMPT_RE = null`; `class-colors` added to `COMPONENT_DIRS` | AZ-511 (gate strengthening) | +| `tests/architecture_imports.test.ts` | AC-4 inverted to assert deep imports FAIL | AZ-511 (regression guard) | + +## Sources + +- `_docs/03_implementation/batch_13_cycle3_report.md` (AZ-510) +- `_docs/03_implementation/batch_14_cycle3_report.md` (AZ-511) +- `_docs/03_implementation/batch_15_cycle3_report.md` (AZ-512 deferred) +- `_docs/03_implementation/implementation_report_auth_classcolors_cycle3.md` +- `_docs/03_implementation/implementation_completeness_cycle3_report.md` +- `_docs/03_implementation/deploy_cycle3_report.md` +- `_docs/05_security/security_report_cycle3_delta.md` +- `_docs/02_document/module-layout.md` +- `_docs/02_document/architecture_compliance_baseline.md` diff --git a/_docs/LESSONS.md b/_docs/LESSONS.md index 43a0215..f96a383 100644 --- a/_docs/LESSONS.md +++ b/_docs/LESSONS.md @@ -8,6 +8,36 @@ Categories: estimation · architecture · testing · dependencies · tooling · --- +- [2026-05-13] [process] When a task spec defines a Cross-Workspace Verification + BLOCKING gate and the user skips the choice prompt, the autodev MUST default + to the most conservative spec-aligned option (Option A: file prerequisite + ticket on the sibling workspace, park the task in `backlog/`) — never invent + a workaround that bypasses the missing dependency, never silently ship a UI + affordance against a non-existent endpoint, and always preserve the user's + ability to override at the next invocation (AZ-512 → AZ-513 pattern). + Source: _docs/06_metrics/retro_2026-05-13_cycle3.md + +- [2026-05-13] [architecture] Introducing a module-scoped state guard in + production source (e.g., a top-level `let bootstrapInflight: Promise | null + = null` for React 18 StrictMode dedupe) requires the same batch to ship 4 + coupled changes — (a) a test-only reset hook re-exported via the public + barrel (STC-ARCH-01 compliance), (b) an `afterEach` reset in + `tests/setup.ts`, (c) a defensive default-fixture invariant check (e.g., + MSW handler must seed required nullable fields the helper consumes), (d) a + planned ripple swap in handler mocks for any HTTP method or wire-shape + change — skipping any one costs a separate test-stabilization loop, as + AZ-510's ~4-attempt arc demonstrated. + Source: _docs/06_metrics/retro_2026-05-13_cycle3.md + +- [2026-05-13] [process] Track "user-action backlog at cycle close" as a + first-class retrospective metric (count of leftover items broken down by + manual-third-party / cross-workspace-prerequisite / cross-workspace-deploy + / push-pending categories) — backlog grew monotonically 0 → 3 → 7 across + cycles 1-3 and that accumulation is a process-shape signal, not noise; + surfacing it makes the cost of conservative-path defaults visible per + cycle and creates pressure for an explicit drain mechanism. + Source: _docs/06_metrics/retro_2026-05-13_cycle3.md + - [2026-05-12] [process] When externalizing a committed API key, always follow the 4-step rotation discipline: (a) extract to env-var via a service module so unit tests can stub it, (b) add a literal-scan static gate (STC-SECx) diff --git a/_docs/_autodev_state.md b/_docs/_autodev_state.md index 2de0673..31e1606 100644 --- a/_docs/_autodev_state.md +++ b/_docs/_autodev_state.md @@ -2,17 +2,19 @@ ## Current Step flow: existing-code -step: 16 -name: Deploy +step: 9 +name: New Task status: not_started sub_step: phase: 0 name: awaiting-invocation detail: "" retry_count: 0 -cycle: 3 +cycle: 4 tracker: jira ## Notes -- Cycle 3 Step 10 (Implement) shipped 6 of 9 points: AZ-510 + AZ-511 done; AZ-512 deferred to backlog/ at its BLOCKING cross-workspace verification gate (admin/ workspace lacks the prerequisite /classes routes). Leftover: `_docs/_process_leftovers/2026-05-13_az-512-admin-classes-prereq.md`. -- Cycle 2 leftovers still pending (deploy + manual key revocations). +- Cycle 3 closed 2026-05-13: AZ-510 + AZ-511 shipped (6/9 pts, B3 + F3 closed); AZ-512 deferred to backlog at cross-workspace gate (AZ-513 filed on admin/). +- Retro: `_docs/06_metrics/retro_2026-05-13_cycle3.md`. Structural snapshot: `_docs/06_metrics/structure_2026-05-13.md`. +- 7 user-action items in backlog (carry from cycles 2-3): see `_docs/_process_leftovers/`. +- Pre-Step-9 (cycle 4) sweep: cycle-3 unstaged docs + `ripple_log_cycle3.md` + `security_report_cycle3_delta.md` (untracked) NOT in any commit yet — flag to user before starting cycle 4.