Update autodev state and lessons documentation

- Changed current step from 16 (Deploy) to 9 (New Task) and updated cycle from 1 to 2 in _docs/_autodev_state.md.
- Closed Cycle 1 (Phase B) and noted that Steps 14, 15, and 16 were skipped due to no changes in auth, wire, or performance surfaces.
- Added new lessons to _docs/LESSONS.md, including insights on architecture gates and handling state discrepancies during session resumes, sourced from recent retrospectives.

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

_docs/06_metrics/retro_2026-05-12.md

@@ -0,0 +1,134 @@
+# Retrospective — 2026-05-12
+
+**Mode**: cycle-end (autodev existing-code Step 17)
+**Scope**: Phase B, cycle 1 (`state.cycle = 1`)
+**Epic**: AZ-447 (`01-testability-refactoring`)
+**Cycle duration**: 2 batches over 1 working day (2026-05-11)
+**Previous retro**: N/A — first retrospective for this project
+
+## Implementation Summary
+
+| Metric | Value |
+|--------|-------|
+| Total tasks | 2 (AZ-485, AZ-486) |
+| Total batches | 2 (batch 09, batch 10) |
+| Total complexity points | 10 (5 + 5) |
+| Avg tasks per batch | 1 |
+| Avg complexity per batch | 5 |
+| Source files mutated | 28 production + 23 test/colocated + 3 scripts + 4 docs (across both batches) |
+
+Source: `implementation_report_refactor_phase_b_cycle1.md` + `batch_09_report.md` + `batch_10_report.md`.
+
+## Quality Metrics
+
+### Code Review Results
+
+| Verdict | Count | Percentage |
+|---------|-------|-----------|
+| PASS | 2 | 100 % |
+| PASS_WITH_WARNINGS | 0 | 0 % |
+| FAIL | 0 | 0 % |
+
+*Cumulative review (K=3 trigger) did NOT fire — cycle had only 2 batches.* Next cumulative review window opens at cycle 2 / batch 3.
+
+### Findings by Severity
+
+| Severity | Count |
+|----------|-------|
+| Critical | 0 |
+| High | 0 |
+| Medium | 0 |
+| Low | 0 |
+
+### Findings by Category
+
+| Category | Count | Top Files |
+|----------|-------|-----------|
+| Bug | 0 | — |
+| Spec-Gap | 0 | — |
+| Security | 0 | — |
+| Performance | 0 | — |
+| Maintainability | 0 | — |
+| Style | 0 | — |
+| Scope | 0 | — |
+
+## Structural Metrics
+
+Source: `_docs/06_metrics/structure_2026-05-12.md`.
+
+| Metric | Value | Delta vs baseline (Phase A close) |
+|--------|-------|-----------------------------------|
+| Component count | 12 | 0 |
+| Public-API barrels | 11 / 11 (100 %) | +11 (F4 closed) |
+| Commit-time static gates | 31 / 31 PASS | +2 (STC-ARCH-01, STC-ARCH-02) |
+| Architecture cycles | 0 | 0 (held) |
+| Documented feature→feature edges | 1 (F2 grandfathered through barrel) | 0 |
+| Architecture findings open (baseline F1–F9) | 7 of 9 | **−2** (F4, F7 resolved) |
+| Newly introduced architecture violations | 0 | 0 |
+| Net architecture delta this cycle | **−2** (improvement) | — |
+| Wire-contract assertions (`endpoints.test.ts`) | 36 | +36 (new contract surface) |
+| Fast-profile suite | 209 PASS / 13 SKIP / 0 FAIL | +46 (+42 this cycle on top of +4 from batch 9) |
+
+### Auto-lesson triggers (per skill Step 1)
+
+- Net Architecture delta > 0? **No** — delta is −2; no `architecture` regression lesson required.
+- Structural metric regression > 20 %? **No** — every structural metric improved or held.
+- Contract coverage % decreased? **N/A** — no `_docs/02_document/contracts/` directory; project uses code-derived contracts (`endpoints.test.ts`), which expanded by 36 new assertions this cycle.
+
+## Efficiency
+
+| Metric | Value |
+|--------|-------|
+| Blocked tasks | 0 |
+| Tasks requiring fixes after review | 0 |
+| Batch with most findings | None — both batches 0 findings |
+| Auto-fix loops invoked | 1 (batch 09, classColors circular import; documented as F3-pending exemption) |
+| Stuck-agent incidents | 0 |
+
+### Blocker Analysis
+
+| Blocker Type | Count | Prevention |
+|--------------|-------|-----------|
+| None this cycle | 0 | — |
+
+### Auto-fix root-cause (batch 09)
+
+- **Symptom**: `tests/detection_classes.test.tsx` failed with `TypeError: Cannot read properties of undefined (reading 'map')` after `FALLBACK_CLASS_NAMES` was migrated to import through the `06_annotations` barrel.
+- **Root cause**: barrel-induced runtime circular import (`AnnotationsPage → DetectionClasses → 06_annotations barrel → AnnotationsPage`).
+- **Resolution**: structural exemption (NOT a re-order hack) — `classColors` removed from the `06_annotations` barrel, exemption documented in 5 coupled locations (barrel file, consumer file, static-check script regex, `module-layout.md` Rule #3, architecture test exemption case). Exemption clears when F3 moves the file to its physical/logical owner.
+- **Lesson seed**: documented under §Top 3 Improvement Actions #2 and reflected in LESSONS.md (architecture).
+
+## Trend Comparison
+
+*No previous retrospective — this is the project's first cycle retro. Baseline metrics established above will form the comparison surface for cycle 2.*
+
+## Top 3 Improvement Actions
+
+1. **Establish a "micro-cumulative" review for cycles with < K batches.**
+   Cycle 1 closed in 2 batches, below the implement skill's K=3 cumulative-review trigger. No aggregate cross-batch review fired at cycle close — only the two per-batch self-reviews. Both were clean, so it cost nothing this time, but the gap exists by design and silently widens for any tightly-scoped cycle. Recommend adding a lightweight "end-of-cycle micro cumulative" pass (Phase 6 + Phase 7 only) when `cycle_batch_count < K`, gated to ≤ 30 minutes.
+   - Impact: medium — catches cross-batch consistency drift that single-batch self-review misses.
+   - Effort: low — extend implement skill Step 14.5 with a `cycle_close` branch; no new tooling.
+
+2. **Codify the `STC-ARCH-*` single-script-multi-mode pattern as the standard architecture-gate recipe.**
+   Both gates this cycle (STC-ARCH-01 / STC-ARCH-02) share one script (`scripts/check-arch-imports.mjs`) with a `--mode` flag, one symmetric test harness (`tests/architecture_imports.test.ts` with fixture-driven fail-on-synthetic + pass-on-migrated cases), and a uniform 5-place exemption-documentation discipline. The next architecture gate (e.g., STC-ARCH-03 for F6's `src/shared/` move, or a future cross-layer prohibition) should follow the same shape rather than reinventing.
+   - Impact: high — halves the drift surface for every future architecture gate; the pattern is already battle-tested for two gates.
+   - Effort: low — promote the pattern explicitly in `_docs/02_document/module-layout.md` (currently described per-rule) and reference it from `coderule.mdc` or a new architecture-gates rule file.
+
+3. **Promote the autodev state-reconciliation rule as a canonical example.**
+   The session that closed AZ-486 started by detecting that `state.cycle` / `state.step` disagreed with the working tree (most of AZ-486 was already implemented but uncommitted). The autodev orchestrator surfaced the disagreement as a Choose block — option A "continue the in-progress work" was selected — and the session resumed cleanly with no auto-fix loops on the resume itself.
+   - Impact: process — confirms the rule in `state.md` "trust folders over state file" works in practice; recording it in `_docs/LESSONS.md` (and possibly as an example block under `state.md`) makes it discoverable.
+   - Effort: very low — LESSONS.md entry + one optional example block.
+
+## Suggested Rule / Skill Updates
+
+| File | Change | Rationale |
+|------|--------|-----------|
+| `.cursor/skills/implement/SKILL.md` (Step 14.5) | Add a `cycle_close && batch_count < K` branch that runs a Phase-6 + Phase-7 only "micro-cumulative" review. | §Top 3 Improvement Action #1. |
+| `_docs/02_document/module-layout.md` (after Layout Rules) | Add a short "Architecture Gate Recipe" section: one script + `--mode` dispatcher + fixture-driven test pair + 5-place exemption discipline. Cross-reference STC-ARCH-01 and STC-ARCH-02 as the canonical examples. | §Top 3 Improvement Action #2. |
+| `_docs/LESSONS.md` (top) | Append the 3 lessons in §LESSONS Append below. | Skill Step 4. |
+
+## LESSONS Append (top 3, single-sentence, tagged)
+
+1. **[architecture]** When adding an architecture gate (STC-ARCH-*), extend the existing single-script dispatcher with a new `--mode` flag instead of forking a second script; same walker, same comment-skip, same test harness — half the drift surface.
+2. **[architecture]** When a barrel re-export causes a runtime circular import, treat the carve-out as a structural exemption documented in five coupled places (barrel, consumer, script regex, layout doc, gate test), not as a re-order hack — the exemption clears when the deeper structural fix lands and never silently drifts in the meantime.
+3. **[process]** When autodev detects state ↔ working-tree disagreement on session resume (`state.cycle` / `state.step` ≠ on-disk artifact set), ALWAYS surface as a Choose block before resuming work — never silently merge or restart; the rule in `state.md` "trust folders over state file" worked end-to-end on the AZ-486 resume.

_docs/06_metrics/structure_2026-05-12.md

@@ -0,0 +1,64 @@
+# Structural Snapshot — 2026-05-12 (Phase B Cycle 1 close)
+
+**Cycle**: Phase B, cycle 1 (`state.cycle = 1`)
+**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`.
+
+## Component Inventory
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| Component count | 12 | `00_foundation`, `01_api-transport`, `02_auth`, `03_shared-ui`, `04_login`, `05_flights`, `06_annotations`, `07_dataset`, `08_admin`, `09_settings`, `10_app-shell`, `11_class-colors` |
+| Components with Public API barrels | 11 | Every component except `10_app-shell` (intentionally barrel-less; collection of root files like `App.tsx`, `main.tsx`) |
+| Barrel coverage of barrel-eligible components | 11 / 11 = 100 % | F4 closed by AZ-485 (commit `23746ec`) |
+| Documented feature→feature edges | 1 | F2 grandfathered: `07_dataset → 06_annotations` for `CanvasEditor`, routed through the `06_annotations` barrel (STC-ARCH-01 compliant) |
+| Documented F3-pending exemption | 1 | `src/features/annotations/classColors` direct path — exempted by `STC-ARCH-01` until F3 lands; tracked in 5 places (barrel, consumer, script regex, layout doc, test) |
+| Cycles in component import graph | 0 | Verified by `STC-T1` (`tsc --noEmit`) + `STC-B1` (`vite build`) — both green |
+
+## Architecture Gates (cycle close)
+
+| Gate | Added in | Enforces | Status |
+|------|----------|----------|--------|
+| `STC-ARCH-01` | Batch 09 / AZ-485 / Phase B cycle 1 | No cross-component deep imports; barrels are the Public API | PASS |
+| `STC-ARCH-02` | Batch 10 / AZ-486 / Phase B cycle 1 | No hardcoded `/api/<service>/...` literals in production source | PASS |
+
+Total commit-time static gates: **31** (29 at start of Phase B cycle 1; +2 this cycle).
+
+## Architecture Baseline Delta vs `architecture_compliance_baseline.md`
+
+| Finding | Category | Baseline status | After cycle 1 |
+|---------|----------|-----------------|---------------|
+| F1 — mission-planner vs flights duplication | Architecture | Open | Open (out of cycle scope) |
+| F2 — cross-feature edge `07_dataset → 06_annotations` | Architecture | Open | Open (grandfathered; routed through barrel post-AZ-485) |
+| F3 — classColors physical/logical owner split | Architecture | Open | Open (exemption holds; deferred) |
+| **F4 — No Public API barrels** | Architecture | Open | **RESOLVED (AZ-485, STC-ARCH-01)** |
+| F5 — Pre-existing cycle inside `mission-planner` | Architecture | Open | Open (port-source, out of scope) |
+| F6 — No `src/shared/` | Architecture | Open | Open (deferred; AZ-486 builds the relocation-friendly barrel pattern that makes F6 trivial later) |
+| **F7 — Hardcoded `/api/<service>/` literals** | Architecture | Open | **RESOLVED (AZ-486, STC-ARCH-02)** |
+| F8 — Layering-table inconsistency | Architecture | Open | Open (doc-only fix; deferred) |
+| F9 — Inert second Vite entry tree | Architecture | Open | Open (port-source, out of scope) |
+
+- **Resolved this cycle**: 2 (F4, F7)
+- **Newly introduced**: 0
+- **Net delta**: −2 (improvement)
+
+## Contract Coverage
+
+- `_docs/02_document/contracts/` does NOT exist in this project. The project uses the **"code-derived documentation" pattern**: `src/api/endpoints.test.ts` (36 assertions, AZ-486) IS the wire-contract document for every `/api/<service>/` path. Computed coverage % is not applicable.
+- Wire-contract surface: 25 endpoint builders × multi-arity inputs = 36 pinned URL assertions in fast suite.
+
+## Test Suite Snapshot
+
+| Profile | Files | Count | Wall-clock |
+|---------|-------|-------|------------|
+| Fast | 28 | 209 PASS / 13 SKIP / 0 FAIL | ~22.6 s |
+| Static | — | 31 / 31 PASS | ~14 s |
+| e2e | — | env-blocked (registry-access; same condition as Step 7) | n/a |
+
+## Sources
+
+- `_docs/03_implementation/batch_09_report.md` (AZ-485, batch 1 of 2)
+- `_docs/03_implementation/batch_10_report.md` (AZ-486, batch 2 of 2)
+- `_docs/03_implementation/implementation_report_refactor_phase_b_cycle1.md`
+- `_docs/03_implementation/test_run_report_phase_b_cycle1.md`
+- `_docs/02_document/module-layout.md`
+- `_docs/02_document/architecture_compliance_baseline.md`

_docs/LESSONS.md

@@ -1,8 +1,32 @@
 # Lessons
 
-Short, actionable retros from past sessions. Newest at top. Each entry: one
-line title + ≤6 lines body. The `autodev` orchestrator surfaces the top 3
-entries on every invocation.
+Short, actionable retros from past sessions. Newest at top. Ring buffer of
+the last 15 entries. The `autodev` orchestrator surfaces the top 3 entries
+on every invocation.
+
+Categories: estimation · architecture · testing · dependencies · tooling · process
+
+---
+
+- [2026-05-12] [architecture] When adding an architecture gate (STC-ARCH-*),
+  extend the existing single-script dispatcher with a new `--mode` flag
+  instead of forking a second script; same walker, same comment-skip, same
+  test harness — half the drift surface.
+  Source: _docs/06_metrics/retro_2026-05-12.md
+
+- [2026-05-12] [architecture] When a barrel re-export causes a runtime
+  circular import, treat the carve-out as a structural exemption documented
+  in five coupled places (barrel, consumer, script regex, layout doc, gate
+  test), not as a re-order hack — the exemption clears when the deeper
+  structural fix lands and never silently drifts in the meantime.
+  Source: _docs/06_metrics/retro_2026-05-12.md
+
+- [2026-05-12] [process] When autodev detects state ↔ working-tree
+  disagreement on session resume (`state.cycle` / `state.step` ≠ on-disk
+  artifact set), ALWAYS surface as a Choose block before resuming work —
+  never silently merge or restart; the rule in `state.md` "trust folders
+  over state file" worked end-to-end on the AZ-486 resume.
+  Source: _docs/06_metrics/retro_2026-05-12.md
 
 ---
 

_docs/_autodev_state.md

@@ -2,28 +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: 1
+cycle: 2
 tracker: jira
 
 ## Notes
-- Cycle 1 (Phase B) refactor cycle: F4 (AZ-485, `23746ec`) and F7
-  (AZ-486, `8a461a2`) closed.
-- Step 13 (Update Docs) DONE in working tree, NOT YET COMMITTED. User
-  skipped the commit gate; 12 module docs + new `src__api__endpoints.md`
-  + `01_api-transport/description.md` + ripple log + 2 cycle reports
-  pending review. Commit subject for when ready:
-  `[AZ-485] [AZ-486] Cycle 1 docs refresh (Step 13)`.
-- Step 14 (Security Audit) SKIPPED — cycle 1 was structural refactor
-  only; URL strings character-identical to pre-refactor (pinned by
-  `endpoints.test.ts`), no new auth / wire / permission surface.
-- Step 15 (Performance Test) SKIPPED — same rationale; no
-  latency-/throughput-relevant code paths changed.
-- Next: Step 16 (Deploy) — destructive; awaiting user decision.
+- Cycle 1 (Phase B) CLOSED. Retro: `_docs/06_metrics/retro_2026-05-12.md`
+  (+ `structure_2026-05-12.md`). Lessons appended to `_docs/LESSONS.md`.
+  Steps 14, 15, 16 SKIPPED (character-identical structural refactor); no
+  auth/wire/perf/deploy-relevant surface changed.