Commit 716209f
committed
Docs: Move the architecture guide to the root and split out the decision log
The repo had two files called ARCHITECTURE.md. The root one, an untracked
Architecture Vision file excluded via .git/info/exclude, was last touched on
26 July and described the tiered Packages/ layout that the consolidation
replaced. The tracked docs/ARCHITECTURE.md was the maintained one. Reading the
stale file while I edited the other is what surfaced this.
The guide now sits at the root, where a newcomer looks alongside README and
CONTRIBUTING, and is tracked normally with the exclude entry removed. Three
sections were merged from the vision file first, each verified against the code:
the design principles (point 8 rewritten, since it described the retired
Packages/ tiers), state ownership (reworded to stop overloading the word
service, because git status, tasks and LSP sessions live in feature targets
rather than service targets), and the rejected-options list.
Two claims in that list were wrong and are corrected. The @observable entry
justified itself with a macOS 13 minimum, but the declared target is 14 in both
the pbxproj and the manifest, so the blocker is team agreement rather than code.
The Combine entry claimed the EventBus could swap to AsyncStream without
touching call sites; subscribe(_:) returns AnyPublisher and all five subscribers
use sink and AnyCancellable, so it would rewrite every one.
The guide dropped from 557 to 435 lines by moving decision records to
docs/architecture-decisions.md: the four target-separation rulings, what the I/O
norm prevents, the panel seam detail, the Core charter evidence, and the
singletons inventory. What stayed is the rule plus its reasoning. Panel
contributions shrank from 41 lines to the reusable pattern, since it is the
first of several seams and logging each in full would bloat the guide. Folder
conventions lost its per-target history, which is the only content deleted
rather than moved: 170 words.
Also removes the em dash separator from CONTRIBUTING.md prose, per the writing
style rule.1 parent 85256b8 commit 716209f
4 files changed
Lines changed: 236 additions & 161 deletions
0 commit comments