docs: RSR-PHILOSOPHY.adoc — canonical 'solutions at source' doctrine

RSR-PHILOSOPHY.adoc

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+= RSR Philosophy — The Estate's Operating Doctrine (canonical)
+:toc: preamble
+:icons: font
+
+[.lead]
+This is the *canonical* statement of the operating principles every hyperpolymath
+repository is worked under. It is the source that `rsr-template-repo` operationalises
+and that the estate arrival-pack projects, in summary form, into the top of every
+`CLAUDE.md`. The owner's `manifesto` states the same doctrine in its own voice;
+where wording must be reconciled, the manifesto prevails.
+
+The principles are deliberately few and blunt. They describe not only *what* good
+work is but the *order* and *manner* in which it is undertaken.
+
+== Solutions at source
+
+*Fix the canonical, upstream origin of a problem — never patch the downstream
+symptom.*
+
+When a defect, a drift, or a wrong setting appears in many places, it is almost
+never many problems: it is one problem at a source, expressed many times.
+Remediating the copies while leaving the source untouched guarantees the problem
+returns — and worse, makes it look solved. The estate's own shape makes the source
+explicit: `standards → rsr-template-repo → (every repo)`. A fix that belongs at the
+template does not belong, hand-applied, in hundreds of leaves.
+
+Two obligations follow, and neither is optional:
+
+. *Find the source.* Before acting, trace the thing back to where it is actually
+  defined — the template, the generator, the canon, the single point everything
+  else inherits from — and fix it there.
+. *Be mindful of every up- and down-stream.* A change at a source propagates.
+  Before making it, know what feeds the thing you are changing (upstream) and what
+  depends on it (downstream), and ensure the change is safe across all of them. A
+  correct fix that breaks a downstream consumer is not yet a fix.
+
+Where the source genuinely cannot be reached in one pass — an upstream you do not
+own, a change gated on owner ratification — remediate the downstream *and* record
+the source fix as the real work still owed. Silently patching the symptom as if it
+were the cure is itself a soundness hole (see _fail loudly_).
+
+This principle stands beside its two siblings: *holes before goals* and *always
+fail loudly*. Together they govern the order of work (holes first), the manner of
+work (loudly, never silently green), and the locus of work (at the source, never
+the symptom).
+
+== Holes before goals
+
+Fix soundness holes before features, optimisation, or documentation. A hole is
+anywhere the system can be wrong without saying so. Goals are everything one would
+rather be doing. Let the holes set the agenda — a goal reached on top of a hole is
+not reached.
+
+== Always fail loudly
+
+No silent green. A check that cannot fail is not a check; a fallback that hides a
+broken precondition is a forged result. Seams (ABI / FFI) are sealed and proven,
+not assumed. Prefer a build that breaks to a build that lies.
+
+== The full Doctrine
+
+The complete, always-current operating Doctrine is maintained as estate-common
+content in the arrival-pack and projected into every repository's `CLAUDE.md`. In
+addition to the three principles above it holds: ground-truth by running the tool,
+not trusting status docs; distrust the neural for exactness (licences, invariants,
+equivalence belong to PLASMA, not an LLM); squabble, don't bypass (reach green by
+satisfying the gate, never by admin-override); no automated licence edits; no
+deletion by access-recency; wire first; always sign; report faithfully (no
+overclaim); stop-first on costly or outward-facing actions; boundaries are real;
+and equivalence as identity.
+
+== See also
+
+* `hyperpolymath/manifesto` — the doctrine in the owner's voice.
+* `hyperpolymath/rsr-template-repo` — `RSR-PHILOSOPHY.adoc` and the arrival-pack
+  that projects the Doctrine summary into every `CLAUDE.md`.