# Lessons

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

---

## 2026-05-11 — Don't replace `URL` via `vi.stubGlobal('URL', { ...URL, ... })`

When stubbing `URL.createObjectURL` / `URL.revokeObjectURL` for a JSDOM-backed
test, **patch the methods on the constructor directly**. Never do
`vi.stubGlobal('URL', { ...URL, createObjectURL })` — the spread copies only
own enumerable properties of the `URL` *function object*, not its prototype, so
the global `URL` becomes a plain object. `new URL(...)` then throws / returns
garbage in MSW handlers and the SPA's API helper, and the test silently sees
"no fetch was made" instead of the real failure. Pattern in
`tests/upload_size_cap.test.tsx` is the canonical fix.

---