name the layer, not only the primitive

The constitution asks which primitive a feature is. It never asked *where* the
feature belongs, and that let a whole feature get built at the wrong layer.

Four layers, outermost wins: content on disk, engine (facts only the engine can
produce), theme (markup), browser (CSS, then JS). Two rules fall out — the engine
never edits authored text to change how it looks, and a feature needing no engine
fact is not an engine feature. architecture.md carries the table and the test;
CLAUDE.md carries the one-line version, since it is the file always loaded.

The example is named in the docs on purpose. A rule with a scar attached is one an
agent can apply; a rule stated in the abstract gets reasoned around.
This commit is contained in:
2026-08-01 02:23:36 +06:00
parent 7abb2fbee1
commit f48cf018d4
3 changed files with 34 additions and 0 deletions
+6
View File
@@ -35,6 +35,12 @@ Definitions and STATUS: `docs/architecture.md`.
Name the primitive before writing code. If it reduces to none it is a **trunk** (wants a permanent
service or a core-model change): stop, say so in a paragraph, propose the leaf, wait.
**Name the layer too.** Content on disk · engine (data only the engine can produce) · theme (markup) ·
browser (CSS, and only then JS). Build it at the outermost layer that can do the job: a line-breaking or
spacing problem CSS solves is not an engine feature, and code that edits an author's text to fix how it
*looks* is at the wrong layer by definition (ADR-0045 — a whole feature was deleted for this). Layers and
the test: `docs/architecture.md`.
## 3. Hard rules
1. **No abstraction before its second concrete use** — pipeline, resolver, interface, generic, config