FormingWorlds · egpbos · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
@@ -0,0 +1,62 @@
+# Whole-planet oxygen accounting
+
+Read this before touching element budgets, `M_planet` bookkeeping, escape
+partitioning, the desiccation gate, or anything that sets or consumes
+`planet.elements.O_mode`. Originates from issue #677.
+
+> **Discovery note.** PROTEUS keeps its Claude-Code rule files under
+> `.github/.claude/rules/` (not the conventional repo-root `.claude/`, which is
+> gitignored and so cannot be shared with collaborators). Claude does NOT
+> auto-discover them at this path; `.github/copilot-instructions.md` names this
+> file so readers and AI tooling know to load it.
+
+## Config contract
+
+Every config must declare an explicit `planet.elements.O_mode`. Four valid modes:
+
+- `"ic_chemistry"`: defer the IC O budget to CALLIOPE's fO2-buffered
+  equilibrium. Preserves pre-fix behaviour; backwards-compatible.
+- `"ppmw"`, `"kg"`: parallel to the H/C/N/S modes; sets O_kg directly.
+- `"FeO_mantle_wt_pct"`: alternative unit for petrologists. The number is
+  interpreted as `O_kg = M_mantle * (wt% / 100) * (M_O / M_FeO)`. The mantle EOS
+  density is NOT modified; PALEOS still assumes its built-in FeO content. The
+  mode is a unit-of-convenience for setting the volatile-O budget in familiar
+  terms.
+
+## Design (D1A)
+
+Under D1A, the chosen design, CALLIOPE / atmodeller chemistry is unchanged.
+Oxygen is treated as a buffered element at the chemistry step but a tracked
+element in PROTEUS-side mass accounting.
+
+The asymmetry that previously let `M_atm > M_planet` at high H budgets is closed
+by including O in:
+
+- `M_ele`
+- the Zalmoxis dry-mass subtraction
+- the proportional escape distribution
+- the desiccation gate
+
+Escape includes O in the unfractionated partitioning so
+`sum(esc_rate_e) == esc_rate_total` to within rounding.
+
+## Runtime guards
+
+- `assert_mass_conservation` in the main loop enforces `M_atm <= M_planet` every
+  iteration. If a change weakens or removes it, push back: it is the safety net
+  that catches O-skip reintroductions.
+- `check_ic_oxygen_budget`, called once after the first outgas call, hard-fails
+  on >50% divergence between the user-supplied O_budget and CALLIOPE's
+  equilibrium value.
+
+## Aggregation symmetry
+
+All aggregation sites must use the same element set. A new `if e == 'O':
+continue` skip in any of them is a red flag; it likely re-introduces the
+asymmetry that issue #677 closed. The sites are enumerated under "Whole-element
+aggregation symmetry" in [`proteus-code-review.md`](proteus-code-review.md).
+
+## Sister rules
+
+- [`.github/copilot-instructions.md`](../../copilot-instructions.md): repo-wide rules.
+- [`proteus-code-review.md`](proteus-code-review.md): the aggregation-site list and review criteria.
@@ -0,0 +1,56 @@
+# SOCRATES build flags
+
+Read this before changing `tools/get_socrates.sh`, before debugging an
+illegal-instruction crash from a restored SOCRATES tree, and before producing
+numbers that have to be bit-reproducible.
+
+> **Discovery note.** PROTEUS keeps its Claude-Code rule files under
+> `.github/.claude/rules/` (not the conventional repo-root `.claude/`, which is
+> gitignored and so cannot be shared with collaborators). Claude does NOT
+> auto-discover them at this path; `.github/copilot-instructions.md` names this
+> file under "Build Commands" so readers and AI tooling know to load it.
+
+## Default flags and the portable switch
+
+By default `tools/get_socrates.sh` keeps the configure flags `-Ofast
+-march=native`, which give the best performance on the build host. Set
+`SOCRATES_PORTABLE_FLAGS=1` to compile with `-O2 -fno-fast-math` instead.
+
+The `-march=native` default bakes the build host's CPU extensions into the
+binary, so a compiled tree reused on a different processor aborts with an
+illegal-instruction fault, while the portable flags run on any CPU. CI sets the
+switch because its caches are restored across runner machines with mixed CPU
+generations.
+
+Dropping fast-math also removes compiler value reordering, the build-to-build
+component of the ULP-level non-determinism that AGNI's Newton solver amplifies
+into 1-2 % F_atm variance; run-to-run scatter from OpenMP threading remains
+while OMPARG is set.
+
+In portable mode the build fails loudly if a future SOCRATES release changes the
+flag string, so no manual edit is needed.
+
+## Full bit-reproducibility
+
+For paper plots, CHILI, and SPIDER-parity work, install with
+
+```bash
+SOCRATES_PORTABLE_FLAGS=1 bash tools/get_socrates.sh
+```
+
+and also clear `OMPARG = -fopenmp` in `socrates/make/Mk_cmd`, then force a
+recompile:
+
+```bash
+cd socrates/bin && make clean && cd .. && ./build_code
+```
+
+The clean is required: no make rule depends on `Mk_cmd`, so rebuilding without
+it reuses the OpenMP objects unchanged. The install path keeps OpenMP enabled
+and does not clear it automatically.
+
+## Sister rules
+
+- [`.github/copilot-instructions.md`](../../copilot-instructions.md): repo-wide rules.
+- [`proteus-tests.md`](proteus-tests.md): test quality deep-dive.
+- [`proteus-code-review.md`](proteus-code-review.md): review criteria.
@@ -4,7 +4,13 @@ description: PROTEUS test quality deep-dive. Anti-happy-path patterns, discrimin
 
 # PROTEUS Test Quality Rules
 
