ui/_docs/LESSONS.md

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] [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) against the rotated value as defense-in-depth, (c) document in .env.example using the established <your-...> placeholder convention, (d) leave the actual key revocation as a manual deliverable AC with evidence-attachment requirement — never assume the static gate alone neutralizes the leaked credential. Source: _docs/06_metrics/retro_2026-05-12_cycle2.md

• [2026-05-12] [dependencies] When bun audit reports advisories on a transitive dep that direct bun update <dep> does not clear (because nested copies persist under sibling tools, e.g. vitest/node_modules/<dep>), use package.json "overrides" to floor the resolution AND clean reinstall (rm -rf node_modules bun.lock && bun install) — a direct update alone cannot displace nested copies, and Bun honors the npm-compatible overrides field exactly as npm does. Source: _docs/06_metrics/retro_2026-05-12_cycle2.md

• [2026-05-12] [tooling] When the autodev orchestrator delegates to a sub-skill that ends in a HIGH-severity blocking gate (e.g. security audit FAIL → user picks "fix inline"), capture the inline-fix sub-step results as a separate batch report (batch_NN_report.md) — not as an extension of the prior batch — so the cycle metrics correctly attribute findings, ACs, and complexity to the work boundary that produced them. Source: _docs/06_metrics/retro_2026-05-12_cycle2.md

• [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.

---