agentic-dev/docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md

Refactor Changelog — Lazar Pattern Conformance

Started: 2026-05-05 Spec: 2026-05-05-lazar-pattern-conformance-design.md Plan: 2026-05-05-plan-8-lazar-conformance.md Branch: feature/lazar-conformance

This document captures every architectural change made during Plan 8 execution, organized by category. After the plan is merged, use the "Doc update checklist" at the bottom to update external docs in a single follow-up pass.

---

Summary

(Filled in at Task 10 — total files added/modified/deleted/renamed; net test count change; commits.)

---

1. File renames (before → after)

(populated as work progresses)

2. Files added (with purpose)

(populated as work progresses)

3. Files deleted (with reason)

(populated as work progresses)

4. Pattern changes (code-level)

4.1 Use cases — factory function pattern

(populated when a use case is migrated)

4.2 Controllers — one per use case

(populated when controllers are split)

4.3 Entities split — models/ + errors/ subdirs

(populated when entities are reshaped)

5. DI changes

5.1 Inversify .toDynamicValue bindings

(populated when DI modules are updated)

5.2 Mock siblings registered as default bindings

(populated when modules are updated)

6. Test refactor patterns

6.1 Direct injection (no container rebinding)

(populated when tests are migrated)

7. Open issues / deferred decisions

(populated as encountered)

---

Doc update checklist (deferred — run after merge)

After Plan 8 is merged to main, work through this list in a single batched doc-update pass. Each item points at an external doc that references the pre-Plan-8 layout or pattern and needs to be brought in line.

• CLAUDE.md — Key Conventions section: update file path examples to use entities/models/<x>.ts; mention factory-function use cases; show I*UseCase type aliases
• AGENTS.md (root) — Per-Package Conventions: update naming examples (<x>.repository.{ts,mock.ts,interface.ts}); add note about I*UseCase / I*Controller type aliases; document factory-style DI
• docs/guides/adding-a-feature.md — restructure to use factory-function pattern in every step; update file paths to new layout; show .toDynamicValue() bindings
• docs/guides/tdd-workflow.md — update "When to mock" decision tree to show direct factory injection (signInUseCase(mocks)(input)) instead of container rebinding; update factory usage examples to reference entities/models/* paths
• docs/guides/testing-strategy.md — Mocking section: remove DI-rebinding pattern as the default; show direct factory injection
• docs/architecture/vertical-feature-spec.md — update §10 (file shape examples) to new template; update §13 (testing) to reflect factory pattern + direct injection
• docs/architecture/overview.md — layer descriptions: mention factory-function use cases; add note that controllers are one-per-use-case
• docs/architecture/dependency-flow.md — verify dep flow still accurate with new DI bindings; update examples if any reference old paths
• docs/decisions/adr-012-lazar-conformance.md — NEW ADR documenting the conformance decision and the four intentional divergences (per-feature DI, inversify retained, colocated tests, no Sentry/instrumentation services)
• Per-feature AGENTS.md (auth/blog/media/marketing-pages/navigation) — update file path references; document factory pattern; update Tests section
• packages/core-testing/AGENTS.md — update factory examples to reference entities/models/<x>.ts paths
• packages/auth/AGENTS.md — document the new real UsersRepository and AuthenticationService (Payload-backed)
• packages/media/AGENTS.md — full rewrite — media now has all Clean Architecture layers (entities, application, infrastructure, interface-adapters, DI, integrations/api)
• Plan 7 plan/spec docs — add a one-line note at the top noting that paths reference the pre-Plan-8 layout; link to refactor changelog

---

Notes for the doc-update pass author

When updating external docs, apply these substitutions globally:

Old reference	New reference
entities/<x>.ts	entities/models/<x>.ts
entities/errors.ts	entities/errors/<domain>.ts (or entities/errors/common.ts)
mock-<x>.repository.ts	<x>.repository.mock.ts
payload-<x>.repository.ts	<x>.repository.ts (real impl is now the canonical name)
<x>-repository.interface.ts	<x>.repository.interface.ts
class PayloadXRepository	class XRepository
Use case calls container.get(...) inside its body	Use case is a factory function: (deps) => async (input) => result
Controller bundles multiple methods (articles.controller.ts)	One controller per use case (get-articles.controller.ts, create-article.controller.ts)
Test does container.unbind(...).bind(...) in beforeEach	Test constructs mocks and injects: const useCase = signInUseCase(mockUsers, mockAuth);
DI binds use case with .to(...)	DI binds use case with .toDynamicValue((ctx) => factoryFn(ctx.container.get(...)))
Use case + controller imports inject via container	Imports take dependencies as constructor/factory args

Add I*UseCase and I*Controller type alias examples wherever use cases / controllers are explained.