-This file is the canonical deep-dive on test quality. The high-level summary lives in [`.github/copilot-instructions.md`](../../copilot-instructions.md) under "Testing Standards". The two files MUST stay in sync. If you change one, mirror the change in the other.
+This file is the canonical deep-dive on test quality, and for most clauses it is the ONLY statement of them. [`.github/copilot-instructions.md`](../../copilot-instructions.md) loads into every session in full, so it keeps only the contract a reader needs before knowing whether tests are in scope: the structure rule, the marker table, the physics-invariant tiers, the anti-happy-path rules, and the certification markers. Its "Detail carried by the deep-dive" table maps the remaining clauses to sections here.
+
+Consequences for editing:
+
+- A clause that lives only here can be changed here alone.
+- A clause the root file also states (structure, markers, invariant tiers, anti-happy-path, certification markers) must be changed in both files in the same commit.
+- Adding or removing a section here means updating the mapping table in the root file.
 
 > **Discovery note.** PROTEUS keeps its Claude-Code rule files under `.github/.claude/rules/` (not the conventional repo-root `.claude/`) so they can be tracked in git and shared across collaborators. Claude does NOT auto-discover them at this path; the repo-root `CLAUDE.md` (symlinked to `.github/copilot-instructions.md`) names this file and `proteus-code-review.md` explicitly so AI tooling and human readers know to load them. **When opening or editing any file under `tests/**` or `src/proteus/**`, read this file first.**
 
@@ -394,7 +400,7 @@ When you spot a new variant of these, add it here.
 
 ## 17. Sister rules (cross-link)
 
-- `.github/copilot-instructions.md` "Testing Standards" -- the high-level summary readers without `tests/**` context see first.
+- `.github/copilot-instructions.md` "Testing Standards" -- the contract summary readers without `tests/**` context see first, plus the mapping table pointing here for everything else.
 - `.claude/rules/proteus-code-review.md` "Test marker discipline" -- the review-pass gate that backs up the rules in this file. Also contains domain-aware physics checks (Stefan-Boltzmann exponent, hf_row override pattern, IC consistency, whole-element aggregation symmetry) that apply when reviewing the **source** code that tests cover.
 
-Any change to the rule set: update both files in the same commit and call out the cross-reference in the commit body.
+When changing a clause the root file also states, update both files in the same commit and call out the cross-reference in the commit body. When adding or removing a section here, update the root file's mapping table.