Merge pull request #84 from ModernRelay/ragnorc/read-docs

docs: lead AGENTS.md first principle with integrated-over-time framing

AGENTS.md

@@ -97,9 +97,9 @@ Full diagram and concurrency model: [docs/architecture.md](docs/architecture.md)
 
 ---
 
-## First principle: minimize ongoing liability
+## First principle: engineering is programming integrated over time
 
-Every decision — adding code, removing code, picking an abstraction, choosing a layer, writing a doc paragraph — carries an ongoing maintenance cost. Before any change, ask: **which option has the lower ongoing cost over time?** Not "shorter now," not "fastest to ship," but which leaves the codebase narrower in the long run.
+Software engineering is **programming integrated over time** (Winters, *Software Engineering at Google*). A line of code costs you at every future read, refactor, migration, and dependent change — not just at write-time. So the operative question for any change is: **which option has the lower ongoing liability?** Not "shorter now," not "fastest to ship," but which leaves the codebase narrower in the long run. **Complexity should be earned** — by demonstrated correctness, performance, or future-shape cost; never by speculation.
 
 This is a decision lens, not a code-size rule. It cuts both ways. Sometimes the lower-liability option is:
 
@@ -113,6 +113,11 @@ This is a decision lens, not a code-size rule. It cuts both ways. Sometimes the
 
 When evaluating a design, ask: *"what does this look like after 5 more changes like it?"* If the answer is "this converges to one shape", cost is bounded. If it's "this forks every time", the option is mortgaging the future for present convenience — pick differently.
 
+### Tiebreakers when liability alone is silent
+
+- **Correctness > simplicity > performance.** Lexicographic — give up performance for simpler code; give up simplicity for correct code; never give up correctness. The deny-list ("no silent failures," "no acks before durable persistence," "no reads of partial commits") is this rule's hard floor.
+- **Reversibility shapes evidence demand.** Reversible changes wait for evidence: prefer prod metrics over napkin math over RFCs. Irreversible changes (substrate choice, on-disk format, the §VI database guarantees) earn an RFC, because by the time prod tells you they were wrong, you've shipped years of dependent code. Reviewers should spot both failure modes — RFC-ing a one-line config, and measuring-your-way into a substrate decision.
+
 The always-on rules below and the §IX deny-list in [docs/invariants.md](docs/invariants.md) are specific applications of this principle; when the rules are silent, fall back to it.
 
 ---
@@ -150,6 +155,7 @@ If a proposal fits one of these, the burden is on the proposer to justify why th
 - Hand-rolling something Lance already does — check the spec first.
 - Mutating in place state that should be immutable (Lance fragments, index segments) — new segments instead.
 - Silent failures — OOM, timeout, partial result must all be surfaced and bounded.
+- Shipping observable behavior as if it weren't part of the contract — output ordering, error-message text, timestamp precision, default-flag values, latency profile. Per Hyrum's Law, every observable behavior gets depended on once shipped; don't expose what you don't want to commit to.
 
 ---
 

docs/invariants.md

@@ -220,6 +220,7 @@ If a proposal fits one of these, the burden is on the proposer to justify why th
 - **Hand-rolling something the substrate already does.** Check the spec first (§I.1).
 - **Mutating in place** state that should be immutable (Lance fragments, index segments). New segments instead.
 - **Silent failures.** OOM, timeout, partial result — all surfaced and bounded (§V.20).
+- **Shipping observable behavior as if it weren't part of the contract.** Output ordering, error-message text, timestamp precision, default-flag values, latency profile, query-result column order — every observable behavior gets depended on once shipped (Hyrum's Law). Don't expose what you don't want to commit to; treat changes to undocumented-but-observable behavior as breaking changes.
 - **Strict-serial coordination expressed as locks held across queries.** Branches are the agent-native primitive for that (§VI.35).
 - **Auto-resolving merge conflicts when the per-type policy is silent or absent.** Pause and surface the conflict; never silently pick a side (§VI.37).