Context
PR #56 (docs_architecture_domain) is the "super-branch" containing a large refactor with breaking changes. Landing it as a single merge is risky and hard to review. Instead, we'll decompose it via ADRs that can be implemented incrementally on master.
Phase 1: ADR Documentation (Prerequisites)
These PRs document architectural decisions. Once merged, they become the specification for incremental implementation.
| ADR |
Title |
PR |
| ADR 002 |
Doctrine Test Architecture |
#75 |
| ADR 003 |
Workflow Orchestration via Handler Services |
#76 |
| ADR 004 |
Execution-Agnostic Use Cases |
#77 |
| ADR 005 |
Doctrine and Policy Separation |
#78 |
| ADR 006 |
Code-Outward Documentation |
#79 |
| ADR 007 |
Semantic Relations Decorator Pattern |
#71 |
| ADR 008 |
Generic CRUD Use Case Generators |
#72 |
| ADR 009 |
Repository vs Service Protocol Distinction |
#73 |
| ADR 010 |
Apps Layer and Reserved Words Architecture |
#74 |
Phase 2: Implementation Tickets
Implementation Dependencies
Hard dependencies
| ADR |
Depends on |
Reason |
| 005 |
002 |
Refactors the doctrine test structure that 002 creates |
| 006 |
005 |
References doctrine/policy distinction in its approach |
| 004 |
003 |
ClockService/ExecutionService follow the handler service pattern |
| 008 |
003 |
Generic CRUD has post_create_handler integration |
Soft dependencies (cleaner if ordered)
| ADR |
After |
Reason |
| 003 |
009 |
Handler protocols are services; benefits from 009's repo/service clarity |
Independent (only need 002)
- ADR 007 (Semantic Relations) — just needs doctrine test infrastructure
- ADR 009 (Repo vs Service) — just needs doctrine test infrastructure
- ADR 010 (Apps Layer) — just needs doctrine test infrastructure
Suggested order
- ADR 002 — creates doctrine test infrastructure all others need
- ADR 009 — clarifies repo vs service distinction
- ADR 005 — refactors 002's structure into doctrine/policy
- ADR 010, ADR 007 — independent, can parallel
- ADR 003 — handler pattern (after 009 for clarity)
- ADR 006 — documentation (after 005)
- ADR 004, ADR 008 — build on 003, can parallel
Action Items
1. Merge ADR documentation PRs
Review and merge PRs #71–#79 to establish the architectural specifications.
2. Create implementation branches/PRs
For each implementation ticket, respecting the dependency order above:
- Create a branch from
master
- Implement the ADR
- Open a PR
3. Backport master to super-branch
Once all ADR implementations are merged to master, backport master into the super-branch (docs_architecture_domain). This should resolve most conflicts and reduce the diff significantly.
4. Final review and merge
Review the now-not-so-super branch. The remaining diff should be small—residual changes that didn't fit neatly into any ADR. Merge to complete the landing.
Related
Context
PR #56 (
docs_architecture_domain) is the "super-branch" containing a large refactor with breaking changes. Landing it as a single merge is risky and hard to review. Instead, we'll decompose it via ADRs that can be implemented incrementally onmaster.Phase 1: ADR Documentation (Prerequisites)
These PRs document architectural decisions. Once merged, they become the specification for incremental implementation.
Phase 2: Implementation Tickets
Implementation Dependencies
Hard dependencies
post_create_handlerintegrationSoft dependencies (cleaner if ordered)
Independent (only need 002)
Suggested order
Action Items
1. Merge ADR documentation PRs
Review and merge PRs #71–#79 to establish the architectural specifications.
2. Create implementation branches/PRs
For each implementation ticket, respecting the dependency order above:
master3. Backport master to super-branch
Once all ADR implementations are merged to
master, backportmasterinto the super-branch (docs_architecture_domain). This should resolve most conflicts and reduce the diff significantly.4. Final review and merge
Review the now-not-so-super branch. The remaining diff should be small—residual changes that didn't fit neatly into any ADR. Merge to complete the landing.
Related