ui/_docs/06_metrics/retro_2026-05-13_cycle3.md

# 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 `<sibling/>` 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 `<sibling>`", "calls `/api/admin/<new>`") 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).