Commit 112d263
authored
docs(entity): entity docs describe data, not controller choreography (#350)
## Summary
### Why?
Entity doc comments had started narrating pipeline choreography — which
controller writes a field, which seams read it, which stage never
touches it (e.g. "written only by the orchestrator's speculate
controller … the seams never write it"). That is control-flow knowledge
that belongs with the code that owns the behavior; restated on the
entity it goes stale as the pipeline evolves and distracts from what the
entity actually guarantees.
### What?
Adds entity guideline 7 to CLAUDE.md: docs describe what a type or field
*is* and its invariants (immutability, uniqueness scope, units, valid
range) — never which controller/stage/seam reads or writes it; ownership
and write-path rules live in controller/store/extension docs. Lifecycle
enums may define states in terms of pipeline stages where that is the
state's meaning, but must not name the components performing
transitions. Also trims the one instance in the merged entity files this
stack touches (`SpeculationPathBuild.Version`'s "version arithmetic is
owned by the controller" clause — the convention is already documented
in CLAUDE.md and the storage README).
## Test Plan
Doc-only change.
## Issues
## Stack
1. @ #350
1. #351
1. #3531 parent c92e4e3 commit 112d263
2 files changed
Lines changed: 3 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
120 | 120 | | |
121 | 121 | | |
122 | 122 | | |
| 123 | + | |
123 | 124 | | |
124 | 125 | | |
125 | 126 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
36 | | - | |
37 | | - | |
| 36 | + | |
| 37 | + | |
38 | 38 | | |
39 | 39 | | |
0 commit comments