diff --git a/_docs/06_metrics/retro_2026-05-12.md b/_docs/06_metrics/retro_2026-05-12.md new file mode 100644 index 0000000..76ff523 --- /dev/null +++ b/_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. diff --git a/_docs/06_metrics/structure_2026-05-12.md b/_docs/06_metrics/structure_2026-05-12.md new file mode 100644 index 0000000..320dcaa --- /dev/null +++ b/_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//...` 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//` 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//` 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` diff --git a/_docs/LESSONS.md b/_docs/LESSONS.md index 5e125cc..2441906 100644 --- a/_docs/LESSONS.md +++ b/_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 --- diff --git a/_docs/_autodev_state.md b/_docs/_autodev_state.md index b593c14..e929a26 100644 --- a/_docs/_autodev_state.md +++ b/_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.