# 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.

---